feature #4454 More concrete explanation of validation groups (peterrehm)

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #4454).

Discussion
----------

More concrete explanation of validation groups

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | -

Improved the explanation of default validation groups in reference with my discussion with @webmozart in symfony/symfony#�11880.

Commits
-------

81728b6 More concrete explanation of validation groups

Author: weaverryan

book/forms.rst

@@ -526,6 +526,7 @@ to an array callback::
 
     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
+    // ...
     public function setDefaultOptions(OptionsResolverInterface $resolver)
     {
         $resolver->setDefaults(array(
@@ -541,23 +542,51 @@ This will call the static method ``determineValidationGroups()`` on the
 The Form object is passed as an argument to that method (see next example).
 You can also define whole logic inline by using a ``Closure``::
 
+    use Acme\AcmeBundle\Entity\Client;
     use Symfony\Component\Form\FormInterface;
     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
+    // ...
     public function setDefaultOptions(OptionsResolverInterface $resolver)
     {
         $resolver->setDefaults(array(
             'validation_groups' => function(FormInterface $form) {
                 $data = $form->getData();
-                if (Entity\Client::TYPE_PERSON == $data->getType()) {
+                if (Client::TYPE_PERSON == $data->getType()) {
                     return array('person');
-                } else {
-                    return array('company');
                 }
+
+                return array('company');
+            },
+        ));
+    }
+
+Using the ``validation_groups`` option overrides the default validation
+group which is being used. If you want to validate the default constraints
+of the entity as well you have to adjust the option as follows::
+
+    use Acme\AcmeBundle\Entity\Client;
+    use Symfony\Component\Form\FormInterface;
+    use Symfony\Component\OptionsResolver\OptionsResolverInterface;
+
+    // ...
+    public function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        $resolver->setDefaults(array(
+            'validation_groups' => function(FormInterface $form) {
+                $data = $form->getData();
+                if (Client::TYPE_PERSON == $data->getType()) {
+                    return array('Default', 'person');
+                }
+
+                return array('Default', 'company');
             },
         ));
     }
 
+You can find more information about how the validation groups and the default constraints
+work in the book section about :ref:`validation groups <book-validation-validation-groups>`.
+
 .. index::
    single: Forms; Validation groups based on clicked button
 

book/validation.rst

@@ -814,11 +814,38 @@ With this configuration, there are three validation groups:
     that belong to no other group.
 
 ``User``
-    Equivalent to all constraints of the ``User`` object in the ``Default`` group.
+    Equivalent to all constraints of the ``User`` object in the ``Default``
+    group. This is always the name of the class. The difference between this
+    and ``Default`` is explained below.
 
 ``registration``
     Contains the constraints on the ``email`` and ``password`` fields only.
 
+Constraints in the ``Default`` group of a class are the constraints that have either no
+explicit group configured or that are configured to a group equal to the class name or
+the string ``Default``.
+
+.. caution::
+
+    When validating *just* the User object, there is no difference between the ``Default`` group
+    and the ``User`` group. But, there is a difference if ``User`` has embedded objects. For example,
+    imagine ``User`` has an ``address`` property that contains some ``Address`` object and that
+    you've added the :doc:`/reference/constraints/valid` constraint to this property so that it's
+    validated when you validate the ``User`` object.
+
+    If you validate ``User`` using the ``Default`` group, then any constraints on the ``Address``
+    class that are in the ``Default`` group *will* be used. But, if you validate ``User`` using the
+    ``User`` validation group, then only constraints on the ``Address`` class with the ``User``
+    group will be validated.
+
+    In other words, the ``Default`` group and the class name group (e.g. ``User``) are identical,
+    except when the class is embedded in another object that's actually the one being validated.
+
+    In case you have inheritance in your data model and you validate with the class name of
+    the subclass in the subclass and in the baseclass all constraints in the default group
+    will be validated. If you use the name of the baseclass only the constraints in the base
+    class will be validated.
+
 To tell the validator to use a specific group, pass one or more group names
 as the second argument to the ``validate()`` method::