From 5ba5224d1658775ae95a7b89a75b9277feddc35d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Przemys=C5=82aw=20Bogusz?= Date: Mon, 23 Mar 2020 21:31:08 +0100 Subject: [PATCH] [Validator] Add description for AtLeastOne constraint --- reference/constraints.rst | 1 + reference/constraints/AtLeastOneOf.rst | 195 +++++++++++++++++++++++++ reference/constraints/map.rst.inc | 1 + 3 files changed, 197 insertions(+) create mode 100644 reference/constraints/AtLeastOneOf.rst diff --git a/reference/constraints.rst b/reference/constraints.rst index 760c0199b89..faa5ed3cac2 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -63,6 +63,7 @@ Validation Constraints Reference constraints/Isbn constraints/Issn + constraints/AtLeastOneOf constraints/Sequentially constraints/Compound constraints/Callback diff --git a/reference/constraints/AtLeastOneOf.rst b/reference/constraints/AtLeastOneOf.rst new file mode 100644 index 00000000000..e3c7e1ecd68 --- /dev/null +++ b/reference/constraints/AtLeastOneOf.rst @@ -0,0 +1,195 @@ +AtLeastOneOf +============ + +This constraint enables you to create a set of constraints, +allowing to interrupt the validation once the first constraint is satisfied. + +.. versionadded:: 5.1 + + The ``AtLeastOneOf`` constraint was introduced in Symfony 5.1. + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `constraints`_ + - `includeInternalMessages`_ + - `message`_ + - `messageCollection`_ + - `groups`_ + - `payload`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\AtLeastOneOf` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\AtLeastOneOfValidator` +========== =================================================================== + +Basic Usage +----------- + +The following constraints ensure that: + +* the ``password`` of a ``Student`` either contains ``#`` or is at least ``10`` characters long +* the ``grades`` of a ``Student`` is an array which contains at least ``3`` elements or + that each element is greater than or equal to ``5`` + +.. configuration-block:: + + .. code-block:: php-annotations + + // src/Entity/Student.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + + class Student + { + /** + * @Assert\AtLeastOneOf({ + * @Assert\Regex("/#/"), + * @Assert\Length(min=10) + * }) + */ + protected $password; + + /** + * @Assert\AtLeastOneOf({ + * @Assert\Count(min=3), + * @Assert\All( + * @Assert\GreaterThanOrEqual(5) + * ) + * }) + */ + protected $grades; + } + + .. code-block:: yaml + + # config/validator/validation.yaml + App\Entity\Student: + properties: + password: + - AtLeastOneOf: + - Regex: '/#/' + - Length: + min: 10 + grades: + - AtLeastOneOf: + - Count: + min: 3 + - All: + - GreaterThanOrEqual: 5 + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/Student.php + namespace App\Entity; + + use Symfony\Component\Validator\Constraints as Assert; + use Symfony\Component\Validator\Mapping\ClassMetadata; + + class Student + { + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('password', new Assert\AtLeastOneOf([ + 'constraints' => [ + new Assert\Regex(['pattern' => '/#/']), + new Assert\Length(['min' => 10]), + ], + ])); + + $metadata->addPropertyConstraint('grades', new Assert\AtLeastOneOf([ + 'constraints' => [ + new Assert\Count(['min' => 3]), + new Assert\All([ + 'constraints' => [ + new Assert\GreaterThanOrEqual(['value' => 5]), + ], + ]), + ], + ])); + } + } + +Options +------- + +constraints +~~~~~~~~~~~ + +**type**: ``array`` [:ref:`default option `] + +This required option is the array of validation constraints from which at least one of +has to be satisfied in order for the validation to succeed. + +includeInternalMessages +~~~~~~~~~~~~~~~~~~~~~~~ + +**type**: ``bool`` **default**: ``true`` + +If set to ``true``, the message that is shown if the validation fails, +will include the list of messages for the internal constraints. See option +`message`_ for an example. + +message +~~~~~~~ + +**type**: ``string`` **default**: ``This value should satisfy at least one of the following constraints:`` + +This is the intro of the message that will be shown if the validation fails. By default, +it will be followed by the list of messages for the internal constraints +(configurable by `includeInternalMessages`_ option) . For example, +if the above ``grades`` property fails to validate, the message will be +``This value should satisfy at least one of the following constraints: +[1] This collection should contain 3 elements or more. +[2] Each element of this collection should satisfy its own set of constraints.`` + +messageCollection +~~~~~~~~~~~~~~~~~ + +**type**: ``string`` **default**: ``Each element of this collection should satisfy its own set of constraints.`` + +This is the message that will be shown if the validation fails +and the internal constraint is either :doc:`/reference/constraints/All` +or :doc:`/reference/constraints/Collection`. See option `message`_ for an example. + +.. include:: /reference/constraints/_groups-option.rst.inc + +.. include:: /reference/constraints/_payload-option.rst.inc diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index dbc6a3b5d74..05e820db8ee 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -84,6 +84,7 @@ Financial and other Number Constraints Other Constraints ~~~~~~~~~~~~~~~~~ +* :doc:`AtLeastOneOf ` * :doc:`Sequentially ` * :doc:`Compound ` * :doc:`Callback `