From 779f0e780406bf36b6049caf9ca8105a68bb66e9 Mon Sep 17 00:00:00 2001 From: Ben Glassman Date: Sat, 30 Mar 2013 17:07:12 -0400 Subject: [PATCH 1/8] Add documentation to Collection constraint showing usage of Required and Optional classes. --- reference/constraints/Collection.rst | 69 ++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index f8ec600f7e2..06a5d58c505 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -163,6 +163,75 @@ 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`` constraint classes were added to give additional + flexibility over the existing ``allowExtraFields`` and ``allowMissingFields`` options + for fields within a Collection. + +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 example, 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: + + .. code-block:: php-annotations + + // src/Acme/BlogBundle/Entity/Author.php + namespace Acme\BlogBundle\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Constraints\Collection\Optional; + use Symfony\Component\Validator\Constraints\Collection\Required; + + class Author + { + /** + * @Assert\Collection( + * fields={ + * "personal_email" = @Required({@Assert\NotBlank, @Assert\Email}), + * "alternate_email" = @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; + use Symfony\Component\Validator\Constraints\Collection\Optional; + use Symfony\Component\Validator\Constraints\Collection\Required; + + class Author + { + private $options = array(); + + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('profileData', new Assert\Collection(array( + 'fields' => array( + 'personal_email' => new Required(array(new Assert\NotBlank(), new Assert\Email())), + 'alternate_email' => new Optional(array(new Assert\Email())), + ) + ))); + } + } + +Even without ``allowMissingFields`` set to true, you can now omit the ``alternate_email`` property complete 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 ------- From a7e150ad90d7412f7724021887de15e64bc79450 Mon Sep 17 00:00:00 2001 From: Ben Glassman Date: Sat, 30 Mar 2013 18:54:08 -0400 Subject: [PATCH 2/8] Fix missing line breaks and heading line length. --- reference/constraints/Collection.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 06a5d58c505..f383a8fc36c 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -169,7 +169,7 @@ from the ``$personalData`` property, no validation error would occur. for fields within a Collection. 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``) @@ -228,9 +228,10 @@ field is optional but must be a valid email if supplied, you can do the followin } } -Even without ``allowMissingFields`` set to true, you can now omit the ``alternate_email`` property complete 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``. +Even without ``allowMissingFields`` set to true, you can now omit the ``alternate_email`` property +complete 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 ------- From b659e2418a3b5109284fe8de5617fd0c6acf4304 Mon Sep 17 00:00:00 2001 From: Ben Glassman Date: Sat, 30 Mar 2013 20:10:43 -0400 Subject: [PATCH 3/8] Change complete to completely. --- reference/constraints/Collection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index f383a8fc36c..4972c11e03b 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -229,7 +229,7 @@ field is optional but must be a valid email if supplied, you can do the followin } Even without ``allowMissingFields`` set to true, you can now omit the ``alternate_email`` property -complete from the profileData array, since it is ``Optional``. However, if the the ``personal_email`` +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``. From e83d16f4d6495bf4c577cd5ff2e514afa49a397a Mon Sep 17 00:00:00 2001 From: Ben Glassman Date: Sat, 30 Mar 2013 20:15:48 -0400 Subject: [PATCH 4/8] Added configuration-block:: annotation to example section. --- reference/constraints/Collection.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 4972c11e03b..6fe97de28bd 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -179,6 +179,8 @@ For example, 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 From 3f3848395b28fb2136acbcd457ff94db71f08519 Mon Sep 17 00:00:00 2001 From: afishnamedsquish Date: Mon, 1 Apr 2013 12:26:42 -0300 Subject: [PATCH 5/8] Update Collection.rst Formatting changes per comments from @WouterJ --- reference/constraints/Collection.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 6fe97de28bd..4d5a2d2978c 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -164,9 +164,7 @@ 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`` constraint classes were added to give additional - flexibility over the existing ``allowExtraFields`` and ``allowMissingFields`` options - for fields within a Collection. + The ``Required`` and ``Optional`` constraints are new to Symfony 2.1. Required and Optional Field Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -195,13 +193,13 @@ field is optional but must be a valid email if supplied, you can do the followin /** * @Assert\Collection( * fields={ - * "personal_email" = @Required({@Assert\NotBlank, @Assert\Email}), + * "personal_email" = @Required({@Assert\NotBlank, @Assert\Email}), * "alternate_email" = @Optional({@Assert\Email}), * } * ) */ protected $profileData = array( - 'personal_email' + 'personal_email', ); } @@ -217,15 +215,15 @@ field is optional but must be a valid email if supplied, you can do the followin class Author { - private $options = array(); + protected $profileData = array('personal_email'); public static function loadValidatorMetadata(ClassMetadata $metadata) { $metadata->addPropertyConstraint('profileData', new Assert\Collection(array( 'fields' => array( - 'personal_email' => new Required(array(new Assert\NotBlank(), new Assert\Email())), + 'personal_email' => new Required(array(new Assert\NotBlank(), new Assert\Email())), 'alternate_email' => new Optional(array(new Assert\Email())), - ) + ), ))); } } From 2938e6c46691a4dae4fda779c00bd34f0af7d3f9 Mon Sep 17 00:00:00 2001 From: afishnamedsquish Date: Mon, 1 Apr 2013 12:28:32 -0300 Subject: [PATCH 6/8] Update Collection.rst Change 'example' to 'instance'. --- reference/constraints/Collection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 4d5a2d2978c..28009cc27c7 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -173,7 +173,7 @@ 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 example, if you want to require that the ``personal_email`` field of the +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: From f826f609f5b6ccf9d6e91bf4762cad590c5fa4e9 Mon Sep 17 00:00:00 2001 From: afishnamedsquish Date: Mon, 1 Apr 2013 12:53:39 -0300 Subject: [PATCH 7/8] Update Collection.rst Add variable indicators around profileData --- reference/constraints/Collection.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 28009cc27c7..12936b322f3 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -229,7 +229,7 @@ field is optional but must be a valid email if supplied, you can do the followin } 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`` +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``. From 2d4eb951195775f0dedfd59f4b25e5aacd17cf18 Mon Sep 17 00:00:00 2001 From: afishnamedsquish Date: Mon, 1 Apr 2013 12:55:59 -0300 Subject: [PATCH 8/8] Update Collection.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removed use statements for Required/Optional. Instead use Assert\Collection\Required. --- reference/constraints/Collection.rst | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index 12936b322f3..2174b0187d3 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -185,16 +185,14 @@ field is optional but must be a valid email if supplied, you can do the followin namespace Acme\BlogBundle\Entity; use Symfony\Component\Validator\Constraints as Assert; - use Symfony\Component\Validator\Constraints\Collection\Optional; - use Symfony\Component\Validator\Constraints\Collection\Required; class Author { /** * @Assert\Collection( * fields={ - * "personal_email" = @Required({@Assert\NotBlank, @Assert\Email}), - * "alternate_email" = @Optional({@Assert\Email}), + * "personal_email" = @Assert\Collection\Required({@Assert\NotBlank, @Assert\Email}), + * "alternate_email" = @Assert\Collection\Optional({@Assert\Email}), * } * ) */ @@ -210,8 +208,6 @@ field is optional but must be a valid email if supplied, you can do the followin use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - use Symfony\Component\Validator\Constraints\Collection\Optional; - use Symfony\Component\Validator\Constraints\Collection\Required; class Author { @@ -221,8 +217,8 @@ field is optional but must be a valid email if supplied, you can do the followin { $metadata->addPropertyConstraint('profileData', new Assert\Collection(array( 'fields' => array( - 'personal_email' => new Required(array(new Assert\NotBlank(), new Assert\Email())), - 'alternate_email' => new Optional(array(new Assert\Email())), + 'personal_email' => new Assert\Collection\Required(array(new Assert\NotBlank(), new Assert\Email())), + 'alternate_email' => new Assert\Collection\Optional(array(new Assert\Email())), ), ))); }