The Intl Component
Edit this pageWarning: You are browsing the documentation for Symfony 4.3, which is no longer maintained.
Read the updated version of this page for Symfony 6.3 (the current stable version).
The Intl Component
This component provides access to the localization data of the ICU library. It also provides a PHP replacement layer for the C intl extension.
Caution
The replacement layer is limited to the locale "en". If you want to use other locales, you should install the intl extension instead.
See also
This article explains how to use the Intl features as an independent component in any PHP application. Read the Translations article to learn about how to internationalize and manage the user locale in Symfony applications.
Installation
1
$ composer require symfony/intl
Note
If you install this component outside of a Symfony application, you must
require the vendor/autoload.php
file in your code to enable the class
autoloading mechanism provided by Composer. Read
this article for more details.
If you install the component via Composer, the following classes and functions of the intl extension will be automatically provided if the intl extension is not loaded:
- Collator
- IntlDateFormatter
- Locale
- NumberFormatter
- intl_error_name
- intl_is_failure
- intl_get_error_code
- intl_get_error_message
When the intl extension is not available, the following classes are used to replace the intl classes:
Composer automatically exposes these classes in the global namespace.
Accessing ICU Data
This component provides the following ICU data:
Language and Script Names
The Languages
class provides access to the name of all languages
according to the ISO 639-1 alpha-2 list and the ISO 639-2 alpha-3 list:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\Languages;
\Locale::setDefault('en');
$languages = Languages::getNames();
// ('languageCode' => 'languageName')
// => ['ab' => 'Abkhazian', 'ace' => 'Achinese', ...]
$language = Languages::getName('fr');
// => 'French'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2 3 4 5
$languages = Languages::getNames('de');
// => ['ab' => 'Abchasisch', 'ace' => 'Aceh', ...]
$language = Languages::getName('fr', 'de');
// => 'Französisch'
If the given locale doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given language code is valid:
1
$isValidLanguage = Languages::exists($languageCode);
4.3
The Languages
class was introduced in Symfony 4.3.
The Scripts
class provides access to the optional four-letter script code
that can follow the language code according to the Unicode ISO 15924 Registry
(e.g. HANS
in zh_HANS
for simplified Chinese and HANT
in zh_HANT
for traditional Chinese):
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\Scripts;
\Locale::setDefault('en');
$scripts = Scripts::getNames();
// ('scriptCode' => 'scriptName')
// => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]
$script = Scripts::getName('Hans');
// => 'Simplified'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2 3 4 5
$scripts = Scripts::getNames('de');
// => ['Adlm' => 'Adlam', 'Afak' => 'Afaka', ...]
$script = Scripts::getName('Hans', 'de');
// => 'Vereinfacht'
If the given script code doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given script code is valid:
1
$isValidScript = Scripts::exists($scriptCode);
4.3
The Scripts
class was introduced in Symfony 4.3.
Country Names
The Countries
class provides access to the name of all countries according
to the ISO 3166-1 alpha-2 list of officially recognized countries and
territories:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\Countries;
\Locale::setDefault('en');
$countries = Countries::getNames();
// ('countryCode' => 'countryName')
// => ['AF' => 'Afghanistan', 'AX' => 'Åland Islands', ...]
$country = Countries::getName('GB');
// => 'United Kingdom'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2 3 4 5
$countries = Countries::getNames('de');
// => ['AF' => 'Afghanistan', 'EG' => 'Ägypten', ...]
$country = Countries::getName('GB', 'de');
// => 'Vereinigtes Königreich'
If the given country code doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given country code is valid:
1
$isValidCountry = Countries::exists($countryCode);
4.3
The Countries
class was introduced in Symfony 4.3.
Locales
A locale is the combination of a language and a region. For example, "Chinese"
is the language and zh_Hans_MO
is the locale for "Chinese" (language) +
"Simplified" (script) + "Macau SAR China" (region). The Locales
class
provides access to the name of all locales:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\Locales;
\Locale::setDefault('en');
$locales = Locales::getNames();
// ('localeCode' => 'localeName')
// => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]
$locale = Locales::getName('zh_Hans_MO');
// => 'Chinese (Simplified, Macau SAR China)'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2 3 4 5
$locales = Locales::getNames('de');
// => ['af' => 'Afrikaans', 'af_NA' => 'Afrikaans (Namibia)', ...]
$locale = Locales::getName('zh_Hans_MO', 'de');
// => 'Chinesisch (Vereinfacht, Sonderverwaltungsregion Macau)'
If the given locale code doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given locale code is valid:
1
$isValidLocale = Locales::exists($localeCode);
4.3
The Locales
class was introduced in Symfony 4.3.
Currencies
The Currencies
class provides access to the name of all currencies as well
as some of their information (symbol, fraction digits, etc.):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
use Symfony\Component\Intl\Currencies;
\Locale::setDefault('en');
$currencies = Currencies::getNames();
// ('currencyCode' => 'currencyName')
// => ['AFN' => 'Afghan Afghani', 'ALL' => 'Albanian Lek', ...]
$currency = Currencies::getName('INR');
// => 'Indian Rupee'
$symbol = Currencies::getSymbol('INR');
// => '₹'
$fractionDigits = Currencies::getFractionDigits('INR');
// => 2
$roundingIncrement = Currencies::getRoundingIncrement('INR');
// => 0
All methods (except for getFractionDigits()
and getRoundingIncrement()
)
accept the translation locale as the last, optional parameter, which defaults to
the current default locale:
1 2 3 4 5
$currencies = Currencies::getNames('de');
// => ['AFN' => 'Afghanischer Afghani', 'EGP' => 'Ägyptisches Pfund', ...]
$currency = Currencies::getName('INR', 'de');
// => 'Indische Rupie'
If the given currency code doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given currency code is valid:
1
$isValidCurrency = Currencies::exists($currencyCode);
4.3
The Currencies
class was introduced in Symfony 4.3.
Timezones
The Timezones
class provides several utilities related to timezones. First,
you can get the name and values of all timezones in all languages:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\Timezones;
\Locale::setDefault('en');
$timezones = Timezones::getNames();
// ('timezoneID' => 'timezoneValue')
// => ['America/Eirunepe' => 'Acre Time (Eirunepe)', 'America/Rio_Branco' => 'Acre Time (Rio Branco)', ...]
$timezone = Timezones::getName('Africa/Nairobi');
// => 'East Africa Time (Nairobi)'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2 3 4 5
$timezones = Timezones::getNames('de');
// => ['America/Eirunepe' => 'Acre-Zeit (Eirunepe)', 'America/Rio_Branco' => 'Acre-Zeit (Rio Branco)', ...]
$timezone = Timezones::getName('Africa/Nairobi', 'de');
// => 'Ostafrikanische Zeit (Nairobi)'
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:
1 2 3
// 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:
1 2
$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):
1 2 3 4 5 6 7
$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:
1 2 3 4 5
// 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:
1 2
$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'
If the given timezone ID doesn't exist, the methods trigger a MissingResourceException. In addition to catching the exception, you can also check if a given timezone ID is valid:
1
$isValidTimezone = Timezones::exists($timezoneId);
4.3
The Timezones
class was introduced in Symfony 4.3.