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 diff --git a/reference/constraints/Collection.rst b/reference/constraints/Collection.rst index daf59746588..12dc1e2f07a 100644 --- a/reference/constraints/Collection.rst +++ b/reference/constraints/Collection.rst @@ -11,6 +11,11 @@ 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 + 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..681c4dc18b6 --- /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 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 ` +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..2d2b658dee1 100644 --- a/reference/constraints/UniqueEntity.rst +++ b/reference/constraints/UniqueEntity.rst @@ -5,6 +5,11 @@ 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 + 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 ~~~~~~~~~~~~~~~~