The Intl Component

Warning: You are browsing the documentation for Symfony 3.x, which is no longer maintained.

Read the updated version of this page for Symfony 7.1 (the current stable version).

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.

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:^3.4

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.

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');
}

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\Compiler\BundleCompiler;
use Symfony\Component\Intl\ResourceBundle\Writer\TextBundleWriter;

$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

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();
// => ['ab' => 'Abkhazian', ...]

$language = Intl::getLanguageBundle()->getLanguageName('de');
// => 'German'

$language = Intl::getLanguageBundle()->getLanguageName('de', 'AT');
// => 'Austrian German'

$scripts = Intl::getLanguageBundle()->getScriptNames();
// => ['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');
// => ['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();
// => ['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');
// => ['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();
// => ['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');
// => ['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();
// => ['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');
// => ['AFN' => 'Afghanische Afghani', ...]

That's all you need to know for now. Have fun coding!

Learn more

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