From 4221db82d872d63525cdbb6bfe57e0c76fd4bb25 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sat, 23 Aug 2014 10:28:59 +0200
Subject: [PATCH 1/2] describe how to access form errors

---
 components/form/introduction.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/components/form/introduction.rst b/components/form/introduction.rst
index 2cd6ad86a19..8f090568b77 100644
--- a/components/form/introduction.rst
+++ b/components/form/introduction.rst
@@ -687,6 +687,13 @@ object::
     errors from that field. However, there is no way to determine which field
     an error was originally attached to.
 
+.. note::
+
+    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.
+
 .. _Packagist: https://packagist.org/packages/symfony/form
 .. _Twig:      http://twig.sensiolabs.org
 .. _`Twig Configuration`: http://twig.sensiolabs.org/doc/intro.html

From 0245e919e9a8f8b110437baaf3a712ef26c2b8b4 Mon Sep 17 00:00:00 2001
From: Christian Flothmann <christian.flothmann@xabbuh.de>
Date: Sat, 23 Aug 2014 11:13:11 +0200
Subject: [PATCH 2/2] [Form] document $deep and $flatten of getErrors()

---
 components/form/introduction.rst | 41 +++++++++++++++++++-------------
 1 file changed, 25 insertions(+), 16 deletions(-)

diff --git a/components/form/introduction.rst b/components/form/introduction.rst
index 8f090568b77..3a872513a4f 100644
--- a/components/form/introduction.rst
+++ b/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