includes/cache/MessageBlobStore.php

   1 <?php
   2 /**
   3  * Resource message blobs storage used by ResourceLoader.
   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  * @author Roan Kattouw
  22  * @author Trevor Parscal
  23  */
  24
  25 /**
  26  * This class provides access to the message blobs used by ResourceLoader modules.
  27  *
  28  * A message blob is a JSON object containing the interface messages for a
  29  * certain module in a certain language. These message blobs are cached
  30  * in the automatically invalidated when one of their constituent messages,
  31  * or the module definition, is changed.
  32  */
  33 class MessageBlobStore {
  34         /**
  35          * In-process cache for message blobs.
  36          *
  37          * Keyed by language code, then module name.
  38          *
  39          * @var array
  40          */
  41         protected $blobCache = array();
  42
  43         /* @var ResourceLoader */
  44         protected $resourceloader;
  45
  46         /**
  47          * @param ResourceLoader $resourceloader
  48          */
  49         public function __construct( ResourceLoader $resourceloader = null ) {
  50                 $this->resourceloader = $resourceloader;
  51         }
  52
  53         /**
  54          * Get the message blobs for a set of modules
  55          *
  56          * @param ResourceLoader $resourceLoader
  57          * @param array $modules Array of module objects keyed by module name
  58          * @param string $lang Language code
  59          * @return array An array mapping module names to message blobs
  60          */
  61         public function get( ResourceLoader $resourceLoader, $modules, $lang ) {
  62                 if ( !count( $modules ) ) {
  63                         return array();
  64                 }
  65
  66                 $blobs = array();
  67
  68                 // Try in-process cache
  69                 $missingFromCache = array();
  70                 foreach ( $modules as $name => $module ) {
  71                         if ( isset( $this->blobCache[$lang][$name] ) ) {
  72                                 $blobs[$name] = $this->blobCache[$lang][$name];
  73                         } else {
  74                                 $missingFromCache[$name] = $module;
  75                         }
  76                 }
  77
  78                 // Try DB cache
  79                 if ( $missingFromCache ) {
  80                         $blobs += $this->getFromDB( $missingFromCache, $lang );
  81                 }
  82
  83                 // Generate new blobs for any remaining modules and store in DB
  84                 $missingFromDb = array_diff( array_keys( $modules ), array_keys( $blobs ) );
  85                 foreach ( $missingFromDb as $name ) {
  86                         $blob = $this->insertMessageBlob( $name, $modules[$name], $lang );
  87                         if ( $blob ) {
  88                                 $blobs[$name] = $blob;
  89                         }
  90                 }
  91
  92                 // Update in-process cache
  93                 if ( isset( $this->blobCache[$lang] ) ) {
  94                         $this->blobCache[$lang] += $blobs;
  95                 } else {
  96                         $this->blobCache[$lang] = $blobs;
  97                 }
  98
  99                 return $blobs;
 100         }
 101
 102         /**
 103          * Generate and insert a new message blob. If the blob was already
 104          * present, it is not regenerated; instead, the preexisting blob
 105          * is fetched and returned.
 106          *
 107          * @param string $name Module name
 108          * @param ResourceLoaderModule $module
 109          * @param string $lang Language code
 110          * @return string JSON blob
 111          */
 112         public function insertMessageBlob( $name, ResourceLoaderModule $module, $lang ) {
 113                 $blob = $this->generateMessageBlob( $module, $lang );
 114
 115                 if ( !$blob ) {
 116                         return false;
 117                 }
 118
 119                 try {
 120                         $dbw = wfGetDB( DB_MASTER );
 121                         $success = $dbw->insert( 'msg_resource', array(
 122                                         'mr_lang' => $lang,
 123                                         'mr_resource' => $name,
 124                                         'mr_blob' => $blob,
 125                                         'mr_timestamp' => $dbw->timestamp()
 126                                 ),
 127                                 __METHOD__,
 128                                 array( 'IGNORE' )
 129                         );
 130
 131                         if ( $success && $dbw->affectedRows() == 0 ) {
 132                                 // Blob was already present, fetch it
 133                                 $blob = $dbw->selectField( 'msg_resource', 'mr_blob', array(
 134                                                 'mr_resource' => $name,
 135                                                 'mr_lang' => $lang,
 136                                         ),
 137                                         __METHOD__
 138                                 );
 139                         }
 140                 } catch ( DBError $e ) {
 141                         wfDebug( __METHOD__ . " failed to update DB: $e\n" );
 142                 }
 143                 return $blob;
 144         }
 145
 146         /**
 147          * Update the message blob for a given module in a given language
 148          *
 149          * @param string $name Module name
 150          * @param ResourceLoaderModule $module
 151          * @param string $lang Language code
 152          * @return string|null Regenerated message blob, or null if there was no blob for
 153          *   the given module/language pair.
 154          */
 155         public function updateModule( $name, ResourceLoaderModule $module, $lang ) {
 156                 $dbw = wfGetDB( DB_MASTER );
 157                 $row = $dbw->selectRow( 'msg_resource', 'mr_blob',
 158                         array( 'mr_resource' => $name, 'mr_lang' => $lang ),
 159                         __METHOD__
 160                 );
 161                 if ( !$row ) {
 162                         return null;
 163                 }
 164
 165                 $newBlob = $this->generateMessageBlob( $module, $lang );
 166
 167                 try {
 168                         $newRow = array(
 169                                 'mr_resource' => $name,
 170                                 'mr_lang' => $lang,
 171                                 'mr_blob' => $newBlob,
 172                                 'mr_timestamp' => $dbw->timestamp()
 173                         );
 174
 175                         $dbw->replace( 'msg_resource',
 176                                 array( array( 'mr_resource', 'mr_lang' ) ),
 177                                 $newRow, __METHOD__
 178                         );
 179                 } catch ( Exception $e ) {
 180                         wfDebug( __METHOD__ . " failed to update DB: $e\n" );
 181                 }
 182                 return $newBlob;
 183         }
 184
 185         /**
 186          * Update a single message in all message blobs it occurs in.
 187          *
 188          * @param string $key Message key
 189          */
 190         public function updateMessage( $key ) {
 191                 try {
 192                         $dbw = wfGetDB( DB_MASTER );
 193
 194                         // Keep running until the updates queue is empty.
 195                         // Due to update conflicts, the queue might not be emptied
 196                         // in one iteration.
 197                         $updates = null;
 198                         do {
 199                                 $updates = $this->getUpdatesForMessage( $key, $updates );
 200
 201                                 foreach ( $updates as $k => $update ) {
 202                                         // Update the row on the condition that it
 203                                         // didn't change since we fetched it by putting
 204                                         // the timestamp in the WHERE clause.
 205                                         $success = $dbw->update( 'msg_resource',
 206                                                 array(
 207                                                         'mr_blob' => $update['newBlob'],
 208                                                         'mr_timestamp' => $dbw->timestamp() ),
 209                                                 array(
 210                                                         'mr_resource' => $update['resource'],
 211                                                         'mr_lang' => $update['lang'],
 212                                                         'mr_timestamp' => $update['timestamp'] ),
 213                                                 __METHOD__
 214                                         );
 215
 216                                         // Only requeue conflicted updates.
 217                                         // If update() returned false, don't retry, for
 218                                         // fear of getting into an infinite loop
 219                                         if ( !( $success && $dbw->affectedRows() == 0 ) ) {
 220                                                 // Not conflicted
 221                                                 unset( $updates[$k] );
 222                                         }
 223                                 }
 224                         } while ( count( $updates ) );
 225
 226                 } catch ( Exception $e ) {
 227                         wfDebug( __METHOD__ . " failed to update DB: $e\n" );
 228                 }
 229         }
 230
 231         public function clear() {
 232                 try {
 233                         // Not using TRUNCATE, because that needs extra permissions,
 234                         // which maybe not granted to the database user.
 235                         $dbw = wfGetDB( DB_MASTER );
 236                         $dbw->delete( 'msg_resource', '*', __METHOD__ );
 237                 } catch ( Exception $e ) {
 238                         wfDebug( __METHOD__ . " failed to update DB: $e\n" );
 239                 }
 240         }
 241
 242         /**
 243          * @return ResourceLoader
 244          */
 245         protected function getResourceLoader() {
 246                 // For back-compat this class supports instantiation without passing ResourceLoader
 247                 // Lazy-initialise this property because most callers don't need it.
 248                 if ( $this->resourceloader === null ) {
 249                         wfDebug( __CLASS__ . ' created without a ResourceLoader instance' );
 250                         $this->resourceloader = new ResourceLoader();
 251                 }
 252
 253                 return $this->resourceloader;
 254         }
 255
 256         /**
 257          * Create an update queue for updateMessage()
 258          *
 259          * @param string $key Message key
 260          * @param array $prevUpdates Updates queue to refresh or null to build a fresh update queue
 261          * @return array Updates queue
 262          */
 263         private function getUpdatesForMessage( $key, $prevUpdates = null ) {
 264                 $dbw = wfGetDB( DB_MASTER );
 265
 266                 if ( is_null( $prevUpdates ) ) {
 267                         $rl = $this->getResourceLoader();
 268                         $moduleNames = $rl->getModulesByMessage( $key );
 269                         // Fetch all blobs referencing $key
 270                         $res = $dbw->select(
 271                                 array( 'msg_resource' ),
 272                                 array( 'mr_resource', 'mr_lang', 'mr_blob', 'mr_timestamp' ),
 273                                 array(
 274                                         'mr_resource' => $moduleNames,
 275                                 ),
 276                                 __METHOD__
 277                         );
 278                 } else {
 279                         // Refetch the blobs referenced by $prevUpdates
 280
 281                         // Reorganize the (resource, lang) pairs in the format
 282                         // expected by makeWhereFrom2d()
 283                         $twoD = array();
 284
 285                         foreach ( $prevUpdates as $update ) {
 286                                 $twoD[$update['resource']][$update['lang']] = true;
 287                         }
 288
 289                         $res = $dbw->select( 'msg_resource',
 290                                 array( 'mr_resource', 'mr_lang', 'mr_blob', 'mr_timestamp' ),
 291                                 $dbw->makeWhereFrom2d( $twoD, 'mr_resource', 'mr_lang' ),
 292                                 __METHOD__
 293                         );
 294                 }
 295
 296                 // Build the new updates queue
 297                 $updates = array();
 298
 299                 foreach ( $res as $row ) {
 300                         $updates[] = array(
 301                                 'resource' => $row->mr_resource,
 302                                 'lang' => $row->mr_lang,
 303                                 'timestamp' => $row->mr_timestamp,
 304                                 'newBlob' => $this->reencodeBlob( $row->mr_blob, $key, $row->mr_lang )
 305                         );
 306                 }
 307
 308                 return $updates;
 309         }
 310
 311         /**
 312          * @param string $key Message key
 313          * @param string $lang Language code
 314          * @return string
 315          */
 316         private function fetchMessage( $key, $lang ) {
 317                 $message = wfMessage( $key )->inLanguage( $lang );
 318                 if ( !$message->exists() ) {
 319                         wfDebugLog( 'resourceloader', __METHOD__ . " failed to find: '$key' ($lang)" );
 320                 }
 321                 return $message->plain();
 322         }
 323
 324         /**
 325          * Reencode a message blob with the updated value for a message
 326          *
 327          * @param string $blob Message blob (JSON object)
 328          * @param string $key Message key
 329          * @param string $lang Language code
 330          * @return string Message blob with $key replaced with its new value
 331          */
 332         private function reencodeBlob( $blob, $key, $lang ) {
 333                 $decoded = FormatJson::decode( $blob, true );
 334                 $decoded[$key] = $this->fetchMessage( $key, $lang );
 335                 return FormatJson::encode( (object)$decoded );
 336         }
 337
 338         /**
 339          * Get the message blobs for a set of modules from the database.
 340          * Modules whose blobs are not in the database are silently dropped.
 341          *
 342          * @param array $modules Array of module objects by name
 343          * @param string $lang Language code
 344          * @throws MWException
 345          * @return array Array mapping module names to blobs
 346          */
 347         private function getFromDB( $modules, $lang ) {
 348                 if ( !count( $modules ) ) {
 349                         return array();
 350                 }
 351
 352                 $retval = array();
 353                 $dbr = wfGetDB( DB_SLAVE );
 354                 $res = $dbr->select( 'msg_resource',
 355                         array( 'mr_blob', 'mr_resource', 'mr_timestamp' ),
 356                         array( 'mr_resource' => array_keys( $modules ), 'mr_lang' => $lang ),
 357                         __METHOD__
 358                 );
 359
 360                 foreach ( $res as $row ) {
 361                         if ( !isset( $modules[ $row->mr_resource ] ) ) {
 362                                 // This shouldn't be possible
 363                                 throw new MWException( __METHOD__ . ' passed an invalid module name' );
 364                         }
 365                         $module = $modules[ $row->mr_resource ];
 366
 367                         // Update the module's blob if the list of messages changed
 368                         $blobKeys = array_keys( FormatJson::decode( $row->mr_blob, true ) );
 369                         $moduleMsgs = array_values( array_unique( $module->getMessages() ) );
 370                         if ( $blobKeys !== $moduleMsgs ) {
 371                                 $retval[$row->mr_resource] = $this->updateModule( $row->mr_resource, $module, $lang );
 372                         } else {
 373                                 $retval[$row->mr_resource] = $row->mr_blob;
 374                         }
 375                 }
 376
 377                 return $retval;
 378         }
 379
 380         /**
 381          * Generate the message blob for a given module in a given language.
 382          *
 383          * @param ResourceLoaderModule $module
 384          * @param string $lang Language code
 385          * @return string JSON blob
 386          */
 387         private function generateMessageBlob( ResourceLoaderModule $module, $lang ) {
 388                 $messages = array();
 389
 390                 foreach ( $module->getMessages() as $key ) {
 391                         $messages[$key] = $this->fetchMessage( $key, $lang );
 392                 }
 393
 394                 return FormatJson::encode( (object)$messages );
 395         }
 396 }