Locale

class Locale (View source)

A "Locale" is an identifier used to get language, culture, or regionally-specific behavior from an API. PHP locales are organized and identified the same way that the CLDR locales used by ICU (and many vendors of Unix-like operating systems, the Mac, Java, and so forth) use. Locales are identified using RFC 4646 language tags (which use hyphen, not underscore) in addition to the more traditional underscore-using identifiers. Unless otherwise noted the functions in this class are tolerant of both formats.

Examples of identifiers include: en-US (English, United States) zh-Hant-TW (Chinese, Traditional Script, Taiwan) fr-CA, fr-FR (French for Canada and France respectively) The Locale class (and related procedural functions) are used to interact with locale identifiers--to verify that an ID is well-formed, valid, etc. The extensions used by CLDR in UAX #35 (and inherited by ICU) are valid and used wherever they would be in ICU normally. Locales cannot be instantiated as objects. All of the functions/methods provided are static. The null or empty string obtains the "root" locale. The "root" locale is equivalent to "en_US_POSIX" in CLDR. Language tags (and thus locale identifiers) are case insensitive. There exists a canonicalization function to make case match the specification.

Constants

ACTUAL_LOCALE

This is locale the data actually comes from.
VALID_LOCALE

This is the most specific locale supported by ICU.
DEFAULT_LOCALE

Used as locale parameter with the methods of the various locale affected classes, such as NumberFormatter. This constant would make the methods to use default locale.
LANG_TAG

Language subtag
EXTLANG_TAG

Extended language subtag
SCRIPT_TAG

Script subtag
REGION_TAG

Region subtag
VARIANT_TAG

Variant subtag
GRANDFATHERED_LANG_TAG

Grandfathered Language subtag
PRIVATE_TAG

Private subtag

Methods

static string
getDefault()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the default locale value from the INTL global 'default_locale'

static bool
setDefault(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
sets the default runtime locale

static string|null
getPrimaryLanguage(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the primary language for the input locale

static string|null
getScript(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the script for the input locale

static string|null
getRegion(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the region for the input locale

static array|false|null
getKeywords(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the keywords for the input locale

static string|false
getDisplayScript(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for script of the input locale

static string|false
getDisplayRegion(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for region of the input locale

static string|false
getDisplayName(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for the input locale

static string|false
getDisplayKeyword(string $keyword, string|null $displayLocale = null)

No description

static string|false
getDisplayKeywordValue(string $locale, string $keyword, string|null $displayLocale = null)

No description

static string|false
getDisplayLanguage(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for language of the inputlocale

static string|false
getDisplayVariant(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for variants of the input locale

static string|false
composeLocale(array $subtags)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns a correctly ordered and delimited locale ID

static array|null
parseLocale(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns a key-value array of locale ID subtag elements.

static array|null
getAllVariants(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the variants for the input locale

static bool|null
filterMatches(string $languageTag, string $locale, bool $canonicalize = false)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Checks if a language tag filter matches with locale

static string|null
lookup(array $languageTag, string $locale, bool $canonicalize = false, string $defaultLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Searches the language tag list for the best match to the language

static string|null
canonicalize(string $locale)

Canonicalize the locale string

static string|false
acceptFromHttp(string $header)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Tries to find out best available locale based on HTTP "Accept-Language" header

static bool
isRightToLeft(string $locale)

Check whether a locale uses a right-to-left writing system

static string|false
addLikelySubtags(string $locale)

No description

static string|false
minimizeSubtags(string $locale)

No description

Details

at line 1515
static string getDefault()

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the default locale value from the INTL global 'default_locale'

Return Value

string

The current runtime locale

at line 1527
static bool setDefault(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
sets the default runtime locale

Parameters

string $locale

Is a BCP 47 compliant language tag containing the

Return Value

bool

TRUE on success or FALSE on failure.

at line 1540
static string|null getPrimaryLanguage(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the primary language for the input locale

Parameters

string $locale

The locale to extract the primary language code from

Return Value

string|null

The language code associated with the language or NULL in case of error.

at line 1552
static string|null getScript(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the script for the input locale

Parameters

string $locale

The locale to extract the script code from

Return Value

string|null

The script subtag for the locale or NULL if not present

at line 1564
static string|null getRegion(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the region for the input locale

Parameters

string $locale

The locale to extract the region code from

Return Value

string|null

The region subtag for the locale or NULL if not present

at line 1576
static array|false|null getKeywords(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the keywords for the input locale

Parameters

string $locale

The locale to extract the keywords from

Return Value

array|false|null

Associative array containing the keyword-value pairs for this locale

at line 1592
static string|false getDisplayScript(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for script of the input locale

Parameters

string $locale

The locale to return a display script for

string $displayLocale

Optional format locale to use to display the script name

Return Value

string|false

Display name of the script for the $locale in the format appropriate for $in_locale.

at line 1612
static string|false getDisplayRegion(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for region of the input locale

Parameters

string $locale

The locale to return a display region for.

string $displayLocale

Optional format locale to use to display the region name

Return Value

string|false

display name of the region for the $locale in the format appropriate for $in_locale.

at line 1629
static string|false getDisplayName(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for the input locale

Parameters

string $locale

The locale to return a display name for.

string $displayLocale

optional format locale

Return Value

string|false

Display name of the locale in the format appropriate for $in_locale.

at line 1642
static string|false getDisplayKeyword(string $keyword, string|null $displayLocale = null)

Since: 8.6

No description

Parameters

string $keyword
string|null $displayLocale

Return Value

string|false

at line 1651
static string|false getDisplayKeywordValue(string $locale, string $keyword, string|null $displayLocale = null)

Since: 8.6

No description

Parameters

string $locale
string $keyword
string|null $displayLocale

Return Value

string|false

at line 1666
static string|false getDisplayLanguage(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for language of the inputlocale

Parameters

string $locale

The locale to return a display language for

string $displayLocale

Optional format locale to use to display the language name

Return Value

string|false

display name of the language for the $locale in the format appropriate for $in_locale.

at line 1686
static string|false getDisplayVariant(string $locale, string $displayLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns an appropriately localized display name for variants of the input locale

Parameters

string $locale

The locale to return a display variant for

string $displayLocale

Optional format locale to use to display the variant name

Return Value

string|false

Display name of the variant for the $locale in the format appropriate for $in_locale.

at line 1717
static string|false composeLocale(array $subtags)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns a correctly ordered and delimited locale ID

Parameters

array $subtags

an array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values.

The 'variant' and 'private' subtags can take maximum 15 values whereas 'extlang' can take maximum 3 values.e.g. Variants are allowed with the suffix ranging from 0-14. Hence the keys for the input array can be variant0, variant1, ...,variant14. In the returned locale id, the subtag is ordered by suffix resulting in variant0 followed by variant1 followed by variant2 and so on.

The 'variant', 'private' and 'extlang' multiple values can be specified both as array under specific key (e.g. 'variant') and as multiple numbered keys (e.g. 'variant0', 'variant1', etc.).

Return Value

string|false

The corresponding locale identifier.

at line 1736
static array|null parseLocale(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Returns a key-value array of locale ID subtag elements.

Parameters

string $locale

The locale to extract the subtag array from. Note: The 'variant' and 'private' subtags can take maximum 15 values whereas 'extlang' can take maximum 3 values.

Return Value

array|null

an array containing a list of key-value pairs, where the keys identify the particular locale ID subtags, and the values are the associated subtag values. The array will be ordered as the locale id subtags e.g. in the locale id if variants are '-varX-varY-varZ' then the returned array will have variant0=>varX , variant1=>varY , variant2=>varZ

at line 1749
static array|null getAllVariants(string $locale)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Gets the variants for the input locale

Parameters

string $locale

The locale to extract the variants from

Return Value

array|null

The array containing the list of all variants subtag for the locale or NULL if not present

at line 1768
static bool|null filterMatches(string $languageTag, string $locale, bool $canonicalize = false)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Checks if a language tag filter matches with locale

Parameters

string $languageTag

The language tag to check

string $locale

The language range to check against

bool $canonicalize

If true, the arguments will be converted to canonical form before matching.

Return Value

bool|null

TRUE if $locale matches $langtag FALSE otherwise.

at line 1796
static string|null lookup(array $languageTag, string $locale, bool $canonicalize = false, string $defaultLocale = null)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Searches the language tag list for the best match to the language

Parameters

array $languageTag

An array containing a list of language tags to compare to locale. Maximum 100 items allowed.

string $locale

The locale to use as the language range when matching.

bool $canonicalize

If true, the arguments will be converted to canonical form before matching.

string $defaultLocale

The locale to use if no match is found.

Return Value

string|null

The closest matching language tag or default value.

at line 1816
static string|null canonicalize(string $locale)

Canonicalize the locale string

Canonicalizes the passed locale string to ICU format.

Parameters

string $locale

Original locale string.

Return Value

string|null

Canonicalized locale string. Returns null when the length of locale exceeds INTL_MAX_LOCALE_LEN.

at line 1828
static string|false acceptFromHttp(string $header)

(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)
Tries to find out best available locale based on HTTP "Accept-Language" header

Parameters

string $header

The string containing the "Accept-Language" header according to format in RFC 2616.

Return Value

string|false

The corresponding locale identifier.

at line 1839
static bool isRightToLeft(string $locale)

Since: 8.5

Check whether a locale uses a right-to-left writing system

Determines whether a locale uses a right-to-left writing system.

Parameters

string $locale

Return Value

bool

at line 1844
static string|false addLikelySubtags(string $locale)

Since: 8.5

No description

Parameters

string $locale

Return Value

string|false

at line 1849
static string|false minimizeSubtags(string $locale)

Since: 8.5

No description

Parameters

string $locale

Return Value

string|false