Merge pull request symfony#2432 from afishnamedsquish/collection_constraint_optional_required_docs

weaverryan · weaverryan · commit 2928045dde58 · 2013-04-09T15:33:27.000-07:00
Validator Documentation for Collection constraint Required/Optional options
diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst
@@ -163,6 +163,72 @@ the above example, the ``allowMissingFields`` option was set to true, meaning
 that if either of the ``personal_email`` or ``short_bio`` elements were missing
 from the ``$personalData`` property, no validation error would occur.
 
+.. versionadded:: 2.1
+    The ``Required`` and ``Optional`` constraints are new to Symfony 2.1.
+
+Required and Optional Field Constraints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Constraints for fields within a collection can be wrapped in the ``Required`` or
+``Optional`` constraint to control whether they should always be applied (``Required``)
+or only applied when the field is present (``Optional``).
+
+For instance, if you want to require that the ``personal_email`` field of the
+``profileData`` array is not blank and is a valid email but the ``alternate_email``
+field is optional but must be a valid email if supplied, you can do the following:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            /**
+             * @Assert\Collection(
+             *     fields={
+             *         "personal_email"  = @Assert\Collection\Required({@Assert\NotBlank, @Assert\Email}),
+             *         "alternate_email" = @Assert\Collection\Optional({@Assert\Email}),
+             *     }
+             * )
+             */
+             protected $profileData = array(
+                 'personal_email',
+             );
+        }
+
+    .. code-block:: php
+
+        // src/Acme/BlogBundle/Entity/Author.php
+        namespace Acme\BlogBundle\Entity;
+
+        use Symfony\Component\Validator\Mapping\ClassMetadata;
+        use Symfony\Component\Validator\Constraints as Assert;
+
+        class Author
+        {
+            protected $profileData = array('personal_email');
+
+            public static function loadValidatorMetadata(ClassMetadata $metadata)
+            {
+                $metadata->addPropertyConstraint('profileData', new Assert\Collection(array(
+                    'fields' => array(
+                        'personal_email'  => new Assert\Collection\Required(array(new Assert\NotBlank(), new Assert\Email())),
+                        'alternate_email' => new Assert\Collection\Optional(array(new Assert\Email())),
+                    ),
+                )));
+            }
+        }
+
+Even without ``allowMissingFields`` set to true, you can now omit the ``alternate_email`` property 
+completely from the ``profileData`` array, since it is ``Optional``. However, if the the ``personal_email`` 
+field does not exist in the array there will be a constraint violation that the field is missing, 
+since it is ``Required``.
+
 Options
 -------
 
