Skip to content

Commit 323391d

Browse files
alexandre-dauboisalexandre-daubois
committed
[Validator] Add Week constraint
1 parent f1c7127 commit 323391d

File tree

2 files changed

+173
-0
lines changed

2 files changed

+173
-0
lines changed

‎reference/constraints/Week.rst

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
Week
2+
====
3+
4+
.. versionadded:: 7.2
5+
6+
The ``Week`` constraint was introduced in Symfony 7.2.
7+
8+
Validates that a string (or an object implementing the ``Stringable`` PHP interface)
9+
matches a given week number. The week number format is defined by `ISO-8601`_
10+
and should be composed of the year and the week number, separated by a hyphen
11+
(e.g. ``2022-W01``).
12+
13+
========== =======================================================================
14+
Applies to :ref:`property or method <validation-property-target>`
15+
Class :class:`Symfony\\Component\\Validator\\Constraints\\Week`
16+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\WeekValidator`
17+
========== =======================================================================
18+
19+
Basic Usage
20+
-----------
21+
22+
If you wanted to ensure that the ``startWeek`` property of an ``OnlineCourse``
23+
class is between the first and the twentieth week of the year 2022, you could do
24+
the following:
25+
26+
.. configuration-block::
27+
28+
.. code-block:: php-attributes
29+
30+
// src/Entity/OnlineCourse.php
31+
namespace App\Entity;
32+
33+
use Symfony\Component\Validator\Constraints as Assert;
34+
35+
class OnlineCourse
36+
{
37+
#[Assert\Week(min: '2022-W01', max: '2022-W20')]
38+
protected string $startWeek;
39+
}
40+
41+
.. code-block:: yaml
42+
43+
# config/validator/validation.yaml
44+
App\Entity\OnlineCourse:
45+
properties:
46+
startWeek:
47+
- Week:
48+
min: '2022-W01'
49+
max: '2022-W20'
50+
51+
.. code-block:: xml
52+
53+
<!-- config/validator/validation.xml -->
54+
<?xml version="1.0" encoding="UTF-8" ?>
55+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
56+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
57+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
58+
59+
<class name="App\Entity\OnlineCourse">
60+
<property name="startWeek">
61+
<constraint name="Week">
62+
<option name="min">2022-W01</option>
63+
<option name="max">2022-W20</option>
64+
</constraint>
65+
</property>
66+
</class>
67+
</constraint-mapping>
68+
69+
.. code-block:: php
70+
71+
// src/Entity/OnlineCourse.php
72+
namespace App\Entity;
73+
74+
use Symfony\Component\Validator\Constraints as Assert;
75+
use Symfony\Component\Validator\Mapping\ClassMetadata;
76+
77+
class OnlineCourse
78+
{
79+
// ...
80+
81+
public static function loadValidatorMetadata(ClassMetadata $metadata): void
82+
{
83+
$metadata->addPropertyConstraint('startWeek', new Assert\Week([
84+
'min' => '2022-W01',
85+
'max' => '2022-W20',
86+
]));
87+
}
88+
}
89+
90+
.. note::
91+
92+
The constraint also checks that the given week exists in the calendar. For example,
93+
``2022-W53`` is not a valid week number for 2022, because 2022 only had 52 weeks.
94+
95+
Options
96+
-------
97+
98+
``min``
99+
~~~~~~~
100+
101+
**type**: ``string`` **default**: ``null``
102+
103+
The minimum week number that the value must match.
104+
105+
``max``
106+
~~~~~~~
107+
108+
**type**: ``string`` **default**: ``null``
109+
110+
The maximum week number that the value must match.
111+
112+
.. include:: /reference/constraints/_groups-option.rst.inc
113+
114+
``invalidFormatMessage``
115+
~~~~~~~~~~~~~~~~~~~~~~~~
116+
117+
**type**: ``string`` **default**: ``This value does not represent a valid week in the ISO 8601 format.``
118+
119+
This is the message that will be shown if the value does not match the ISO 8601
120+
week format.
121+
122+
``invalidWeekNumberMessage``
123+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124+
125+
**type**: ``string`` **default**: ``The week "{{ value }}" is not a valid week.``
126+
127+
This is the message that will be shown if the value does not match a valid week
128+
number.
129+
130+
You can use the following parameters in this message:
131+
132+
================ ==================================================
133+
Parameter Description
134+
================ ==================================================
135+
``{{ value }}`` The value that was passed to the constraint
136+
================ ==================================================
137+
138+
``tooLowMessage``
139+
~~~~~~~~~~~~~~~~~
140+
141+
**type**: ``string`` **default**: ``The value should not be before week "{{ min }}".``
142+
143+
This is the message that will be shown if the value is lower than the minimum
144+
week number.
145+
146+
You can use the following parameters in this message:
147+
148+
================ ==================================================
149+
Parameter Description
150+
================ ==================================================
151+
``{{ min }}`` The minimum week number
152+
================ ==================================================
153+
154+
``tooHighMessage``
155+
~~~~~~~~~~~~~~~~~~
156+
157+
**type**: ``string`` **default**: ``The value should not be after week "{{ max }}".``
158+
159+
This is the message that will be shown if the value is higher than the maximum
160+
week number.
161+
162+
You can use the following parameters in this message:
163+
164+
================ ==================================================
165+
Parameter Description
166+
================ ==================================================
167+
``{{ max }}`` The maximum week number
168+
================ ==================================================
169+
170+
.. include:: /reference/constraints/_payload-option.rst.inc
171+
172+
.. _ISO-8601: https://en.wikipedia.org/wiki/ISO_8601

‎reference/constraints/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Date Constraints
6464
* :doc:`DateTime </reference/constraints/DateTime>`
6565
* :doc:`Time </reference/constraints/Time>`
6666
* :doc:`Timezone </reference/constraints/Timezone>`
67+
* :doc:`Week </reference/constraints/Week>`
6768

6869
Choice Constraints
6970
~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)