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