Skip to content

Commit 5ba5224

Browse files
przemyslaw-boguszjaviereguiluz
przemyslaw-bogusz
authored and
javiereguiluz
committed
[Validator] Add description for AtLeastOne constraint
1 parent a2846b9 commit 5ba5224

File tree

3 files changed

+197
-0
lines changed

3 files changed

+197
-0
lines changed

‎reference/constraints.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ Validation Constraints Reference
6363
constraints/Isbn
6464
constraints/Issn
6565

66+
constraints/AtLeastOneOf
6667
constraints/Sequentially
6768
constraints/Compound
6869
constraints/Callback

‎reference/constraints/AtLeastOneOf.rst

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
AtLeastOneOf
2+
============
3+
4+
This constraint enables you to create a set of constraints,
5+
allowing to interrupt the validation once the first constraint is satisfied.
6+
7+
.. versionadded:: 5.1
8+
9+
The ``AtLeastOneOf`` constraint was introduced in Symfony 5.1.
10+
11+
========== ===================================================================
12+
Applies to :ref:`property or method <validation-property-target>`
13+
Options - `constraints`_
14+
- `includeInternalMessages`_
15+
- `message`_
16+
- `messageCollection`_
17+
- `groups`_
18+
- `payload`_
19+
Class :class:`Symfony\\Component\\Validator\\Constraints\\AtLeastOneOf`
20+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\AtLeastOneOfValidator`
21+
========== ===================================================================
22+
23+
Basic Usage
24+
-----------
25+
26+
The following constraints ensure that:
27+
28+
* the ``password`` of a ``Student`` either contains ``#`` or is at least ``10`` characters long
29+
* the ``grades`` of a ``Student`` is an array which contains at least ``3`` elements or
30+
that each element is greater than or equal to ``5``
31+
32+
.. configuration-block::
33+
34+
.. code-block:: php-annotations
35+
36+
// src/Entity/Student.php
37+
namespace App\Entity;
38+
39+
use Symfony\Component\Validator\Constraints as Assert;
40+
41+
class Student
42+
{
43+
/**
44+
* @Assert\AtLeastOneOf({
45+
* @Assert\Regex("/#/"),
46+
* @Assert\Length(min=10)
47+
* })
48+
*/
49+
protected $password;
50+
51+
/**
52+
* @Assert\AtLeastOneOf({
53+
* @Assert\Count(min=3),
54+
* @Assert\All(
55+
* @Assert\GreaterThanOrEqual(5)
56+
* )
57+
* })
58+
*/
59+
protected $grades;
60+
}
61+
62+
.. code-block:: yaml
63+
64+
# config/validator/validation.yaml
65+
App\Entity\Student:
66+
properties:
67+
password:
68+
- AtLeastOneOf:
69+
- Regex: '/#/'
70+
- Length:
71+
min: 10
72+
grades:
73+
- AtLeastOneOf:
74+
- Count:
75+
min: 3
76+
- All:
77+
- GreaterThanOrEqual: 5
78+
79+
.. code-block:: xml
80+
81+
<!-- config/validator/validation.xml -->
82+
<?xml version="1.0" encoding="UTF-8" ?>
83+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
84+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
85+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
86+
87+
<class name="App\Entity\Student">
88+
<property name="password">
89+
<constraint name="AtLeastOneOf">
90+
<option name="constraints">
91+
<constraint name="Regex">
92+
<option name="pattern">/#/</option>
93+
</constraint>
94+
<constraint name="Length">
95+
<option name="min">10</option>
96+
</constraint>
97+
</option>
98+
</constraint>
99+
</property>
100+
<property name="grades">
101+
<constraint name="AtLeastOneOf">
102+
<option name="constraints">
103+
<constraint name="Count">
104+
<option name="min">3</option>
105+
</constraint>
106+
<constraint name="All">
107+
<option name="constraints">
108+
<constraint name="GreaterThanOrEqual">
109+
5
110+
</constraint>
111+
</option>
112+
</constraint>
113+
</option>
114+
</constraint>
115+
</property>
116+
</class>
117+
</constraint-mapping>
118+
119+
.. code-block:: php
120+
121+
// src/Entity/Student.php
122+
namespace App\Entity;
123+
124+
use Symfony\Component\Validator\Constraints as Assert;
125+
use Symfony\Component\Validator\Mapping\ClassMetadata;
126+
127+
class Student
128+
{
129+
public static function loadValidatorMetadata(ClassMetadata $metadata)
130+
{
131+
$metadata->addPropertyConstraint('password', new Assert\AtLeastOneOf([
132+
'constraints' => [
133+
new Assert\Regex(['pattern' => '/#/']),
134+
new Assert\Length(['min' => 10]),
135+
],
136+
]));
137+
138+
$metadata->addPropertyConstraint('grades', new Assert\AtLeastOneOf([
139+
'constraints' => [
140+
new Assert\Count(['min' => 3]),
141+
new Assert\All([
142+
'constraints' => [
143+
new Assert\GreaterThanOrEqual(['value' => 5]),
144+
],
145+
]),
146+
],
147+
]));
148+
}
149+
}
150+
151+
Options
152+
-------
153+
154+
constraints
155+
~~~~~~~~~~~
156+
157+
**type**: ``array`` [:ref:`default option <validation-default-option>`]
158+
159+
This required option is the array of validation constraints from which at least one of
160+
has to be satisfied in order for the validation to succeed.
161+
162+
includeInternalMessages
163+
~~~~~~~~~~~~~~~~~~~~~~~
164+
165+
**type**: ``bool`` **default**: ``true``
166+
167+
If set to ``true``, the message that is shown if the validation fails,
168+
will include the list of messages for the internal constraints. See option
169+
`message`_ for an example.
170+
171+
message
172+
~~~~~~~
173+
174+
**type**: ``string`` **default**: ``This value should satisfy at least one of the following constraints:``
175+
176+
This is the intro of the message that will be shown if the validation fails. By default,
177+
it will be followed by the list of messages for the internal constraints
178+
(configurable by `includeInternalMessages`_ option) . For example,
179+
if the above ``grades`` property fails to validate, the message will be
180+
``This value should satisfy at least one of the following constraints:
181+
[1] This collection should contain 3 elements or more.
182+
[2] Each element of this collection should satisfy its own set of constraints.``
183+
184+
messageCollection
185+
~~~~~~~~~~~~~~~~~
186+
187+
**type**: ``string`` **default**: ``Each element of this collection should satisfy its own set of constraints.``
188+
189+
This is the message that will be shown if the validation fails
190+
and the internal constraint is either :doc:`/reference/constraints/All`
191+
or :doc:`/reference/constraints/Collection`. See option `message`_ for an example.
192+
193+
.. include:: /reference/constraints/_groups-option.rst.inc
194+
195+
.. include:: /reference/constraints/_payload-option.rst.inc

‎reference/constraints/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ Financial and other Number Constraints
8484
Other Constraints
8585
~~~~~~~~~~~~~~~~~
8686

87+
* :doc:`AtLeastOneOf </reference/constraints/AtLeastOneOf>`
8788
* :doc:`Sequentially </reference/constraints/Sequentially>`
8889
* :doc:`Compound </reference/constraints/Compound>`
8990
* :doc:`Callback </reference/constraints/Callback>`

0 commit comments

Comments
 (0)