From 706b813cce1a545e8e982e368910845951fc597b Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 29 Mar 2019 10:27:45 +0100 Subject: [PATCH 1/4] Documented the new Unique constraint --- reference/constraints/Collection.rst | 6 ++ reference/constraints/Unique.rst | 113 +++++++++++++++++++++++++ reference/constraints/UniqueEntity.rst | 6 ++ reference/constraints/map.rst.inc | 1 + 4 files changed, 126 insertions(+) create mode 100644 reference/constraints/Unique.rst diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index daf59746588..e7751b86b93 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -11,6 +11,12 @@ constraint. This constraint can also make sure that certain collection keys are present and that extra keys are not present. +.. seealso:: + + If you want to validate that all the elements of the collection are unique + (none of them is present more than once) use the + :doc:`Unique constraint `. + ========== =================================================================== Applies to :ref:`property or method ` Options - `allowExtraFields`_ diff --git a/reference/constraints/Unique.rst b/reference/constraints/Unique.rst new file mode 100644 index 00000000000..c8e0e4a3082 --- /dev/null +++ b/reference/constraints/Unique.rst @@ -0,0 +1,113 @@ +Unique +====== + +Validates that all the elements of the given collection are unique (none of them +is present more than once). Elements are compared strictly, so ``'7'`` and ``7`` +are considered different elements (a string and an integer, respectively). + +.. seealso:: + + If you want to apply different validation constraints to the elements of a + collection or want to make sure that certain collection keys are present, + use the :doc:`Collection constraint `. + +.. seealso:: + + If you want to validate that a given entity property is unique among all + entities (e.g. the user email) use the + :doc:`UniqueEntity constraint `. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\Unique` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\UniqueValidator` +========== =================================================================== + +Basic Usage +----------- + +This constraint can be applied to any property of type array or ``\Traversable``. +In the following example, ``$contactEmails`` is an array of strings: + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/Person.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + + /** + * @Assert\Unique + */ + protected $contactEmails; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Person: + properties: + contactEmails: + - Unique: ~ + + .. code-block:: xml + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Person.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class Person + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('contactEmails', new Assert\Unique()); + } + } + +Options +------- + +.. include:: /reference/constraints/_groups-option.rst.inc + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This collection should contain only unique elements.`` + +This is the message that will be shown if at least one element is repeated in +the collection. + +You can use the following parameters in this message: + +============================= ================================================ +Parameter Description +============================= ================================================ +``{{ value }}`` The repeated value +============================= ================================================ + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index f6c4ddf8bce..1382f1fcb3d 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -5,6 +5,12 @@ Validates that a particular field (or fields) in a Doctrine entity is (are) unique. This is commonly used, for example, to prevent a new user to register using an email address that already exists in the system. +.. seealso:: + + If you want to validate that all the elements of the collection are unique + (none of them is present more than once) use the + :doc:`Unique constraint `. + ========== =================================================================== Applies to :ref:`class ` Options - `em`_ diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index 4f95a168242..1ccfc1ec691 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -37,6 +37,7 @@ Comparison Constraints * :doc:`GreaterThanOrEqual ` * :doc:`Range ` * :doc:`DivisibleBy ` +* :doc:`Unique ` Date Constraints ~~~~~~~~~~~~~~~~ From 6e48749f3832eced71a91f5d9bca1ee7eb9cff70 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 29 Mar 2019 11:40:18 +0100 Subject: [PATCH 2/4] Fixes --- reference/constraints/Unique.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/constraints/Unique.rst b/reference/constraints/Unique.rst index c8e0e4a3082..1917e32942e 100644 --- a/reference/constraints/Unique.rst +++ b/reference/constraints/Unique.rst @@ -29,8 +29,9 @@ Validator :class:`Symfony\\Component\\Validator\\Constraints\\UniqueValidator` Basic Usage ----------- -This constraint can be applied to any property of type array or ``\Traversable``. -In the following example, ``$contactEmails`` is an array of strings: +This constraint can be applied to any property of type ``array`` or +``\Traversable``. In the following example, ``$contactEmails`` is an array of +strings: .. configuration-block:: @@ -43,7 +44,6 @@ In the following example, ``$contactEmails`` is an array of strings: class Person { - /** * @Assert\Unique */ From 52fc627691ebd5822f75e50402fd116629847532 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 29 Mar 2019 12:32:25 +0100 Subject: [PATCH 3/4] Tweaks --- reference/constraints/Collection.rst | 3 +-- reference/constraints/Unique.rst | 6 +++--- reference/constraints/UniqueEntity.rst | 3 +-- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index e7751b86b93..12dc1e2f07a 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -14,8 +14,7 @@ and that extra keys are not present. .. seealso:: If you want to validate that all the elements of the collection are unique - (none of them is present more than once) use the - :doc:`Unique constraint `. + use the :doc:`Unique constraint `. ========== =================================================================== Applies to :ref:`property or method ` diff --git a/reference/constraints/Unique.rst b/reference/constraints/Unique.rst index 1917e32942e..681c4dc18b6 100644 --- a/reference/constraints/Unique.rst +++ b/reference/constraints/Unique.rst @@ -13,9 +13,9 @@ are considered different elements (a string and an integer, respectively). .. seealso:: - If you want to validate that a given entity property is unique among all - entities (e.g. the user email) use the - :doc:`UniqueEntity constraint `. + If you want to validate that the value of an entity property is unique among + all entities of the same type (e.g. the registration email of all users) use + the :doc:`UniqueEntity constraint `. ========== =================================================================== Applies to :ref:`property or method ` diff --git a/reference/constraints/UniqueEntity.rst b/reference/constraints/UniqueEntity.rst index 1382f1fcb3d..2d2b658dee1 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -8,8 +8,7 @@ using an email address that already exists in the system. .. seealso:: If you want to validate that all the elements of the collection are unique - (none of them is present more than once) use the - :doc:`Unique constraint `. + use the :doc:`Unique constraint `. ========== =================================================================== Applies to :ref:`class ` From 0d094fa9c013a3a462c5a4347fc8dbc668d7c9a5 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 1 Apr 2019 08:59:31 +0200 Subject: [PATCH 4/4] Fixed the missing link to the new article --- reference/constraints.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/constraints.rst b/reference/constraints.rst index d81a4eefd37..d068494b8a2 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -31,6 +31,7 @@ Validation Constraints Reference constraints/GreaterThanOrEqual constraints/Range constraints/DivisibleBy + constraints/Unique constraints/Date constraints/DateTime