8000 [Validator] add documentation for the new `Timezone` constraint. · symfony/symfony-docs@b0b1498 · GitHub
[go: up one dir, main page]
Skip to content

Commit b0b1498

Browse files
hhamonhhamon
committed
[Validator] add documentation for the new Timezone constraint.
1 parent 3f83193 commit b0b1498

File tree

2 files changed

+129
-0
lines changed

2 files changed

+129
-0
lines changed

‎reference/constraints.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,8 @@ Validation Constraints Reference
4242
constraints/DateTime
4343
constraints/Time
4444

45+
constraints/Timezone
46+
4547
constraints/Choice
4648
constraints/Collection
4749
constraints/Count

‎reference/constraints/Timezone.rst

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
Timezone
2+
========
3+
4+
Validates that a value is a valid timezone identifier (ie. ``Europe/Paris``).
5+
6+
========== ===================================================================
7+
Applies to :ref:`property or method <validation-property-target>`
8+
Options - `groups`_
9+
- `message`_
10+
- `payload`_
11+
Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone`
12+
Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator`
13+
========== ===================================================================
14+
15+
Basic Usage
16+
-----------
17+
18+
Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a string
19+
meant to contain a timezone identifier (ie. `America/New_York`):
20+
21+
.. configuration-block::
22+
23+
.. code-block:: php-annotations
24+
25+
// src/Entity/UserSettings.php
26+
namespace App\Entity;
27+
28+
use Symfony\Component\Validator\Constraints as Assert;
29+
30+
class UserSettings
31+
{
32+
/**
33+
* @Assert\Timezone
34+
* @var string A timezone identifier
35+
*/
36+
protected $timezone;
37+
}
38+
39+
.. code-block:: yaml
40+
41+
# config/validator/validation.yaml
42+
App\Entity\UserSettings:
43+
properties:
44+
timezone:
45+
- Timezone: ~
46+
47+
.. code-block:: xml
48+
49+
<!-- config/validator/validation.xml -->
50+
<?xml version="1.0" encoding="UTF-8" ?>
51+
<constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping"
52+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
53+
xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd">
54+
55+
<class name="App\Entity\UserSettings">
56+
<property name="timezone">
57+
<constraint name="Timezone"/>
58+
</property>
59+
</class>
60+
</constraint-mapping>
61+
62+
.. code-block:: php
63+
64+
// src/Entity/UserSettings.php
65+
namespace App\Entity;
66+
67+
use Symfony\Component\Validator\Mapping\ClassMetadata;
68+
use Symfony\Component\Validator\Constraints as Assert;
69+
70+
class Event
71+
{
72+
/**
73+
* @var string A timezone identifier
74+
*/
75+
protected $timezone;
76+
77+
public static function loadValidatorMetadata(ClassMetadata $metadata)
78+
{
79+
$metadata->addPropertyConstraint('startsAt', new Assert\Timezone());
80+
}
81+
}
82+
83+
.. include:: /reference/constraints/_empty-values-are-valid.rst.inc
84+
85+
Options
86+
-------
87+
88+
.. include:: /reference/constraints/_groups-option.rst.inc
89+
90+
message
91+
~~~~~~~
92+
93+
**type**: ``string`` **default**: ``This value is not a valid time.``
94+
95+
This message is shown if the underlying data is not a valid time.
96+
97+
You can use the following parameters in this message:
98+
99+
=============== ==============================================================
100+
Parameter Description
101+
=============== ==============================================================
102+
``{{ value }}`` The current (invalid) value
103+
=============== ==============================================================
104+
105+
.. include:: /reference/constraints/_payload-option.rst.inc
106+
107+
zone
108+
~~~~
109+
110+
**type**: ``string`` **default**: ``\DateTimeZone::ALL.``
111+
112+
The geographical zone in which to validate the timezone identifier.
113+
114+
Value must be any of the `DateTimeZone`_ class constants values.
115+
116+
countryCode
117+
~~~~~~~~~~~
118+
119+
**type**: ``string`` **default**: ``null``
120+
121+
This option must be used only when the ``zone`` option value equals ``\DateTimeZone::PER_COUNTRY``.
122+
123+
The ``countryCode`` option enables to validate the timezone identifier is supported by the country code.
124+
125+
Value must be a valid `ISO 3166-1 alpha-2` country code (ie. `BE`).
126+
127+
.. _DateTimeZone: https://www.php.net/datetimezone

0 commit comments

Comments
 (0)
0