feature #4169 [Components][Form] document $deep and $flatten of getEr…

…rors() (xabbuh)

This PR was merged into the 2.5 branch.

Discussion
----------

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

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#9918)
| Applies to    | 2.5+
| Fixed tickets | #3660

This is based on #4168.

Commits
-------

0245e91 [Form] document $deep and $flatten of getErrors()
4221db8 describe how to access form errors

components/form/introduction.rst

@@ -663,29 +663,45 @@ 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.
+
+.. versionadded:: 2.5
+    The ``$deep`` and ``$flatten`` arguments were introduced 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 = ...;
 
     // ...
 
-    // an array of FormError objects, but only errors attached to this form level (e.g. "global errors)
+    // a FormErrorIterator instance, but only errors attached to this form level (e.g. "global errors)
     $errors = $form->getErrors();
 
-    // an array of FormError objects, but only errors attached to the "firstName" field
+    // a FormErrorIterator instance, but only errors attached to the "firstName" field
     $errors = $form['firstName']->getErrors();
 
-    // a string representation of all errors of the whole form tree
-    $errors = $form->getErrorsAsString();
+    // a FormErrorIterator instance in a flattened structure
+    // use getOrigin() to determine the form causing the error
+    $errors = $form->getErrors(true);
 
-.. note::
+    // a FormErrorIterator instance representing the form tree structure
+    $errors = $form->getErrors(true, false);
+
+.. 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());
 
-    If you enable the :ref:`error_bubbling <reference-form-option-error-bubbling>`
-    option on a field, calling ``getErrors()`` on the parent form will include
-    errors from that field. However, there is no way to determine which field
-    an error was originally attached to.
+    This is useful, for example, if you want to use PHP's ``array_`` function
+    on the form errors.
 
 .. _Packagist: https://packagist.org/packages/symfony/form
 .. _Twig:      http://twig.sensiolabs.org