CLDR

The CLDR package facilitates the internationalization of your application by leveraging the data and conventions established by the Unicode Common Locale Data Repository (CLDR). It provides valuable locale information such as names for territories, languages, days… as well as formatters for numbers, currencies, dates and times, units, sequences, and lists.

Note

The package targets CLDR version 47; Revision 75.

Example usage

<?phpuseICanBoogie\CLDR\Numbers\Currency;
/* @var ICanBoogie\CLDR\Repository $repository */# You get a locale from the repository, here the locale for French.$fr = $repository->locale_for('fr');
# You can use a locale instance as an arrayecho$fr['characters']['auxiliary']; // [á å ä ã ā ē í ì ī ñ ó ò ö ø ú ǔ]echo$fr['delimiters']['quotationStart']; // «echo$fr['territories']['TF']; // Terres australes françaises# You can localize it and get its local nameecho$fr->localized($fr)->name; // Français# You can use it to format numbers, percents, currencies, lists…echo$fr->format_number(12345.67); // 12 345,67echo$fr->format_percent(.1234567); // 12 %echo$fr->format_currency(12345.67, 'EUR'); // 12 345,67 €echo$fr->format_list([ "Un", "deux", "trois" ]); // Un, deux et trois# You can get the default calendar for a locale and access its data$calendar = $fr->calendar;
echo$calendar['days']['format']['wide']['sun']; // dimancheecho$calendar->wide_days['sun']; // dimanche# You can use the calendar to format dates, times, or both$datetime = '2018-11-24 20:12:22 UTC';
echo$calendar->format_date($datetime, 'long'); // 24 novembre 2018echo$calendar->format_time($datetime, 'long'); // 20:12:22 UTCecho$calendar->format_datetime($datetime, 'full'); // samedi 24 novembre 2018 à 20:12:22 UTC# Alternatively, you can localize a DateTimeInterface and get formatted dates of various lengths$datetime = new \DateTime('2013-11-04 20:21:22 UTC');
$fr_datetime = new \ICanBoogie\CLDR\Dates\LocalizedDateTime($datetime, $fr);
echo$fr_datetime->as_full; // lundi 4 novembre 2013 à 20:21:22 UTCecho$fr_datetime->as_long; // 4 novembre 2013 à 20:21:22 UTCecho$fr_datetime->as_medium; // 4 nov. 2013 20:21:22echo$fr_datetime->as_short; // 04/11/2013 20:21# You can format units$units = $repository->locale_for('en')->units;
echo$units->duration_hour->name; // hoursecho$units->duration_hour->short_name; // hecho$units->duration_hour(1); // 1 hourecho$units->duration_hour(23); // 23 hoursecho$units->duration_hour(23)->as_short; // 23 hrecho$units->duration_hour(23)->as_narrow; // 23h# You can format a unit per another unitecho$units->volume_liter(12.345)->per($units->duration_hour);
// 12.345 liters per hourecho$units->volume_liter(12.345)->per($units->duration_hour)->as_short;
// 12.345 L/hecho$units->volume_liter(12.345)->per($units->duration_hour)->as_narrow;
// 12.345L/h# You can format sequences of units$units->sequence->angle_degree(5)->duration_minute(30)->as_narrow;
// 5° 30m$units->sequence->length_foot(3)->length_inch(2)->as_short;
// 3 ft, 2 in# You can access plural rules$repository->plurals->rule_for(1.5, 'fr'); // one$repository->plurals->rule_for(2, 'fr'); // other$repository->plurals->rule_for(2, 'ar'); // two# You can access currencies and their localized data$euro = Currency::of('EUR');
$fr_euro = $euro->localized($fr);
echo$fr_euro->name;
echo$fr_euro->name_for(1); // euroecho$fr_euro->name_for(10); // eurosecho$fr_euro->format(12345.67); // 12 345,67 €# You can access territories and their localized data$territory = $repository->territory_for('FR');
echo$territory; // FRecho$territory->currency; // EURecho$territory->currency_at('1977-06-06'); // FRFecho$territory->currency_at('now'); // EURecho$territory->name_as('fr'); // Franceecho$territory->name_as('it'); // Franciaecho$territory->name_as('ja'); // フランスecho$repository->territory_for('FR')->first_day; // monecho$repository->territory_for('EG')->first_day; // satecho$repository->territory_for('BS')->first_day; // sunecho$repository->territory_for('AE')->weekend_start; // friecho$repository->territory_for('AE')->weekend_end; // satecho$territory->localized('fr')->name; // Franceecho$territory->localized('it')->name; // Franciaecho$territory->localized('ja')->name; // フランス

Installation

composer require icanboogie/cldr

Documentation

The documentation is divided into the following parts, mimicking Unicode's documentation:

• Part 1: Core (languages, locales, basic structure)
• Part 2: General (display names & transforms, etc.)
• Part 3: Numbers (number & currency formatting)
• Part 4: Dates (date, time, time zone formatting)
• Part 5: Collation (sorting, searching, grouping)
• Part 6: Supplemental (supplemental data)

Getting started

The CLDR is represented by a Repository instance, which accesses data through a Provider instance. The package offers several and caching mechanisms. Choosing the right provider depends on your requirements: you may prioritize flexibility during development or predictability in production.

Favor flexibility

WebProvider offers maximum flexibility by retrieving data from the JSON distribution hosted on GitHub as needed. To minimize web requests, it is advised to use a collection of caches, each with its own strategy. For example, FileCache stores the retrieved data as PHP files, allowing it to benefit from opcache.

The following example demonstrates how a repository can be instantiated:

<?phpuseICanBoogie\CLDR\Cache\CacheCollection;
useICanBoogie\CLDR\Cache\FileCache;
useICanBoogie\CLDR\Cache\RedisCache;
useICanBoogie\CLDR\Cache\RuntimeCache;
useICanBoogie\CLDR\Provider\CachedProvider;
useICanBoogie\CLDR\Provider\WebProvider;
useICanBoogie\CLDR\Repository;
/* @var \Redis $redis_client */$provider = newCachedProvider(
newWebProvider,
newCacheCollection([
newRunTimeCache,
// You don't have to use Redis, this is only an examplenewRedisCache($redis_client),
newFileCache(FileCache::RECOMMENDED_DIR)
])
);
$cldr = newRepository($provider);

Favor predictability

For greater predictability, consider limiting the repository's usage to a few specific locales and distributing them as part of your application. You can prepopulate the CLDR cache during development and commit the files, or incorporate this step into your CI/CD pipeline build process.

Use the cldr command to warm up the CLDR cache:

./vendor/bin/cldr warm-up de en fr

The following example illustrates a setup to limit data access to the cache. RestrictedProvider throws an exception in an attempt to retrieve data not available in the cache.

<?phpuseICanBoogie\CLDR\Cache\FileCache;
useICanBoogie\CLDR\Provider\CachedProvider;
useICanBoogie\CLDR\Provider\RestrictedProvider;
useICanBoogie\CLDR\Repository;
$provider = newCachedProvider(
newRestrictedProvider(),
newFileCache(FileCache::RECOMMENDED_DIR),
);
$cldr = newRepository($provider);

---

Continuous Integration

The project is continuously tested by GitHub actions.

Code of Conduct

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you're expected to uphold this code.

Contributing

See CONTRIBUTING for details.

License

icanboogie/cldr is released under the MIT License.