@@ -247,7 +247,8 @@ You can also check if a given currency code is valid::
247
247
Timezones
248
248
~~~~~~~~~
249
249
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::
251
252
252
253
use Symfony\Component\Intl\Timezones;
253
254
@@ -269,7 +270,51 @@ which defaults to the current default locale::
269
270
$timezone = Timezones::getName('Africa/Nairobi', 'de');
270
271
// => 'Ostafrikanische Zeit (Nairobi)'
271
272
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::
273
318
274
319
$isValidTimezone = Timezones::exists($timezoneId);
275
320
@@ -297,3 +342,5 @@ Learn more
297
342
.. _ICU library : http://site.icu-project.org/
298
343
.. _`Unicode ISO 15924 Registry` : https://www.unicode.org/iso15924/iso15924-codes.html
299
344
.. _`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