Skip to content

Commit d479fc2

Browse files
wouterjwouterj
committed
feature #11317 [Validator] add documentation for the new Timezone constraint. (hhamon, javiereguiluz)
This PR was merged into the master branch. Discussion ---------- [Validator] add documentation for the new `Timezone` constraint. This is the documentation related to PR symfony/symfony#30900 Commits ------- 8e33d47 Fixes classification 5ec9159 Fix option ec7bd40 Revert country_code to countryCode 9cbeb75 Fixes options list table c5681bf Add more explanations b37bc78 Minor fixes d564218 Minor fixes ac6282f Listed the geographical zones defined by PHP 135c5ff Minor fixes b0b1498 [Validator] add documentation for the new `Timezone` constraint.
2 parents 3e5d4a5 + 8e33d47 commit d479fc2

File tree

3 files changed

+146
-0
lines changed

3 files changed

+146
-0
lines changed

‎reference/constraints.rst

+1
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ Validation Constraints Reference
4949
constraints/Language
5050
constraints/Locale
5151
constraints/Country
52+
constraints/Timezone
5253

5354
constraints/File
5455
constraints/Image

‎reference/constraints/Timezone.rst

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
Timezone
2+
========
3+
4+
Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``).
5+
6+
========== ======================================================================
7+
Applies to :ref:`property or method <validation-property-target>`
8+
Options - `groups`_
9+
- `message`_
10+
- `payload`_
11+
- `zone`_
12+
- `countryCode`_
13+
Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone`
14+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator`
15+
========== ======================================================================
16+
17+
Basic Usage
18+
-----------
19+
20+
Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a
21+
string meant to contain a timezone identifier (e.g. ``America/New_York``):
22+
23+
.. configuration-block::
24+
25+
.. code-block:: php-annotations
26+
27+
// src/Entity/UserSettings.php
28+
namespace App\Entity;
29+
30+
use Symfony\Component\Validator\Constraints as Assert;
31+
32+
class UserSettings
33+
{
34+
/**
35+
* @Assert\Timezone
36+
*/
37+
protected $timezone;
38+
}
39+
40+
.. code-block:: yaml
41+
42+
# config/validator/validation.yaml
43+
App\Entity\UserSettings:
44+
properties:
45+
timezone:
46+
- Timezone: ~
47+
48+
.. code-block:: xml
49+
50+
<!-- config/validator/validation.xml -->
51+
<?xml version="1.0" encoding="UTF-8" ?>
52+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
53+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
54+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
55+
56+
<class name="App\Entity\UserSettings">
57+
<property name="timezone">
58+
<constraint name="Timezone"/>
59+
</property>
60+
</class>
61+
</constraint-mapping>
62+
63+
.. code-block:: php
64+
65+
// src/Entity/UserSettings.php
66+
namespace App\Entity;
67+
68+
use Symfony\Component\Validator\Mapping\ClassMetadata;
69+
use Symfony\Component\Validator\Constraints as Assert;
70+
71+
class UserSettings
72+
{
73+
protected $timezone;
74+
75+
public static function loadValidatorMetadata(ClassMetadata $metadata)
76+
{
77+
$metadata->addPropertyConstraint('timezone', new Assert\Timezone());
78+
}
79+
}
80+
81+
.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
82+
83+
Options
84+
-------
85+
86+
.. include:: /reference/constraints/_groups-option.rst.inc
87+
88+
message
89+
~~~~~~~
90+
91+
**type**: ``string`` **default**: ``This value is not a valid timezone.``
92+
93+
This message is shown if the underlying data is not a valid timezone identifier.
94+
95+
You can use the following parameters in this message:
96+
97+
=============== ==============================================================
98+
Parameter Description
99+
=============== ==============================================================
100+
``{{ value }}`` The current (invalid) value
101+
=============== ==============================================================
102+
103+
.. include:: /reference/constraints/_payload-option.rst.inc
104+
105+
zone
106+
~~~~
107+
108+
**type**: ``string`` **default**: ``\DateTimeZone::ALL``
109+
110+
Set this option to any of the following constants to restrict the valid timezone
111+
identifiers to the ones that belong to that geographical zone:
112+
113+
* ``\DateTimeZone::AFRICA``
114+
* ``\DateTimeZone::AMERICA``
115+
* ``\DateTimeZone::ANTARCTICA``
116+
* ``\DateTimeZone::ARCTIC``
117+
* ``\DateTimeZone::ASIA``
118+
* ``\DateTimeZone::ATLANTIC``
119+
* ``\DateTimeZone::AUSTRALIA``
120+
* ``\DateTimeZone::EUROPE``
121+
* ``\DateTimeZone::INDIAN``
122+
* ``\DateTimeZone::PACIFIC``
123+
124+
The special ``\DateTimeZone::ALL`` zone accepts any timezone excluding deprecated timezones.
125+
126+
The special ``\DateTimeZone::ALL_WITH_BC`` zone accepts any timezone including deprecated timezones.
127+
128+
The special ``\DateTimeZone::PER_COUNTRY`` zone limits the timezones to a certain country. This zone
129+
value must be used in combination with the ``countryCode`` option.
130+
131+
countryCode
132+
~~~~~~~~~~~
133+
134+
**type**: ``string`` **default**: ``null``
135+
136+
If the ``zone`` option is set to ``\DateTimeZone::PER_COUNTRY``, this option
137+
restricts the valid timezone identifiers to the ones that belong to the given
138+
country.
139+
140+
The value of this option must be a valid `ISO 3166-1 alpha-2`_ country code
141+
(e.g. ``CN`` for China).
142+
143+
.. _`DateTimeZone`: https://www.php.net/datetimezone
144+
.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

‎reference/constraints/map.rst.inc

+1
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ Choice Constraints
6161
* :doc:`Language </reference/constraints/Language>`
6262
* :doc:`Locale </reference/constraints/Locale>`
6363
* :doc:`Country </reference/constraints/Country>`
64+
* :doc:`Timezone </reference/constraints/Timezone>`
6465

6566
File Constraints
6667
~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)