Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

304 lines (281 sloc) 10.414 kb
<?php
/**
* Lithium: the most rad php framework
*
* @copyright Copyright 2012, Union of RAD (http://union-of-rad.org)
* @license http://opensource.org/licenses/bsd-license.php The BSD License
*/
namespace lithium\g11n;
use BadMethodCallException;
use InvalidArgumentException;
use lithium\action\Request as ActionRequest;
use lithium\console\Request as ConsoleRequest;
/**
* The `Locale` class provides methods to deal with locale identifiers. The locale
* (here: _locale identifier_) is used to distinguish among different sets of common
* preferences.
*
* In order to avoid unnecessary overhead all methods throughout the framework accepting
* a locale require it to be well-formed according to the structure laid out below. For
* assuring the correct format use `Locale::canonicalize()` once on the locale.
*
* However the methods within this class will also work with not-so-well-formed locales.
* They accept both underscores and hyphens as separators between and don't care about the
* case of the individual tags.
*
* The identifier used by Lithium is based in its structure upon Unicode's
* language identifier and is compliant to BCP 47.
*
* `language[_Script][_TERRITORY][_VARIANT]`
* - `language` The spoken language, here represented by an ISO 639-1 code,
* where not available ISO 639-3 and ISO 639-5 codes are allowed too) tag.
* The tag should be lower-cased and is required.
* - `Script` The tag should have it's first character capitalized, all others
* lower-cased. The tag is optional.
* - `TERRITORY` A geographical area, here represented by an ISO 3166-1 code.
* Should be all upper-cased and is optional.
* - `VARIANT` Should be all upper-cased and is optional.
*
* @link http://www.unicode.org/reports/tr35/tr35-12.html#Identifiers
* @link http://www.rfc-editor.org/rfc/bcp/bcp47.txt
* @link http://www.iana.org/assignments/language-subtag-registry
*/
class Locale extends \lithium\core\StaticObject {
/**
* Properties for locale tags.
*
* @var array
*/
protected static $_tags = array(
'language' => array('formatter' => 'strtolower'),
'script' => array('formatter' => array('strtolower', 'ucfirst')),
'territory' => array('formatter' => 'strtoupper'),
'variant' => array('formatter' => 'strtoupper')
);
/**
* Magic method enabling `language`, `script`, `territory` and `variant`
* methods to parse and retrieve individual tags from a locale.
*
* {{{
* Locale::language('en_US'); // returns 'en'
* Locale::territory('en_US'); // returns 'US'
* }}}
*
* @see lithium\g11n\Locale::$_tags
* @see lithium\g11n\Locale::decompose()
* @param string $method
* @param array $params
* @return mixed
*/
public static function __callStatic($method, $params = array()) {
$tags = static::invokeMethod('decompose', $params);
if (!isset(static::$_tags[$method])) {
throw new BadMethodCallException("Invalid locale tag `{$method}`.");
}
return isset($tags[$method]) ? $tags[$method] : null;
}
/**
* Composes a locale from locale tags. This is the pendant to `Locale::decompose()`.
*
* @param array $tags An array as obtained from `Locale::decompose()`.
* @return string A locale with tags separated by underscores or `null`
* if none of the passed tags could be used to compose a locale.
*/
public static function compose($tags) {
$result = array();
foreach (static::$_tags as $name => $tag) {
if (isset($tags[$name])) {
$result[] = $tags[$name];
}
}
if ($result) {
return implode('_', $result);
}
}
/**
* Parses a locale into locale tags. This is the pendant to `Locale::compose()``.
*
* @param string $locale A locale in an arbitrary form (i.e. `'en_US'` or `'EN-US'`).
* @return array Parsed language, script, territory and variant tags.
* @throws InvalidArgumentException
*/
public static function decompose($locale) {
$regex = '(?P<language>[a-z]{2,3})';
$regex .= '(?:[_-](?P<script>[a-z]{4}))?';
$regex .= '(?:[_-](?P<territory>[a-z]{2}))?';
$regex .= '(?:[_-](?P<variant>[a-z]{5,}))?';
if (!preg_match("/^{$regex}$/i", $locale, $matches)) {
throw new InvalidArgumentException("Locale `{$locale}` could not be parsed.");
}
return array_filter(array_intersect_key($matches, static::$_tags));
}
/**
* Returns a locale in its canonical form with tags formatted properly.
*
* @param string $locale A locale in an arbitrary form (i.e. `'ZH-HANS-HK_REVISED'`).
* @return string A locale in it's canonical form (i.e. `'zh_Hans_HK_REVISED'`).
*/
public static function canonicalize($locale) {
$tags = static::decompose($locale);
foreach ($tags as $name => &$tag) {
foreach ((array) static::$_tags[$name]['formatter'] as $formatter) {
$tag = $formatter($tag);
}
}
return static::compose($tags);
}
/**
* Cascades a locale.
*
* Usage:
* {{{
* Locale::cascade('en_US');
* // returns array('en_US', 'en', 'root')
*
* Locale::cascade('zh_Hans_HK_REVISED');
* // returns array('zh_Hans_HK_REVISED', 'zh_Hans_HK', 'zh_Hans', 'zh', 'root')
* }}}
*
* @link http://www.unicode.org/reports/tr35/tr35-13.html#Locale_Inheritance
* @param string $locale A locale in an arbitrary form (i.e. `'en_US'` or `'EN-US'`).
* @return array Indexed array of locales (starting with the most specific one).
*/
public static function cascade($locale) {
$locales[] = $locale;
if ($locale === 'root') {
return $locales;
}
$tags = static::decompose($locale);
while (count($tags) > 1) {
array_pop($tags);
$locales[] = static::compose($tags);
}
$locales[] = 'root';
return $locales;
}
/**
* Searches an array of locales for the best match to a locale. The locale
* is iteratively simplified until either it matches one of the locales
* in the list or the locale can't be further simplified.
*
* This method partially implements the lookup matching scheme as described
* in RFC 4647, section 3.4 and thus does not strictly conform to the
* specification.
*
* Differences to specification:
* - No support for wildcards in the to-be-matched locales.
* - No support for locales with private subtags.
* - No support for a default return value.
* - Passed locales are required to be in canonical form (i.e. `'ja_JP'`).
*
* @link http://www.ietf.org/rfc/rfc4647.txt
* @param array $locales Locales to match against `$locale`.
* @param string $locale A locale in it's canonical form (i.e. `'zh_Hans_HK_REVISED'`).
* @return string The matched locale.
*/
public static function lookup($locales, $locale) {
$tags = static::decompose($locale);
$count = count($tags);
while ($count > 0) {
if (($key = array_search(static::compose($tags), $locales)) !== false) {
return $locales[$key];
} elseif ($count == 1) {
foreach ($locales as $currentLocale) {
if (strpos($currentLocale, current($tags) . '_') === 0) {
return $currentLocale;
}
}
}
if (($key = array_search(static::compose($tags), $locales)) !== false) {
return $locales[$key];
}
array_pop($tags);
$count = count($tags);
}
}
/**
* Determines the preferred locale from a request or array. Optionally negotiates
* the preferred locale with available locales.
*
* @see lithium\g11n\Locale::_preferredAction()
* @see lithium\g11n\Locale::_preferredConsole()
* @see lithium\g11n\Locale::lookup()
* @param object|array $request An action or console request object or an array of locales.
* @param array $available A list of locales to negotiate the preferred locale with.
* @return string The preferred locale in it's canonical form (i.e. `'fr_CA'`).
* @todo Rewrite this to remove hard-coded class names.
*/
public static function preferred($request, $available = null) {
if (is_array($request)) {
$result = $request;
} elseif ($request instanceof ActionRequest) {
$result = static::_preferredAction($request);
} elseif ($request instanceof ConsoleRequest) {
$result = static::_preferredConsole($request);
} else {
return null;
}
if (!$available) {
return array_shift($result);
}
foreach ((array) $result as $locale) {
if ($match = static::lookup($available, $locale)) {
return $match;
}
}
}
/**
* Detects preferred locales from an action request by looking at the
* `'Accept-Language'` header as described by RFC 2616, section 14.4.
*
* @link http://www.ietf.org/rfc/rfc2616.txt
* @param object $request An instance of `lithium\action\Request`.
* @return array Preferred locales in their canonical form (i.e. `'fr_CA'`).
*/
protected static function _preferredAction($request) {
$regex = '/^\s*(?P<locale>\w\w(?:[-]\w\w)?)(?:;q=(?P<quality>[0-9]+\.[0-9]+))?\s*$/';
$result = array();
foreach (explode(',', $request->env('HTTP_ACCEPT_LANGUAGE')) as $part) {
if (preg_match($regex, $part, $matches)) {
$locale = static::canonicalize($matches['locale']);
$quality = isset($matches['quality']) ? $matches['quality'] : 1;
$result[$locale] = $quality;
}
}
arsort($result);
return array_keys($result);
}
/**
* Detects preferred locales from a console request by looking at certain
* environment variables. The environment variables may be present or not
* depending on your system. If multiple variables are present the following
* hierarchy is used: `'LANGUAGE'`, `'LC_ALL'`, `'LANG'`.
*
* The locales of the `'LC_ALL'` and the `'LANG'` are formatted according
* to the posix standard: `language(_territory)(.encoding)(@modifier)`.
* Locales having such a format are automatically canonicalized and transformed
* into the `Locale` class' format.
*
* @link http://www.linux.com/archive/feature/53781
* @param object $request An instance of `lithium\console\Request`.
* @return array Preferred locales in their canonical form (i.e. `'fr_CA'`).
*/
protected static function _preferredConsole($request) {
$regex = '(?P<locale>[\w\_]+)(\.|@|$)+';
$result = array();
if ($value = $request->env('LANGUAGE')) {
return explode(':', $value);
}
foreach (array('LC_ALL', 'LANG') as $variable) {
$value = $request->env($variable);
if (!$value || $value == 'C' || $value == 'POSIX') {
continue;
}
if (preg_match("/{$regex}/", $value, $matches)) {
return (array) $matches['locale'];
}
}
return $result;
}
}
?>
Jump to Line
Something went wrong with that request. Please try again.