8000 [Validation] Documented the intlCompatible option in Timezone constraint by javiereguiluz · Pull Request #12057 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

[Validation] Documented the intlCompatible option in Timezone constraint #12057

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 31, 2019
Merged

[Validation] Documented the intlCompatible option in Timezone constraint #12057

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions components/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,8 @@ to catching the exception, you can also check if a given currency code is valid:

The ``Currencies`` class was introduced in Symfony 4.3.

.. _component-intl-timezones:

Timezones
~~~~~~~~~

Expand Down
46 changes: 31 additions & 15 deletions reference/constraints/Timezone.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@ Validates that a value is a valid timezone identifier (e.g. ``Europe/Paris``).

========== ======================================================================
Applies to :ref:`property or method <validation-property-target>`
Options - `groups`_
Options - `countryCode`_
- `groups`_
- `intlCompatible`_
- `message`_
- `payload`_
- `zone`_
- `countryCode`_
Class :class:`Symfony\\Component\\Validator\\Constraints\\Timezone`
Validator :class:`Symfony\\Component\\Validator\\Constraints\\TimezoneValidator`
========== ======================================================================
Expand All @@ -22,7 +23,7 @@ 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``):
string which contains any of the `PHP timezone identifiers`_ (e.g. ``America/New_York``):

.. configuration-block::

Expand Down Expand Up @@ -85,8 +86,34 @@ string meant to contain a timezone identifier (e.g. ``America/New_York``):
Options
-------

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).

.. include:: /reference/constraints/_groups-option.rst.inc

intlCompatible
~~~~~~~~~~~~~~

**type**: ``boolean`` **default**: ``false``

This constraint considers valid both the `PHP timezone identifiers`_ and the
:ref:`ICU timezones <component-intl-timezones>` provided by Symfony's
:doc:`Intl component </components/intl>`

However, the timezones provided by the Intl component can be different from the
timezones provided by PHP's Intl extension (because they use different ICU
versions). If this option is set to ``true``, this constraint only considers
valid the values created with the PHP ``\IntlTimeZone::createTimeZone()`` method.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so this option is really confusing i guess :)

both PHP+SF intl timezones are considered valid, regardless of this option. The SF intl timezones are only considered valid if the component is available.

However, because of 2 possible different versions of ICU (the version used to compile SF intl vs. the version used by ext-intl compiled in PHP) an edge case might occur:

if a timezone is considered valid by SF intl (based on the latest ICU version in SF), it might be unknown when using it in PHP (e.g. $model = \IntlTimeZone::createTimeZone($tzValidatedBySfIntl);) due a different ICU version PHP is compiled with.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so the TLDR of this option is, it ensures you can use the timezone ID with IntlTimeZone::createTimeZone($tz) :) and you'll never get Etc/Unknown

Copy link
Member Author
@javiereguiluz javiereguiluz Jul 30, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, the name of this option is super confusing. The name tells me that true/false enables/disables support for Intl timezones.

But you say that Intl is unconditionally enabled. The, when should I set this option to true/false and what does it do? Thanks.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

did you see the last comment?

"intl" can mean 2 things: SF Intl or PHP Intl (https://www.php.net/manual/en/book.intl.php). Here it means the latter

We have no control of the ICU version used by PHP, hence this option to ensure a valid timezone ID when using \IntlTimeZone for a model (this class is provided by PHP Intl)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so TLDR :D

set this option to true if you're modelling the validated timezone ID with \IntlTimeZone, or aim to do so in the future and you want to prepare your data already

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Phewwww ... I think I finally understood this! Please review the latest reword ... and thanks for your patience 😅

message
~~~~~~~

Expand Down Expand Up @@ -131,17 +158,6 @@ In addition, there are some special zone values:
* ``\DateTimeZone::PER_COUNTRY`` restricts the valid timezones to a certain
country (which is defined using 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).

.. _`PHP timezone identifiers`: https://www.php.net/manual/en/timezones.php
.. _`DateTimeZone`: https://www.php.net/datetimezone
.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
0