Permalink
Browse files

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
  • Loading branch information...
weaverryan committed Nov 20, 2014
2 parents 08ca28a + 0245e91 commit 766e01fa0698203db0661b11cdf941daac657459
Showing with 27 additions and 11 deletions.
  1. +27 −11 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

0 comments on commit 766e01f

Please sign in to comment.