8000 Documented more missing Timezones features by javiereguiluz · Pull Request #11616 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Documented more missing Timezones features #11616

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

Closed
wants to merge 4 commits into from
Closed

Documented more missing Timezones features #11616

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4c73827
Documented more missing Timezones features
javiereguiluz May 28, 2019
d65c84d
Finished the docs
javiereguiluz May 29, 2019
94d6158
Documented the third parameter of GmtOffset()
javiereguiluz May 29, 2019
b69f19b
-
javiereguiluz May 29, 2019
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
51 changes: 49 additions & 2 deletions components/intl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,7 +247,8 @@ You can also check if a given currency code is valid::
Timezones
~~~~~~~~~

The ``Timezones`` class provides access to the name and values of all timezones::
The ``Timezones`` class provides several utilities related to timezones. First,
you can get the name and values of all timezones in all languages::

use Symfony\Component\Intl\Timezones;

Expand All @@ -269,7 +270,51 @@ which defaults to the current default locale::
$timezone = Timezones::getName('Africa/Nairobi', 'de');
// => 'Ostafrikanische Zeit (Nairobi)'

You can also check if a given timezone ID is valid::
You can also get all the timezones that exist in a given country. The
``forCountryCode()`` method returns one or more timezone IDs, which you can
translate into any locale with the ``getName()`` method shown earlier::

// unlike language codes, country codes are always uppercase (CL = Chile)
$timezones = Timezones::forCountryCode('CL');
// => ['America/Punta_Arenas', 'America/Santiago', 'Pacific/Easter']

The reverse lookup is also possible thanks to the ``getCountryCode()`` method,
which returns the code of the country where the given timezone ID belongs to::

$countryCode = Timezones::getCountryCode('America/Vancouver')
// => $countryCode = 'CA' (CA = Canada)

The `UTC/GMT time offsets`_ of all timezones are provided by ``getRawOffset()``
(which returns an integer representing the offset in seconds) and
``getGmtOffset()`` (which returns a string representation of the offset to
display it to users)::

$offset = Timezones::getRawOffset('Etc/UTC'); // $offset = 0
$offset = Timezones::getRawOffset('America/Buenos_Aires'); // $offset = -10800
$offset = Timezones::getRawOffset('Asia/Katmandu'); // $offset = 20700

$offset = Timezones::getGmtOffset('Etc/UTC'); // $offset = 'GMT+00:00'
$offset = Timezones::getGmtOffset('America/Buenos_Aires'); // $offset = 'GMT-03:00'
$offset = Timezones::getGmtOffset('Asia/Katmandu'); // $offset = 'GMT+05:45'

The timezone offset can vary in time because of the `daylight saving time (DST)`_
practice. By default these methods use the ``time()`` PHP function to get the
current timezone offset value, but you can pass a timestamp as their second
arguments to get the offset at any given point in time::

// In 2019, the DST period in Madrid (Spain) went from March 31 to October 27
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('March 31, 2019')); // $offset = 3600
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('April 1, 2019')); // $offset = 7200
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 27, 2019')); // $offset = 'GMT+02:00'
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019')); // $offset = 'GMT+01:00'

The string representation of the GMT offset can vary depending on the locale, so
you can pass the locale as the third optional argument::

$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'ar')); // $offset = 'غرينتش+01:00'
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'dz')); // $offset = 'ཇི་ཨེམ་ཏི་+01:00'

Finally, you can also check if a given timezone ID is valid::

$isValidTimezone = Timezones::exists($timezoneId);

Expand Down Expand Up @@ -297,3 +342,5 @@ Learn more
.. _ICU library: http://site.icu-project.org/
.. _`Unicode ISO 15924 Registry`: https://www.unicode.org/iso15924/iso15924-codes.html
.. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
.. _`UTC/GMT time offsets`: https://en.wikipedia.org/wiki/List_of_UTC_time_offsets
.. _`daylight saving time (DST)`: https://en.wikipedia.org/wiki/Daylight_saving_time
0