[Validator] add documentation for the new Timezone constraint.
#11317
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| Timezone | ||
| ======== | ||
|
|
||
| Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``). | ||
|
|
||
| ========== =================================================================== | ||
OskarStark marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| Applies to :ref:`property or method <validation-property-target>` | ||
| Options - `groups`_ | ||
|
There was a problem hiding this comment. @symfony/team-symfony-docs do we use ordered options here and the same order for the explanations? There was a problem hiding this comment. We didn't reorder descriptions for existing docs in the past and only sorted the table of contents to keep the diff maintainable. But here it makes sense to sort from the beginning. There was a problem hiding this comment. What do you mean? Ordering options like:
There was a problem hiding this comment. @xabbuh although you are right ... for the Constraints docs we recently sorted both the list of options and their descriptions. It was a hell to fix all the conflicts, but we did it anyways :) |
||
| - `message`_ | ||
| - `payload`_ | ||
| Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone` | ||
| Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator` | ||
| ========== =================================================================== | ||
OskarStark marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Basic Usage | ||
| ----------- | ||
|
|
||
| Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a | ||
| string meant to contain a timezone identifier (ie. ``America/New_York``): | ||
javiereguiluz marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| .. configuration-block:: | ||
|
|
||
| .. code-block:: php-annotations | ||
|
|
||
| // src/Entity/UserSettings.php | ||
| namespace App\Entity; | ||
|
|
||
| use Symfony\Component\Validator\Constraints as Assert; | ||
|
|
||
| class UserSettings | ||
| { | ||
| /** | ||
| * @Assert\Timezone | ||
| */ | ||
| protected $timezone; | ||
| } | ||
|
|
||
| .. code-block:: yaml | ||
|
|
||
| # config/validator/validation.yaml | ||
| App\Entity\UserSettings: | ||
| properties: | ||
| timezone: | ||
| - Timezone: ~ | ||
|
|
||
| .. code-block:: xml | ||
|
|
||
| <!-- config/validator/validation.xml --> | ||
| <?xml version="1.0" encoding="UTF-8" ?> | ||
| <constraint-mapping xmlns="http://symfony.com/schema/dic/constraint-mapping" | ||
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | ||
| xsi:schemaLocation="http://symfony.com/schema/dic/constraint-mapping https://symfony.com/schema/dic/constraint-mapping/constraint-mapping-1.0.xsd"> | ||
|
|
||
| <class name="App\Entity\UserSettings"> | ||
| <property name="timezone"> | ||
| <constraint name="Timezone"/> | ||
| </property> | ||
| </class> | ||
| </constraint-mapping> | ||
|
|
||
| .. code-block:: php | ||
|
|
||
| // src/Entity/UserSettings.php | ||
| namespace App\Entity; | ||
|
|
||
| use Symfony\Component\Validator\Mapping\ClassMetadata; | ||
| use Symfony\Component\Validator\Constraints as Assert; | ||
|
|
||
| class Event | ||
hhamon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| { | ||
| protected $timezone; | ||
|
There was a problem hiding this comment. If I am correct, this should be removed as it is not added in other constraints |
||
|
|
||
| public static function loadValidatorMetadata(ClassMetadata $metadata) | ||
| { | ||
| $metadata->addPropertyConstraint('startsAt', new Assert\Timezone()); | ||
javiereguiluz marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| } | ||
|
|
||
| .. include:: /reference/constraints/_empty-values-are-valid.rst.inc | ||
|
|
||
| Options | ||
| ------- | ||
|
|
||
| .. include:: /reference/constraints/_groups-option.rst.inc | ||
|
|
||
| message | ||
| ~~~~~~~ | ||
|
|
||
| **type**: ``string`` **default**: ``This value is not a valid timezone.`` | ||
|
|
||
| This message is shown if the underlying data is not a valid timezone identifier. | ||
|
|
||
| You can use the following parameters in this message: | ||
|
|
||
| =============== ============================================================== | ||
| Parameter Description | ||
| =============== ============================================================== | ||
| ``{{ value }}`` The current (invalid) value | ||
| =============== ============================================================== | ||
|
|
||
| .. include:: /reference/constraints/_payload-option.rst.inc | ||
|
|
||
| zone | ||
| ~~~~ | ||
|
|
||
| **type**: ``string`` **default**: ``\DateTimeZone::ALL`` | ||
|
|
||
| The geographical zone in which to validate the timezone identifier. | ||
|
|
||
| Value must be any of the `DateTimeZone`_ class constants values. | ||
|
|
||
| countryCode | ||
hhamon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ~~~~~~~~~~~ | ||
|
|
||
| **type**: ``string`` **default**: ``null`` | ||
|
|
||
| This option must be used only when the ``zone`` option value equals ``\DateTimeZone::PER_COUNTRY``. | ||
|
|
||
| The ``countryCode`` option enables to validate the timezone identifier is supported by the country code. | ||
javiereguiluz marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| Value must be a valid `ISO 3166-1 alpha-2`_ country code (e.g. ``BE``). | ||
|
|
||
| .. _`DateTimeZone`: https://www.php.net/datetimezone | ||
| .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.