diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index f8ec600f7e2..2174b0187d3 100644 --- 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 -------