[Form] Changed Form::getErrors() to return an iterator and added two …

…optional parameters $deep and $flatten

UPGRADE-2.5.md

@@ -5,3 +5,42 @@ Routing
 -------
 
  * Added a new optional parameter `$requiredSchemes` to `Symfony\Component\Routing\Generator\UrlGenerator::doGenerate()`
+
+Form
+----
+
+ * The method `FormInterface::getErrors()` now returns an instance of
+   `Symfony\Component\Form\FormErrorIterator` instead of an array. This object
+   is traversable, countable and supports array access. However, you can not
+   pass it to any of PHP's `array_*` functions anymore. You should use
+   `iterator_to_array()` in those cases where you did.
+
+   Before:
+
+   ```
+   $errors = array_map($callback, $form->getErrors());
+   ```
+
+   After:
+
+   ```
+   $errors = array_map($callback, iterator_to_array($form->getErrors()));
+   ```
+
+ * The method `FormInterface::getErrors()` now has two additional, optional
+   parameters. Make sure to add these parameters to the method signatures of
+   your implementations of that interface.
+
+   Before:
+
+   ```
+   public function getErrors()
+   {
+   ```
+
+   After:
+
+   ```
+   public function getErrors($deep = false, $flatten = false)
+   {
+   ```

UPGRADE-3.0.md

@@ -180,6 +180,22 @@ UPGRADE FROM 2.x to 3.0
  * The options "csrf_provider" and "intention" were renamed to "csrf_token_generator"
    and "csrf_token_id".
 
+ * The method `Form::getErrorsAsString()` was removed. Use `Form::getErrors()`
+   instead with the argument `$deep` set to true and cast the returned iterator
+   to a string (if not done implicitly by PHP).
+
+   Before:
+
+   ```
+   echo $form->getErrorsAsString();
+   ```
+
+   After:
+
+   ```
+   echo $form->getErrors(true);
+   ```
+
 
 ### FrameworkBundle
 

src/Symfony/Bundle/FrameworkBundle/Resources/views/Form/form_errors.html.php

@@ -1,4 +1,4 @@
-<?php if ($errors): ?>
+<?php if (count($errors) > 0): ?>
     <ul>
         <?php foreach ($errors as $error): ?>
             <li><?php echo $error->getMessage() ?></li>

src/Symfony/Component/Form/Button.php

@@ -184,9 +184,11 @@ public function all()
     /**
      * {@inheritdoc}
      */
-    public function getErrors()
+    public function getErrors($deep = false, $flatten = false)
     {
-        return array();
+        $errors = array();
+
+        return new FormErrorIterator($errors, $this, $deep, $flatten);
     }
 
     /**

src/Symfony/Component/Form/CHANGELOG.md

@@ -7,6 +7,9 @@ CHANGELOG
  * added an option for multiple files upload
  * form errors now reference their cause (constraint violation, exception, ...)
  * form errors now remember which form they were originally added to
+ * [BC BREAK] added two optional parameters to FormInterface::getErrors() and
+   changed the method to return a Symfony\Component\Form\FormErrorIterator
+   instance instead of an array
 
 2.4.0
 -----

src/Symfony/Component/Form/Form.php

@@ -778,9 +778,9 @@ public function getClickedButton()
     /**
      * {@inheritdoc}
      */
-    public function getErrors()
+    public function getErrors($deep = false, $flatten = false)
     {
-        return $this->errors;
+        return new FormErrorIterator($this->errors, $this, $deep, $flatten);
     }
 
     /**
@@ -791,24 +791,13 @@ public function getErrors()
      * @param integer $level The indentation level (used internally)
      *
      * @return string A string representation of all errors
+     *
+     * @deprecated Deprecated since version 2.5, to be removed in 3.0. Use
+     *             {@link getErrors()} instead and cast the result to a string.
      */
     public function getErrorsAsString($level = 0)
     {
-        $errors = '';
-        foreach ($this->errors as $error) {
-            $errors .= str_repeat(' ', $level).'ERROR: '.$error->getMessage()."\n";
-        }
-
-        foreach ($this->children as $key => $child) {
-            $errors .= str_repeat(' ', $level).$key.":\n";
-            if ($child instanceof self && $err = $child->getErrorsAsString($level + 4)) {
-                $errors .= $err;
-            } else {
-                $errors .= str_repeat(' ', $level + 4)."No errors\n";
-            }
-        }
-
-        return $errors;
+        return self::indent((string) $this->getErrors(true), $level);
     }
 
     /**
@@ -1115,4 +1104,19 @@ private function viewToNorm($value)
 
         return $value;
     }
+
+    /**
+     * Utility function for indenting multi-line strings.
+     *
+     * @param string  $string The string
+     * @param integer $level  The number of spaces to use for indentation
+     *
+     * @return string The indented string
+     */
+    private static function indent($string, $level)
+    {
+        $indentation = str_repeat(' ', $level);
+
+        return rtrim($indentation.str_replace("\n", "\n".$indentation, $string), ' ');
+    }
 }