MediaWiki fundraising/REL1_35
MessageCache Class Reference

Cache of messages that are defined by MediaWiki namespace pages or by hooks. More...

Inheritance diagram for MessageCache:
Collaboration diagram for MessageCache:

Public Member Functions

 __construct (WANObjectCache $wanCache, BagOStuff $clusterCache, BagOStuff $serverCache, Language $contLang, ILanguageConverter $contLangConverter, LoggerInterface $logger, array $options, LanguageFactory $langFactory, LocalisationCache $localisationCache, LanguageNameUtils $languageNameUtils, LanguageFallback $languageFallback, HookContainer $hookContainer)
 
 clear ()
 Clear all stored messages in global and local cache.
 
 disable ()
 
 enable ()
 
 figureMessage ( $key)
 
 get ( $key, $useDB=true, $langcode=true)
 Get a message from either the content language or the user language.
 
 getAllMessageKeys ( $code)
 Get all message keys stored in the message cache for a given language.
 
 getCheckKey ( $code)
 
 getMsgFromNamespace ( $title, $code)
 Get a message from the MediaWiki namespace, with caching.
 
 getParser ()
 
 isDisabled ()
 Whether DB/cache usage is disabled for determining messages.
 
 parse ( $text, $title=null, $linestart=true, $interface=false, $language=null)
 
 refreshAndReplaceInternal ( $code, array $replacements)
 
 replace ( $title, $text)
 Updates cache as necessary when message page is changed.
 
 setLogger (LoggerInterface $logger)
 
 transform ( $message, $interface=false, $language=null, $title=null)
 
 updateMessageOverride (LinkTarget $linkTarget, Content $content=null)
 Purge message caches when a MediaWiki: page is created, updated, or deleted.
 

Static Public Member Functions

static normalizeKey ( $key)
 Normalize message key input.
 
static singleton ()
 Get the singleton instance of this class.
 

Protected Member Functions

 getLocalCache ( $code)
 Try to load the cache from APC.
 
 getMessageFromFallbackChain ( $lang, $lckey, $useDB)
 Given a language, try and fetch messages from that language.
 
 getReentrantScopedLock ( $key, $timeout=self::WAIT_SEC)
 
 getValidationHash ( $code)
 Get the md5 used to validate the local APC cache.
 
 isCacheExpired ( $cache)
 Is the given cache array expired due to time passing or a version change?
 
 load ( $code, $mode=null)
 Loads messages from caches or from database in this order: (1) local message cache (if $wgUseLocalMessageCache is enabled) (2) memcached (3) from the database.
 
 loadFromDB ( $code, $mode=null)
 Loads cacheable messages from the database.
 
 loadFromDBWithLock ( $code, array &$where, $mode=null)
 
 saveToCaches (array $cache, $dest, $code=false)
 Shortcut to update caches.
 
 saveToLocalCache ( $code, $cache)
 Save the cache to APC.
 
 setValidationHash ( $code, array $cache)
 Set the md5 used to validate the local disk cache.
 

Protected Attributes

MapCacheLRU $cache
 Process cache of loaded messages that are defined in MediaWiki namespace.
 
bool[] $cacheVolatile = []
 Map of (language code => boolean)
 
BagOStuff $clusterCache
 
Language $contLang
 
ILanguageConverter $contLangConverter
 
LanguageFactory $langFactory
 
LanguageFallback $languageFallback
 
LanguageNameUtils $languageNameUtils
 
LocalisationCache $localisationCache
 
bool $mDisable
 Should mean that database cannot be used, but check.
 
bool $mInParser = false
 
Parser $mParser
 
ParserOptions $mParserOptions
 Message cache has its own parser which it uses to transform messages.
 
BagOStuff $srvCache
 
WANObjectCache $wanCache
 

Private Member Functions

 bigMessageCacheKey ( $hash, $title)
 
 getMessageForLang ( $lang, $lckey, $useDB, &$alreadyTried)
 Given a language, try and fetch messages from that language and its fallbacks.
 
 getMessagePageName ( $langcode, $uckey)
 Get the message page name for a given language.
 
 getMessageTextFromContent (Content $content=null)
 
 getParserOptions ()
 ParserOptions is lazy initialised.
 
 isLanguageLoaded ( $lang)
 Whether the language was loaded and its data is still in the process cache.
 
 isMainCacheable ( $name, $code=null)
 Can the given DB key be added to the main cache blob? To reduce the impact of abuse of the MediaWiki namespace by {{int:}} and CentralNotice, this is only true if the page overrides a predefined message.
 
 loadCachedMessagePageEntry ( $dbKey, $code, $hash)
 

Private Attributes

HookRunner $hookRunner
 
LoggerInterface $logger
 
array $systemMessageNames
 Map of (lowercase message key => unused) for all software defined messages.
 
const FOR_UPDATE = 1
 
const LOCK_TTL = 30
 How long memcached locks last.
 
const WAIT_SEC = 15
 How long to wait for memcached locks.
 

Detailed Description

Cache of messages that are defined by MediaWiki namespace pages or by hooks.

Performs various MediaWiki namespace-related functions

Definition at line 50 of file MessageCache.php.

Constructor & Destructor Documentation

◆ __construct()

MessageCache::__construct ( WANObjectCache $wanCache,
BagOStuff $clusterCache,
BagOStuff $serverCache,
Language $contLang,
ILanguageConverter $contLangConverter,
LoggerInterface $logger,
array $options,
LanguageFactory $langFactory,
LocalisationCache $localisationCache,
LanguageNameUtils $languageNameUtils,
LanguageFallback $languageFallback,
HookContainer $hookContainer )

Definition at line 171 of file MessageCache.php.

References true.

Member Function Documentation

◆ bigMessageCacheKey()

MessageCache::bigMessageCacheKey ( $hash,
$title )
private
Parameters
string$hashHash for this version of the entire key/value overrides map
string$titleMessage cache key with initial uppercase letter
Returns
string

Definition at line 1470 of file MessageCache.php.

References $title.

Referenced by loadCachedMessagePageEntry(), and refreshAndReplaceInternal().

◆ clear()

MessageCache::clear ( )

Clear all stored messages in global and local cache.

Mainly used after a mass rebuild

Definition at line 1353 of file MessageCache.php.

References getCheckKey().

◆ disable()

MessageCache::disable ( )

Definition at line 1324 of file MessageCache.php.

◆ enable()

MessageCache::enable ( )

Definition at line 1328 of file MessageCache.php.

◆ figureMessage()

MessageCache::figureMessage ( $key)
Parameters
string$key
Returns
array

Definition at line 1365 of file MessageCache.php.

References $lang, and $wgLanguageCode.

Referenced by replace().

◆ get()

MessageCache::get ( $key,
$useDB = true,
$langcode = true )

Get a message from either the content language or the user language.

First, assemble a list of languages to attempt getting the message from. This chain begins with the requested language and its fallbacks and then continues with the content language and its fallbacks. For each language in the chain, the following process will occur (in this order):

  1. If a language-specific override, i.e., [[MW:msg/lang]], is available, use that. Note: for the content language, there is no /lang subpage.
  2. Fetch from the static CDB cache.
  3. If available, check the database for fallback language overrides.

This process provides a number of guarantees. When changing this code, make sure all of these guarantees are preserved.

  • If the requested language is not the content language, then the CDB cache for that specific language will take precedence over the root database page ([[MW:msg]]).
  • Fallbacks will be just that: fallbacks. A fallback language will never be reached if the message is available anywhere in the language for which it is a fallback.
Parameters
string$keyThe message key
bool$useDBIf true, look for the message in the DB, false to use only the compiled l10n cache.
bool | string | object$langcodeCode of the language to get the message for.
  • If string and a valid code, will create a standard language object
  • If string but not a valid code, will create a basic language object
  • If boolean and false, create object from the current users language
  • If boolean and true, create object from the wikis content language
  • If language object, use it as given
Exceptions
MWExceptionWhen given an invalid key
Returns
string|bool False if the message doesn't exist, otherwise the message (which can be empty)

Definition at line 926 of file MessageCache.php.

References getMessageFromFallbackChain(), and wfGetLangObj().

◆ getAllMessageKeys()

MessageCache::getAllMessageKeys ( $code)

Get all message keys stored in the message cache for a given language.

If $code is the content language code, this will return all message keys for which MediaWiki:msgkey exists. If $code is another language code, this will ONLY return message keys for which MediaWiki:msgkey/$code exists.

Parameters
string$codeLanguage code
Returns
array Array of message keys (strings)

Definition at line 1391 of file MessageCache.php.

References $cache, and load().

◆ getCheckKey()

MessageCache::getCheckKey ( $code)
Parameters
string$codeLanguage code
Returns
string WAN cache key usable as a "check key" against language page edits

Definition at line 1433 of file MessageCache.php.

Referenced by clear(), and refreshAndReplaceInternal().

◆ getLocalCache()

MessageCache::getLocalCache ( $code)
protected

Try to load the cache from APC.

Parameters
string$codeOptional language code, see documentation of load().
Returns
array|bool The cache array, or false if not in cache.

Definition at line 240 of file MessageCache.php.

Referenced by load().

◆ getMessageForLang()

MessageCache::getMessageForLang ( $lang,
$lckey,
$useDB,
& $alreadyTried )
private

Given a language, try and fetch messages from that language and its fallbacks.

See also
MessageCache::get
Parameters
Language | StubObject$langPreferred language
string$lckeyLowercase key for the message (as for localisation cache)
bool$useDBWhether to include messages from the wiki database
bool[]&$alreadyTriedContains true for each language that has been tried already
Returns
string|bool The message, or false if not found

Definition at line 1025 of file MessageCache.php.

References $lang, getMessagePageName(), and getMsgFromNamespace().

Referenced by getMessageFromFallbackChain().

◆ getMessageFromFallbackChain()

MessageCache::getMessageFromFallbackChain ( $lang,
$lckey,
$useDB )
protected

Given a language, try and fetch messages from that language.

Will also consider fallbacks of that language, the site language, and fallbacks for the site language.

See also
MessageCache::get
Parameters
Language | StubObject$langPreferred language
string$lckeyLowercase key for the message (as for localisation cache)
bool$useDBWhether to include messages from the wiki database
Returns
string|bool The message, or false if not found

Definition at line 1001 of file MessageCache.php.

References $lang, and getMessageForLang().

Referenced by get().

◆ getMessagePageName()

MessageCache::getMessagePageName ( $langcode,
$uckey )
private

Get the message page name for a given language.

Parameters
string$langcode
string$uckeyUppercase key for the message
Returns
string The page name

Definition at line 1081 of file MessageCache.php.

References $wgLanguageCode.

Referenced by getMessageForLang().

◆ getMessageTextFromContent()

MessageCache::getMessageTextFromContent ( Content $content = null)
private
Parameters
Content | null$contentContent or null if the message page does not exist
Returns
string|bool|null Returns false if $content is null and null on error

Definition at line 1441 of file MessageCache.php.

References $content.

Referenced by loadCachedMessagePageEntry(), loadFromDB(), refreshAndReplaceInternal(), and updateMessageOverride().

◆ getMsgFromNamespace()

MessageCache::getMsgFromNamespace ( $title,
$code )

Get a message from the MediaWiki namespace, with caching.

The key must first be converted to two-part lang/msg form if necessary.

Unlike self::get(), this function doesn't resolve fallback chains, and some callers require this behavior. LanguageConverter::parseCachedTable() and self::get() are some examples in core.

Parameters
string$titleMessage cache key with initial uppercase letter
string$codeCode denoting the language to try
Returns
string|bool The message, or false if it does not exist or on error

Definition at line 1104 of file MessageCache.php.

References $title, isMainCacheable(), load(), and loadCachedMessagePageEntry().

Referenced by getMessageForLang().

◆ getParser()

MessageCache::getParser ( )
Returns
Parser

Definition at line 1264 of file MessageCache.php.

Referenced by parse(), and transform().

◆ getParserOptions()

MessageCache::getParserOptions ( )
private

ParserOptions is lazy initialised.

Returns
ParserOptions

Definition at line 211 of file MessageCache.php.

Referenced by parse(), and transform().

◆ getReentrantScopedLock()

MessageCache::getReentrantScopedLock ( $key,
$timeout = self::WAIT_SEC )
protected
Parameters
string$keyA language message cache key that stores blobs
int$timeoutWait timeout in seconds
Returns
null|ScopedCallback

Definition at line 889 of file MessageCache.php.

Referenced by load(), loadFromDBWithLock(), and refreshAndReplaceInternal().

◆ getValidationHash()

MessageCache::getValidationHash ( $code)
protected

Get the md5 used to validate the local APC cache.

Parameters
string$code
Returns
array (hash or false, bool expiry/volatility status)

Definition at line 835 of file MessageCache.php.

Referenced by load().

◆ isCacheExpired()

MessageCache::isCacheExpired ( $cache)
protected

Is the given cache array expired due to time passing or a version change?

Parameters
array$cache
Returns
bool

Definition at line 792 of file MessageCache.php.

References $cache, MSG_CACHE_VERSION, and wfTimestampNow().

Referenced by load().

◆ isDisabled()

MessageCache::isDisabled ( )

Whether DB/cache usage is disabled for determining messages.

If so, this typically indicates either:

  • a) load() failed to find a cached copy nor query the DB
  • b) we are in a special context or error mode that cannot use the DB If the DB is ignored, any derived HTML output or cached objects may be wrong. To avoid long-term cache pollution, TTLs can be adjusted accordingly.
Returns
bool
Since
1.27

Definition at line 1344 of file MessageCache.php.

◆ isLanguageLoaded()

MessageCache::isLanguageLoaded ( $lang)
private

Whether the language was loaded and its data is still in the process cache.

Parameters
string$lang
Returns
bool

Definition at line 617 of file MessageCache.php.

References $lang.

Referenced by load().

◆ isMainCacheable()

MessageCache::isMainCacheable ( $name,
$code = null )
private

Can the given DB key be added to the main cache blob? To reduce the impact of abuse of the MediaWiki namespace by {{int:}} and CentralNotice, this is only true if the page overrides a predefined message.

Parameters
string$nameMessage name (possibly with /code suffix)
string | null$codeThe language code. If this is null, message presence will be bulk loaded for the content language. Otherwise, presence will be detected by loading the specified message.
Returns
bool

Definition at line 638 of file MessageCache.php.

References $wgLanguageCode.

Referenced by getMsgFromNamespace(), and loadFromDB().

◆ load()

MessageCache::load ( $code,
$mode = null )
protected

Loads messages from caches or from database in this order: (1) local message cache (if $wgUseLocalMessageCache is enabled) (2) memcached (3) from the database.

When successfully loading from (2) or (3), all higher level caches are updated for the newest version.

Nothing is loaded if member variable mDisable is true, either manually set by calling code or if message loading fails (is this possible?).

Returns true if cache is already populated or it was successfully populated, or false if populating empty cache fails. Also returns true if MessageCache is disabled.

Parameters
string$codeLanguage to which load messages
int | null$modeUse MessageCache::FOR_UPDATE to skip process cache [optional]
Exceptions
InvalidArgumentException
Returns
bool

Definition at line 278 of file MessageCache.php.

References $cache, $success, getLocalCache(), getReentrantScopedLock(), getValidationHash(), isCacheExpired(), isLanguageLoaded(), loadFromDBWithLock(), and saveToCaches().

Referenced by getAllMessageKeys(), getMsgFromNamespace(), loadFromDB(), and refreshAndReplaceInternal().

◆ loadCachedMessagePageEntry()

MessageCache::loadCachedMessagePageEntry ( $dbKey,
$code,
$hash )
private
Parameters
string$dbKey
string$code
string$hash
Returns
string Either " <MESSAGE>" or "!NONEXISTANT"

Definition at line 1178 of file MessageCache.php.

References $content, $title, bigMessageCacheKey(), DB_REPLICA, getMessageTextFromContent(), NS_MEDIAWIKI, and wfGetDB().

Referenced by getMsgFromNamespace().

◆ loadFromDB()

MessageCache::loadFromDB ( $code,
$mode = null )
protected

Loads cacheable messages from the database.

Messages bigger than $wgMaxMsgCacheEntrySize are assigned a special value, and are loaded on-demand from the database later.

Parameters
string$codeLanguage code
int | null$modeUse MessageCache::FOR_UPDATE to skip process cache
Returns
array Loaded messages for storing in caches

Definition at line 483 of file MessageCache.php.

References $cache, $content, $dbr, $res, $revQuery, $wgAdaptiveMessageCache, $wgLanguageCode, $wgMaxMsgCacheEntrySize, DB_MASTER, DB_REPLICA, getMessageTextFromContent(), isMainCacheable(), load(), MSG_CACHE_VERSION, NS_MEDIAWIKI, serialize(), wfGetDB(), and wfTimestamp().

Referenced by loadFromDBWithLock(), and refreshAndReplaceInternal().

◆ loadFromDBWithLock()

MessageCache::loadFromDBWithLock ( $code,
array & $where,
$mode = null )
protected
Parameters
string$code
string[]&$whereList of debug comments
int | null$modeUse MessageCache::FOR_UPDATE to use DB_MASTER
Returns
bool|string True on success or one of ("cantacquire", "disabled")

Definition at line 421 of file MessageCache.php.

References $cache, getReentrantScopedLock(), loadFromDB(), and saveToCaches().

Referenced by load().

◆ normalizeKey()

static MessageCache::normalizeKey ( $key)
static

Normalize message key input.

Parameters
string$keyInput message key to be normalized
Returns
string Normalized message key

Definition at line 143 of file MessageCache.php.

◆ parse()

MessageCache::parse ( $text,
$title = null,
$linestart = true,
$interface = false,
$language = null )
Parameters
string$text
Title | null$title
bool$linestartWhether or not this is at the start of a line
bool$interfaceWhether this is an interface message
Language | string | null$languageLanguage code
Returns
ParserOutput|string

Definition at line 1284 of file MessageCache.php.

References $res, $title, $wgTitle, getParser(), getParserOptions(), and NS_SPECIAL.

◆ refreshAndReplaceInternal()

MessageCache::refreshAndReplaceInternal ( $code,
array $replacements )
Parameters
string$code
array[]$replacementsList of (title, message key) pairs
Exceptions
MWException

Definition at line 703 of file MessageCache.php.

References $cache, $title, $wgMaxMsgCacheEntrySize, bigMessageCacheKey(), getCheckKey(), getMessageTextFromContent(), getReentrantScopedLock(), load(), loadFromDB(), NS_MEDIAWIKI, saveToCaches(), and serialize().

◆ replace()

MessageCache::replace ( $title,
$text )

Updates cache as necessary when message page is changed.

Parameters
string$titleMessage cache key with initial uppercase letter
string | bool$textNew contents of the page (false if deleted)

Definition at line 669 of file MessageCache.php.

References $title, $wgLanguageCode, and figureMessage().

Referenced by updateMessageOverride().

◆ saveToCaches()

MessageCache::saveToCaches ( array $cache,
$dest,
$code = false )
protected

Shortcut to update caches.

Parameters
array$cacheCached messages with a version.
string$destEither "local-only" to save to local caches only or "all" to save to all caches.
string | bool$codeLanguage code (default: false)
Returns
bool

Definition at line 815 of file MessageCache.php.

References $cache, $success, saveToLocalCache(), and setValidationHash().

Referenced by load(), loadFromDBWithLock(), and refreshAndReplaceInternal().

◆ saveToLocalCache()

MessageCache::saveToLocalCache ( $code,
$cache )
protected

Save the cache to APC.

Parameters
string$code
array$cacheThe cache array

Definition at line 252 of file MessageCache.php.

References $cache.

Referenced by saveToCaches().

◆ setLogger()

MessageCache::setLogger ( LoggerInterface $logger)

Definition at line 202 of file MessageCache.php.

◆ setValidationHash()

MessageCache::setValidationHash ( $code,
array $cache )
protected

Set the md5 used to validate the local disk cache.

If $cache has a 'LATEST' UNIX timestamp key, then the hash will not be treated as "volatile" by getValidationHash() for the next few seconds. This is triggered when $cache is generated using FOR_UPDATE mode.

Parameters
string$code
array$cacheCached messages with a version

Definition at line 873 of file MessageCache.php.

References $cache.

Referenced by saveToCaches().

◆ singleton()

static MessageCache::singleton ( )
static

Get the singleton instance of this class.

Deprecated
in 1.34 inject an instance of this class instead of using global state
Since
1.18
Returns
MessageCache

Definition at line 133 of file MessageCache.php.

◆ transform()

MessageCache::transform ( $message,
$interface = false,
$language = null,
$title = null )
Parameters
string$message
bool$interface
Language | null$language
Title | null$title
Returns
string

Definition at line 1235 of file MessageCache.php.

References $title, getParser(), and getParserOptions().

Referenced by EmailNotification\composeCommonMailtext().

◆ updateMessageOverride()

MessageCache::updateMessageOverride ( LinkTarget $linkTarget,
Content $content = null )

Purge message caches when a MediaWiki: page is created, updated, or deleted.

Parameters
LinkTarget$linkTargetMessage page title
Content | null$contentNew content for edit/create, null on deletion
Since
1.29

Definition at line 1416 of file MessageCache.php.

References $content, MediaWiki\Linker\LinkTarget\getDBkey(), getMessageTextFromContent(), and replace().

Member Data Documentation

◆ $cache

MapCacheLRU MessageCache::$cache
protected

Process cache of loaded messages that are defined in MediaWiki namespace.

Map of (language code => key => " <MESSAGE>" or "!TOO BIG" or "!ERROR")

Definition at line 72 of file MessageCache.php.

◆ $cacheVolatile

bool [] MessageCache::$cacheVolatile = []
protected

Map of (language code => boolean)

Definition at line 84 of file MessageCache.php.

◆ $clusterCache

BagOStuff MessageCache::$clusterCache
protected

Definition at line 108 of file MessageCache.php.

◆ $contLang

Language MessageCache::$contLang
protected

Definition at line 112 of file MessageCache.php.

◆ $contLangConverter

ILanguageConverter MessageCache::$contLangConverter
protected

Definition at line 114 of file MessageCache.php.

◆ $hookRunner

HookRunner MessageCache::$hookRunner
private

Definition at line 124 of file MessageCache.php.

◆ $langFactory

LanguageFactory MessageCache::$langFactory
protected

Definition at line 116 of file MessageCache.php.

◆ $languageFallback

LanguageFallback MessageCache::$languageFallback
protected

Definition at line 122 of file MessageCache.php.

◆ $languageNameUtils

LanguageNameUtils MessageCache::$languageNameUtils
protected

Definition at line 120 of file MessageCache.php.

◆ $localisationCache

LocalisationCache MessageCache::$localisationCache
protected

Definition at line 118 of file MessageCache.php.

◆ $logger

LoggerInterface MessageCache::$logger
private
Initial value:
=
private const WAN_TTL IExpiringStore::TTL_DAY

Definition at line 65 of file MessageCache.php.

◆ $mDisable

bool MessageCache::$mDisable
protected

Should mean that database cannot be used, but check.

Definition at line 90 of file MessageCache.php.

◆ $mInParser

bool MessageCache::$mInParser = false
protected

Definition at line 103 of file MessageCache.php.

◆ $mParser

Parser MessageCache::$mParser
protected

Definition at line 98 of file MessageCache.php.

◆ $mParserOptions

ParserOptions MessageCache::$mParserOptions
protected

Message cache has its own parser which it uses to transform messages.

Definition at line 96 of file MessageCache.php.

◆ $srvCache

BagOStuff MessageCache::$srvCache
protected

Definition at line 110 of file MessageCache.php.

◆ $systemMessageNames

array MessageCache::$systemMessageNames
private

Map of (lowercase message key => unused) for all software defined messages.

Definition at line 79 of file MessageCache.php.

◆ $wanCache

WANObjectCache MessageCache::$wanCache
protected

Definition at line 106 of file MessageCache.php.

◆ FOR_UPDATE

const MessageCache::FOR_UPDATE = 1
private

Definition at line 51 of file MessageCache.php.

◆ LOCK_TTL

const MessageCache::LOCK_TTL = 30
private

How long memcached locks last.

Definition at line 56 of file MessageCache.php.

◆ WAIT_SEC

const MessageCache::WAIT_SEC = 15
private

How long to wait for memcached locks.

Definition at line 54 of file MessageCache.php.


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