You are browsing the Symfony 4 documentation, which changes significantly from Symfony 3.x. If your app doesn't use Symfony 4 yet, browse the Symfony 3.4 documentation.

The Intl Component

4.3 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.

Caution

The replacement layer is limited to the locale "en". If you want to use other locales, you should install the intl extension instead.

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:

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.

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', [
    'Data' => [
        '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', [
    'Data' => [
        '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', ['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',
    ['Data', 'entry1'],
    false
));

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
use Symfony\Component\Intl\Languages;

\Locale::setDefault('en');

$languages = Languages::getNames();
// => ['ab' => 'Abkhazian', ...]

$language = Languages::getName('de');
// => 'German'

$language = Languages::getName('de', 'AT');
// => 'Austrian German'

All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:

$languages = Languages::getNames('de');
// => ['ab' => 'Abchasisch', ...]

New in version 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
use Symfony\Component\Intl\Scripts;

\Locale::setDefault('en');

$scripts = Scripts::getNames();
// => ['Arab' => 'Arabic', ...]

$script = Scripts::getName('Hans');
// => 'Simplified'

New in version 4.3: The Scrcipts class was introduced in Symfony 4.3.

Country and Region Names

In the world there are some territorial disputes that make it hard to define what a country is. That's why the Intl component provides a Regions class instead of a Countries class:

1
2
3
4
5
6
7
8
9
use Symfony\Component\Intl\Regions;

\Locale::setDefault('en');

$countries = Regions::getNames();
// => ['AF' => 'Afghanistan', ...]

$country = Regions::getName('GB');
// => 'United Kingdom'

All methods accept the translation locale as the last, optional parameter, which defaults to the current default locale:

$countries = Regions::getNames('de');
// => ['AF' => 'Afghanistan', ...]

New in version 4.3: The Regions 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
use Symfony\Component\Intl\Locales;

\Locale::setDefault('en');

$locales = Locales::getNames();
// => ['af' => 'Afrikaans', ...]

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

$locales = Locales::getNames('de');
// => ['af' => 'Afrikaans', ...]

New in version 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
use Symfony\Component\Intl\Currencies;

\Locale::setDefault('en');

$currencies = Currencies::getNames();
// => ['AFN' => 'Afghan Afghani', ...]

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

$currencies = Currencies::getNames('de');
// => ['AFN' => 'Afghanische Afghani', ...]

New in version 4.3: The Currencies class was introduced in Symfony 4.3.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.