includes/cache/MessageCache.php

   1 <?php
   2 /**
   3  * Localisation messages cache.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Cache
  22  */
  23
  24 /**
  25  * MediaWiki message cache structure version.
  26  * Bump this whenever the message cache format has changed.
  27  */
  28 define( 'MSG_CACHE_VERSION', 1 );
  29
  30 /**
  31  * Memcached timeout when loading a key.
  32  * See MessageCache::load()
  33  */
  34 define( 'MSG_LOAD_TIMEOUT', 60 );
  35
  36 /**
  37  * Memcached timeout when locking a key for a writing operation.
  38  * See MessageCache::lock()
  39  */
  40 define( 'MSG_LOCK_TIMEOUT', 30 );
  41 /**
  42  * Number of times we will try to acquire a lock from Memcached.
  43  * This comes in addition to MSG_LOCK_TIMEOUT.
  44  */
  45 define( 'MSG_WAIT_TIMEOUT', 30 );
  46
  47 /**
  48  * Message cache
  49  * Performs various MediaWiki namespace-related functions
  50  * @ingroup Cache
  51  */
  52 class MessageCache {
  53         const FOR_UPDATE = 1; // force message reload
  54
  55         /**
  56          * Process local cache of loaded messages that are defined in
  57          * MediaWiki namespace. First array level is a language code,
  58          * second level is message key and the values are either message
  59          * content prefixed with space, or !NONEXISTENT for negative
  60          * caching.
  61          */
  62         protected $mCache;
  63
  64         /**
  65          * Should  mean that database cannot be used, but check
  66          * @var bool $mDisable
  67          */
  68         protected $mDisable;
  69
  70         /**
  71          * Lifetime for cache, used by object caching.
  72          * Set on construction, see __construct().
  73          */
  74         protected $mExpiry;
  75
  76         /**
  77          * Message cache has its own parser which it uses to transform
  78          * messages.
  79          */
  80         protected $mParserOptions, $mParser;
  81
  82         /**
  83          * Variable for tracking which variables are already loaded
  84          * @var array $mLoadedLanguages
  85          */
  86         protected $mLoadedLanguages = array();
  87
  88         /**
  89          * @var bool $mInParser
  90          */
  91         protected $mInParser = false;
  92
  93         /** @var BagOStuff */
  94         protected $mMemc;
  95         /** @var WANObjectCache */
  96         protected $wanCache;
  97
  98         /**
  99          * Singleton instance
 100          *
 101          * @var MessageCache $instance
 102          */
 103         private static $instance;
 104
 105         /**
 106          * Get the signleton instance of this class
 107          *
 108          * @since 1.18
 109          * @return MessageCache
 110          */
 111         public static function singleton() {
 112                 if ( is_null( self::$instance ) ) {
 113                         global $wgUseDatabaseMessages, $wgMsgCacheExpiry;
 114                         self::$instance = new self(
 115                                 wfGetMessageCacheStorage(),
 116                                 $wgUseDatabaseMessages,
 117                                 $wgMsgCacheExpiry
 118                         );
 119                 }
 120
 121                 return self::$instance;
 122         }
 123
 124         /**
 125          * Destroy the singleton instance
 126          *
 127          * @since 1.18
 128          */
 129         public static function destroyInstance() {
 130                 self::$instance = null;
 131         }
 132
 133         /**
 134          * Normalize message key input
 135          *
 136          * @param string $key Input message key to be normalized
 137          * @return string Normalized message key
 138          */
 139         public static function normalizeKey( $key ) {
 140                 global $wgContLang;
 141                 $lckey = strtr( $key, ' ', '_' );
 142                 if ( ord( $lckey ) < 128 ) {
 143                         $lckey[0] = strtolower( $lckey[0] );
 144                 } else {
 145                         $lckey = $wgContLang->lcfirst( $lckey );
 146                 }
 147
 148                 return $lckey;
 149         }
 150
 151         /**
 152          * @param BagOStuff $memCached A cache instance. If none, fall back to CACHE_NONE.
 153          * @param bool $useDB
 154          * @param int $expiry Lifetime for cache. @see $mExpiry.
 155          */
 156         function __construct( $memCached, $useDB, $expiry ) {
 157                 if ( !$memCached ) {
 158                         $memCached = wfGetCache( CACHE_NONE );
 159                 }
 160
 161                 $this->mMemc = $memCached;
 162                 $this->mDisable = !$useDB;
 163                 $this->mExpiry = $expiry;
 164
 165                 $this->wanCache = ObjectCache::getMainWANInstance();
 166         }
 167
 168         /**
 169          * ParserOptions is lazy initialised.
 170          *
 171          * @return ParserOptions
 172          */
 173         function getParserOptions() {
 174                 if ( !$this->mParserOptions ) {
 175                         $this->mParserOptions = new ParserOptions;
 176                         $this->mParserOptions->setEditSection( false );
 177                 }
 178
 179                 return $this->mParserOptions;
 180         }
 181
 182         /**
 183          * Try to load the cache from a local file.
 184          *
 185          * @param string $hash The hash of contents, to check validity.
 186          * @param string $code Optional language code, see documenation of load().
 187          * @return array The cache array
 188          */
 189         function getLocalCache( $hash, $code ) {
 190                 global $wgCacheDirectory;
 191
 192                 $filename = "$wgCacheDirectory/messages-" . wfWikiID() . "-$code";
 193
 194                 # Check file existence
 195                 MediaWiki\suppressWarnings();
 196                 $file = fopen( $filename, 'r' );
 197                 MediaWiki\restoreWarnings();
 198                 if ( !$file ) {
 199                         return false; // No cache file
 200                 }
 201
 202                 // Check to see if the file has the hash specified
 203                 $localHash = fread( $file, 32 );
 204                 if ( $hash === $localHash ) {
 205                         // All good, get the rest of it
 206                         $serialized = '';
 207                         while ( !feof( $file ) ) {
 208                                 $serialized .= fread( $file, 100000 );
 209                         }
 210                         fclose( $file );
 211
 212                         return unserialize( $serialized );
 213                 } else {
 214                         fclose( $file );
 215
 216                         return false; // Wrong hash
 217                 }
 218         }
 219
 220         /**
 221          * Save the cache to a local file.
 222          * @param string $serialized
 223          * @param string $hash
 224          * @param string $code
 225          */
 226         function saveToLocal( $serialized, $hash, $code ) {
 227                 global $wgCacheDirectory;
 228
 229                 $filename = "$wgCacheDirectory/messages-" . wfWikiID() . "-$code";
 230                 wfMkdirParents( $wgCacheDirectory, null, __METHOD__ ); // might fail
 231
 232                 MediaWiki\suppressWarnings();
 233                 $file = fopen( $filename, 'w' );
 234                 MediaWiki\restoreWarnings();
 235
 236                 if ( !$file ) {
 237                         wfDebug( "Unable to open local cache file for writing\n" );
 238
 239                         return;
 240                 }
 241
 242                 fwrite( $file, $hash . $serialized );
 243                 fclose( $file );
 244                 MediaWiki\suppressWarnings();
 245                 chmod( $filename, 0666 );
 246                 MediaWiki\restoreWarnings();
 247         }
 248
 249         /**
 250          * Loads messages from caches or from database in this order:
 251          * (1) local message cache (if $wgUseLocalMessageCache is enabled)
 252          * (2) memcached
 253          * (3) from the database.
 254          *
 255          * When succesfully loading from (2) or (3), all higher level caches are
 256          * updated for the newest version.
 257          *
 258          * Nothing is loaded if member variable mDisable is true, either manually
 259          * set by calling code or if message loading fails (is this possible?).
 260          *
 261          * Returns true if cache is already populated or it was succesfully populated,
 262          * or false if populating empty cache fails. Also returns true if MessageCache
 263          * is disabled.
 264          *
 265          * @param bool|string $code Language to which load messages
 266          * @param integer $mode Use MessageCache::FOR_UPDATE to skip process cache
 267          * @throws MWException
 268          * @return bool
 269          */
 270         function load( $code = false, $mode = null ) {
 271                 global $wgUseLocalMessageCache;
 272
 273                 if ( !is_string( $code ) ) {
 274                         # This isn't really nice, so at least make a note about it and try to
 275                         # fall back
 276                         wfDebug( __METHOD__ . " called without providing a language code\n" );
 277                         $code = 'en';
 278                 }
 279
 280                 # Don't do double loading...
 281                 if ( isset( $this->mLoadedLanguages[$code] ) && $mode != self::FOR_UPDATE ) {
 282                         return true;
 283                 }
 284
 285                 # 8 lines of code just to say (once) that message cache is disabled
 286                 if ( $this->mDisable ) {
 287                         static $shownDisabled = false;
 288                         if ( !$shownDisabled ) {
 289                                 wfDebug( __METHOD__ . ": disabled\n" );
 290                                 $shownDisabled = true;
 291                         }
 292
 293                         return true;
 294                 }
 295
 296                 # Loading code starts
 297                 $success = false; # Keep track of success
 298                 $staleCache = false; # a cache array with expired data, or false if none has been loaded
 299                 $hashExpired = false; # whether the cluster-local validation hash is stale
 300                 $where = array(); # Debug info, delayed to avoid spamming debug log too much
 301
 302                 # Local cache
 303                 # Hash of the contents is stored in memcache, to detect if local cache goes
 304                 # out of date (e.g. due to replace() on some other server)
 305                 if ( $wgUseLocalMessageCache ) {
 306                         list( $hash, $hashExpired ) = $this->getValidationHash( $code );
 307                         if ( $hash ) {
 308                                 $cache = $this->getLocalCache( $hash, $code );
 309                                 if ( !$cache ) {
 310                                         $where[] = 'local cache is empty or has the wrong hash';
 311                                 } elseif ( $this->isCacheExpired( $cache ) ) {
 312                                         $where[] = 'local cache is expired';
 313                                         $staleCache = $cache;
 314                                 } elseif ( $hashExpired ) {
 315                                         $where[] = 'local cache validation key is expired';
 316                                         $staleCache = $cache;
 317                                 } else {
 318                                         $where[] = 'got from local cache';
 319                                         $success = true;
 320                                         $this->mCache[$code] = $cache;
 321                                 }
 322                         }
 323                 }
 324
 325                 if ( !$success ) {
 326                         $cacheKey = wfMemcKey( 'messages', $code ); # Key in memc for messages
 327                         # Try the global cache. If it is empty, try to acquire a lock. If
 328                         # the lock can't be acquired, wait for the other thread to finish
 329                         # and then try the global cache a second time.
 330                         for ( $failedAttempts = 0; $failedAttempts < 2; $failedAttempts++ ) {
 331                                 if ( $hashExpired && $staleCache ) {
 332                                         # Do not bother fetching the whole cache blob to avoid I/O.
 333                                         # Instead, just try to get the non-blocking $statusKey lock
 334                                         # below, and use the local stale value if it was not acquired.
 335                                         $where[] = 'global cache is presumed expired';
 336                                 } else {
 337                                         $cache = $this->mMemc->get( $cacheKey );
 338                                         if ( !$cache ) {
 339                                                 $where[] = 'global cache is empty';
 340                                         } elseif ( $this->isCacheExpired( $cache ) ) {
 341                                                 $where[] = 'global cache is expired';
 342                                                 $staleCache = $cache;
 343                                         } else {
 344                                                 $where[] = 'got from global cache';
 345                                                 $this->mCache[$code] = $cache;
 346                                                 $this->saveToCaches( $cache, 'local-only', $code );
 347                                                 $success = true;
 348                                         }
 349                                 }
 350
 351                                 if ( $success ) {
 352                                         # Done, no need to retry
 353                                         break;
 354                                 }
 355
 356                                 # We need to call loadFromDB. Limit the concurrency to one process.
 357                                 # This prevents the site from going down when the cache expires.
 358                                 if ( $this->loadFromDBWithLock( $code, $where ) ) {
 359                                         # Load from DB complete, no need to retry
 360                                         $success = true;
 361                                         break;
 362                                 } elseif ( $staleCache ) {
 363                                         # Use the stale cache while some other thread constructs the new one
 364                                         $where[] = 'using stale cache';
 365                                         $this->mCache[$code] = $staleCache;
 366                                         $success = true;
 367                                         break;
 368                                 } elseif ( $failedAttempts > 0 ) {
 369                                         # Already retried once, still failed, so don't do another lock/unlock cycle
 370                                         # This case will typically be hit if memcached is down, or if
 371                                         # loadFromDB() takes longer than MSG_WAIT_TIMEOUT
 372                                         $where[] = "could not acquire status key.";
 373                                         break;
 374                                 } else {
 375                                         $statusKey = wfMemcKey( 'messages', $code, 'status' );
 376                                         $status = $this->mMemc->get( $statusKey );
 377                                         if ( $status === 'error' ) {
 378                                                 # Disable cache
 379                                                 break;
 380                                         } else {
 381                                                 # Wait for the other thread to finish, then retry
 382                                                 $where[] = 'waited for other thread to complete';
 383                                                 $this->lock( $cacheKey );
 384                                                 $this->unlock( $cacheKey );
 385                                         }
 386                                 }
 387                         }
 388                 }
 389
 390                 if ( !$success ) {
 391                         $where[] = 'loading FAILED - cache is disabled';
 392                         $this->mDisable = true;
 393                         $this->mCache = false;
 394                         # This used to throw an exception, but that led to nasty side effects like
 395                         # the whole wiki being instantly down if the memcached server died
 396                 } else {
 397                         # All good, just record the success
 398                         $this->mLoadedLanguages[$code] = true;
 399                 }
 400
 401                 $info = implode( ', ', $where );
 402                 wfDebugLog( 'MessageCache', __METHOD__ . ": Loading $code... $info\n" );
 403
 404                 return $success;
 405         }
 406
 407         /**
 408          * @param string $code
 409          * @param array $where List of wfDebug() comments
 410          * @return bool Lock acquired and loadFromDB() called
 411          */
 412         protected function loadFromDBWithLock( $code, array &$where ) {
 413                 global $wgUseLocalMessageCache;
 414
 415                 $memCache = $this->mMemc;
 416
 417                 $statusKey = wfMemcKey( 'messages', $code, 'status' );
 418                 if ( !$memCache->add( $statusKey, 'loading', MSG_LOAD_TIMEOUT ) ) {
 419                         return false; // could not acquire lock
 420                 }
 421
 422                 # Unlock the status key if there is an exception
 423                 $statusUnlocker = new ScopedCallback( function () use ( $memCache, $statusKey ) {
 424                         $memCache->delete( $statusKey );
 425                 } );
 426
 427                 # Now let's regenerate
 428                 $where[] = 'loading from database';
 429
 430                 $cacheKey = wfMemcKey( 'messages', $code );
 431                 # Lock the cache to prevent conflicting writes
 432                 # If this lock fails, it doesn't really matter, it just means the
 433                 # write is potentially non-atomic, e.g. the results of a replace()
 434                 # may be discarded.
 435                 if ( $this->lock( $cacheKey ) ) {
 436                         $that = $this;
 437                         $mainUnlocker = new ScopedCallback( function () use ( $that, $cacheKey ) {
 438                                 $that->unlock( $cacheKey );
 439                         } );
 440                 } else {
 441                         $mainUnlocker = null;
 442                         $where[] = 'could not acquire main lock';
 443                 }
 444
 445                 $cache = $this->loadFromDB( $code );
 446                 $this->mCache[$code] = $cache;
 447                 $saveSuccess = $this->saveToCaches( $cache, 'all', $code );
 448
 449                 # Unlock
 450                 ScopedCallback::consume( $mainUnlocker );
 451                 ScopedCallback::consume( $statusUnlocker );
 452
 453                 if ( !$saveSuccess ) {
 454                         # Cache save has failed.
 455                         # There are two main scenarios where this could be a problem:
 456                         #
 457                         #   - The cache is more than the maximum size (typically
 458                         #     1MB compressed).
 459                         #
 460                         #   - Memcached has no space remaining in the relevant slab
 461                         #     class. This is unlikely with recent versions of
 462                         #     memcached.
 463                         #
 464                         # Either way, if there is a local cache, nothing bad will
 465                         # happen. If there is no local cache, disabling the message
 466                         # cache for all requests avoids incurring a loadFromDB()
 467                         # overhead on every request, and thus saves the wiki from
 468                         # complete downtime under moderate traffic conditions.
 469                         if ( !$wgUseLocalMessageCache ) {
 470                                 $memCache->set( $statusKey, 'error', 60 * 5 );
 471                                 $where[] = 'could not save cache, disabled globally for 5 minutes';
 472                         } else {
 473                                 $where[] = "could not save global cache";
 474                         }
 475                 }
 476
 477                 return true;
 478         }
 479
 480         /**
 481          * Loads cacheable messages from the database. Messages bigger than
 482          * $wgMaxMsgCacheEntrySize are assigned a special value, and are loaded
 483          * on-demand from the database later.
 484          *
 485          * @param string $code Language code.
 486          * @return array Loaded messages for storing in caches.
 487          */
 488         function loadFromDB( $code ) {
 489                 global $wgMaxMsgCacheEntrySize, $wgLanguageCode, $wgAdaptiveMessageCache;
 490
 491                 $dbr = wfGetDB( DB_SLAVE );
 492                 $cache = array();
 493
 494                 # Common conditions
 495                 $conds = array(
 496                         'page_is_redirect' => 0,
 497                         'page_namespace' => NS_MEDIAWIKI,
 498                 );
 499
 500                 $mostused = array();
 501                 if ( $wgAdaptiveMessageCache && $code !== $wgLanguageCode ) {
 502                         if ( !isset( $this->mCache[$wgLanguageCode] ) ) {
 503                                 $this->load( $wgLanguageCode );
 504                         }
 505                         $mostused = array_keys( $this->mCache[$wgLanguageCode] );
 506                         foreach ( $mostused as $key => $value ) {
 507                                 $mostused[$key] = "$value/$code";
 508                         }
 509                 }
 510
 511                 if ( count( $mostused ) ) {
 512                         $conds['page_title'] = $mostused;
 513                 } elseif ( $code !== $wgLanguageCode ) {
 514                         $conds[] = 'page_title' . $dbr->buildLike( $dbr->anyString(), '/', $code );
 515                 } else {
 516                         # Effectively disallows use of '/' character in NS_MEDIAWIKI for uses
 517                         # other than language code.
 518                         $conds[] = 'page_title NOT' . $dbr->buildLike( $dbr->anyString(), '/', $dbr->anyString() );
 519                 }
 520
 521                 # Conditions to fetch oversized pages to ignore them
 522                 $bigConds = $conds;
 523                 $bigConds[] = 'page_len > ' . intval( $wgMaxMsgCacheEntrySize );
 524
 525                 # Load titles for all oversized pages in the MediaWiki namespace
 526                 $res = $dbr->select( 'page', 'page_title', $bigConds, __METHOD__ . "($code)-big" );
 527                 foreach ( $res as $row ) {
 528                         $cache[$row->page_title] = '!TOO BIG';
 529                 }
 530
 531                 # Conditions to load the remaining pages with their contents
 532                 $smallConds = $conds;
 533                 $smallConds[] = 'page_latest=rev_id';
 534                 $smallConds[] = 'rev_text_id=old_id';
 535                 $smallConds[] = 'page_len <= ' . intval( $wgMaxMsgCacheEntrySize );
 536
 537                 $res = $dbr->select(
 538                         array( 'page', 'revision', 'text' ),
 539                         array( 'page_title', 'old_text', 'old_flags' ),
 540                         $smallConds,
 541                         __METHOD__ . "($code)-small"
 542                 );
 543
 544                 foreach ( $res as $row ) {
 545                         $text = Revision::getRevisionText( $row );
 546                         if ( $text === false ) {
 547                                 // Failed to fetch data; possible ES errors?
 548                                 // Store a marker to fetch on-demand as a workaround...
 549                                 $entry = '!TOO BIG';
 550                                 wfDebugLog(
 551                                         'MessageCache',
 552                                         __METHOD__
 553                                                 . ": failed to load message page text for {$row->page_title} ($code)"
 554                                 );
 555                         } else {
 556                                 $entry = ' ' . $text;
 557                         }
 558                         $cache[$row->page_title] = $entry;
 559                 }
 560
 561                 $cache['VERSION'] = MSG_CACHE_VERSION;
 562                 $cache['EXPIRY'] = wfTimestamp( TS_MW, time() + $this->mExpiry );
 563
 564                 return $cache;
 565         }
 566
 567         /**
 568          * Updates cache as necessary when message page is changed
 569          *
 570          * @param string $title Name of the page changed.
 571          * @param mixed $text New contents of the page.
 572          */
 573         public function replace( $title, $text ) {
 574                 global $wgMaxMsgCacheEntrySize, $wgContLang, $wgLanguageCode;
 575
 576                 if ( $this->mDisable ) {
 577                         return;
 578                 }
 579
 580                 list( $msg, $code ) = $this->figureMessage( $title );
 581                 if ( strpos( $title, '/' ) !== false && $code === $wgLanguageCode ) {
 582                         # Content language overrides do not use the /<code> suffix
 583                         return;
 584                 }
 585
 586                 $cacheKey = wfMemcKey( 'messages', $code );
 587                 $this->lock( $cacheKey );
 588                 $this->load( $code, self::FOR_UPDATE );
 589
 590                 $titleKey = wfMemcKey( 'messages', 'individual', $title );
 591
 592                 if ( $text === false ) {
 593                         # Article was deleted
 594                         $this->mCache[$code][$title] = '!NONEXISTENT';
 595                         $this->mMemc->delete( $titleKey );
 596                 } elseif ( strlen( $text ) > $wgMaxMsgCacheEntrySize ) {
 597                         # Check for size
 598                         $this->mCache[$code][$title] = '!TOO BIG';
 599                         $this->mMemc->set( $titleKey, ' ' . $text, $this->mExpiry );
 600                 } else {
 601                         $this->mCache[$code][$title] = ' ' . $text;
 602                         $this->mMemc->delete( $titleKey );
 603                 }
 604
 605                 # Update caches
 606                 $this->saveToCaches( $this->mCache[$code], 'all', $code );
 607                 $this->unlock( $cacheKey );
 608                 $this->wanCache->touchCheckKey( wfMemcKey( 'messages', $code ) );
 609
 610                 // Also delete cached sidebar... just in case it is affected
 611                 $codes = array( $code );
 612                 if ( $code === 'en' ) {
 613                         // Delete all sidebars, like for example on action=purge on the
 614                         // sidebar messages
 615                         $codes = array_keys( Language::fetchLanguageNames() );
 616                 }
 617
 618                 foreach ( $codes as $code ) {
 619                         $sidebarKey = wfMemcKey( 'sidebar', $code );
 620                         $this->wanCache->delete( $sidebarKey, 5 );
 621                 }
 622
 623                 // Update the message in the message blob store
 624                 $blobStore = new MessageBlobStore();
 625                 $blobStore->updateMessage( $wgContLang->lcfirst( $msg ) );
 626
 627                 Hooks::run( 'MessageCacheReplace', array( $title, $text ) );
 628         }
 629
 630         /**
 631          * Is the given cache array expired due to time passing or a version change?
 632          *
 633          * @param array $cache
 634          * @return bool
 635          */
 636         protected function isCacheExpired( $cache ) {
 637                 if ( !isset( $cache['VERSION'] ) || !isset( $cache['EXPIRY'] ) ) {
 638                         return true;
 639                 }
 640                 if ( $cache['VERSION'] != MSG_CACHE_VERSION ) {
 641                         return true;
 642                 }
 643                 if ( wfTimestampNow() >= $cache['EXPIRY'] ) {
 644                         return true;
 645                 }
 646
 647                 return false;
 648         }
 649
 650         /**
 651          * Shortcut to update caches.
 652          *
 653          * @param array $cache Cached messages with a version.
 654          * @param string $dest Either "local-only" to save to local caches only
 655          *   or "all" to save to all caches.
 656          * @param string|bool $code Language code (default: false)
 657          * @return bool
 658          */
 659         protected function saveToCaches( $cache, $dest, $code = false ) {
 660                 global $wgUseLocalMessageCache;
 661
 662                 if ( $dest === 'all' ) {
 663                         $cacheKey = wfMemcKey( 'messages', $code );
 664                         $success = $this->mMemc->set( $cacheKey, $cache );
 665                 } else {
 666                         $success = true;
 667                 }
 668
 669                 # Save to local cache
 670                 if ( $wgUseLocalMessageCache ) {
 671                         $serialized = serialize( $cache );
 672                         $hash = md5( $serialized );
 673                         $this->setValidationHash( $code, $hash );
 674                         $this->saveToLocal( $serialized, $hash, $code );
 675                 }
 676
 677                 return $success;
 678         }
 679
 680         /**
 681          * Get the md5 used to validate the local disk cache
 682          *
 683          * @param string $code
 684          * @return array (hash or false, bool expiry status)
 685          */
 686         protected function getValidationHash( $code ) {
 687                 $curTTL = null;
 688                 $value = $this->wanCache->get(
 689                         wfMemcKey( 'messages', $code, 'hash' ),
 690                         $curTTL,
 691                         array( wfMemcKey( 'messages', $code ) )
 692                 );
 693                 $expired = ( $curTTL === null || $curTTL < 0 );
 694
 695                 return array( $value, $expired );
 696         }
 697
 698         /**
 699          * Set the md5 used to validate the local disk cache
 700          *
 701          * @param string $code
 702          * @param string $hash
 703          */
 704         protected function setValidationHash( $code, $hash ) {
 705                 $this->wanCache->set(
 706                         wfMemcKey( 'messages', $code, 'hash' ),
 707                         $hash,
 708                         WANObjectCache::TTL_NONE
 709                 );
 710         }
 711
 712         /**
 713          * Represents a write lock on the messages key.
 714          *
 715          * Will retry MessageCache::MSG_WAIT_TIMEOUT times, each operations having
 716          * a timeout of MessageCache::MSG_LOCK_TIMEOUT.
 717          *
 718          * @param string $key
 719          * @return bool Success
 720          */
 721         function lock( $key ) {
 722                 $lockKey = $key . ':lock';
 723                 $acquired = false;
 724                 $testDone = false;
 725                 for ( $i = 0; $i < MSG_WAIT_TIMEOUT && !$acquired; $i++ ) {
 726                         $acquired = $this->mMemc->add( $lockKey, 1, MSG_LOCK_TIMEOUT );
 727                         if ( $acquired ) {
 728                                 break;
 729                         }
 730
 731                         # Fail fast if memcached is totally down
 732                         if ( !$testDone ) {
 733                                 $testDone = true;
 734                                 if ( !$this->mMemc->set( wfMemcKey( 'test' ), 'test', 1 ) ) {
 735                                         break;
 736                                 }
 737                         }
 738                         sleep( 1 );
 739                 }
 740
 741                 return $acquired;
 742         }
 743
 744         function unlock( $key ) {
 745                 $lockKey = $key . ':lock';
 746                 $this->mMemc->delete( $lockKey );
 747         }
 748
 749         /**
 750          * Get a message from either the content language or the user language.
 751          *
 752          * First, assemble a list of languages to attempt getting the message from. This
 753          * chain begins with the requested language and its fallbacks and then continues with
 754          * the content language and its fallbacks. For each language in the chain, the following
 755          * process will occur (in this order):
 756          *  1. If a language-specific override, i.e., [[MW:msg/lang]], is available, use that.
 757          *     Note: for the content language, there is no /lang subpage.
 758          *  2. Fetch from the static CDB cache.
 759          *  3. If available, check the database for fallback language overrides.
 760          *
 761          * This process provides a number of guarantees. When changing this code, make sure all
 762          * of these guarantees are preserved.
 763          *  * If the requested language is *not* the content language, then the CDB cache for that
 764          *    specific language will take precedence over the root database page ([[MW:msg]]).
 765          *  * Fallbacks will be just that: fallbacks. A fallback language will never be reached if
 766          *    the message is available *anywhere* in the language for which it is a fallback.
 767          *
 768          * @param string $key The message key
 769          * @param bool $useDB If true, look for the message in the DB, false
 770          *   to use only the compiled l10n cache.
 771          * @param bool|string|object $langcode Code of the language to get the message for.
 772          *   - If string and a valid code, will create a standard language object
 773          *   - If string but not a valid code, will create a basic language object
 774          *   - If boolean and false, create object from the current users language
 775          *   - If boolean and true, create object from the wikis content language
 776          *   - If language object, use it as given
 777          * @param bool $isFullKey Specifies whether $key is a two part key "msg/lang".
 778          *
 779          * @throws MWException When given an invalid key
 780          * @return string|bool False if the message doesn't exist, otherwise the
 781          *   message (which can be empty)
 782          */
 783         function get( $key, $useDB = true, $langcode = true, $isFullKey = false ) {
 784                 global $wgContLang;
 785
 786                 if ( is_int( $key ) ) {
 787                         // Fix numerical strings that somehow become ints
 788                         // on their way here
 789                         $key = (string)$key;
 790                 } elseif ( !is_string( $key ) ) {
 791                         throw new MWException( 'Non-string key given' );
 792                 } elseif ( $key === '' ) {
 793                         // Shortcut: the empty key is always missing
 794                         return false;
 795                 }
 796
 797                 // For full keys, get the language code from the key
 798                 $pos = strrpos( $key, '/' );
 799                 if ( $isFullKey && $pos !== false ) {
 800                         $langcode = substr( $key, $pos + 1 );
 801                         $key = substr( $key, 0, $pos );
 802                 }
 803
 804                 // Normalise title-case input (with some inlining)
 805                 $lckey = MessageCache::normalizeKey( $key );
 806
 807                 Hooks::run( 'MessageCache::get', array( &$lckey ) );
 808
 809                 if ( ord( $lckey ) < 128 ) {
 810                         $uckey = ucfirst( $lckey );
 811                 } else {
 812                         $uckey = $wgContLang->ucfirst( $lckey );
 813                 }
 814
 815                 // Loop through each language in the fallback list until we find something useful
 816                 $lang = wfGetLangObj( $langcode );
 817                 $message = $this->getMessageFromFallbackChain(
 818                         $lang,
 819                         $lckey,
 820                         $uckey,
 821                         !$this->mDisable && $useDB
 822                 );
 823
 824                 // If we still have no message, maybe the key was in fact a full key so try that
 825                 if ( $message === false ) {
 826                         $parts = explode( '/', $lckey );
 827                         // We may get calls for things that are http-urls from sidebar
 828                         // Let's not load nonexistent languages for those
 829                         // They usually have more than one slash.
 830                         if ( count( $parts ) == 2 && $parts[1] !== '' ) {
 831                                 $message = Language::getMessageFor( $parts[0], $parts[1] );
 832                                 if ( $message === null ) {
 833                                         $message = false;
 834                                 }
 835                         }
 836                 }
 837
 838                 // Post-processing if the message exists
 839                 if ( $message !== false ) {
 840                         // Fix whitespace
 841                         $message = str_replace(
 842                                 array(
 843                                         # Fix for trailing whitespace, removed by textarea
 844                                         '&#32;',
 845                                         # Fix for NBSP, converted to space by firefox
 846                                         '&nbsp;',
 847                                         '&#160;',
 848                                 ),
 849                                 array(
 850                                         ' ',
 851                                         "\xc2\xa0",
 852                                         "\xc2\xa0"
 853                                 ),
 854                                 $message
 855                         );
 856                 }
 857
 858                 return $message;
 859         }
 860
 861         /**
 862          * Given a language, try and fetch a message from that language, then the
 863          * fallbacks of that language, then the site language, then the fallbacks for the
 864          * site language.
 865          *
 866          * @param Language $lang Requested language
 867          * @param string $lckey Lowercase key for the message
 868          * @param string $uckey Uppercase key for the message
 869          * @param bool $useDB Whether to use the database
 870          *
 871          * @see MessageCache::get
 872          * @return string|bool The message, or false if not found
 873          */
 874         protected function getMessageFromFallbackChain( $lang, $lckey, $uckey, $useDB ) {
 875                 global $wgLanguageCode, $wgContLang;
 876
 877                 $langcode = $lang->getCode();
 878                 $message = false;
 879
 880                 // First try the requested language.
 881                 if ( $useDB ) {
 882                         if ( $langcode === $wgLanguageCode ) {
 883                                 // Messages created in the content language will not have the /lang extension
 884                                 $message = $this->getMsgFromNamespace( $uckey, $langcode );
 885                         } else {
 886                                 $message = $this->getMsgFromNamespace( "$uckey/$langcode", $langcode );
 887                         }
 888                 }
 889
 890                 if ( $message !== false ) {
 891                         return $message;
 892                 }
 893
 894                 // Check the CDB cache
 895                 $message = $lang->getMessage( $lckey );
 896                 if ( $message !== null ) {
 897                         return $message;
 898                 }
 899
 900                 list( $fallbackChain, $siteFallbackChain ) =
 901                         Language::getFallbacksIncludingSiteLanguage( $langcode );
 902
 903                 // Next try checking the database for all of the fallback languages of the requested language.
 904                 if ( $useDB ) {
 905                         foreach ( $fallbackChain as $code ) {
 906                                 if ( $code === $wgLanguageCode ) {
 907                                         // Messages created in the content language will not have the /lang extension
 908                                         $message = $this->getMsgFromNamespace( $uckey, $code );
 909                                 } else {
 910                                         $message = $this->getMsgFromNamespace( "$uckey/$code", $code );
 911                                 }
 912
 913                                 if ( $message !== false ) {
 914                                         // Found the message.
 915                                         return $message;
 916                                 }
 917                         }
 918                 }
 919
 920                 // Now try checking the site language.
 921                 if ( $useDB ) {
 922                         $message = $this->getMsgFromNamespace( $uckey, $wgLanguageCode );
 923                         if ( $message !== false ) {
 924                                 return $message;
 925                         }
 926                 }
 927
 928                 $message = $wgContLang->getMessage( $lckey );
 929                 if ( $message !== null ) {
 930                         return $message;
 931                 }
 932
 933                 // Finally try the DB for the site language's fallbacks.
 934                 if ( $useDB ) {
 935                         foreach ( $siteFallbackChain as $code ) {
 936                                 $message = $this->getMsgFromNamespace( "$uckey/$code", $code );
 937                                 if ( $message === false && $code === $wgLanguageCode ) {
 938                                         // Messages created in the content language will not have the /lang extension
 939                                         $message = $this->getMsgFromNamespace( $uckey, $code );
 940                                 }
 941
 942                                 if ( $message !== false ) {
 943                                         // Found the message.
 944                                         return $message;
 945                                 }
 946                         }
 947                 }
 948
 949                 return false;
 950         }
 951
 952         /**
 953          * Get a message from the MediaWiki namespace, with caching. The key must
 954          * first be converted to two-part lang/msg form if necessary.
 955          *
 956          * Unlike self::get(), this function doesn't resolve fallback chains, and
 957          * some callers require this behavior. LanguageConverter::parseCachedTable()
 958          * and self::get() are some examples in core.
 959          *
 960          * @param string $title Message cache key with initial uppercase letter.
 961          * @param string $code Code denoting the language to try.
 962          * @return string|bool The message, or false if it does not exist or on error
 963          */
 964         function getMsgFromNamespace( $title, $code ) {
 965                 $this->load( $code );
 966                 if ( isset( $this->mCache[$code][$title] ) ) {
 967                         $entry = $this->mCache[$code][$title];
 968                         if ( substr( $entry, 0, 1 ) === ' ' ) {
 969                                 // The message exists, so make sure a string
 970                                 // is returned.
 971                                 return (string)substr( $entry, 1 );
 972                         } elseif ( $entry === '!NONEXISTENT' ) {
 973                                 return false;
 974                         } elseif ( $entry === '!TOO BIG' ) {
 975                                 // Fall through and try invididual message cache below
 976                         }
 977                 } else {
 978                         // XXX: This is not cached in process cache, should it?
 979                         $message = false;
 980                         Hooks::run( 'MessagesPreLoad', array( $title, &$message ) );
 981                         if ( $message !== false ) {
 982                                 return $message;
 983                         }
 984
 985                         return false;
 986                 }
 987
 988                 # Try the individual message cache
 989                 $titleKey = wfMemcKey( 'messages', 'individual', $title );
 990                 $entry = $this->mMemc->get( $titleKey );
 991                 if ( $entry ) {
 992                         if ( substr( $entry, 0, 1 ) === ' ' ) {
 993                                 $this->mCache[$code][$title] = $entry;
 994
 995                                 // The message exists, so make sure a string
 996                                 // is returned.
 997                                 return (string)substr( $entry, 1 );
 998                         } elseif ( $entry === '!NONEXISTENT' ) {
 999                                 $this->mCache[$code][$title] = '!NONEXISTENT';
1000
1001                                 return false;
1002                         } else {
1003                                 # Corrupt/obsolete entry, delete it
1004                                 $this->mMemc->delete( $titleKey );
1005                         }
1006                 }
1007
1008                 # Try loading it from the database
1009                 $revision = Revision::newFromTitle(
1010                         Title::makeTitle( NS_MEDIAWIKI, $title ), false, Revision::READ_LATEST
1011                 );
1012                 if ( $revision ) {
1013                         $content = $revision->getContent();
1014                         if ( !$content ) {
1015                                 // A possibly temporary loading failure.
1016                                 wfDebugLog(
1017                                         'MessageCache',
1018                                         __METHOD__ . ": failed to load message page text for {$title} ($code)"
1019                                 );
1020                                 $message = null; // no negative caching
1021                         } else {
1022                                 // XXX: Is this the right way to turn a Content object into a message?
1023                                 // NOTE: $content is typically either WikitextContent, JavaScriptContent or
1024                                 //       CssContent. MessageContent is *not* used for storing messages, it's
1025                                 //       only used for wrapping them when needed.
1026                                 $message = $content->getWikitextForTransclusion();
1027
1028                                 if ( $message === false || $message === null ) {
1029                                         wfDebugLog(
1030                                                 'MessageCache',
1031                                                 __METHOD__ . ": message content doesn't provide wikitext "
1032                                                         . "(content model: " . $content->getContentHandler() . ")"
1033                                         );
1034
1035                                         $message = false; // negative caching
1036                                 } else {
1037                                         $this->mCache[$code][$title] = ' ' . $message;
1038                                         $this->mMemc->set( $titleKey, ' ' . $message, $this->mExpiry );
1039                                 }
1040                         }
1041                 } else {
1042                         $message = false; // negative caching
1043                 }
1044
1045                 if ( $message === false ) { // negative caching
1046                         $this->mCache[$code][$title] = '!NONEXISTENT';
1047                         $this->mMemc->set( $titleKey, '!NONEXISTENT', $this->mExpiry );
1048                 }
1049
1050                 return $message;
1051         }
1052
1053         /**
1054          * @param string $message
1055          * @param bool $interface
1056          * @param string $language Language code
1057          * @param Title $title
1058          * @return string
1059          */
1060         function transform( $message, $interface = false, $language = null, $title = null ) {
1061                 // Avoid creating parser if nothing to transform
1062                 if ( strpos( $message, '{{' ) === false ) {
1063                         return $message;
1064                 }
1065
1066                 if ( $this->mInParser ) {
1067                         return $message;
1068                 }
1069
1070                 $parser = $this->getParser();
1071                 if ( $parser ) {
1072                         $popts = $this->getParserOptions();
1073                         $popts->setInterfaceMessage( $interface );
1074                         $popts->setTargetLanguage( $language );
1075
1076                         $userlang = $popts->setUserLang( $language );
1077                         $this->mInParser = true;
1078                         $message = $parser->transformMsg( $message, $popts, $title );
1079                         $this->mInParser = false;
1080                         $popts->setUserLang( $userlang );
1081                 }
1082
1083                 return $message;
1084         }
1085
1086         /**
1087          * @return Parser
1088          */
1089         function getParser() {
1090                 global $wgParser, $wgParserConf;
1091                 if ( !$this->mParser && isset( $wgParser ) ) {
1092                         # Do some initialisation so that we don't have to do it twice
1093                         $wgParser->firstCallInit();
1094                         # Clone it and store it
1095                         $class = $wgParserConf['class'];
1096                         if ( $class == 'ParserDiffTest' ) {
1097                                 # Uncloneable
1098                                 $this->mParser = new $class( $wgParserConf );
1099                         } else {
1100                                 $this->mParser = clone $wgParser;
1101                         }
1102                 }
1103
1104                 return $this->mParser;
1105         }
1106
1107         /**
1108          * @param string $text
1109          * @param Title $title
1110          * @param bool $linestart Whether or not this is at the start of a line
1111          * @param bool $interface Whether this is an interface message
1112          * @param string $language Language code
1113          * @return ParserOutput|string
1114          */
1115         public function parse( $text, $title = null, $linestart = true,
1116                 $interface = false, $language = null
1117         ) {
1118                 if ( $this->mInParser ) {
1119                         return htmlspecialchars( $text );
1120                 }
1121
1122                 $parser = $this->getParser();
1123                 $popts = $this->getParserOptions();
1124                 $popts->setInterfaceMessage( $interface );
1125                 $popts->setTargetLanguage( $language );
1126
1127                 if ( !$title || !$title instanceof Title ) {
1128                         global $wgTitle;
1129                         wfDebugLog( 'GlobalTitleFail', __METHOD__ . ' called by ' .
1130                                 wfGetAllCallers( 5 ) . ' with no title set.' );
1131                         $title = $wgTitle;
1132                 }
1133                 // Sometimes $wgTitle isn't set either...
1134                 if ( !$title ) {
1135                         # It's not uncommon having a null $wgTitle in scripts. See r80898
1136                         # Create a ghost title in such case
1137                         $title = Title::makeTitle( NS_SPECIAL, 'Badtitle/title not set in ' . __METHOD__ );
1138                 }
1139
1140                 $this->mInParser = true;
1141                 $res = $parser->parse( $text, $title, $popts, $linestart );
1142                 $this->mInParser = false;
1143
1144                 return $res;
1145         }
1146
1147         function disable() {
1148                 $this->mDisable = true;
1149         }
1150
1151         function enable() {
1152                 $this->mDisable = false;
1153         }
1154
1155         /**
1156          * Clear all stored messages. Mainly used after a mass rebuild.
1157          */
1158         function clear() {
1159                 $langs = Language::fetchLanguageNames( null, 'mw' );
1160                 foreach ( array_keys( $langs ) as $code ) {
1161                         # Global and local caches
1162                         $this->wanCache->touchCheckKey( wfMemcKey( 'messages', $code ) );
1163                 }
1164
1165                 $this->mLoadedLanguages = array();
1166         }
1167
1168         /**
1169          * @param string $key
1170          * @return array
1171          */
1172         public function figureMessage( $key ) {
1173                 global $wgLanguageCode;
1174
1175                 $pieces = explode( '/', $key );
1176                 if ( count( $pieces ) < 2 ) {
1177                         return array( $key, $wgLanguageCode );
1178                 }
1179
1180                 $lang = array_pop( $pieces );
1181                 if ( !Language::fetchLanguageName( $lang, null, 'mw' ) ) {
1182                         return array( $key, $wgLanguageCode );
1183                 }
1184
1185                 $message = implode( '/', $pieces );
1186
1187                 return array( $message, $lang );
1188         }
1189
1190         /**
1191          * Get all message keys stored in the message cache for a given language.
1192          * If $code is the content language code, this will return all message keys
1193          * for which MediaWiki:msgkey exists. If $code is another language code, this
1194          * will ONLY return message keys for which MediaWiki:msgkey/$code exists.
1195          * @param string $code Language code
1196          * @return array Array of message keys (strings)
1197          */
1198         public function getAllMessageKeys( $code ) {
1199                 global $wgContLang;
1200                 $this->load( $code );
1201                 if ( !isset( $this->mCache[$code] ) ) {
1202                         // Apparently load() failed
1203                         return null;
1204                 }
1205                 // Remove administrative keys
1206                 $cache = $this->mCache[$code];
1207                 unset( $cache['VERSION'] );
1208                 unset( $cache['EXPIRY'] );
1209                 // Remove any !NONEXISTENT keys
1210                 $cache = array_diff( $cache, array( '!NONEXISTENT' ) );
1211
1212                 // Keys may appear with a capital first letter. lcfirst them.
1213                 return array_map( array( $wgContLang, 'lcfirst' ), array_keys( $cache ) );
1214         }
1215 }