The Intl Component
Edit this pageWarning: You are browsing the documentation for Symfony 2.3, which is no longer maintained.
Read the updated version of this page for Symfony 6.3 (the current stable version).
The Intl Component
A PHP replacement layer for the C intl extension that also provides access to the localization data of the ICU library.
2.3
The Intl component was introduced in Symfony 2.3. In earlier versions of Symfony, you should use the Locale component instead.
Caution
The replacement layer is limited to the locale "en". If you want to use other locales, you should install the intl extension instead.
Installation
You can install the component in two different ways:
- Install it via Composer (
symfony/intl
on Packagist); - Using the official Git repository (https://github.com/symfony/intl).
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.
If you don't use Composer but the Symfony ClassLoader component, you need to expose them manually by adding the following lines to your autoload code:
1 2 3 4 5
if (!function_exists('intl_is_failure')) {
require '/path/to/Icu/Resources/stubs/functions.php';
$loader->registerPrefixFallback('/path/to/Icu/Resources/stubs');
}
ICU and Deployment Problems
Note
These deployment problems only affect the following Symfony versions: 2.3.0 to 2.3.20 versions, any 2.4.x version and 2.5.0 to 2.5.5 versions.
The intl extension internally uses the ICU library to obtain localization data such as number formats in different languages, country names and more. To make this data accessible to userland PHP libraries, Symfony ships a copy in the Icu component.
Depending on the ICU version compiled with your intl extension, a matching version of that component needs to be installed. It sounds complicated, but usually Composer does this for you automatically:
- 1.0.*: when the intl extension is not available
- 1.1.*: when intl is compiled with ICU 4.0 or higher
- 1.2.*: when intl is compiled with ICU 4.4 or higher
These versions are important when you deploy your application to a server with a lower ICU version than your development machines, because deployment will fail if:
- the development machines are compiled with ICU 4.4 or higher, but the server is compiled with a lower ICU version than 4.4;
- the intl extension is available on the development machines but not on the server.
For example, consider that your development machines ship ICU 4.8 and the server
ICU 4.2. When you run composer update
on the development machine, version
1.2.* of the Icu component will be installed. But after deploying the
application, composer install
will fail with the following error:
1 2 3 4 5 6 7 8 9
$ composer install
Loading composer repositories with package information
Installing dependencies from lock file
Your requirements could not be resolved to an installable set of packages.
Problem 1
- symfony/icu 1.2.x requires lib-icu >=4.4 -> the requested linked
library icu has the wrong version installed or is missing from your
system, make sure to have the extension providing it.
The error tells you that the requested version of the Icu component, version 1.2, is not compatible with PHP's ICU version 4.2.
One solution to this problem is to run composer update
instead of
composer install
. It is highly recommended not to do this. The
update
command will install the latest versions of each Composer dependency
to your production server and potentially break the application.
A better solution is to fix your composer.json to the version required by the production server. First, determine the ICU version on the server:
1 2
$ php -i | grep ICU
ICU version => 4.2.1
Then fix the Icu component in your composer.json
file to a matching version:
1 2 3 4 5
{
"require": {
"symfony/icu": "1.1.*"
}
}
Set the version to
- "1.0.*" if the server does not have the intl extension installed;
- "1.1.*" if the server is compiled with ICU 4.2 or lower.
Finally, run composer update symfony/icu
on your development machine, test
extensively and deploy again. The installation of the dependencies will now
succeed.
Writing and Reading Resource Bundles
The ResourceBundle class is not currently supported by this component. Instead, it includes a set of readers and writers for reading and writing arrays (or array-like objects) from/to resource bundle files. The following classes are supported:
- TextBundleWriter
- PhpBundleWriter
- BinaryBundleReader
- PhpBundleReader
- BufferedBundleReader
- StructuredBundleReader
Continue reading if you are interested in how to use these classes. Otherwise skip this section and jump to Accessing ICU Data.
TextBundleWriter
The TextBundleWriter writes an array or an array-like object to a plain-text resource bundle. The resulting .txt file can be converted to a binary .res file with the BundleCompiler class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14
use Symfony\Component\Intl\ResourceBundle\Writer\TextBundleWriter;
use Symfony\Component\Intl\ResourceBundle\Compiler\BundleCompiler;
$writer = new TextBundleWriter();
$writer->write('/path/to/bundle', 'en', array(
'Data' => array(
'entry1',
'entry2',
// ...
),
));
$compiler = new BundleCompiler();
$compiler->compile('/path/to/bundle', '/path/to/binary/bundle');
The command "genrb" must be available for the BundleCompiler to work. If the command is located in a non-standard location, you can pass its path to the BundleCompiler constructor.
PhpBundleWriter
The PhpBundleWriter writes an array or an array-like object to a .php resource bundle:
1 2 3 4 5 6 7 8 9 10
use Symfony\Component\Intl\ResourceBundle\Writer\PhpBundleWriter;
$writer = new PhpBundleWriter();
$writer->write('/path/to/bundle', 'en', array(
'Data' => array(
'entry1',
'entry2',
// ...
),
));
BinaryBundleReader
The BinaryBundleReader reads binary resource bundle files and returns an array or an array-like object. This class currently only works with the intl extension installed:
1 2 3 4 5 6
use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
$reader = new BinaryBundleReader();
$data = $reader->read('/path/to/bundle', 'en');
var_dump($data['Data']['entry1']);
PhpBundleReader
The PhpBundleReader reads resource bundles from .php files and returns an array or an array-like object:
1 2 3 4 5 6
use Symfony\Component\Intl\ResourceBundle\Reader\PhpBundleReader;
$reader = new PhpBundleReader();
$data = $reader->read('/path/to/bundle', 'en');
var_dump($data['Data']['entry1']);
BufferedBundleReader
The BufferedBundleReader wraps another reader, but keeps the last N reads in a buffer, where N is a buffer size passed to the constructor:
1 2 3 4 5 6 7 8 9 10 11 12 13
use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
use Symfony\Component\Intl\ResourceBundle\Reader\BufferedBundleReader;
$reader = new BufferedBundleReader(new BinaryBundleReader(), 10);
// actually reads the file
$data = $reader->read('/path/to/bundle', 'en');
// returns data from the buffer
$data = $reader->read('/path/to/bundle', 'en');
// actually reads the file
$data = $reader->read('/path/to/bundle', 'fr');
StructuredBundleReader
The StructuredBundleReader
wraps another reader and offers a
readEntry()
method for reading an entry of the resource bundle without having to worry
whether array keys are set or not. If a path cannot be resolved, null
is
returned:
1 2 3 4 5 6 7 8 9 10 11 12
use Symfony\Component\Intl\ResourceBundle\Reader\BinaryBundleReader;
use Symfony\Component\Intl\ResourceBundle\Reader\StructuredBundleReader;
$reader = new StructuredBundleReader(new BinaryBundleReader());
$data = $reader->read('/path/to/bundle', 'en');
// Produces an error if the key "Data" does not exist
var_dump($data['Data']['entry1']);
// Returns null if the key "Data" does not exist
var_dump($reader->readEntry('/path/to/bundle', 'en', array('Data', 'entry1')));
Additionally, the
readEntry()
method resolves fallback locales. For example, the fallback locale of "en_GB" is
"en". For single-valued entries (strings, numbers etc.), the entry will be read
from the fallback locale if it cannot be found in the more specific locale. For
multi-valued entries (arrays), the values of the more specific and the fallback
locale will be merged. In order to suppress this behavior, the last parameter
$fallback
can be set to false
:
1 2 3 4 5 6
var_dump($reader->readEntry(
'/path/to/bundle',
'en',
array('Data', 'entry1'),
false
));
Accessing ICU Data
The ICU data is located in several "resource bundles". You can access a PHP wrapper of these bundles through the static Intl class. At the moment, the following data is supported:
Language and Script Names
The translations of language and script names can be found in the language bundle:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
use Symfony\Component\Intl\Intl;
\Locale::setDefault('en');
$languages = Intl::getLanguageBundle()->getLanguageNames();
// => array('ab' => 'Abkhazian', ...)
$language = Intl::getLanguageBundle()->getLanguageName('de');
// => 'German'
$language = Intl::getLanguageBundle()->getLanguageName('de', 'AT');
// => 'Austrian German'
$scripts = Intl::getLanguageBundle()->getScriptNames();
// => array('Arab' => 'Arabic', ...)
$script = Intl::getLanguageBundle()->getScriptName('Hans');
// => 'Simplified'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2
$languages = Intl::getLanguageBundle()->getLanguageNames('de');
// => array('ab' => 'Abchasisch', ...)
Country Names
The translations of country names can be found in the region bundle:
1 2 3 4 5 6 7 8 9
use Symfony\Component\Intl\Intl;
\Locale::setDefault('en');
$countries = Intl::getRegionBundle()->getCountryNames();
// => array('AF' => 'Afghanistan', ...)
$country = Intl::getRegionBundle()->getCountryName('GB');
// => 'United Kingdom'
All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:
1 2
$countries = Intl::getRegionBundle()->getCountryNames('de');
// => array('AF' => 'Afghanistan', ...)
Locales
The translations of locale names can be found in the locale bundle:
1 2 3 4 5 6 7 8 9
use Symfony\Component\Intl\Intl;
\Locale::setDefault('en');
$locales = Intl::getLocaleBundle()->getLocaleNames();
// => array('af' => 'Afrikaans', ...)
$locale = Intl::getLocaleBundle()->getLocaleName('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
$locales = Intl::getLocaleBundle()->getLocaleNames('de');
// => array('af' => 'Afrikaans', ...)
Currencies
The translations of currency names and other currency-related information can be found in the currency bundle:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
use Symfony\Component\Intl\Intl;
\Locale::setDefault('en');
$currencies = Intl::getCurrencyBundle()->getCurrencyNames();
// => array('AFN' => 'Afghan Afghani', ...)
$currency = Intl::getCurrencyBundle()->getCurrencyName('INR');
// => 'Indian Rupee'
$symbol = Intl::getCurrencyBundle()->getCurrencySymbol('INR');
// => '₹'
$fractionDigits = Intl::getCurrencyBundle()->getFractionDigits('INR');
// => 2
$roundingIncrement = Intl::getCurrencyBundle()->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
$currencies = Intl::getCurrencyBundle()->getCurrencyNames('de');
// => array('AFN' => 'Afghanische Afghani', ...)
That's all you need to know for now. Have fun coding!