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

Author: xabbuh

components/form/introduction.rst

@@ -663,36 +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);
 
-    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.
+.. tip::
 
-.. note::
+    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());
 
-    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.
+    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