Caching for the contents of localisation files. More...

Inheritance diagram for LocalisationCache:

Public Member Functions
	__construct (ServiceOptions $options, LCStore $store, LoggerInterface $logger, array $clearStoreCallbacks, LanguageNameUtils $langNameUtils, HookContainer $hookContainer)
	For constructor parameters, see the documentation for the LocalisationCacheConf setting in docs/Configuration.md.

	disableBackend ()
	Disable the storage backend.

	getCompiledPluralRules ( $code)
	Get the compiled plural rules for a given language from the XML files.

	getItem ( $code, $key)
	Get a cache item.

	getMessagesDirs ()
	Gets the combined list of messages dirs from core and extensions.

	getPluralRules ( $code)
	Get the plural rules for a given language from the XML files.

	getPluralRuleTypes ( $code)
	Get the plural rule types for a given language from the XML files.

	getSubitem ( $code, $key, $subkey)
	Get a subitem, for instance a single message for a given language.

	getSubitemList ( $code, $key)
	Get the list of subitem keys for a given item.

	getSubitemWithSource ( $code, $key, $subkey)
	Get a subitem with its source language.

	initShallowFallback ( $primaryCode, $fallbackCode)
	Create a fallback from one language to another, without creating a complete persistent cache.

	isExpired ( $code)
	Returns true if the cache identified by $code is missing or expired.

	isMergeableKey ( $key)
	Returns true if the given key is mergeable, that is, if it is an associative array which can be merged through a fallback sequence.

	readJSONFile ( $fileName)
	Read a JSON file containing localisation messages.

	recache ( $code)
	Load localisation data for a given language for both core and extensions and save it to the persistent cache store and the process cache.

	unload ( $code)
	Unload the data for a given language from the object cache.

	unloadAll ()
	Unload all data.

Static Public Member Functions
static	getStoreFromConf (array $conf, $fallbackCacheDir)
	Return a suitable LCStore as specified by the given configuration.

Public Attributes
const	CONSTRUCTOR_OPTIONS

const	VERSION = 5

Static Public Attributes
static	$allKeys
	All item keys.

static	$magicWordKeys = [ 'magicWords' ]
	Keys for items that are formatted like $magicWords.

static	$mergeableAliasListKeys = [ 'specialPageAliases' ]
	Keys for items which contain an array of arrays of equivalent aliases for each subitem.

static	$mergeableListKeys = []
	Keys for items which are a numbered array.

static	$mergeableMapKeys
	Keys for items which consist of associative arrays, which may be merged by a fallback sequence.

static	$optionalMergeKeys = [ 'bookstoreList' ]
	Keys for items which contain an associative array, and may be merged if the primary value contains the special array key "inherit".

static	$preloadedKeys = [ 'dateFormats', 'namespaceNames' ]
	Keys which are loaded automatically by initLanguage()

static	$sourcePrefixKeys = [ 'messages' ]
	Keys for items that will be prefixed with its source language code, which should be stripped out when loading from cache.

static	$splitKeys = [ 'messages' ]
	Keys for items where the subitems are stored in the backend separately.

Protected Member Functions
	buildPreload ( $data)
	Build the preload item from the given pre-cache data.

	initLanguage ( $code)
	Initialise a language in this object.

	loadItem ( $code, $key)
	Load an item into the cache.

	loadPluralFile ( $fileName)
	Load a plural XML file with the given filename, compile the relevant rules, and save the compiled rules in a process-local cache.

	loadPluralFiles ()
	Load the plural XML files.

	loadSubitem ( $code, $key, $subkey)
	Load a subitem into the cache.

	mergeExtensionItem ( $codeSequence, $key, &$value, $fallbackValue)
	Given an array mapping language code to localisation value, such as is found in extension *.i18n.php files, iterate through a fallback sequence to merge the given data with an existing primary value.

	mergeItem ( $key, &$value, $fallbackValue)
	Merge two localisation values, a primary and a fallback, overwriting the primary value in place.

	mergeMagicWords (&$value, $fallbackValue)

	readPHPFile ( $_fileName, $_fileType)
	Read a PHP file containing localisation data.

	readSourceFilesAndRegisterDeps ( $code, &$deps)
	Read the data from the source files for a given language, and register the relevant dependencies in the $deps array.

Protected Attributes
	$data = []
	The cache data.

	$sourceLanguage = []
	The source language of cached data items.

const	SOURCEPREFIX_SEPARATOR = ':'
	Separator for the source language prefix.

Detailed Description

Caching for the contents of localisation files.

Including for i18n JSON files under /languages/messages, Messages*.php, and *.i18n.php.

An instance of this class is available using MediaWikiServices.

The values retrieved from here are merged, containing items from extension files, core messages files and the language fallback sequence (e.g. zh-cn -> zh-hans -> en ). Some common errors are corrected, for example namespace names with spaces instead of underscores, but heavyweight processing, such as grammatical transformation, is done by the caller.

Definition at line 46 of file LocalisationCache.php.

Constructor & Destructor Documentation

◆ __construct()

LocalisationCache::__construct	(	ServiceOptions	$options,
		LCStore	$store,
		LoggerInterface	$logger,
		array	$clearStoreCallbacks,
		LanguageNameUtils	$langNameUtils,
		HookContainer	$hookContainer )

For constructor parameters, see the documentation for the LocalisationCacheConf setting in docs/Configuration.md.

Do not construct this directly. Use MediaWikiServices.

Parameters

ServiceOptions	$options
LCStore	$store	What backend to use for storage
LoggerInterface	$logger
callable[]	$clearStoreCallbacks	To be called whenever the cache is cleared. Can be used to clear other caches that depend on this one, such as ResourceLoader's MessageBlobStore.
LanguageNameUtils	$langNameUtils
HookContainer	$hookContainer

Exceptions

MWException

Definition at line 278 of file LocalisationCache.php.

References MediaWiki\Config\ServiceOptions\assertRequiredOptions(), and MediaWiki\Config\ServiceOptions\get().

Member Function Documentation

◆ buildPreload()

LocalisationCache::buildPreload ( $data )

protected

Build the preload item from the given pre-cache data.

The preload item will be loaded automatically, improving performance for the commonly-requested items it contains.

Parameters

array $data

Returns: array

Definition at line 1156 of file LocalisationCache.php.

◆ disableBackend()

LocalisationCache::disableBackend ( )

Disable the storage backend.

Definition at line 1202 of file LocalisationCache.php.

◆ getCompiledPluralRules()

LocalisationCache::getCompiledPluralRules ( $code )

Get the compiled plural rules for a given language from the XML files.

Since: 1.20

Parameters

string $code

Returns: array|null

Definition at line 680 of file LocalisationCache.php.

◆ getItem()

LocalisationCache::getItem	(		$code,
			$key )

Get a cache item.

Warning: this may be slow for split items (messages), since it will need to fetch all of the subitems from the cache individually.

Parameters

string	$code
string	$key

Returns: mixed

Reimplemented in LocalisationCacheBulkLoad.

Definition at line 328 of file LocalisationCache.php.

◆ getMessagesDirs()

LocalisationCache::getMessagesDirs ( )

Gets the combined list of messages dirs from core and extensions.

Since: 1.25

Returns: array

Definition at line 894 of file LocalisationCache.php.

References $IP.

◆ getPluralRules()

LocalisationCache::getPluralRules ( $code )

Get the plural rules for a given language from the XML files.

Cached.

Since: 1.20

Parameters

string $code

Returns: array|null

Definition at line 703 of file LocalisationCache.php.

◆ getPluralRuleTypes()

LocalisationCache::getPluralRuleTypes ( $code )

Get the plural rule types for a given language from the XML files.

Cached.

Since: 1.22

Parameters

string $code

Returns: array|null

Definition at line 717 of file LocalisationCache.php.

◆ getStoreFromConf()

static LocalisationCache::getStoreFromConf	(	array	$conf,
			$fallbackCacheDir )

static

Return a suitable LCStore as specified by the given configuration.

Since: 1.34

Parameters

array	$conf	In the format of $wgLocalisationCacheConf
string \| false \| null	$fallbackCacheDir	In case 'storeDirectory' isn't specified

Returns: LCStore

Definition at line 226 of file LocalisationCache.php.

◆ getSubitem()

LocalisationCache::getSubitem	(	$code,
		$key,
		$subkey )

Get a subitem, for instance a single message for a given language.

Parameters

string	$code
string	$key
string	$subkey

Returns: mixed|null

Reimplemented in LocalisationCacheBulkLoad.

Definition at line 348 of file LocalisationCache.php.

◆ getSubitemList()

LocalisationCache::getSubitemList	(		$code,
			$key )

Get the list of subitem keys for a given item.

This is faster than array_keys($lc->getItem(...)) for the items listed in self::$splitKeys.

Will return null if the item is not found, or false if the item is not an array.

Parameters

string	$code
string	$key

Returns: bool|null|string|string[]

Definition at line 390 of file LocalisationCache.php.

◆ getSubitemWithSource()

LocalisationCache::getSubitemWithSource	(	$code,
		$key,
		$subkey )

Get a subitem with its source language.

Only supports messages for now.

Since: 1.41 (backported to 1.40.2 and 1.39.6)

Parameters

string	$code
string	$key
string	$subkey

Returns: string[]|null Return [ subitem, sourceLanguage ] if the subitem is defined.

Definition at line 367 of file LocalisationCache.php.

◆ initLanguage()

LocalisationCache::initLanguage ( $code )

protected

Initialise a language in this object.

Rebuild the cache if necessary.

Parameters

string $code

Exceptions

MWException

Definition at line 527 of file LocalisationCache.php.

◆ initShallowFallback()

LocalisationCache::initShallowFallback	(		$primaryCode,
			$fallbackCode )

Create a fallback from one language to another, without creating a complete persistent cache.

Parameters

string	$primaryCode
string	$fallbackCode

Definition at line 605 of file LocalisationCache.php.

◆ isExpired()

LocalisationCache::isExpired ( $code )

Returns true if the cache identified by $code is missing or expired.

Parameters

string $code

Returns: bool

Definition at line 489 of file LocalisationCache.php.

References $keys, and CacheDependency\isExpired().

◆ isMergeableKey()

LocalisationCache::isMergeableKey ( $key )

Returns true if the given key is mergeable, that is, if it is an associative array which can be merged through a fallback sequence.

Parameters

string $key

Returns: bool

Definition at line 305 of file LocalisationCache.php.

◆ loadItem()

LocalisationCache::loadItem	(		$code,
			$key )

protected

Load an item into the cache.

Parameters

string	$code
string	$key

Definition at line 408 of file LocalisationCache.php.

◆ loadPluralFile()

LocalisationCache::loadPluralFile ( $fileName )

protected

Load a plural XML file with the given filename, compile the relevant rules, and save the compiled rules in a process-local cache.

Parameters

string $fileName

Exceptions

MWException

Definition at line 750 of file LocalisationCache.php.

◆ loadPluralFiles()

LocalisationCache::loadPluralFiles ( )

protected

Load the plural XML files.

Definition at line 727 of file LocalisationCache.php.

◆ loadSubitem()

LocalisationCache::loadSubitem	(	$code,
		$key,
		$subkey )

protected

Load a subitem into the cache.

Parameters

string	$code
string	$key
string	$subkey

Definition at line 445 of file LocalisationCache.php.

◆ mergeExtensionItem()

LocalisationCache::mergeExtensionItem	(		$codeSequence,
			$key,
		&	$value,
			$fallbackValue )

protected

Given an array mapping language code to localisation value, such as is found in extension *.i18n.php files, iterate through a fallback sequence to merge the given data with an existing primary value.

Returns true if any data from the extension array was used, false otherwise.

Parameters

array	$codeSequence
string	$key
mixed	&$value
mixed	$fallbackValue

Returns: bool

Definition at line 875 of file LocalisationCache.php.

◆ mergeItem()

LocalisationCache::mergeItem	(		$key,
		&	$value,
			$fallbackValue )

protected

Merge two localisation values, a primary and a fallback, overwriting the primary value in place.

Parameters

string	$key
mixed	&$value
mixed	$fallbackValue

Definition at line 820 of file LocalisationCache.php.

◆ mergeMagicWords()

LocalisationCache::mergeMagicWords	(	&	$value,
			$fallbackValue )

protected

Parameters

mixed	&$value
mixed	$fallbackValue

Definition at line 848 of file LocalisationCache.php.

◆ readJSONFile()

LocalisationCache::readJSONFile ( $fileName )

Read a JSON file containing localisation messages.

Parameters

string $fileName Name of file to read

Exceptions

MWException If there is a syntax error in the JSON file

Returns: array Array with a 'messages' key, or empty array if the file doesn't exist

Definition at line 649 of file LocalisationCache.php.

◆ readPHPFile()

LocalisationCache::readPHPFile	(		$_fileName,
			$_fileType )

protected

Read a PHP file containing localisation data.

Parameters

string	$_fileName
string	$_fileType

Exceptions

MWException

Returns: array

Reimplemented in LocalisationCacheBulkLoad.

Definition at line 619 of file LocalisationCache.php.

◆ readSourceFilesAndRegisterDeps()

LocalisationCache::readSourceFilesAndRegisterDeps	(		$code,
		&	$deps )

protected

Read the data from the source files for a given language, and register the relevant dependencies in the $deps array.

If the localisation exists, the data array is returned, otherwise false is returned.

Parameters

string	$code
array	&$deps

Returns: array

Definition at line 789 of file LocalisationCache.php.

◆ recache()

LocalisationCache::recache ( $code )

Load localisation data for a given language for both core and extensions and save it to the persistent cache store and the process cache.

Parameters

string $code

Exceptions

MWException

Reimplemented in LocalisationCacheBulkLoad.

Definition at line 913 of file LocalisationCache.php.

◆ unload()

LocalisationCache::unload ( $code )

Unload the data for a given language from the object cache.

Reduces memory usage.

Parameters

string $code

Reimplemented in LocalisationCacheBulkLoad.

Definition at line 1175 of file LocalisationCache.php.

◆ unloadAll()

LocalisationCache::unloadAll ( )

Unload all data.

Definition at line 1193 of file LocalisationCache.php.

References $lang.

Member Data Documentation

◆ $allKeys

LocalisationCache::$allKeys

static

Initial value:

= [
        'fallback', 'namespaceNames', 'bookstoreList',
        'magicWords', 'messages', 'rtl',
        'digitTransformTable', 'separatorTransformTable',
        'minimumGroupingDigits', 'fallback8bitEncoding',
        'linkPrefixExtension', 'linkTrail', 'linkPrefixCharset',
        'namespaceAliases', 'dateFormats', 'datePreferences',
        'datePreferenceMigrationMap', 'defaultDateFormat',
        'specialPageAliases', 'imageFiles', 'preloadedMessages',
        'namespaceGenderAliases', 'digitGroupingPattern', 'pluralRules',
        'pluralRuleTypes', 'compiledPluralRules',
    ]

All item keys.

Definition at line 131 of file LocalisationCache.php.

◆ $data

LocalisationCache::$data = []

protected

The cache data.

3-d array, where the first key is the language code, the second key is the item key e.g. 'messages', and the third key is an item specific subkey index. Some items are not arrays and so for those items, there are no subkeys.

Definition at line 65 of file LocalisationCache.php.

Referenced by LocalisationCacheBulkLoad\readPHPFile().

◆ $magicWordKeys

LocalisationCache::$magicWordKeys = [ 'magicWords' ]

static

Keys for items that are formatted like $magicWords.

Definition at line 173 of file LocalisationCache.php.

◆ $mergeableAliasListKeys

LocalisationCache::$mergeableAliasListKeys = [ 'specialPageAliases' ]

static

Keys for items which contain an array of arrays of equivalent aliases for each subitem.

The aliases may be merged by a fallback sequence.

Definition at line 161 of file LocalisationCache.php.

◆ $mergeableListKeys

LocalisationCache::$mergeableListKeys = []

static

Keys for items which are a numbered array.

Definition at line 155 of file LocalisationCache.php.

◆ $mergeableMapKeys

LocalisationCache::$mergeableMapKeys

static

Initial value:

= [ 'messages', 'namespaceNames',
        'namespaceAliases', 'dateFormats', 'imageFiles', 'preloadedMessages'
    ]

Keys for items which consist of associative arrays, which may be merged by a fallback sequence.

Definition at line 148 of file LocalisationCache.php.

◆ $optionalMergeKeys

LocalisationCache::$optionalMergeKeys = [ 'bookstoreList' ]

static

Keys for items which contain an associative array, and may be merged if the primary value contains the special array key "inherit".

That array key is removed after the first merge.

Definition at line 168 of file LocalisationCache.php.

◆ $preloadedKeys

LocalisationCache::$preloadedKeys = [ 'dateFormats', 'namespaceNames' ]

static

Keys which are loaded automatically by initLanguage()

Definition at line 194 of file LocalisationCache.php.

◆ $sourceLanguage

LocalisationCache::$sourceLanguage = []

protected

The source language of cached data items.

Only supports messages for now.

Definition at line 70 of file LocalisationCache.php.

◆ $sourcePrefixKeys

LocalisationCache::$sourcePrefixKeys = [ 'messages' ]

static

Keys for items that will be prefixed with its source language code, which should be stripped out when loading from cache.

Definition at line 184 of file LocalisationCache.php.

◆ $splitKeys

LocalisationCache::$splitKeys = [ 'messages' ]

static

Keys for items where the subitems are stored in the backend separately.

Definition at line 178 of file LocalisationCache.php.

◆ CONSTRUCTOR_OPTIONS

const LocalisationCache::CONSTRUCTOR_OPTIONS

Initial value:

= [
        
        'forceRecache',
        'manualRecache',
        MainConfigNames::ExtensionMessagesFiles,
        MainConfigNames::MessagesDirs,
    ]

Access: internal: For use by ServiceWiring

Definition at line 254 of file LocalisationCache.php.

◆ SOURCEPREFIX_SEPARATOR

const LocalisationCache::SOURCEPREFIX_SEPARATOR = ':'

protected

Separator for the source language prefix.

Definition at line 189 of file LocalisationCache.php.

◆ VERSION

const LocalisationCache::VERSION = 5

Definition at line 47 of file LocalisationCache.php.

The documentation for this class was generated from the following file:

includes/language/LocalisationCache.php

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ buildPreload()

◆ disableBackend()

◆ getCompiledPluralRules()

◆ getItem()

◆ getMessagesDirs()

◆ getPluralRules()

◆ getPluralRuleTypes()

◆ getStoreFromConf()

◆ getSubitem()

◆ getSubitemList()

◆ getSubitemWithSource()

◆ initLanguage()

◆ initShallowFallback()

◆ isExpired()

◆ isMergeableKey()

◆ loadItem()

◆ loadPluralFile()

◆ loadPluralFiles()

◆ loadSubitem()

◆ mergeExtensionItem()

◆ mergeItem()

◆ mergeMagicWords()

◆ readJSONFile()

◆ readPHPFile()

◆ readSourceFilesAndRegisterDeps()

◆ recache()

◆ unload()

◆ unloadAll()

Member Data Documentation

◆ $allKeys

◆ $data

◆ $magicWordKeys

◆ $mergeableAliasListKeys

◆ $mergeableListKeys

◆ $mergeableMapKeys

◆ $optionalMergeKeys

◆ $preloadedKeys

◆ $sourceLanguage

◆ $sourcePrefixKeys

◆ $splitKeys

◆ CONSTRUCTOR_OPTIONS

◆ SOURCEPREFIX_SEPARATOR

◆ VERSION