bakame / laravel-intl-formatter
Global helpers for internalization in Laravel application
Fund package maintenance!
nyamsprod
Requires
- php: ^7.4 || ^8.0
- ext-intl: *
- ext-json: *
- bakame/intl-formatter: ~0.3.0
- illuminate/config: ^8.0 || ^9.0
- illuminate/support: ^8.0 || ^9.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.8
- moneyphp/money: ^3.0 || ^4.0
- nunomaduro/larastan: ^1.0.0 || ^2.1
- orchestra/testbench: ^6.6.0 || ^7.5
- phpstan/phpstan: ^1.7
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-phpunit: ^1.1
- phpstan/phpstan-strict-rules: ^1.2
- phpunit/phpunit: ^9.5
Suggests
- moneyphp/money: To format currency based on the Money library
README
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 nyamsprod@gmail.com instead of using the issue tracker.
Credits
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.