README.md

Laravel Intl Formatter

This is a Laravel port of the Twig Intl Extension package.

The package can be used in any Laravel based application to quickly handle internationalization by providing helper functions in Blade templates or Laravel codebase.

System Requirements

• Laravel 8 and/or 9
• Symfony Intl component

Installation

Use composer:

composer require bakame/laravel-intl-formatter

Configuration

In order to edit the default configuration you need to publish the package configuration to your application config directory:

php artisan vendor:publish --provider="Bakame\Laravel\Intl" --tag=config

The configuration file will be published to config/bakame-intl-formatter.php in your application directory.

Please refer to the config file for an overview of the available options.

Documentation

Once installed the package provides the following global helper functions:

Country Name

Returns the country name given its two-letter/five-letter code;

country name: {{ country_name($country, $locale) }}

echo view($templatePath, ['country' => 'FR', 'locale' => 'NL'])->render();
// country name: Frankrijk

Currency Name

Returns the currency name given its three-letter code;

currency name: {{ currency_name($currency, $locale) }}

echo view($templatePath, ['currency' => 'JPY', 'locale' => 'PT'])->render();
// currency name: Iene japonês

Currency Symbol

Returns the currency symbol given its three-letter code;

currency symbol: {{ currency_symbol($currency, $locale) }}

echo view($templatePath, ['currency' => 'JPY', 'locale' => 'PT'])->render();
// currency symbol: JP¥

Language name

Returns the currency symbol given its three-letter code;

language name: {{ language_name($language, $locale) }}

echo view($templatePath, ['language' => 'it', 'locale' => 'nl'])->render();
// language name: Italiaans

Locale name

Returns the currency symbol given its three-letter code;

locale name: {{ locale_name($data, $locale) }}

echo view($templatePath, ['data' => 'sw', 'locale' => 'nl'])->render();
// locale name: Swahili

Timezone name

Returns the timezone name given its identifier;

timezone name: {{ locale_name($data, $locale) }}

echo view($templatePath, ['timezone' => 'Asia/Tokyo', 'locale' => 'es'])->render();
// timezone name: hora de Japón (Tokio)

Country Timezones

Returns the timezone identifiers of the given country code;

country timezones: {{ implde(", ", country_timezones($country)) }}

$content = view($templatePath, ['country' => 'CD', 'locale' => 'es'])->render();
echo $content, PHP_EOL; // country timezones: Africa/Kinshasa, Africa/Lubumbashi

Format Currency

Formats a number as a currency;

format currency: {{ format_currency($amount, $currency, $attrs, $locale) }}

$templateData = [
    'amount' => 100.356, 
    'currency' => 'USD', 
    'locale' => 'ES', 
    'attrs' => [
        'fraction_digit' => 1,
        'rounding_mode' => 'floor',
    ]
];
echo view($templatePath, $templateData)->render();
// format currency: 100,3 US$

Format Number

Formats a number;

format number: {{ format_number($number, $locale, $attrs) }}

$templateData = [
    'number' => 100.356, 
    'locale' => 'nl', 
    'style' => 'spellout',
    'type' => 'double',
    'attrs' => [
        'fraction_digit' => 1,
        'rounding_mode' => 'floor',
    ]
];
echo view($templatePath, $templateData)->render();
// format number: honderd komma drie

Format DateTime

Formats a date and time;

format datetime: {{ format_datetime($date, $locale, $timezone, $dateFormat, $timeFormat, $pattern, $calendar) }}

$templateData = [
    'date' => 'yesterday', 
    'dateFormat' => 'full', 
    'timeFormat' => 'full', 
    'pattern' => '' ,
    'timezone' => 'Africa/Lubumbashi', 
    'calendar' => 'gregorian' ,
    'locale' => 'sw',
];
echo view($templatePath, $templateData)->render();
// format datetime: Alhamisi, 2 Juni 2022 00:00:00 Saa za Afrika ya Kati

Format Date

Formats a the date portion of a datetime;

format date: {{ format_date($date, $locale, $timezone, $dateFormat, $pattern, $calendar) }}

$templateData = [
    'date' => 'yesterday', 
    'dateFormat' => 'long', 
    'pattern' => '' ,
    'timezone' => 'Africa/Lubumbashi', 
    'calendar' => 'gregorian' ,
    'locale' => 'sw',
];
echo view($templatePath, $templateData)->render();
// format date: 2 Juni 2022

Format Time

Formats the time portion of a datetime;

format time: {{ format_time($date, $locale, $timezone, $timeFormat, $pattern, $calendar) }}

$templateData = [
    'date' => 'yesterday', 
    'dateFormat' => 'full', 
    'pattern' => '' ,
    'timezone' => 'Africa/Lubumbashi', 
    'calendar' => 'gregorian' ,
    'locale' => 'sw',
];
echo view($templatePath, $templateData)->render();
// format time: 00:00:00 Saa za Afrika ya Kati

Each function uses the same arguments in the same order as the Twig Extra package filters/functions.

Locale specification

If no locale is specified in function calls, the function will use the result of Illuminate\Support\Facades\App::currentLocale() as the locale value to use.

functions signature

In PHP8+, you can use named parameters to improve functions usages as they tend to have a lot of arguments:

In PHP7.4

<?php

echo format_datetime('2019-08-07 23:39:12', 'fr', null, medium', 'medium', '', 'gregorian', 'fr');

In PHP8+

<?php

echo format_datetime(date: '2019-08-07 23:39:12', locale: 'fr');

Contributing

Contributions are welcome and will be fully credited. Please see CONTRIBUTING and CODE OF CONDUCT for details.

Testing

The library:

• has a PHPUnit test suite
• has a coding style compliance test suite using PHP CS Fixer.
• has a code analysis compliance test suite using PHPStan.

To run the tests, run the following command from the project folder.

$ composer test

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• ignace nyamagana butera
• All Contributors

Attribution

The package helpers functions are heavily inspired by previous works done by Fabien Potencier on Twig Intl Extension.

License

The MIT License (MIT). Please see License File for more information.