includes/resourceloader/ResourceLoaderModule.php

   1 <?php
   2 /**
   3  * Abstraction for resource loader modules.
   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 Trevor Parscal
  22  * @author Roan Kattouw
  23  */
  24
  25 /**
  26  * Abstraction for resource loader modules, with name registration and maxage functionality.
  27  */
  28 abstract class ResourceLoaderModule {
  29         # Type of resource
  30         const TYPE_SCRIPTS = 'scripts';
  31         const TYPE_STYLES = 'styles';
  32         const TYPE_COMBINED = 'combined';
  33
  34         # sitewide core module like a skin file or jQuery component
  35         const ORIGIN_CORE_SITEWIDE = 1;
  36
  37         # per-user module generated by the software
  38         const ORIGIN_CORE_INDIVIDUAL = 2;
  39
  40         # sitewide module generated from user-editable files, like MediaWiki:Common.js, or
  41         # modules accessible to multiple users, such as those generated by the Gadgets extension.
  42         const ORIGIN_USER_SITEWIDE = 3;
  43
  44         # per-user module generated from user-editable files, like User:Me/vector.js
  45         const ORIGIN_USER_INDIVIDUAL = 4;
  46
  47         # an access constant; make sure this is kept as the largest number in this group
  48         const ORIGIN_ALL = 10;
  49
  50         # script and style modules form a hierarchy of trustworthiness, with core modules like
  51         # skins and jQuery as most trustworthy, and user scripts as least trustworthy.  We can
  52         # limit the types of scripts and styles we allow to load on, say, sensitive special
  53         # pages like Special:UserLogin and Special:Preferences
  54         protected $origin = self::ORIGIN_CORE_SITEWIDE;
  55
  56         /* Protected Members */
  57
  58         protected $name = null;
  59         protected $targets = array( 'desktop' );
  60
  61         // In-object cache for file dependencies
  62         protected $fileDeps = array();
  63         // In-object cache for message blob mtime
  64         protected $msgBlobMtime = array();
  65         // In-object cache for version hash
  66         protected $versionHash = array();
  67
  68         // Whether the position returned by getPosition() is defined in the module configuration
  69         // and not a default value
  70         protected $isPositionDefined = false;
  71
  72         /**
  73          * @var Config
  74          */
  75         protected $config;
  76
  77         /* Methods */
  78
  79         /**
  80          * Get this module's name. This is set when the module is registered
  81          * with ResourceLoader::register()
  82          *
  83          * @return string|null Name (string) or null if no name was set
  84          */
  85         public function getName() {
  86                 return $this->name;
  87         }
  88
  89         /**
  90          * Set this module's name. This is called by ResourceLoader::register()
  91          * when registering the module. Other code should not call this.
  92          *
  93          * @param string $name Name
  94          */
  95         public function setName( $name ) {
  96                 $this->name = $name;
  97         }
  98
  99         /**
 100          * Get this module's origin. This is set when the module is registered
 101          * with ResourceLoader::register()
 102          *
 103          * @return int ResourceLoaderModule class constant, the subclass default
 104          *     if not set manually
 105          */
 106         public function getOrigin() {
 107                 return $this->origin;
 108         }
 109
 110         /**
 111          * Set this module's origin. This is called by ResourceLoader::register()
 112          * when registering the module. Other code should not call this.
 113          *
 114          * @param int $origin Origin
 115          */
 116         public function setOrigin( $origin ) {
 117                 $this->origin = $origin;
 118         }
 119
 120         /**
 121          * @param ResourceLoaderContext $context
 122          * @return bool
 123          */
 124         public function getFlip( $context ) {
 125                 global $wgContLang;
 126
 127                 return $wgContLang->getDir() !== $context->getDirection();
 128         }
 129
 130         /**
 131          * Get all JS for this module for a given language and skin.
 132          * Includes all relevant JS except loader scripts.
 133          *
 134          * @param ResourceLoaderContext $context
 135          * @return string JavaScript code
 136          */
 137         public function getScript( ResourceLoaderContext $context ) {
 138                 // Stub, override expected
 139                 return '';
 140         }
 141
 142         /**
 143          * Takes named templates by the module and returns an array mapping.
 144          *
 145          * @return array of templates mapping template alias to content
 146          */
 147         public function getTemplates() {
 148                 // Stub, override expected.
 149                 return array();
 150         }
 151
 152         /**
 153          * @return Config
 154          * @since 1.24
 155          */
 156         public function getConfig() {
 157                 if ( $this->config === null ) {
 158                         // Ugh, fall back to default
 159                         $this->config = ConfigFactory::getDefaultInstance()->makeConfig( 'main' );
 160                 }
 161
 162                 return $this->config;
 163         }
 164
 165         /**
 166          * @param Config $config
 167          * @since 1.24
 168          */
 169         public function setConfig( Config $config ) {
 170                 $this->config = $config;
 171         }
 172
 173         /**
 174          * Get the URL or URLs to load for this module's JS in debug mode.
 175          * The default behavior is to return a load.php?only=scripts URL for
 176          * the module, but file-based modules will want to override this to
 177          * load the files directly.
 178          *
 179          * This function is called only when 1) we're in debug mode, 2) there
 180          * is no only= parameter and 3) supportsURLLoading() returns true.
 181          * #2 is important to prevent an infinite loop, therefore this function
 182          * MUST return either an only= URL or a non-load.php URL.
 183          *
 184          * @param ResourceLoaderContext $context
 185          * @return array Array of URLs
 186          */
 187         public function getScriptURLsForDebug( ResourceLoaderContext $context ) {
 188                 $resourceLoader = $context->getResourceLoader();
 189                 $derivative = new DerivativeResourceLoaderContext( $context );
 190                 $derivative->setModules( array( $this->getName() ) );
 191                 $derivative->setOnly( 'scripts' );
 192                 $derivative->setDebug( true );
 193
 194                 $url = $resourceLoader->createLoaderURL(
 195                         $this->getSource(),
 196                         $derivative
 197                 );
 198
 199                 return array( $url );
 200         }
 201
 202         /**
 203          * Whether this module supports URL loading. If this function returns false,
 204          * getScript() will be used even in cases (debug mode, no only param) where
 205          * getScriptURLsForDebug() would normally be used instead.
 206          * @return bool
 207          */
 208         public function supportsURLLoading() {
 209                 return true;
 210         }
 211
 212         /**
 213          * Get all CSS for this module for a given skin.
 214          *
 215          * @param ResourceLoaderContext $context
 216          * @return array List of CSS strings or array of CSS strings keyed by media type.
 217          *  like array( 'screen' => '.foo { width: 0 }' );
 218          *  or array( 'screen' => array( '.foo { width: 0 }' ) );
 219          */
 220         public function getStyles( ResourceLoaderContext $context ) {
 221                 // Stub, override expected
 222                 return array();
 223         }
 224
 225         /**
 226          * Get the URL or URLs to load for this module's CSS in debug mode.
 227          * The default behavior is to return a load.php?only=styles URL for
 228          * the module, but file-based modules will want to override this to
 229          * load the files directly. See also getScriptURLsForDebug()
 230          *
 231          * @param ResourceLoaderContext $context
 232          * @return array Array( mediaType => array( URL1, URL2, ... ), ... )
 233          */
 234         public function getStyleURLsForDebug( ResourceLoaderContext $context ) {
 235                 $resourceLoader = $context->getResourceLoader();
 236                 $derivative = new DerivativeResourceLoaderContext( $context );
 237                 $derivative->setModules( array( $this->getName() ) );
 238                 $derivative->setOnly( 'styles' );
 239                 $derivative->setDebug( true );
 240
 241                 $url = $resourceLoader->createLoaderURL(
 242                         $this->getSource(),
 243                         $derivative
 244                 );
 245
 246                 return array( 'all' => array( $url ) );
 247         }
 248
 249         /**
 250          * Get the messages needed for this module.
 251          *
 252          * To get a JSON blob with messages, use MessageBlobStore::get()
 253          *
 254          * @return array List of message keys. Keys may occur more than once
 255          */
 256         public function getMessages() {
 257                 // Stub, override expected
 258                 return array();
 259         }
 260
 261         /**
 262          * Get the group this module is in.
 263          *
 264          * @return string Group name
 265          */
 266         public function getGroup() {
 267                 // Stub, override expected
 268                 return null;
 269         }
 270
 271         /**
 272          * Get the origin of this module. Should only be overridden for foreign modules.
 273          *
 274          * @return string Origin name, 'local' for local modules
 275          */
 276         public function getSource() {
 277                 // Stub, override expected
 278                 return 'local';
 279         }
 280
 281         /**
 282          * Where on the HTML page should this module's JS be loaded?
 283          *  - 'top': in the "<head>"
 284          *  - 'bottom': at the bottom of the "<body>"
 285          *
 286          * @return string
 287          */
 288         public function getPosition() {
 289                 return 'bottom';
 290         }
 291
 292         /**
 293          * Whether the position returned by getPosition() is a default value or comes from the module
 294          * definition. This method is meant to be short-lived, and is only useful until classes added via
 295          * addModuleStyles with a default value define an explicit position. See getModuleStyles() in
 296          * OutputPage for the related migration warning.
 297          *
 298          * @return bool
 299          * @since  1.26
 300          */
 301         public function isPositionDefault() {
 302                 return !$this->isPositionDefined;
 303         }
 304
 305         /**
 306          * Whether this module's JS expects to work without the client-side ResourceLoader module.
 307          * Returning true from this function will prevent mw.loader.state() call from being
 308          * appended to the bottom of the script.
 309          *
 310          * @return bool
 311          */
 312         public function isRaw() {
 313                 return false;
 314         }
 315
 316         /**
 317          * Get the loader JS for this module, if set.
 318          *
 319          * @return mixed JavaScript loader code as a string or boolean false if no custom loader set
 320          */
 321         public function getLoaderScript() {
 322                 // Stub, override expected
 323                 return false;
 324         }
 325
 326         /**
 327          * Get a list of modules this module depends on.
 328          *
 329          * Dependency information is taken into account when loading a module
 330          * on the client side.
 331          *
 332          * To add dependencies dynamically on the client side, use a custom
 333          * loader script, see getLoaderScript()
 334          * @return array List of module names as strings
 335          */
 336         public function getDependencies() {
 337                 // Stub, override expected
 338                 return array();
 339         }
 340
 341         /**
 342          * Get target(s) for the module, eg ['desktop'] or ['desktop', 'mobile']
 343          *
 344          * @return array Array of strings
 345          */
 346         public function getTargets() {
 347                 return $this->targets;
 348         }
 349
 350         /**
 351          * Get the skip function.
 352          *
 353          * Modules that provide fallback functionality can provide a "skip function". This
 354          * function, if provided, will be passed along to the module registry on the client.
 355          * When this module is loaded (either directly or as a dependency of another module),
 356          * then this function is executed first. If the function returns true, the module will
 357          * instantly be considered "ready" without requesting the associated module resources.
 358          *
 359          * The value returned here must be valid javascript for execution in a private function.
 360          * It must not contain the "function () {" and "}" wrapper though.
 361          *
 362          * @return string|null A JavaScript function body returning a boolean value, or null
 363          */
 364         public function getSkipFunction() {
 365                 return null;
 366         }
 367
 368         /**
 369          * Get the files this module depends on indirectly for a given skin.
 370          * Currently these are only image files referenced by the module's CSS.
 371          *
 372          * @param string $skin Skin name
 373          * @return array List of files
 374          */
 375         public function getFileDependencies( $skin ) {
 376                 // Try in-object cache first
 377                 if ( isset( $this->fileDeps[$skin] ) ) {
 378                         return $this->fileDeps[$skin];
 379                 }
 380
 381                 $dbr = wfGetDB( DB_SLAVE );
 382                 $deps = $dbr->selectField( 'module_deps', 'md_deps', array(
 383                                 'md_module' => $this->getName(),
 384                                 'md_skin' => $skin,
 385                         ), __METHOD__
 386                 );
 387                 if ( !is_null( $deps ) ) {
 388                         $this->fileDeps[$skin] = (array)FormatJson::decode( $deps, true );
 389                 } else {
 390                         $this->fileDeps[$skin] = array();
 391                 }
 392                 return $this->fileDeps[$skin];
 393         }
 394
 395         /**
 396          * Set preloaded file dependency information. Used so we can load this
 397          * information for all modules at once.
 398          * @param string $skin Skin name
 399          * @param array $deps Array of file names
 400          */
 401         public function setFileDependencies( $skin, $deps ) {
 402                 $this->fileDeps[$skin] = $deps;
 403         }
 404
 405         /**
 406          * Get the last modification timestamp of the messages in this module for a given language.
 407          * @param string $lang Language code
 408          * @return int UNIX timestamp
 409          */
 410         public function getMsgBlobMtime( $lang ) {
 411                 if ( !isset( $this->msgBlobMtime[$lang] ) ) {
 412                         if ( !count( $this->getMessages() ) ) {
 413                                 return 1;
 414                         }
 415
 416                         $dbr = wfGetDB( DB_SLAVE );
 417                         $msgBlobMtime = $dbr->selectField( 'msg_resource', 'mr_timestamp', array(
 418                                         'mr_resource' => $this->getName(),
 419                                         'mr_lang' => $lang
 420                                 ), __METHOD__
 421                         );
 422                         // If no blob was found, but the module does have messages, that means we need
 423                         // to regenerate it. Return NOW
 424                         if ( $msgBlobMtime === false ) {
 425                                 $msgBlobMtime = wfTimestampNow();
 426                         }
 427                         $this->msgBlobMtime[$lang] = wfTimestamp( TS_UNIX, $msgBlobMtime );
 428                 }
 429                 return $this->msgBlobMtime[$lang];
 430         }
 431
 432         /**
 433          * Set a preloaded message blob last modification timestamp. Used so we
 434          * can load this information for all modules at once.
 435          * @param string $lang Language code
 436          * @param int $mtime UNIX timestamp
 437          */
 438         public function setMsgBlobMtime( $lang, $mtime ) {
 439                 $this->msgBlobMtime[$lang] = $mtime;
 440         }
 441
 442         /**
 443          * Get a string identifying the current version of this module in a given context.
 444          *
 445          * Whenever anything happens that changes the module's response (e.g. scripts, styles, and
 446          * messages) this value must change. This value is used to store module responses in cache.
 447          * (Both client-side and server-side.)
 448          *
 449          * It is not recommended to override this directly. Use getDefinitionSummary() instead.
 450          * If overridden, one must call the parent getVersionHash(), append data and re-hash.
 451          *
 452          * This method should be quick because it is frequently run by ResourceLoaderStartUpModule to
 453          * propagate changes to the client and effectively invalidate cache.
 454          *
 455          * For backward-compatibility, the following optional data providers are automatically included:
 456          *
 457          * - getModifiedTime()
 458          * - getModifiedHash()
 459          *
 460          * @since 1.26
 461          * @param ResourceLoaderContext $context
 462          * @return string Hash (should use ResourceLoader::makeHash)
 463          */
 464         public function getVersionHash( ResourceLoaderContext $context ) {
 465                 // Cache this somewhat expensive operation. Especially because some classes
 466                 // (e.g. startup module) iterate more than once over all modules to get versions.
 467                 $contextHash = $context->getHash();
 468                 if ( !array_key_exists( $contextHash, $this->versionHash ) ) {
 469
 470                         $summary = $this->getDefinitionSummary( $context );
 471                         if ( !isset( $summary['_cacheEpoch'] ) ) {
 472                                 throw new Exception( 'getDefinitionSummary must call parent method' );
 473                         }
 474                         $str = json_encode( $summary );
 475
 476                         $mtime = $this->getModifiedTime( $context );
 477                         if ( $mtime !== null ) {
 478                                 // Support: MediaWiki 1.25 and earlier
 479                                 $str .= strval( $mtime );
 480                         }
 481
 482                         $mhash = $this->getModifiedHash( $context );
 483                         if ( $mhash !== null ) {
 484                                 // Support: MediaWiki 1.25 and earlier
 485                                 $str .= strval( $mhash );
 486                         }
 487
 488                         $this->versionHash[ $contextHash ] = ResourceLoader::makeHash( $str );
 489                 }
 490                 return $this->versionHash[ $contextHash ];
 491         }
 492
 493         /**
 494          * Get the definition summary for this module.
 495          *
 496          * This is the method subclasses are recommended to use to track values in their
 497          * version hash. Call this in getVersionHash() and pass it to e.g. json_encode.
 498          *
 499          * Subclasses must call the parent getDefinitionSummary() and build on that.
 500          * It is recommended that each subclass appends its own new array. This prevents
 501          * clashes or accidental overwrites of existing keys and gives each subclass
 502          * its own scope for simple array keys.
 503          *
 504          * @code
 505          *     $summary = parent::getDefinitionSummary( $context );
 506          *     $summary[] = array(
 507          *         'foo' => 123,
 508          *         'bar' => 'quux',
 509          *     );
 510          *     return $summary;
 511          * @endcode
 512          *
 513          * Return an array containing values from all significant properties of this
 514          * module's definition.
 515          *
 516          * Be careful not to normalise too much. Especially preserve the order of things
 517          * that carry significance in getScript and getStyles (T39812).
 518          *
 519          * Avoid including things that are insiginificant (e.g. order of message keys is
 520          * insignificant and should be sorted to avoid unnecessary cache invalidation).
 521          *
 522          * This data structure must exclusively contain arrays and scalars as values (avoid
 523          * object instances) to allow simple serialisation using json_encode.
 524          *
 525          * If modules have a hash or timestamp from another source, that may be incuded as-is.
 526          *
 527          * A number of utility methods are available to help you gather data. These are not
 528          * called by default and must be included by the subclass' getDefinitionSummary().
 529          *
 530          * - getMsgBlobMtime()
 531          *
 532          * @since 1.23
 533          * @param ResourceLoaderContext $context
 534          * @return array|null
 535          */
 536         public function getDefinitionSummary( ResourceLoaderContext $context ) {
 537                 return array(
 538                         '_class' => get_class( $this ),
 539                         '_cacheEpoch' => $this->getConfig()->get( 'CacheEpoch' ),
 540                 );
 541         }
 542
 543         /**
 544          * Get this module's last modification timestamp for a given context.
 545          *
 546          * @deprecated since 1.26 Use getDefinitionSummary() instead
 547          * @param ResourceLoaderContext $context Context object
 548          * @return int|null UNIX timestamp
 549          */
 550         public function getModifiedTime( ResourceLoaderContext $context ) {
 551                 return null;
 552         }
 553
 554         /**
 555          * Helper method for providing a version hash to getVersionHash().
 556          *
 557          * @deprecated since 1.26 Use getDefinitionSummary() instead
 558          * @param ResourceLoaderContext $context
 559          * @return string|null Hash
 560          */
 561         public function getModifiedHash( ResourceLoaderContext $context ) {
 562                 return null;
 563         }
 564
 565         /**
 566          * Back-compat dummy for old subclass implementations of getModifiedTime().
 567          *
 568          * This method used to use ObjectCache to track when a hash was first seen. That principle
 569          * stems from a time that ResourceLoader could only identify module versions by timestamp.
 570          * That is no longer the case. Use getDefinitionSummary() directly.
 571          *
 572          * @deprecated since 1.26 Superseded by getVersionHash()
 573          * @param ResourceLoaderContext $context
 574          * @return int UNIX timestamp
 575          */
 576         public function getHashMtime( ResourceLoaderContext $context ) {
 577                 if ( !is_string( $this->getModifiedHash( $context ) ) ) {
 578                         return 1;
 579                 }
 580                 // Dummy that is > 1
 581                 return 2;
 582         }
 583
 584         /**
 585          * Back-compat dummy for old subclass implementations of getModifiedTime().
 586          *
 587          * @since 1.23
 588          * @deprecated since 1.26 Superseded by getVersionHash()
 589          * @param ResourceLoaderContext $context
 590          * @return int UNIX timestamp
 591          */
 592         public function getDefinitionMtime( ResourceLoaderContext $context ) {
 593                 if ( $this->getDefinitionSummary( $context ) === null ) {
 594                         return 1;
 595                 }
 596                 // Dummy that is > 1
 597                 return 2;
 598         }
 599
 600         /**
 601          * Check whether this module is known to be empty. If a child class
 602          * has an easy and cheap way to determine that this module is
 603          * definitely going to be empty, it should override this method to
 604          * return true in that case. Callers may optimize the request for this
 605          * module away if this function returns true.
 606          * @param ResourceLoaderContext $context
 607          * @return bool
 608          */
 609         public function isKnownEmpty( ResourceLoaderContext $context ) {
 610                 return false;
 611         }
 612
 613         /** @var JSParser Lazy-initialized; use self::javaScriptParser() */
 614         private static $jsParser;
 615         private static $parseCacheVersion = 1;
 616
 617         /**
 618          * Validate a given script file; if valid returns the original source.
 619          * If invalid, returns replacement JS source that throws an exception.
 620          *
 621          * @param string $fileName
 622          * @param string $contents
 623          * @return string JS with the original, or a replacement error
 624          */
 625         protected function validateScriptFile( $fileName, $contents ) {
 626                 if ( $this->getConfig()->get( 'ResourceLoaderValidateJS' ) ) {
 627                         // Try for cache hit
 628                         // Use CACHE_ANYTHING since filtering is very slow compared to DB queries
 629                         $key = wfMemcKey( 'resourceloader', 'jsparse', self::$parseCacheVersion, md5( $contents ) );
 630                         $cache = wfGetCache( CACHE_ANYTHING );
 631                         $cacheEntry = $cache->get( $key );
 632                         if ( is_string( $cacheEntry ) ) {
 633                                 return $cacheEntry;
 634                         }
 635
 636                         $parser = self::javaScriptParser();
 637                         try {
 638                                 $parser->parse( $contents, $fileName, 1 );
 639                                 $result = $contents;
 640                         } catch ( Exception $e ) {
 641                                 // We'll save this to cache to avoid having to validate broken JS over and over...
 642                                 $err = $e->getMessage();
 643                                 $result = "throw new Error(" . Xml::encodeJsVar( "JavaScript parse error: $err" ) . ");";
 644                         }
 645
 646                         $cache->set( $key, $result );
 647                         return $result;
 648                 } else {
 649                         return $contents;
 650                 }
 651         }
 652
 653         /**
 654          * @return JSParser
 655          */
 656         protected static function javaScriptParser() {
 657                 if ( !self::$jsParser ) {
 658                         self::$jsParser = new JSParser();
 659                 }
 660                 return self::$jsParser;
 661         }
 662
 663         /**
 664          * Safe version of filemtime(), which doesn't throw a PHP warning if the file doesn't exist
 665          * but returns 1 instead.
 666          * @param string $filename File name
 667          * @return int UNIX timestamp
 668          */
 669         protected static function safeFilemtime( $filename ) {
 670                 wfSuppressWarnings();
 671                 $mtime = filemtime( $filename ) ?: 1;
 672                 wfRestoreWarnings();
 673
 674                 return $mtime;
 675         }
 676 }