diff --git a/reference/constraints.rst b/reference/constraints.rst index 9cbe8bcccf9..7eb0b3a5ad8 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -49,6 +49,7 @@ Validation Constraints Reference constraints/Language constraints/Locale constraints/Country + constraints/Timezone constraints/File constraints/Image diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst new file mode 100644 index 00000000000..cbbf9eb3c72 --- /dev/null +++ b/reference/constraints/Timezone.rst @@ -0,0 +1,144 @@ +Timezone +======== + +Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``). + +========== ====================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ + - `zone`_ + - `countryCode`_ +Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone` +Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator` +========== ====================================================================== + +Basic Usage +----------- + +Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a +string meant to contain a timezone identifier (e.g. ``America/New_York``): + +.. 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 + + + + + + + + + + + + + .. code-block:: php + + // src/Entity/UserSettings.php + namespace App\Entity; + + use Symfony\Component\Validator\Mapping\ClassMetadata; + use Symfony\Component\Validator\Constraints as Assert; + + class UserSettings + { + protected $timezone; + + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('timezone', new Assert\Timezone()); + } + } + +.. 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`` + +Set this option to any of the following constants to restrict the valid timezone +identifiers to the ones that belong to that geographical zone: + +* ``\DateTimeZone::AFRICA`` +* ``\DateTimeZone::AMERICA`` +* ``\DateTimeZone::ANTARCTICA`` +* ``\DateTimeZone::ARCTIC`` +* ``\DateTimeZone::ASIA`` +* ``\DateTimeZone::ATLANTIC`` +* ``\DateTimeZone::AUSTRALIA`` +* ``\DateTimeZone::EUROPE`` +* ``\DateTimeZone::INDIAN`` +* ``\DateTimeZone::PACIFIC`` + +The special ``\DateTimeZone::ALL`` zone accepts any timezone excluding deprecated timezones. + +The special ``\DateTimeZone::ALL_WITH_BC`` zone accepts any timezone including deprecated timezones. + +The special ``\DateTimeZone::PER_COUNTRY`` zone limits the timezones to a certain country. This zone +value must be used in combination with the ``countryCode`` option. + +countryCode +~~~~~~~~~~~ + +**type**: ``string`` **default**: ``null`` + +If the ``zone`` option is set to ``\DateTimeZone::PER_COUNTRY``, this option +restricts the valid timezone identifiers to the ones that belong to the given +country. + +The value of this option must be a valid `ISO 3166-1 alpha-2`_ country code +(e.g. ``CN`` for China). + +.. _`DateTimeZone`: https://www.php.net/datetimezone +.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 diff --git a/reference/constraints/map.rst.inc b/reference/constraints/map.rst.inc index f0a5696648d..adbc55017c6 100644 --- a/reference/constraints/map.rst.inc +++ b/reference/constraints/map.rst.inc @@ -60,6 +60,7 @@ Choice Constraints * :doc:`Language ` * :doc:`Locale ` * :doc:`Country ` +* :doc:`Timezone ` File Constraints ~~~~~~~~~~~~~~~~