Merge branch '7.4' into 8.0

* 7.4:
  Minor tweaks
  [Intl] Document `isValidInCountry()`, `isValidInAnyCountry()`, `forCountry()`

Author: javiereguiluz

components/intl.rst

@@ -307,6 +307,52 @@ to catching the exception, you can also check if a given currency code is valid:
 
     $isValidCurrency = Currencies::exists($currencyCode);
 
+By default, the previous currency methods return all currencies, including
+those that are no longer in use. Symfony provides several methods to filter
+currencies so you can work only with those that are actually valid and in use
+for a given country.
+
+These methods use ICU metadata (``tender``, ``from`` and ``to`` dates) to
+determine whether a currency is `legal tender`_ and/or active at a specific
+point in time::
+
+    use Symfony\Component\Intl\Currencies;
+
+    // get the list of today's legal and active currencies for a country
+    $codes = Currencies::forCountry('FR');
+    // ['EUR']
+
+    // include non-legal currencies too, and check them at a given date
+    $codesAll = Currencies::forCountry(
+        'ES',
+        legalTender: null,
+        active: true,
+        date: new \DateTimeImmutable('1982-01-01')
+    );
+    // ['ESP', 'ESB']
+
+    // check if a currency is valid today for a country
+    $isOk = Currencies::isValidInCountry('CH', 'CHF');
+    // true
+
+    // check if a currency is valid in any country on a specific date
+    $isGlobal = Currencies::isValidInAnyCountry(
+        'USD',
+        legalTender: true,
+        active: true,
+        date: new \DateTimeImmutable('2005-01-01')
+    );
+    // true
+
+Note that some currencies (especially non-legal-tender ones) do not have validity
+ranges defined. In such cases, a ``RuntimeException`` will be thrown. In addition,
+an ``InvalidArgumentException`` will be thrown if the specified currency is invalid.
+
+.. versionadded:: 7.4
+
+    The ``forCountry()``, ``isValidInCountry()`` and ``isValidInAnyCountry()``
+    methods were introduced in Symfony 7.4.
+
 .. _component-intl-timezones:
 
 Timezones
@@ -425,6 +471,7 @@ Learn more
 .. _`ISO 3166-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 .. _`ISO 3166-1 alpha-3`: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3
 .. _`ISO 3166-1 numeric`: https://en.wikipedia.org/wiki/ISO_3166-1_numeric
+.. _`legal tender`: https://en.wikipedia.org/wiki/Legal_tender
 .. _`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
 .. _`ISO 639-1 alpha-2`: https://en.wikipedia.org/wiki/ISO_639-1