8000 minor #11616 Documented more missing Timezones features (javiereguiluz) · symfony/symfony-docs@2091a26 · GitHub
[go: up one dir, main page]

Skip to content

Commit 2091a26

Browse files
committed
minor #11616 Documented more missing Timezones features (javiereguiluz)
This PR was squashed before being merged into the 4.3 branch (closes #11616). Discussion ---------- Documented more missing Timezones features Fixes #11499. @ro0NL I need your help. I don't know: * What's the difference between getRawOffset and getGmtOffset * What's the purpose of the timestamp argument defined by both Thanks! Commits ------- b87a85e Documented more missing Timezones features
2 parents 1238553 + b87a85e commit 2091a26

File tree

1 file changed

+49
-2
lines changed

1 file changed

+49
-2
lines changed

components/intl.rst

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -247,7 +247,8 @@ You can also check if a given currency code is valid::
247247
Timezones
248248
~~~~~~~~~
249249

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

252253
use Symfony\Component\Intl\Timezones;
253254

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

272-
You can also check if a given timezone ID is valid::
273+
You can also get all the timezones that exist in a given country. The
274+
``forCountryCode()`` method returns one or more timezone IDs, which you can
275+
translate into any locale with the ``getName()`` method shown earlier::
276+
277+
// unlike language codes, country codes are always uppercase (CL = Chile)
278+
$timezones = Timezones::forCountryCode('CL');
279+
// => ['America/Punta_Arenas', 'America/Santiago', 'Pacific/Easter']
280+
281+
The reverse lookup is also possible thanks to the ``getCountryCode()`` method,
282+
which returns the code of the country where the given timezone ID belongs to::
283+
284+
$countryCode = Timezones::getCountryCode('America/Vancouver')
285+
// => $countryCode = 'CA' (CA = Canada)
286+
287+
The `UTC/GMT time offsets`_ of all timezones are provided by ``getRawOffset()``
288+
(which returns an integer representing the offset in seconds) and
289+
``getGmtOffset()`` (which returns a string representation of the offset to
290+
display it to users)::
291+
292+
$offset = Timezones::getRawOffset('Etc/UTC'); // $offset = 0
293+
$offset = Timezones::getRawOffset('America/Buenos_Aires'); // $offset = -10800
294+
$offset = Timezones::getRawOffset('Asia/Katmandu'); // $offset = 20700
295+
296+
$offset = Timezones::getGmtOffset('Etc/UTC'); // $offset = 'GMT+00:00'
297+
$offset = Timezones::getGmtOffset('America/Buenos_Aires'); // $offset = 'GMT-03:00'
298+
$offset = Timezones::getGmtOffset('Asia/Katmandu'); // $offset = 'GMT+05:45'
299+
300+
The timezone offset can vary in time because of the `daylight saving time (DST)`_
301+
practice. By default these methods use the ``time()`` PHP function to get the
302+
current timezone offset value, but you can pass a timestamp as their second
303+
arguments to get the offset at any given point in time::
304+
305+
// In 2019, the DST period in Madrid (Spain) went from March 31 to October 27
306+
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('March 31, 2019')); // $offset = 3600
307+
$offset = Timezones::getRawOffset('Europe/Madrid', strtotime('April 1, 2019')); // $offset = 7200
308+
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 27, 2019')); // $offset = 'GMT+02:00'
309+
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019')); // $offset = 'GMT+01:00'
310+
311+
The string representation of the GMT offset can vary depending on the locale, so
312+
you can pass the locale as the third optional argument::
313+
314+
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'ar')); // $offset = 'غرينتش+01:00'
315+
$offset = Timezones::getGmtOffset('Europe/Madrid', strtotime('October 28, 2019'), 'dz')); // $offset = 'ཇི་ཨེམ་ཏི་+01:00'
316+
317+
Finally, you can also check if a given timezone ID is valid::
273318

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

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

0 commit comments

Comments
 (0)
0