[#2058] Refactoring how to add validation to a form, using the constraints option on individual forms, which is much easier than adding things globally, as we did in 2.0

Author: weaverryan

book/forms.rst

@@ -1520,72 +1520,24 @@ Adding Validation
 
 The only missing piece is validation. Usually, when you call ``$form->isValid()``,
 the object is validated by reading the constraints that you applied to that
-class. But without a class, how can you add constraints to the data of your
-form?
-
-The answer is to setup the constraints yourself, and pass them into your
-form. The overall approach is covered a bit more in the :ref:`validation chapter<book-validation-raw-values>`,
-but here's a short example::
-
-    // import the namespaces above your controller class
-    use Symfony\Component\Validator\Constraints\Email;
-    use Symfony\Component\Validator\Constraints\Length;
-    use Symfony\Component\Validator\Constraints\Collection;
-
-    $collectionConstraint = new Collection(array(
-        'name' => new Length(array("min" => 5)),
-        'email' => new Email(array('message' => 'Invalid email address')),
-    ));
-
-    // create a form, no default values, pass in the constraint option
-    $form = $this->createFormBuilder(null, array(
-        'constraints' => $collectionConstraint,
-    ))->add('email', 'email')
-        // ...
-    ;
-
-Now, when you call `$form->bind($request)`, the constraints setup here are run
-against your form's data. If you're using a form class, override the ``setDefaultOptions()``
-method to specify the option::
-
-    namespace Acme\TaskBundle\Form\Type;
-
-    use Symfony\Component\Form\AbstractType;
-    use Symfony\Component\Form\FormBuilder;
-    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
-    use Symfony\Component\Validator\Constraints\Email;
-    use Symfony\Component\Validator\Constraints\Length;
-    use Symfony\Component\Validator\Constraints\Collection;
-
-    class ContactType extends AbstractType
-    {
-        // ...
+class. If your form is binding to an object (i.e. you're using the ``data_class``
+option or passing an object to your form), this is almost always the approach
+you want to use. See :doc:`/book/validation` for more details.
 
-        public function setDefaultOptions(OptionsResolverInterface $resolver)
-        {
-            $collectionConstraint = new Collection(array(
-                'name' => new Length(array("min" => 5)),
-                'email' => new Email(
-                    array('message' => 'Invalid email address')
-                ),
-            ));
+.. _form-option-constraints:
 
-            $resolver->setDefaults(array(
-                'constraints' => $collectionConstraint
-            ));
-        }
-    }
+But if you're not binding to an object and are instead retrieving a simple
+array of your submitted data, how can you add constraints to the data of your
+form?
 
-Now, you have the flexibility to create forms - with validation - that return
-an array of data, instead of an object. In most cases, it's better - and
-certainly more robust - to bind your form to an object. But for simple forms,
-this is a great approach.
+The answer is to setup the constraints yourself, and attach them to the individual
+fields. The overall approach is covered a bit more in the :ref:`validation chapter<book-validation-raw-values>`,
+but here's a short example:
 
 .. versionadded:: 2.1
-   Constraints can be added directly to fields using the ``constraints`` option,
-   which accepts a single constraint or an array of constraints (before 2.1,
-   the option was called ``validation_constraint``, and only accepted a single
-   constraint).
+   The ``constraints`` option, which accepts a single constraint or an array
+   of constraints (before 2.1, the option was called ``validation_constraint``,
+   and only accepted a single constraint) is new to Symfony 2.1.
 
 .. code-block:: php
 

reference/forms/types/form.rst

@@ -13,10 +13,14 @@ on all fields.
 
 .. include:: /reference/forms/types/options/required.rst.inc
 
+.. include:: /reference/forms/types/options/constraints.rst.inc
+
 .. include:: /reference/forms/types/options/cascade_validation.rst.inc
 
 .. include:: /reference/forms/types/options/disabled.rst.inc
 
+.. include:: /reference/forms/types/options/disabled.rst.inc
+
 .. include:: /reference/forms/types/options/trim.rst.inc
 
 .. include:: /reference/forms/types/options/mapped.rst.inc

reference/forms/types/options/constraints.rst.inc

@@ -0,0 +1,7 @@
+constraints
+~~~~~~~~~~~
+
+**type**: array or :class:`Symfony\\Component\\Validator\\Constraint` **default**: ``null``
+
+Allows you to attach one or more validation constraints to a specific field.
+For more information, see :ref:`Adding Validation<form-option-constraints>`.