The Intl Component

Edit this page

Warning: 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:

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:

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:

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!

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    Version:
    Put the code quality back at the heart of your project

    Put the code quality back at the heart of your project

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.

    Peruse our complete Symfony & PHP solutions catalog for your web development needs.