@@ -247,7 +247,8 @@ You can also check if a given currency code is valid::
247247Timezones
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