Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit d479fc2

Browse filesBrowse 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
Copy full SHA for d479fc2

File tree

3 files changed

+146
-0
lines changed
Filter options

3 files changed

+146
-0
lines changed

‎reference/constraints.rst

Copy file name to clipboardExpand all lines: reference/constraints.rst
+1Lines changed: 1 addition & 0 deletions
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

Copy file name to clipboard
+144Lines changed: 144 additions & 0 deletions
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

Copy file name to clipboardExpand all lines: reference/constraints/map.rst.inc
+1Lines changed: 1 addition & 0 deletions
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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.