MediaWiki  master
LocalisationCache Class Reference

Class for caching the contents of localisation files, Messages*.php and *.i18n.php. More...

Inheritance diagram for LocalisationCache:
Collaboration diagram for LocalisationCache:

Public Member Functions

 __construct (ServiceOptions $options, LCStore $store, LoggerInterface $logger, array $clearStoreCallbacks, LanguageNameUtils $langNameUtils)
 For constructor parameters, see the documentation in DefaultSettings.php for $wgLocalisationCacheConf. More...
 
 disableBackend ()
 Disable the storage backend. More...
 
 getCompiledPluralRules ( $code)
 Get the compiled plural rules for a given language from the XML files. More...
 
 getItem ( $code, $key)
 Get a cache item. More...
 
 getMessagesDirs ()
 Gets the combined list of messages dirs from core and extensions. More...
 
 getPluralRules ( $code)
 Get the plural rules for a given language from the XML files. More...
 
 getPluralRuleTypes ( $code)
 Get the plural rule types for a given language from the XML files. More...
 
 getSubitem ( $code, $key, $subkey)
 Get a subitem, for instance a single message for a given language. More...
 
 getSubitemList ( $code, $key)
 Get the list of subitem keys for a given item. More...
 
 initShallowFallback ( $primaryCode, $fallbackCode)
 Create a fallback from one language to another, without creating a complete persistent cache. More...
 
 isExpired ( $code)
 Returns true if the cache identified by $code is missing or expired. More...
 
 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. More...
 
 readJSONFile ( $fileName)
 Read a JSON file containing localisation messages. More...
 
 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. More...
 
 unload ( $code)
 Unload the data for a given language from the object cache. More...
 
 unloadAll ()
 Unload all data. More...
 

Static Public Member Functions

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

Public Attributes

const VERSION = 4
 

Static Public Attributes

static $allKeys
 All item keys. More...
 
static $magicWordKeys = [ 'magicWords' ]
 Keys for items that are formatted like $magicWords. More...
 
static $mergeableAliasListKeys = [ 'specialPageAliases' ]
 Keys for items which contain an array of arrays of equivalent aliases for each subitem. More...
 
static $mergeableListKeys = []
 Keys for items which are a numbered array. More...
 
static $mergeableMapKeys
 Keys for items which consist of associative arrays, which may be merged by a fallback sequence. More...
 
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". More...
 
static $preloadedKeys = [ 'dateFormats', 'namespaceNames' ]
 Keys which are loaded automatically by initLanguage() More...
 
static $splitKeys = [ 'messages' ]
 Keys for items where the subitems are stored in the backend separately. More...
 

Protected Member Functions

 buildPreload ( $data)
 Build the preload item from the given pre-cache data. More...
 
 initLanguage ( $code)
 Initialise a language in this object. More...
 
 loadItem ( $code, $key)
 Load an item into the cache. More...
 
 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. More...
 
 loadPluralFiles ()
 Load the plural XML files. More...
 
 loadSubitem ( $code, $key, $subkey)
 Load a subitem into the cache. More...
 
 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. More...
 
 mergeItem ( $key, &$value, $fallbackValue)
 Merge two localisation values, a primary and a fallback, overwriting the primary value in place. More...
 
 mergeMagicWords (&$value, $fallbackValue)
 
 readPHPFile ( $_fileName, $_fileType)
 Read a PHP file containing localisation data. More...
 
 readSourceFilesAndRegisterDeps ( $code, &$deps)
 Read the data from the source files for a given language, and register the relevant dependencies in the $deps array. More...
 

Protected Attributes

 $data = []
 The cache data. More...
 

Private Attributes

callable [] $clearStoreCallbacks
 See comment for parameter in constructor. More...
 
 $initialisedLangs = []
 An array where presence of a key indicates that that language has been initialised. More...
 
LanguageNameUtils $langNameUtils
 
 $loadedItems = []
 A 2-d associative array, code/key, where presence indicates that the item is loaded. More...
 
 $loadedSubitems = []
 A 3-d associative array, code/key/subkey, where presence indicates that the subitem is loaded. More...
 
LoggerInterface $logger
 
 $manualRecache = false
 True if recaching should only be done on an explicit call to recache(). More...
 
 $mergeableKeys = null
 
ServiceOptions $options
 
 $pluralRules = null
 Associative array of cached plural rules. More...
 
 $pluralRuleTypes = null
 Associative array of cached plural rule types. More...
 
 $recachedLangs = []
 An array where the keys are codes that have been recached by this instance. More...
 
 $shallowFallbacks = []
 An array mapping non-existent pseudo-languages to fallback languages. More...
 
LCStore $store
 The persistent store object. More...
 

Detailed Description

Class for caching the contents of localisation files, 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 41 of file LocalisationCache.php.

Constructor & Destructor Documentation

◆ __construct()

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

For constructor parameters, see the documentation in DefaultSettings.php for $wgLocalisationCacheConf.

Do not construct this directly. Use MediaWikiServices.

Parameters
ServiceOptions$options
LCStore$storeWhat 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
Exceptions
MWException

Definition at line 254 of file LocalisationCache.php.

References $clearStoreCallbacks, $langNameUtils, $logger, $options, $store, 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 1062 of file LocalisationCache.php.

References $data.

Referenced by recache().

◆ disableBackend()

LocalisationCache::disableBackend ( )

Disable the storage backend.

Definition at line 1107 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 608 of file LocalisationCache.php.

References getPluralRules().

Referenced by readSourceFilesAndRegisterDeps().

◆ 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

Definition at line 302 of file LocalisationCache.php.

References loadItem().

Referenced by getSubitemList(), and initLanguage().

◆ getMessagesDirs()

LocalisationCache::getMessagesDirs ( )

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

Since
1.25
Returns
array

Definition at line 822 of file LocalisationCache.php.

References $IP.

Referenced by recache().

◆ 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 631 of file LocalisationCache.php.

References loadPluralFiles().

Referenced by getCompiledPluralRules(), and readSourceFilesAndRegisterDeps().

◆ 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 645 of file LocalisationCache.php.

References loadPluralFiles().

Referenced by readSourceFilesAndRegisterDeps().

◆ getStoreFromConf()

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

Return a suitable LCStore as specified by the given configuration.

Since
1.34
Parameters
array$confIn the format of $wgLocalisationCacheConf
string | false | null$fallbackCacheDirIn case 'storeDirectory' isn't specified
Returns
LCStore

Definition at line 202 of file LocalisationCache.php.

Referenced by RebuildLocalisationCache\execute().

◆ 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

Definition at line 321 of file LocalisationCache.php.

References loadSubitem().

Referenced by getSubitemList(), and loadItem().

◆ 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 343 of file LocalisationCache.php.

References getItem(), and getSubitem().

◆ initLanguage()

LocalisationCache::initLanguage (   $code)
protected

Initialise a language in this object.

Rebuild the cache if necessary.

Parameters
string$code
Exceptions
MWException

Definition at line 472 of file LocalisationCache.php.

References getItem(), initShallowFallback(), isExpired(), and recache().

Referenced by loadItem(), and loadSubitem().

◆ 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 533 of file LocalisationCache.php.

Referenced by initLanguage().

◆ isExpired()

LocalisationCache::isExpired (   $code)

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

Parameters
string$code
Returns
bool

Definition at line 434 of file LocalisationCache.php.

References $keys, and CacheDependency\isExpired().

Referenced by initLanguage().

◆ 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 279 of file LocalisationCache.php.

Referenced by recache().

◆ loadItem()

LocalisationCache::loadItem (   $code,
  $key 
)
protected

Load an item into the cache.

Parameters
string$code
string$key

Definition at line 361 of file LocalisationCache.php.

References getSubitem(), and initLanguage().

Referenced by getItem(), and loadSubitem().

◆ 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 674 of file LocalisationCache.php.

Referenced by loadPluralFiles().

◆ loadPluralFiles()

LocalisationCache::loadPluralFiles ( )
protected

Load the plural XML files.

Definition at line 655 of file LocalisationCache.php.

References $IP, and loadPluralFile().

Referenced by getPluralRules(), and getPluralRuleTypes().

◆ loadSubitem()

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

Load a subitem into the cache.

Parameters
string$code
string$key
string$subkey

Definition at line 398 of file LocalisationCache.php.

References initLanguage(), and loadItem().

Referenced by getSubitem().

◆ 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 803 of file LocalisationCache.php.

References mergeItem().

◆ 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 745 of file LocalisationCache.php.

References mergeMagicWords().

Referenced by mergeExtensionItem(), and recache().

◆ mergeMagicWords()

LocalisationCache::mergeMagicWords ( $value,
  $fallbackValue 
)
protected
Parameters
mixed&$value
mixed$fallbackValue

Definition at line 776 of file LocalisationCache.php.

Referenced by mergeItem().

◆ readJSONFile()

LocalisationCache::readJSONFile (   $fileName)

Read a JSON file containing localisation messages.

Parameters
string$fileNameName of file to read
Exceptions
MWExceptionIf 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 576 of file LocalisationCache.php.

References $data, and FormatJson\decode().

Referenced by recache().

◆ readPHPFile()

LocalisationCache::readPHPFile (   $_fileName,
  $_fileType 
)
protected

Read a PHP file containing localisation data.

Parameters
string$_fileName
string$_fileType
Exceptions
MWException
Returns
array

Definition at line 547 of file LocalisationCache.php.

References $data.

Referenced by readSourceFilesAndRegisterDeps(), and recache().

◆ 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 713 of file LocalisationCache.php.

References $data, $IP, getCompiledPluralRules(), getPluralRules(), getPluralRuleTypes(), and readPHPFile().

Referenced by recache().

◆ 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

Definition at line 839 of file LocalisationCache.php.

References $data, $dirs, buildPreload(), getMessagesDirs(), isMergeableKey(), mergeItem(), readJSONFile(), readPHPFile(), readSourceFilesAndRegisterDeps(), and Hooks\run().

Referenced by initLanguage().

◆ unload()

LocalisationCache::unload (   $code)

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

Reduces memory usage.

Parameters
string$code

Definition at line 1081 of file LocalisationCache.php.

Referenced by unloadAll().

◆ unloadAll()

LocalisationCache::unloadAll ( )

Unload all data.

Definition at line 1098 of file LocalisationCache.php.

References $lang, and unload().

Member Data Documentation

◆ $allKeys

LocalisationCache::$allKeys
static
Initial value:
= [
'fallback', 'namespaceNames', 'bookstoreList',
'magicWords', 'messages', 'rtl', 'capitalizeAllNouns',
'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 118 of file LocalisationCache.php.

◆ $clearStoreCallbacks

callable [] LocalisationCache::$clearStoreCallbacks
private

See comment for parameter in constructor.

Definition at line 75 of file LocalisationCache.php.

Referenced by __construct().

◆ $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 60 of file LocalisationCache.php.

Referenced by buildPreload(), readJSONFile(), LocalisationCacheBulkLoad\readPHPFile(), readPHPFile(), readSourceFilesAndRegisterDeps(), and recache().

◆ $initialisedLangs

LocalisationCache::$initialisedLangs = []
private

An array where presence of a key indicates that that language has been initialised.

Initialisation includes checking for cache expiry and doing any necessary updates.

Definition at line 101 of file LocalisationCache.php.

◆ $langNameUtils

LanguageNameUtils LocalisationCache::$langNameUtils
private

Definition at line 78 of file LocalisationCache.php.

Referenced by __construct().

◆ $loadedItems

LocalisationCache::$loadedItems = []
private

A 2-d associative array, code/key, where presence indicates that the item is loaded.

Value arbitrary.

For split items, if set, this indicates that all of the subitems have been loaded.

Definition at line 88 of file LocalisationCache.php.

◆ $loadedSubitems

LocalisationCache::$loadedSubitems = []
private

A 3-d associative array, code/key/subkey, where presence indicates that the subitem is loaded.

Only used for the split items, i.e. messages.

Definition at line 94 of file LocalisationCache.php.

◆ $logger

LoggerInterface LocalisationCache::$logger
private

Definition at line 72 of file LocalisationCache.php.

Referenced by __construct().

◆ $magicWordKeys

LocalisationCache::$magicWordKeys = [ 'magicWords' ]
static

Keys for items that are formatted like $magicWords.

Definition at line 160 of file LocalisationCache.php.

◆ $manualRecache

LocalisationCache::$manualRecache = false
private

True if recaching should only be done on an explicit call to recache().

Setting this reduces the overhead of cache freshness checking, which requires doing a stat() for every extension i18n file.

Definition at line 52 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 148 of file LocalisationCache.php.

◆ $mergeableKeys

LocalisationCache::$mergeableKeys = null
private

Definition at line 192 of file LocalisationCache.php.

◆ $mergeableListKeys

LocalisationCache::$mergeableListKeys = []
static

Keys for items which are a numbered array.

Definition at line 142 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 135 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 155 of file LocalisationCache.php.

◆ $options

ServiceOptions LocalisationCache::$options
private

Definition at line 45 of file LocalisationCache.php.

Referenced by __construct().

◆ $pluralRules

LocalisationCache::$pluralRules = null
private

Associative array of cached plural rules.

The key is the language code, the value is an array of plural rules for that language.

Definition at line 176 of file LocalisationCache.php.

◆ $pluralRuleTypes

LocalisationCache::$pluralRuleTypes = null
private

Associative array of cached plural rule types.

The key is the language code, the value is an array of plural rule types for that language. For example, $pluralRuleTypes['ar'] = ['zero', 'one', 'two', 'few', 'many']. The index for each rule type matches the index for the rule in $pluralRules, thus allowing correlation between the two. The reason we don't just use the type names as the keys in $pluralRules is because Language::convertPlural applies the rules based on numeric order (or explicit numeric parameter), not based on the name of the rule type. For example, {{plural:count|wordform1|wordform2|wordform3}}, rather than {{plural:count|one=wordform1|two=wordform2|many=wordform3}}.

Definition at line 190 of file LocalisationCache.php.

◆ $preloadedKeys

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

Keys which are loaded automatically by initLanguage()

Definition at line 170 of file LocalisationCache.php.

◆ $recachedLangs

LocalisationCache::$recachedLangs = []
private

An array where the keys are codes that have been recached by this instance.

Definition at line 113 of file LocalisationCache.php.

◆ $shallowFallbacks

LocalisationCache::$shallowFallbacks = []
private

An array mapping non-existent pseudo-languages to fallback languages.

This is filled by initShallowFallback() when data is requested from a language that lacks a Messages*.php file.

Definition at line 108 of file LocalisationCache.php.

◆ $splitKeys

LocalisationCache::$splitKeys = [ 'messages' ]
static

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

Definition at line 165 of file LocalisationCache.php.

◆ $store

LCStore LocalisationCache::$store
private

The persistent store object.

An instance of LCStore.

Definition at line 67 of file LocalisationCache.php.

Referenced by __construct().

◆ VERSION

const LocalisationCache::VERSION = 4

Definition at line 42 of file LocalisationCache.php.


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