[Form] document $deep and $flatten of getErrors()

Author: xabbuh

components/form/introduction.rst

@@ -620,23 +620,72 @@ and the errors will display next to the fields on error.
 Accessing Form Errors
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 2.5
+    Before Symfony 2.5, ``getErrors()`` returned an array of ``FormError``
+    objects. The return value was changed to ``FormErrorIterator`` in Symfony
+    2.5.
+
 You can use the :method:`Symfony\\Component\\Form\\FormInterface::getErrors`
-method to access the list of errors. Each element is a :class:`Symfony\\Component\\Form\\FormError`
-object::
+method to access the list of errors. It returns a
+:class:`Symfony\\Component\\Form\\FormErrorIterator` instance::
 
     $form = ...;
 
     // ...
 
-    // array of FormError objects
+    // a FormErrorIterator instance
     $errors = $form->getErrors();
 
-.. note::
+.. tip::
+
+    In older Symfony versions, ``getErrors()`` returned an array. To use the
+    errors the same way in Symfony 2.5 or newer, you have to pass them to
+    PHP's :phpfunction:`iterator_to_array` function::
+
+        $errorsAsArray = iterator_to_array($form->getErrors());
+
+    This is useful, for example, if you want to use PHP's ``array_`` function
+    on the form errors.
+
+Child Form Errors
+.................
+
+.. versionadded:: 2.5
+    The ``$deep`` and ``$flatten`` arguments were introduced in Symfony 2.5.
+
+By default, ``getErrors()`` only returns the errors of the form object it
+was called on. To also include the errors of child forms, you'll have to pass
+``true`` as the first argument to it::
+
+    // ...
 
-    Unless you enable the :ref:`error_bubbling <reference-form-option-error-bubbling>`
-    option on a particular child form, ``getErrors()`` only returns the errors
-    of the form it is accessed on. For debugging purposes, you can use the :method:`Symfony\\Component\\Form\\Form::getErrorsAsString` method which
-    returns a string representation of all errors of the whole form tree.
+    // $errors contains all errors of the whole form tree
+    $errors = $form->getErrors(true);
+
+You can use the :method:`Symfony\\Component\\Form\\FormError::getOrigin` method
+on each element returned by the ``FormErrorIterator`` to determine the form
+the error belongs to.
+
+You can also let the iterator reflect the form tree structure. To achieve
+this, pass ``false`` as the second argument to ``getErrors()``. The iterator
+then, returns an ``FormErrorIterator`` object for each child form instead
+of multiple ``FormError`` childs::
+
+    $form = ...;
+
+    // ...
+
+    $errors = $form->getErrors(true, false);
+
+    foreach ($errors as $error) {
+        if ($error->hasChildren()) {
+            // handle errors of a child form
+            // $error is an instance of FormErrorIterator
+        } else {
+            // handle an error of $form
+            // $error is an instance of FormError
+        }
+    }
 
 .. _Packagist: https://packagist.org/packages/symfony/form
 .. _Twig:      http://twig.sensiolabs.org