From b0b149882557356a8f8b391640b7fd262a2addf8 Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 16:35:42 +0200 Subject: [PATCH 01/10] [Validator] add documentation for the new `Timezone` constraint. --- reference/constraints.rst | 2 + reference/constraints/Timezone.rst | 127 +++++++++++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 reference/constraints/Timezone.rst diff --git a/reference/constraints.rst b/reference/constraints.rst index 9cbe8bcccf9..b0c645cd53b 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -42,6 +42,8 @@ Validation Constraints Reference constraints/DateTime constraints/Time + constraints/Timezone + constraints/Choice constraints/Collection constraints/Count diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst new file mode 100644 index 00000000000..403c5861a6a --- /dev/null +++ b/reference/constraints/Timezone.rst @@ -0,0 +1,127 @@ +Timezone +======== + +Validates that a value is a valid timezone identifier (ie. ``Europe/Paris``). + +========== =================================================================== +Applies to :ref:`property or method ` +Options - `groups`_ + - `message`_ + - `payload`_ +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 (ie. `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 + * @var string A timezone identifier + */ + 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 Event + { + /** + * @var string A timezone identifier + */ + protected $timezone; + + public static function loadValidatorMetadata(ClassMetadata $metadata) + { + $metadata->addPropertyConstraint('startsAt', 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 time.`` + +This message is shown if the underlying data is not a valid time. + +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 +~~~~~~~~~~~ + +**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. + +Value must be a valid `ISO 3166-1 alpha-2` country code (ie. `BE`). + +.. _DateTimeZone: https://www.php.net/datetimezone From 135c5ffed3ccccaaf391a937ba30f451a4af1403 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 6 Apr 2019 16:49:58 +0200 Subject: [PATCH 02/10] Minor fixes --- reference/constraints/Timezone.rst | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 403c5861a6a..2997d343a41 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -1,7 +1,7 @@ Timezone ======== -Validates that a value is a valid timezone identifier (ie. ``Europe/Paris``). +Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``). ========== =================================================================== Applies to :ref:`property or method ` @@ -15,8 +15,8 @@ Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidato 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`): +Suppose you have a ``UserSettings`` class, with a ``timezone`` field that is a +string meant to contain a timezone identifier (ie. ``America/New_York``): .. configuration-block:: @@ -31,7 +31,6 @@ meant to contain a timezone identifier (ie. `America/New_York`): { /** * @Assert\Timezone - * @var string A timezone identifier */ protected $timezone; } @@ -69,9 +68,6 @@ meant to contain a timezone identifier (ie. `America/New_York`): class Event { - /** - * @var string A timezone identifier - */ protected $timezone; public static function loadValidatorMetadata(ClassMetadata $metadata) @@ -90,9 +86,9 @@ Options message ~~~~~~~ -**type**: ``string`` **default**: ``This value is not a valid time.`` +**type**: ``string`` **default**: ``This value is not a valid timezone.`` -This message is shown if the underlying data is not a valid time. +This message is shown if the underlying data is not a valid timezone identifier. You can use the following parameters in this message: @@ -107,7 +103,7 @@ Parameter Description zone ~~~~ -**type**: ``string`` **default**: ``\DateTimeZone::ALL.`` +**type**: ``string`` **default**: ``\DateTimeZone::ALL`` The geographical zone in which to validate the timezone identifier. @@ -122,6 +118,7 @@ This option must be used only when the ``zone`` option value equals ``\DateTimeZ The ``countryCode`` option enables to validate the timezone identifier is supported by the country code. -Value must be a valid `ISO 3166-1 alpha-2` country code (ie. `BE`). +Value must be a valid `ISO 3166-1 alpha-2`_ country code (e.g. ``BE``). -.. _DateTimeZone: https://www.php.net/datetimezone +.. _`DateTimeZone`: https://www.php.net/datetimezone +.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 From ac6282fa3633b7c96a92b9d1b20fefbe048f6e64 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 6 Apr 2019 17:02:43 +0200 Subject: [PATCH 03/10] Listed the geographical zones defined by PHP --- reference/constraints/Timezone.rst | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 2997d343a41..995f278acb1 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -105,20 +105,33 @@ 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. +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. countryCode ~~~~~~~~~~~ **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. +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. -Value must be a valid `ISO 3166-1 alpha-2`_ country code (e.g. ``BE``). +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 From d564218d4811df9a47d91f17063c1248cd5cfdda Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 6 Apr 2019 17:03:36 +0200 Subject: [PATCH 04/10] Minor fixes --- reference/constraints/Timezone.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 995f278acb1..7a0dcb27ffb 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -16,7 +16,7 @@ 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``): +string meant to contain a timezone identifier (e.g. ``America/New_York``): .. configuration-block:: @@ -72,7 +72,7 @@ string meant to contain a timezone identifier (ie. ``America/New_York``): public static function loadValidatorMetadata(ClassMetadata $metadata) { - $metadata->addPropertyConstraint('startsAt', new Assert\Timezone()); + $metadata->addPropertyConstraint('timezone', new Assert\Timezone()); } } From b37bc7855a54e2dbeeef9e722ade7760d4dab7f3 Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:33:57 +0200 Subject: [PATCH 05/10] Minor fixes --- reference/constraints/Timezone.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 7a0dcb27ffb..8e61a9ad3c4 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -3,14 +3,14 @@ Timezone Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``). -========== =================================================================== +========== ====================================================================== Applies to :ref:`property or method ` Options - `groups`_ - `message`_ - `payload`_ Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone` Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator` -========== =================================================================== +========== ====================================================================== Basic Usage ----------- @@ -66,7 +66,7 @@ string meant to contain a timezone identifier (e.g. ``America/New_York``): use Symfony\Component\Validator\Mapping\ClassMetadata; use Symfony\Component\Validator\Constraints as Assert; - class Event + class UserSettings { protected $timezone; From c5681bf05e0510d2aea1b13b9cc4ff195b55e05e Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:38:56 +0200 Subject: [PATCH 06/10] Add more explanations --- reference/constraints/Timezone.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 8e61a9ad3c4..a782242ef90 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -119,10 +119,15 @@ identifiers to the ones that belong to that geographical zone: * ``\DateTimeZone::INDIAN`` * ``\DateTimeZone::PACIFIC`` -The special ``\DateTimeZone::ALL`` zone accepts any timezone. +The special ``\DateTimeZone::ALL`` zone accepts any timezone excluding deprecated timezones. -countryCode -~~~~~~~~~~~ +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 ``country_code`` option. + +country_code +~~~~~~~~~~~~ **type**: ``string`` **default**: ``null`` From 9cbeb75f5763420160044e8e8b0de4d93d551050 Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:40:51 +0200 Subject: [PATCH 07/10] Fixes options list table --- reference/constraints/Timezone.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index a782242ef90..0ffa8c5740f 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -8,6 +8,8 @@ Applies to :ref:`property or method ` Options - `groups`_ - `message`_ - `payload`_ + - `zone`_ + - `country_code`_ Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone` Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator` ========== ====================================================================== From ec7bd4065b5a884014e681f296a7a64e9b16969a Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:43:51 +0200 Subject: [PATCH 08/10] Revert country_code to countryCode --- reference/constraints/Timezone.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 0ffa8c5740f..8e237346404 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -9,7 +9,7 @@ Options - `groups`_ - `message`_ - `payload`_ - `zone`_ - - `country_code`_ + - `countryCode`_ Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone` Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator` ========== ====================================================================== @@ -128,8 +128,8 @@ The special ``\DateTimeZone::ALL_WITH_BC`` zone accepts any timezone including d The special ``\DateTimeZone::PER_COUNTRY`` zone limits the timezones to a certain country. This zone value must be used in combination with the ``country_code`` option. -country_code -~~~~~~~~~~~~ +countryCode +~~~~~~~~~~~ **type**: ``string`` **default**: ``null`` From 5ec9159cd32a19c329bad7de07cee7d9b019ed44 Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:49:54 +0200 Subject: [PATCH 09/10] Fix option --- reference/constraints/Timezone.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/constraints/Timezone.rst b/reference/constraints/Timezone.rst index 8e237346404..cbbf9eb3c72 100644 --- a/reference/constraints/Timezone.rst +++ b/reference/constraints/Timezone.rst @@ -126,7 +126,7 @@ The special ``\DateTimeZone::ALL`` zone accepts any timezone excluding deprecate 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 ``country_code`` option. +value must be used in combination with the ``countryCode`` option. countryCode ~~~~~~~~~~~ From 8e33d4721e32e56955b3499e7e13c28b007a891b Mon Sep 17 00:00:00 2001 From: Hugo Hamon Date: Sat, 6 Apr 2019 17:57:05 +0200 Subject: [PATCH 10/10] Fixes classification --- reference/constraints.rst | 3 +-- reference/constraints/map.rst.inc | 1 + 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/constraints.rst b/reference/constraints.rst index b0c645cd53b..7eb0b3a5ad8 100644 --- a/reference/constraints.rst +++ b/reference/constraints.rst @@ -42,8 +42,6 @@ Validation Constraints Reference constraints/DateTime constraints/Time - constraints/Timezone - constraints/Choice constraints/Collection constraints/Count @@ -51,6 +49,7 @@ Validation Constraints Reference constraints/Language constraints/Locale constraints/Country + constraints/Timezone constraints/File constraints/Image 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 ~~~~~~~~~~~~~~~~