feature #9918 [Form] Changed Form::getErrors() to return an iterator …

…and added two optional parameters $deep and $flatten (webmozart)

This PR was merged into the 2.5-dev branch.

Discussion
----------

[Form] Changed Form::getErrors() to return an iterator and added two optional parameters $deep and $flatten

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | yes
| Deprecations? | yes
| Tests pass?   | yes
| Fixed tickets | #7205
| License       | MIT
| Doc PR        | -

See the changes in the UPGRADE files for more information.

Commits
-------

6b3fbb5 [Form] Changed the default value of $flatten in Form::getErrors() to true
a9268c4 [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 = true)
+   {
+   ```

UPGRADE-3.0.md

@@ -246,6 +246,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 `$flatten` set to false
+   and cast the returned iterator to a string (if not done implicitly by PHP).
+
+   Before:
+
+   ```
+   echo $form->getErrorsAsString();
+   ```
+
+   After:
+
+   ```
+   echo $form->getErrors(true, false);
+   ```
+
 
 ### 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 = true)
     {
-        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 = true)
     {
-        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, false), $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), ' ');
+    }
 }