<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>The Locale class</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="numberformatter.settextattribute.html">NumberFormatter::setTextAttribute</a></div>
<div class="next" style="text-align: right; float: right;"><a href="locale.acceptfromhttp.html">Locale::acceptFromHttp</a></div>
<div class="up"><a href="book.intl.html">intl</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="class.locale" class="reference">
<h1 class="title">The Locale class</h1>
<div class="partintro"><p class="verinfo">(PHP 5 >= 5.3.0, PECL intl >= 1.0.0)</p>
<div class="section" id="locale.intro">
<h2 class="title">Introduction</h2>
<p class="simpara">
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.
</p>
<p class="para">
Examples of identifiers include:
<ul class="simplelist">
<li class="member">en-US (English, United States)</li>
<li class="member">zh-Hant-TW (Chinese, Traditional Script, Taiwan)</li>
<li class="member">fr-CA, fr-FR (French for Canada and France respectively)</li>
</ul>
</p>
<p class="simpara">
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.
</p>
<p class="simpara">
Locales cannot be instantiated as objects. All of the functions/methods
provided are static.
</p>
<p class="simpara">
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.
</p>
</div>
<div class="section" id="locale.synopsis">
<h2 class="title">Class synopsis</h2>
<div class="classsynopsis">
<div class="ooclass">
</div>
<div class="classsynopsisinfo">
<span class="ooclass">
<strong class="classname">Locale</strong>
</span>
{</div>
<div class="classsynopsisinfo classsynopsisinfo_comment">/* Methods */</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.acceptfromhttp.html" class="methodname">acceptFromHttp</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$header</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="modifier">static</span> <span class="type">string</span> <span class="methodname"><a href="locale.canonicalize.html" class="methodname">canonicalize</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.composelocale.html" class="methodname">composeLocale</a></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$subtags</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">bool</span>
<span class="methodname"><a href="locale.filtermatches.html" class="methodname">filterMatches</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$langtag</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">bool</span> <code class="parameter">$canonicalize</code><span class="initializer"> = false</span></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">array</span>
<span class="methodname"><a href="locale.getallvariants.html" class="methodname">getAllVariants</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdefault.html" class="methodname">getDefault</a></span>
( <span class="methodparam">void</span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdisplaylanguage.html" class="methodname">getDisplayLanguage</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$in_locale</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdisplayname.html" class="methodname">getDisplayName</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$in_locale</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdisplayregion.html" class="methodname">getDisplayRegion</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$in_locale</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdisplayscript.html" class="methodname">getDisplayScript</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$in_locale</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getdisplayvariant.html" class="methodname">getDisplayVariant</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$in_locale</code></span>
] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">array</span>
<span class="methodname"><a href="locale.getkeywords.html" class="methodname">getKeywords</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getprimarylanguage.html" class="methodname">getPrimaryLanguage</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getregion.html" class="methodname">getRegion</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.getscript.html" class="methodname">getScript</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">string</span>
<span class="methodname"><a href="locale.lookup.html" class="methodname">lookup</a></span>
( <span class="methodparam"><span class="type">array</span> <code class="parameter">$langtag</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
[, <span class="methodparam"><span class="type">bool</span> <code class="parameter">$canonicalize</code><span class="initializer"> = false</span></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$default</code></span>
]] )</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">array</span>
<span class="methodname"><a href="locale.parselocale.html" class="methodname">parseLocale</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span>
<span class="modifier">static</span>
<span class="type">bool</span>
<span class="methodname"><a href="locale.setdefault.html" class="methodname">setDefault</a></span>
( <span class="methodparam"><span class="type">string</span> <code class="parameter">$locale</code></span>
)</div>
}</div>
</div>
<div class="section" id="intl.locale-constants">
<h2 class="title">Predefined Constants</h2>
<p class="para">
<dl>
<dt id="locale.constants.default-locale">
<span class="term">
<strong><code>Locale::DEFAULT_LOCALE</code></strong>
(<span class="type"><a href="language.types.null.html" class="type null">null</a></span>)
</span>
<dd>
<span class="simpara">
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.
</span>
</dd>
</dt>
</dl>
</p>
<p class="para">
These constants describe the choice of the locale for getLocalte method of
different classes.
<dl>
<dt id="locale.constants.actual-locale">
<span class="term">
<strong><code>Locale::ACTUAL_LOCALE</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">This is locale the data actually comes from.</span>
</dd>
</dt>
<dt id="locale.constants.valid-locale">
<span class="term">
<strong><code>Locale::VALID_LOCALE</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">This is the most specific locale supported by ICU.</span>
</dd>
</dt>
</dl>
</p>
<div class="section" id="intl.locale-constants.subtags">
<p class="para">
These constants define how the Locales are parsed or composed. They should
be used as keys in the argument array to <span class="function"><a href="locale.composelocale.html" class="function">locale_compose()</a></span>
and are returned from <span class="function"><a href="locale.parselocale.html" class="function">locale_parse()</a></span>
as keys of the returned associative <span class="type"><a href="language.types.array.html" class="type array">array</a></span>.
<dl>
<dt id="locale.constants.lang-tag">
<span class="term">
<strong><code>Locale::LANG_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Language subtag</span>
</dd>
</dt>
<dt id="locale.constants.extlang-tag">
<span class="term">
<strong><code>Locale::EXTLANG_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Extended language subtag</span>
</dd>
</dt>
<dt id="locale.constants.script-tag">
<span class="term">
<strong><code>Locale::SCRIPT_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Script subtag</span>
</dd>
</dt>
<dt id="locale.constants.region-tag">
<span class="term">
<strong><code>Locale::REGION_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Region subtag</span>
</dd>
</dt>
<dt id="locale.constants.variant-tag">
<span class="term">
<strong><code>Locale::VARIANT_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Variant subtag</span>
</dd>
</dt>
<dt id="locale.constants.grandfathered-lang-tag">
<span class="term">
<strong><code>Locale::GRANDFATHERED_LANG_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Grandfathered Language subtag</span>
</dd>
</dt>
<dt id="locale.constants.private-tag">
<span class="term">
<strong><code>Locale::PRIVATE_TAG</code></strong>
(<span class="type"><a href="language.types.string.html" class="type string">string</a></span>)
</span>
<dd>
<span class="simpara">Private subtag</span>
</dd>
</dt>
</dl>
</p>
</div>
</div>
<div class="section" id="locale.seealso">
<h2 class="title">See Also</h2>
<p class="para">
<ul class="simplelist">
<li class="member">
<a href="http://www.faqs.org/rfcs/rfc4646" class="link external">» RFC 4646 - Tags for Identifying Languages</a>
</li>
<li class="member">
<a href="http://www.faqs.org/rfcs/rfc4647" class="link external">» RFC 4647 - Matching of Language Tags</a>
</li>
<li class="member">
<a href="http://www.unicode.org/cldr/" class="link external">» Unicode CLDR Project:Common Locale Data Repository</a>
</li>
<li class="member">
<a href="http://www.iana.org/assignments/language-subtag-registry" class="link external">» IANA Language Subtags Registry</a>
</li>
<li class="member">
<a href="http://www.icu-project.org/userguide/locale.html" class="link external">» ICU User Guide - Locale</a>
</li>
<li class="member">
<a href="http://www.icu-project.org/apiref/icu4c/uloc_8h.html#details" class="link external">» ICU Locale api</a>
</li>
</ul>
</p>
</div>
</div>
<h2>Table of Contents</h2><ul class="chunklist chunklist_reference"><li><a href="locale.acceptfromhttp.html">Locale::acceptFromHttp</a> — Tries to find out best available locale based on HTTP "Accept-Language" header</li><li><a href="locale.canonicalize.html">Locale::canonicalize</a> — Canonicalize the locale string</li><li><a href="locale.composelocale.html">Locale::composeLocale</a> — Returns a correctly ordered and delimited locale ID</li><li><a href="locale.filtermatches.html">Locale::filterMatches</a> — Checks if a language tag filter matches with locale</li><li><a href="locale.getallvariants.html">Locale::getAllVariants</a> — Gets the variants for the input locale</li><li><a href="locale.getdefault.html">Locale::getDefault</a> — Gets the default locale value from the INTL global 'default_locale'</li><li><a href="locale.getdisplaylanguage.html">Locale::getDisplayLanguage</a> — Returns an appropriately localized display name for language of the inputlocale</li><li><a href="locale.getdisplayname.html">Locale::getDisplayName</a> — Returns an appropriately localized display name for the input locale</li><li><a href="locale.getdisplayregion.html">Locale::getDisplayRegion</a> — Returns an appropriately localized display name for region of the input locale</li><li><a href="locale.getdisplayscript.html">Locale::getDisplayScript</a> — Returns an appropriately localized display name for script of the input locale</li><li><a href="locale.getdisplayvariant.html">Locale::getDisplayVariant</a> — Returns an appropriately localized display name for variants of the input locale</li><li><a href="locale.getkeywords.html">Locale::getKeywords</a> — Gets the keywords for the input locale</li><li><a href="locale.getprimarylanguage.html">Locale::getPrimaryLanguage</a> — Gets the primary language for the input locale</li><li><a href="locale.getregion.html">Locale::getRegion</a> — Gets the region for the input locale</li><li><a href="locale.getscript.html">Locale::getScript</a> — Gets the script for the input locale</li><li><a href="locale.lookup.html">Locale::lookup</a> — Searches the language tag list for the best match to the language</li><li><a href="locale.parselocale.html">Locale::parseLocale</a> — Returns a key-value array of locale ID subtag elements.</li><li><a href="locale.setdefault.html">Locale::setDefault</a> — sets the default runtime locale</li></ul>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="numberformatter.settextattribute.html">NumberFormatter::setTextAttribute</a></div>
<div class="next" style="text-align: right; float: right;"><a href="locale.acceptfromhttp.html">Locale::acceptFromHttp</a></div>
<div class="up"><a href="book.intl.html">intl</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
