symfony
diff --git a/‎components/intl.rst
Lines changed: 49 additions & 2 deletions b/‎components/intl.rst
Lines changed: 49 additions & 2 deletions
@@ -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;
 
@@ -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);
 
@@ -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