Class List

FastSitePHP\Lang\L10N

Localization (l10n) API

Contains functions for formatting dates, times, and numbers.

[l10n] is spelled "Localisation" in British English. [l10n] is an acronym/numeronym that represents ("l" + 10 characters + "n"). The difference is US English uses "z" while British English uses an "s" in the spelling of the word.

Source Code

GitHub

Related Links

Example Code

Formatting Dates, Times, and Numbers

// FastSitePHP provides an easy to use Localization (l10n) API to allow date
// and number formatting with a user’s local language and regional settings.

// Create a new Lang L10N Object
$l10n = new \FastSitePHP\Lang\L10N();

// Settings can optionally be passed when the class is first created.
/*
$locale = 'en-US';
$timezone = 'America/Los_Angeles';
$l10n = new \FastSitePHP\Lang\L10N($locale, $timezone);
*/

// Use the [timezone()] function to get or set the timezone that will be used
// when formatting dates and times.
//
// If you have a site or application that has users in multiple timezones or
// countries an application design that works well is to save all dates and
// times in UTC and then format based on the users selected timezone.
//
// This example prints:
/*
    UTC                 = 2030-01-01 00:00
    Asia/Tokyo          = 2030-01-01 09:00
    America/Los_Angeles = 2029-12-31 16:00
*/
$date_time = '2030-01-01 00:00:00';
$timezones = ['UTC', 'Asia/Tokyo', 'America/Los_Angeles'];
foreach ($timezones as $timezone) {
    // Change the Timezone
    $l10n->timezone($timezone);
    // Print the formated date and time
    echo $l10n->timezone();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// Change the Timezone back to UTC for the next examples
$l10n->timezone('UTC');

// The [$date_time] parameter for the functions [formatDateTime(), formatDate(),
// and formatTime()] is either a Unix Timestamp (int) or a string in format
// of 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD'
$date_time = 1896181200;
$date_time = '2030-02-01 13:00:00';

// Print Date Time with different locales using [locale()] and
// [formatDateTime()] functions. This example prints:
/*
    ko    = 2030. 2. 1. 오후 1:00
    bn    = ১/২/২০৩০ ১:০০ PM
    en-US = 2/1/2030, 1:00 PM
    de-CH = 01.02.2030, 13:00
    ar    = ‏١‏/٢‏/٢٠٣٠ ١:٠٠ م
*/
$locales = ['ko-KR', 'bn-BD', 'en-US', 'de-CH', 'ar'];
foreach ($locales as $locale) {
    // Change the Locale
    $l10n->locale($locale);
    // Print the formated date and time
    echo $l10n->locale();
    echo ' = ';
    echo $l10n->formatDateTime($date_time);
    echo '<br>';
}
echo '<br>';

// In addition to [formatDateTime()] functions [formatDate()] and
// [formatTime()] can be used to show only a date or time. Prints:
/*
    01/02/2030
    13:00:00
*/
$l10n->locale('fr-FR');
echo $l10n->formatDate($date_time);
echo '<br>';
echo $l10n->formatTime($date_time);
echo '<br>';
echo '<br>';

// Print a formatted Number with different locales using [locale()] and
// [formatNumber()] functions. Decimal places are optional and default
// to 0. This example prints:
/*
    en-US =  1,234,567,890.12345
    en-IN = 1,23,45,67,890.12345
    fr    =  1 234 567 890,12345
    fa    =  ۱٬۲۳۴٬۵۶۷٬۸۹۰٫۱۲۳۴۵
*/
$number = 1234567890.12345;
$decimals = 5;
$locales = ['en-US', 'en-IN', 'fr', 'fa'];
foreach ($locales as $locale) {
    // [locale()] is a chainable getter and setter function
    // so it can be set and read from the same line.
    echo $l10n->locale($locale)->locale();
    echo ' = ';
    echo $l10n->formatNumber($number, $decimals);
    echo '<br>';
}

// Get supported Locales, Languages, and Timezones
$locales    = $l10n->supportedLocales();
$langugages = $l10n->supportedLanguages();
$timezones  = $l10n->supportedTimezones();

Methods

__construct($locale = null, $timezone = null)

Class Constructor Settings can optionally be set when the class is first created.

Example:
  $l10n = new \FastSitePHP\Lang\L10N('en-US', 'America/Los_Angeles');

supportedLocales()

Return a list of supported locales. Each locale has a JSON file in the [Locales] sub-folder.

Territories (Countries) are not always included when the language has a primary Country. For example French ‘fr’ and German ‘de’ do not have locales for ‘fr-FR’ and ‘de-DE’ however setting [locale()] with either value will match to the correct language.

Returns: array

supportedLanguages()

Return an associative array of Supported Languages. The key will contain the language abbreviation and the value will contain the language in English.

Returns: array

locale($locale = null)

Getter / Setter Property

Get or set the locale to be used when formatting dates, times, and numbers. When setting the locale this function is chainable and returns the L10N object instance.

Examples:
  Get:
    $current_locale = $l10n->locale();
  Set:
    $l10n->locale('zh');
    $l10n->locale('fr-FR');
    $l10n->locale('en-US');

Returns: $this | null | string

supportedTimezones()

Return an array of timezones that can be set from the function [timezone()]. This function simply returns the results of the native PHP function [\DateTimeZone::listIdentifiers()].

Returns: array

timezone($timezone = null)

Getter / Setter Property

Get or set the timezone to be used when formatting dates and times. When setting the timezone this function is chainable and returns this L10N object instance.

Examples:
  $time = '2030-01-01 00:00:00';
  $l10n->timezone($timezone)->formatDateTime($time);

  time = $timezone:
  '2030-01-01 00:00' = 'UTC'
  '2030-01-01 09:00' = 'Asia/Tokyo'
  '2029-12-31 16:00' = 'America/Los_Angeles'

Returns: $this | null | string

formatDateTime($date_time)

Format a date and time string based on the selected locale. Seconds are not included in the result.

Example:
  $l10n->timezone('UTC')->formatDateTime('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 2030. 2. 1. 오후 1:00
  'bn-BD' : ১/২/২০৩০ ১:০০ PM
  'en-US' : 2/1/2030, 1:00 PM
  'de-CH' : 01.02.2030, 13:00

To return formatted current date and time:
  $l10n->formatDateTime(time());

If an invalid time is passed and timezone is set then this function will return [null]; otherwise if timezone is not set then the initial value for Unix Timestamp (00:00:00 on 1 January 1970) will be returned.

When using Language 'fa' (Farsi/Persian) or locale 'ar-SA' (Arabic - Saudi Arabia) dates are currently returned with Latin Digits using the Gregorian Calendar instead of Jalaali Calendar for 'fa' and Hijri Calendar for 'ar-SA'. If you need either of these calendars on a web page an option is to use the browser built-in object [Intl.DateTimeFormat] from JavaScript.

Returns: string | null

formatDate($date)

Format a date string (excluding time) based on the selected locale.

Example:
  $l10n->timezone('UTC')->formatDate('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 2030. 2. 1.
  'bn-BD' : ১/২/২০৩০
  'en-US' : 2/1/2030
  'de-CH' : 01.02.2030

To return formatted current date:
  $l10n->formatDate(time());

See additional notes in [formatDateTime()].

Returns: string | null

formatTime($time)

Format a time string (excluding date) based on the selected locale. Hours, minutes, and seconds are included in the result.

Example:
  $l10n->timezone('UTC')->formatTime('2030-02-01 13:00:30');

Returns:
  'ko-KR' : 오후 1:00:30
  'bn-BD' : ১:০০:৩০ PM
  'en-US' : 1:00:30 PM
  'de-CH' : 13:00:30

To return formatted current time:
  $l10n->formatTime(time());

See additional notes in [formatDateTime()].

Returns: string | null

formatNumber($number, $decimals = 0)

Format a number based on the selected locale. Defaults to zero decimal places.

Example:
  $l10n->formatNumber(1234567890.12345, 5)

Returns:
  'en-US' :  1,234,567,890.12345
  'en-IN' : 1,23,45,67,890.12345
  'fr'    :  1 234 567 890,12345
  'ar'    :  ١٬٢٣٤٬٥٦٧٬٨٩٠٫١٢٣٤٥

Returns: string