includes/resourceloader/ResourceLoaderFileModule.php

   1 <?php
   2 /**
   3  * Resource loader module based on local JavaScript/CSS files.
   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  * ResourceLoader module based on local JavaScript/CSS files.
  27  */
  28 class ResourceLoaderFileModule extends ResourceLoaderModule {
  29         /* Protected Members */
  30
  31         /** @var string Local base path, see __construct() */
  32         protected $localBasePath = '';
  33
  34         /** @var string Remote base path, see __construct() */
  35         protected $remoteBasePath = '';
  36
  37         /** @var array Saves a list of the templates named by the modules. */
  38         protected $templates = array();
  39
  40         /**
  41          * @var array List of paths to JavaScript files to always include
  42          * @par Usage:
  43          * @code
  44          * array( [file-path], [file-path], ... )
  45          * @endcode
  46          */
  47         protected $scripts = array();
  48
  49         /**
  50          * @var array List of JavaScript files to include when using a specific language
  51          * @par Usage:
  52          * @code
  53          * array( [language-code] => array( [file-path], [file-path], ... ), ... )
  54          * @endcode
  55          */
  56         protected $languageScripts = array();
  57
  58         /**
  59          * @var array List of JavaScript files to include when using a specific skin
  60          * @par Usage:
  61          * @code
  62          * array( [skin-name] => array( [file-path], [file-path], ... ), ... )
  63          * @endcode
  64          */
  65         protected $skinScripts = array();
  66
  67         /**
  68          * @var array List of paths to JavaScript files to include in debug mode
  69          * @par Usage:
  70          * @code
  71          * array( [skin-name] => array( [file-path], [file-path], ... ), ... )
  72          * @endcode
  73          */
  74         protected $debugScripts = array();
  75
  76         /**
  77          * @var array List of paths to JavaScript files to include in the startup module
  78          * @par Usage:
  79          * @code
  80          * array( [file-path], [file-path], ... )
  81          * @endcode
  82          */
  83         protected $loaderScripts = array();
  84
  85         /**
  86          * @var array List of paths to CSS files to always include
  87          * @par Usage:
  88          * @code
  89          * array( [file-path], [file-path], ... )
  90          * @endcode
  91          */
  92         protected $styles = array();
  93
  94         /**
  95          * @var array List of paths to CSS files to include when using specific skins
  96          * @par Usage:
  97          * @code
  98          * array( [file-path], [file-path], ... )
  99          * @endcode
 100          */
 101         protected $skinStyles = array();
 102
 103         /**
 104          * @var array List of modules this module depends on
 105          * @par Usage:
 106          * @code
 107          * array( [file-path], [file-path], ... )
 108          * @endcode
 109          */
 110         protected $dependencies = array();
 111
 112         /**
 113          * @var string File name containing the body of the skip function
 114          */
 115         protected $skipFunction = null;
 116
 117         /**
 118          * @var array List of message keys used by this module
 119          * @par Usage:
 120          * @code
 121          * array( [message-key], [message-key], ... )
 122          * @endcode
 123          */
 124         protected $messages = array();
 125
 126         /** @var string Name of group to load this module in */
 127         protected $group;
 128
 129         /** @var string Position on the page to load this module at */
 130         protected $position = 'bottom';
 131
 132         /** @var bool Link to raw files in debug mode */
 133         protected $debugRaw = true;
 134
 135         /** @var bool Whether mw.loader.state() call should be omitted */
 136         protected $raw = false;
 137
 138         protected $targets = array( 'desktop' );
 139
 140         /**
 141          * @var bool Whether getStyleURLsForDebug should return raw file paths,
 142          * or return load.php urls
 143          */
 144         protected $hasGeneratedStyles = false;
 145
 146         /**
 147          * @var array Place where readStyleFile() tracks file dependencies
 148          * @par Usage:
 149          * @code
 150          * array( [file-path], [file-path], ... )
 151          * @endcode
 152          */
 153         protected $localFileRefs = array();
 154
 155         /* Methods */
 156
 157         /**
 158          * Constructs a new module from an options array.
 159          *
 160          * @param array $options List of options; if not given or empty, an empty module will be
 161          *     constructed
 162          * @param string $localBasePath Base path to prepend to all local paths in $options. Defaults
 163          *     to $IP
 164          * @param string $remoteBasePath Base path to prepend to all remote paths in $options. Defaults
 165          *     to $wgResourceBasePath
 166          *
 167          * Below is a description for the $options array:
 168          * @throws InvalidArgumentException
 169          * @par Construction options:
 170          * @code
 171          *     array(
 172          *         // Base path to prepend to all local paths in $options. Defaults to $IP
 173          *         'localBasePath' => [base path],
 174          *         // Base path to prepend to all remote paths in $options. Defaults to $wgResourceBasePath
 175          *         'remoteBasePath' => [base path],
 176          *         // Equivalent of remoteBasePath, but relative to $wgExtensionAssetsPath
 177          *         'remoteExtPath' => [base path],
 178          *         // Equivalent of remoteBasePath, but relative to $wgStylePath
 179          *         'remoteSkinPath' => [base path],
 180          *         // Scripts to always include
 181          *         'scripts' => [file path string or array of file path strings],
 182          *         // Scripts to include in specific language contexts
 183          *         'languageScripts' => array(
 184          *             [language code] => [file path string or array of file path strings],
 185          *         ),
 186          *         // Scripts to include in specific skin contexts
 187          *         'skinScripts' => array(
 188          *             [skin name] => [file path string or array of file path strings],
 189          *         ),
 190          *         // Scripts to include in debug contexts
 191          *         'debugScripts' => [file path string or array of file path strings],
 192          *         // Scripts to include in the startup module
 193          *         'loaderScripts' => [file path string or array of file path strings],
 194          *         // Modules which must be loaded before this module
 195          *         'dependencies' => [module name string or array of module name strings],
 196          *         'templates' => array(
 197          *             [template alias with file.ext] => [file path to a template file],
 198          *         ),
 199          *         // Styles to always load
 200          *         'styles' => [file path string or array of file path strings],
 201          *         // Styles to include in specific skin contexts
 202          *         'skinStyles' => array(
 203          *             [skin name] => [file path string or array of file path strings],
 204          *         ),
 205          *         // Messages to always load
 206          *         'messages' => [array of message key strings],
 207          *         // Group which this module should be loaded together with
 208          *         'group' => [group name string],
 209          *         // Position on the page to load this module at
 210          *         'position' => ['bottom' (default) or 'top']
 211          *         // Function that, if it returns true, makes the loader skip this module.
 212          *         // The file must contain valid JavaScript for execution in a private function.
 213          *         // The file must not contain the "function () {" and "}" wrapper though.
 214          *         'skipFunction' => [file path]
 215          *     )
 216          * @endcode
 217          */
 218         public function __construct(
 219                 $options = array(),
 220                 $localBasePath = null,
 221                 $remoteBasePath = null
 222         ) {
 223                 // Flag to decide whether to automagically add the mediawiki.template module
 224                 $hasTemplates = false;
 225                 // localBasePath and remoteBasePath both have unbelievably long fallback chains
 226                 // and need to be handled separately.
 227                 list( $this->localBasePath, $this->remoteBasePath ) =
 228                         self::extractBasePaths( $options, $localBasePath, $remoteBasePath );
 229
 230                 // Extract, validate and normalise remaining options
 231                 foreach ( $options as $member => $option ) {
 232                         switch ( $member ) {
 233                                 // Lists of file paths
 234                                 case 'scripts':
 235                                 case 'debugScripts':
 236                                 case 'loaderScripts':
 237                                 case 'styles':
 238                                         $this->{$member} = (array)$option;
 239                                         break;
 240                                 case 'templates':
 241                                         $hasTemplates = true;
 242                                         $this->{$member} = (array)$option;
 243                                         break;
 244                                 // Collated lists of file paths
 245                                 case 'languageScripts':
 246                                 case 'skinScripts':
 247                                 case 'skinStyles':
 248                                         if ( !is_array( $option ) ) {
 249                                                 throw new InvalidArgumentException(
 250                                                         "Invalid collated file path list error. " .
 251                                                         "'$option' given, array expected."
 252                                                 );
 253                                         }
 254                                         foreach ( $option as $key => $value ) {
 255                                                 if ( !is_string( $key ) ) {
 256                                                         throw new InvalidArgumentException(
 257                                                                 "Invalid collated file path list key error. " .
 258                                                                 "'$key' given, string expected."
 259                                                         );
 260                                                 }
 261                                                 $this->{$member}[$key] = (array)$value;
 262                                         }
 263                                         break;
 264                                 // Lists of strings
 265                                 case 'dependencies':
 266                                 case 'messages':
 267                                 case 'targets':
 268                                         // Normalise
 269                                         $option = array_values( array_unique( (array)$option ) );
 270                                         sort( $option );
 271
 272                                         $this->{$member} = $option;
 273                                         break;
 274                                 // Single strings
 275                                 case 'position':
 276                                         $this->isPositionDefined = true;
 277                                 case 'group':
 278                                 case 'skipFunction':
 279                                         $this->{$member} = (string)$option;
 280                                         break;
 281                                 // Single booleans
 282                                 case 'debugRaw':
 283                                 case 'raw':
 284                                         $this->{$member} = (bool)$option;
 285                                         break;
 286                         }
 287                 }
 288                 if ( $hasTemplates ) {
 289                         $this->dependencies[] = 'mediawiki.template';
 290                         // Ensure relevant template compiler module gets loaded
 291                         foreach ( $this->templates as $alias => $templatePath ) {
 292                                 if ( is_int( $alias ) ) {
 293                                         $alias = $templatePath;
 294                                 }
 295                                 $suffix = explode( '.', $alias );
 296                                 $suffix = end( $suffix );
 297                                 $compilerModule = 'mediawiki.template.' . $suffix;
 298                                 if ( $suffix !== 'html' && !in_array( $compilerModule, $this->dependencies ) ) {
 299                                         $this->dependencies[] = $compilerModule;
 300                                 }
 301                         }
 302                 }
 303         }
 304
 305         /**
 306          * Extract a pair of local and remote base paths from module definition information.
 307          * Implementation note: the amount of global state used in this function is staggering.
 308          *
 309          * @param array $options Module definition
 310          * @param string $localBasePath Path to use if not provided in module definition. Defaults
 311          *     to $IP
 312          * @param string $remoteBasePath Path to use if not provided in module definition. Defaults
 313          *     to $wgResourceBasePath
 314          * @return array Array( localBasePath, remoteBasePath )
 315          */
 316         public static function extractBasePaths(
 317                 $options = array(),
 318                 $localBasePath = null,
 319                 $remoteBasePath = null
 320         ) {
 321                 global $IP, $wgResourceBasePath;
 322
 323                 // The different ways these checks are done, and their ordering, look very silly,
 324                 // but were preserved for backwards-compatibility just in case. Tread lightly.
 325
 326                 if ( $localBasePath === null ) {
 327                         $localBasePath = $IP;
 328                 }
 329                 if ( $remoteBasePath === null ) {
 330                         $remoteBasePath = $wgResourceBasePath;
 331                 }
 332
 333                 if ( isset( $options['remoteExtPath'] ) ) {
 334                         global $wgExtensionAssetsPath;
 335                         $remoteBasePath = $wgExtensionAssetsPath . '/' . $options['remoteExtPath'];
 336                 }
 337
 338                 if ( isset( $options['remoteSkinPath'] ) ) {
 339                         global $wgStylePath;
 340                         $remoteBasePath = $wgStylePath . '/' . $options['remoteSkinPath'];
 341                 }
 342
 343                 if ( array_key_exists( 'localBasePath', $options ) ) {
 344                         $localBasePath = (string)$options['localBasePath'];
 345                 }
 346
 347                 if ( array_key_exists( 'remoteBasePath', $options ) ) {
 348                         $remoteBasePath = (string)$options['remoteBasePath'];
 349                 }
 350
 351                 // Make sure the remote base path is a complete valid URL,
 352                 // but possibly protocol-relative to avoid cache pollution
 353                 $remoteBasePath = wfExpandUrl( $remoteBasePath, PROTO_RELATIVE );
 354
 355                 return array( $localBasePath, $remoteBasePath );
 356         }
 357
 358         /**
 359          * Gets all scripts for a given context concatenated together.
 360          *
 361          * @param ResourceLoaderContext $context Context in which to generate script
 362          * @return string JavaScript code for $context
 363          */
 364         public function getScript( ResourceLoaderContext $context ) {
 365                 $files = $this->getScriptFiles( $context );
 366                 return $this->readScriptFiles( $files );
 367         }
 368
 369         /**
 370          * @param ResourceLoaderContext $context
 371          * @return array
 372          */
 373         public function getScriptURLsForDebug( ResourceLoaderContext $context ) {
 374                 $urls = array();
 375                 foreach ( $this->getScriptFiles( $context ) as $file ) {
 376                         $urls[] = $this->getRemotePath( $file );
 377                 }
 378                 return $urls;
 379         }
 380
 381         /**
 382          * @return bool
 383          */
 384         public function supportsURLLoading() {
 385                 return $this->debugRaw;
 386         }
 387
 388         /**
 389          * Get loader script.
 390          *
 391          * @return string|bool JavaScript code to be added to startup module
 392          */
 393         public function getLoaderScript() {
 394                 if ( count( $this->loaderScripts ) === 0 ) {
 395                         return false;
 396                 }
 397                 return $this->readScriptFiles( $this->loaderScripts );
 398         }
 399
 400         /**
 401          * Get all styles for a given context.
 402          *
 403          * @param ResourceLoaderContext $context
 404          * @return array CSS code for $context as an associative array mapping media type to CSS text.
 405          */
 406         public function getStyles( ResourceLoaderContext $context ) {
 407                 $styles = $this->readStyleFiles(
 408                         $this->getStyleFiles( $context ),
 409                         $this->getFlip( $context ),
 410                         $context
 411                 );
 412                 // Collect referenced files
 413                 $this->localFileRefs = array_unique( $this->localFileRefs );
 414                 // If the list has been modified since last time we cached it, update the cache
 415                 try {
 416                         if ( $this->localFileRefs !== $this->getFileDependencies( $context->getSkin() ) ) {
 417                                 $dbw = wfGetDB( DB_MASTER );
 418                                 $dbw->replace( 'module_deps',
 419                                         array( array( 'md_module', 'md_skin' ) ), array(
 420                                                 'md_module' => $this->getName(),
 421                                                 'md_skin' => $context->getSkin(),
 422                                                 'md_deps' => FormatJson::encode( $this->localFileRefs ),
 423                                         )
 424                                 );
 425                         }
 426                 } catch ( Exception $e ) {
 427                         wfDebugLog( 'resourceloader', __METHOD__ . ": failed to update DB: $e" );
 428                 }
 429                 return $styles;
 430         }
 431
 432         /**
 433          * @param ResourceLoaderContext $context
 434          * @return array
 435          */
 436         public function getStyleURLsForDebug( ResourceLoaderContext $context ) {
 437                 if ( $this->hasGeneratedStyles ) {
 438                         // Do the default behaviour of returning a url back to load.php
 439                         // but with only=styles.
 440                         return parent::getStyleURLsForDebug( $context );
 441                 }
 442                 // Our module consists entirely of real css files,
 443                 // in debug mode we can load those directly.
 444                 $urls = array();
 445                 foreach ( $this->getStyleFiles( $context ) as $mediaType => $list ) {
 446                         $urls[$mediaType] = array();
 447                         foreach ( $list as $file ) {
 448                                 $urls[$mediaType][] = $this->getRemotePath( $file );
 449                         }
 450                 }
 451                 return $urls;
 452         }
 453
 454         /**
 455          * Gets list of message keys used by this module.
 456          *
 457          * @return array List of message keys
 458          */
 459         public function getMessages() {
 460                 return $this->messages;
 461         }
 462
 463         /**
 464          * Gets the name of the group this module should be loaded in.
 465          *
 466          * @return string Group name
 467          */
 468         public function getGroup() {
 469                 return $this->group;
 470         }
 471
 472         /**
 473          * @return string
 474          */
 475         public function getPosition() {
 476                 return $this->position;
 477         }
 478
 479         /**
 480          * Gets list of names of modules this module depends on.
 481          * @param ResourceLoaderContext context
 482          * @return array List of module names
 483          */
 484         public function getDependencies( ResourceLoaderContext $context = null ) {
 485                 return $this->dependencies;
 486         }
 487
 488         /**
 489          * Get the skip function.
 490          * @return null|string
 491          * @throws MWException
 492          */
 493         public function getSkipFunction() {
 494                 if ( !$this->skipFunction ) {
 495                         return null;
 496                 }
 497
 498                 $localPath = $this->getLocalPath( $this->skipFunction );
 499                 if ( !file_exists( $localPath ) ) {
 500                         throw new MWException( __METHOD__ . ": skip function file not found: \"$localPath\"" );
 501                 }
 502                 $contents = file_get_contents( $localPath );
 503                 if ( $this->getConfig()->get( 'ResourceLoaderValidateStaticJS' ) ) {
 504                         $contents = $this->validateScriptFile( $localPath, $contents );
 505                 }
 506                 return $contents;
 507         }
 508
 509         /**
 510          * @return bool
 511          */
 512         public function isRaw() {
 513                 return $this->raw;
 514         }
 515
 516         /**
 517          * Disable module content versioning.
 518          *
 519          * This class uses getDefinitionSummary() instead, to avoid filesystem overhead
 520          * involved with building the full module content inside a startup request.
 521          *
 522          * @return bool
 523          */
 524         public function enableModuleContentVersion() {
 525                 return false;
 526         }
 527
 528         /**
 529          * Helper method to gather file hashes for getDefinitionSummary.
 530          *
 531          * This function is context-sensitive, only computing hashes of files relevant to the
 532          * given language, skin, etc.
 533          *
 534          * @see ResourceLoaderModule::getFileDependencies
 535          * @param ResourceLoaderContext $context
 536          * @return array
 537          */
 538         protected function getFileHashes( ResourceLoaderContext $context ) {
 539                 $files = array();
 540
 541                 // Flatten style files into $files
 542                 $styles = self::collateFilePathListByOption( $this->styles, 'media', 'all' );
 543                 foreach ( $styles as $styleFiles ) {
 544                         $files = array_merge( $files, $styleFiles );
 545                 }
 546
 547                 $skinFiles = self::collateFilePathListByOption(
 548                         self::tryForKey( $this->skinStyles, $context->getSkin(), 'default' ),
 549                         'media',
 550                         'all'
 551                 );
 552                 foreach ( $skinFiles as $styleFiles ) {
 553                         $files = array_merge( $files, $styleFiles );
 554                 }
 555
 556                 // Final merge, this should result in a master list of dependent files
 557                 $files = array_merge(
 558                         $files,
 559                         $this->scripts,
 560                         $this->templates,
 561                         $context->getDebug() ? $this->debugScripts : array(),
 562                         $this->getLanguageScripts( $context->getLanguage() ),
 563                         self::tryForKey( $this->skinScripts, $context->getSkin(), 'default' ),
 564                         $this->loaderScripts
 565                 );
 566                 if ( $this->skipFunction ) {
 567                         $files[] = $this->skipFunction;
 568                 }
 569                 $files = array_map( array( $this, 'getLocalPath' ), $files );
 570                 // File deps need to be treated separately because they're already prefixed
 571                 $files = array_merge( $files, $this->getFileDependencies( $context->getSkin() ) );
 572                 // Filter out any duplicates from getFileDependencies() and others.
 573                 // Most commonly introduced by compileLessFile(), which always includes the
 574                 // entry point Less file we already know about.
 575                 $files = array_values( array_unique( $files ) );
 576
 577                 // Don't include keys or file paths here, only the hashes. Including that would needlessly
 578                 // cause global cache invalidation when files move or if e.g. the MediaWiki path changes.
 579                 // Any significant ordering is already detected by the definition summary.
 580                 return array_map( array( __CLASS__, 'safeFileHash' ), $files );
 581         }
 582
 583         /**
 584          * Get the definition summary for this module.
 585          *
 586          * @param ResourceLoaderContext $context
 587          * @return array
 588          */
 589         public function getDefinitionSummary( ResourceLoaderContext $context ) {
 590                 $summary = parent::getDefinitionSummary( $context );
 591
 592                 $options = array();
 593                 foreach ( array(
 594                         // T104950: Do not include localBasePath! That path may vary over time and needlessly
 595                         // invalidate cache. If the path changes in a way that makes relative file paths point
 596                         // to something else, getFileHashes() will incorporate that already.
 597                         'scripts',
 598                         'debugScripts',
 599                         'loaderScripts',
 600                         'styles',
 601                         'languageScripts',
 602                         'skinScripts',
 603                         'skinStyles',
 604                         'dependencies',
 605                         'messages',
 606                         'targets',
 607                         'templates',
 608                         'group',
 609                         'position',
 610                         'skipFunction',
 611                         'remoteBasePath',
 612                         'debugRaw',
 613                         'raw',
 614                 ) as $member ) {
 615                         $options[$member] = $this->{$member};
 616                 };
 617
 618                 $summary[] = array(
 619                         'options' => $options,
 620                         'fileHashes' => $this->getFileHashes( $context ),
 621                         'msgBlobMtime' => $this->getMsgBlobMtime( $context->getLanguage() ),
 622                 );
 623                 return $summary;
 624         }
 625
 626         /**
 627          * @param string|ResourceLoaderFilePath $path
 628          * @return string
 629          */
 630         protected function getLocalPath( $path ) {
 631                 if ( $path instanceof ResourceLoaderFilePath ) {
 632                         return $path->getLocalPath();
 633                 }
 634
 635                 return "{$this->localBasePath}/$path";
 636         }
 637
 638         /**
 639          * @param string|ResourceLoaderFilePath $path
 640          * @return string
 641          */
 642         protected function getRemotePath( $path ) {
 643                 if ( $path instanceof ResourceLoaderFilePath ) {
 644                         return $path->getRemotePath();
 645                 }
 646
 647                 return "{$this->remoteBasePath}/$path";
 648         }
 649
 650         /**
 651          * Infer the stylesheet language from a stylesheet file path.
 652          *
 653          * @since 1.22
 654          * @param string $path
 655          * @return string The stylesheet language name
 656          */
 657         public function getStyleSheetLang( $path ) {
 658                 return preg_match( '/\.less$/i', $path ) ? 'less' : 'css';
 659         }
 660
 661         /**
 662          * Collates file paths by option (where provided).
 663          *
 664          * @param array $list List of file paths in any combination of index/path
 665          *     or path/options pairs
 666          * @param string $option Option name
 667          * @param mixed $default Default value if the option isn't set
 668          * @return array List of file paths, collated by $option
 669          */
 670         protected static function collateFilePathListByOption( array $list, $option, $default ) {
 671                 $collatedFiles = array();
 672                 foreach ( (array)$list as $key => $value ) {
 673                         if ( is_int( $key ) ) {
 674                                 // File name as the value
 675                                 if ( !isset( $collatedFiles[$default] ) ) {
 676                                         $collatedFiles[$default] = array();
 677                                 }
 678                                 $collatedFiles[$default][] = $value;
 679                         } elseif ( is_array( $value ) ) {
 680                                 // File name as the key, options array as the value
 681                                 $optionValue = isset( $value[$option] ) ? $value[$option] : $default;
 682                                 if ( !isset( $collatedFiles[$optionValue] ) ) {
 683                                         $collatedFiles[$optionValue] = array();
 684                                 }
 685                                 $collatedFiles[$optionValue][] = $key;
 686                         }
 687                 }
 688                 return $collatedFiles;
 689         }
 690
 691         /**
 692          * Get a list of element that match a key, optionally using a fallback key.
 693          *
 694          * @param array $list List of lists to select from
 695          * @param string $key Key to look for in $map
 696          * @param string $fallback Key to look for in $list if $key doesn't exist
 697          * @return array List of elements from $map which matched $key or $fallback,
 698          *  or an empty list in case of no match
 699          */
 700         protected static function tryForKey( array $list, $key, $fallback = null ) {
 701                 if ( isset( $list[$key] ) && is_array( $list[$key] ) ) {
 702                         return $list[$key];
 703                 } elseif ( is_string( $fallback )
 704                         && isset( $list[$fallback] )
 705                         && is_array( $list[$fallback] )
 706                 ) {
 707                         return $list[$fallback];
 708                 }
 709                 return array();
 710         }
 711
 712         /**
 713          * Get a list of file paths for all scripts in this module, in order of proper execution.
 714          *
 715          * @param ResourceLoaderContext $context
 716          * @return array List of file paths
 717          */
 718         protected function getScriptFiles( ResourceLoaderContext $context ) {
 719                 $files = array_merge(
 720                         $this->scripts,
 721                         $this->getLanguageScripts( $context->getLanguage() ),
 722                         self::tryForKey( $this->skinScripts, $context->getSkin(), 'default' )
 723                 );
 724                 if ( $context->getDebug() ) {
 725                         $files = array_merge( $files, $this->debugScripts );
 726                 }
 727
 728                 return array_unique( $files, SORT_REGULAR );
 729         }
 730
 731         /**
 732          * Get the set of language scripts for the given language,
 733          * possibly using a fallback language.
 734          *
 735          * @param string $lang
 736          * @return array
 737          */
 738         private function getLanguageScripts( $lang ) {
 739                 $scripts = self::tryForKey( $this->languageScripts, $lang );
 740                 if ( $scripts ) {
 741                         return $scripts;
 742                 }
 743                 $fallbacks = Language::getFallbacksFor( $lang );
 744                 foreach ( $fallbacks as $lang ) {
 745                         $scripts = self::tryForKey( $this->languageScripts, $lang );
 746                         if ( $scripts ) {
 747                                 return $scripts;
 748                         }
 749                 }
 750
 751                 return array();
 752         }
 753
 754         /**
 755          * Get a list of file paths for all styles in this module, in order of proper inclusion.
 756          *
 757          * @param ResourceLoaderContext $context
 758          * @return array List of file paths
 759          */
 760         public function getStyleFiles( ResourceLoaderContext $context ) {
 761                 return array_merge_recursive(
 762                         self::collateFilePathListByOption( $this->styles, 'media', 'all' ),
 763                         self::collateFilePathListByOption(
 764                                 self::tryForKey( $this->skinStyles, $context->getSkin(), 'default' ),
 765                                 'media',
 766                                 'all'
 767                         )
 768                 );
 769         }
 770
 771         /**
 772          * Gets a list of file paths for all skin styles in the module used by
 773          * the skin.
 774          *
 775          * @param string $skinName The name of the skin
 776          * @return array A list of file paths collated by media type
 777          */
 778         protected function getSkinStyleFiles( $skinName ) {
 779                 return self::collateFilePathListByOption(
 780                         self::tryForKey( $this->skinStyles, $skinName ),
 781                         'media',
 782                         'all'
 783                 );
 784         }
 785
 786         /**
 787          * Gets a list of file paths for all skin style files in the module,
 788          * for all available skins.
 789          *
 790          * @return array A list of file paths collated by media type
 791          */
 792         protected function getAllSkinStyleFiles() {
 793                 $styleFiles = array();
 794                 $internalSkinNames = array_keys( Skin::getSkinNames() );
 795                 $internalSkinNames[] = 'default';
 796
 797                 foreach ( $internalSkinNames as $internalSkinName ) {
 798                         $styleFiles = array_merge_recursive(
 799                                 $styleFiles,
 800                                 $this->getSkinStyleFiles( $internalSkinName )
 801                         );
 802                 }
 803
 804                 return $styleFiles;
 805         }
 806
 807         /**
 808          * Returns all style files and all skin style files used by this module.
 809          *
 810          * @return array
 811          */
 812         public function getAllStyleFiles() {
 813                 $collatedStyleFiles = array_merge_recursive(
 814                         self::collateFilePathListByOption( $this->styles, 'media', 'all' ),
 815                         $this->getAllSkinStyleFiles()
 816                 );
 817
 818                 $result = array();
 819
 820                 foreach ( $collatedStyleFiles as $media => $styleFiles ) {
 821                         foreach ( $styleFiles as $styleFile ) {
 822                                 $result[] = $this->getLocalPath( $styleFile );
 823                         }
 824                 }
 825
 826                 return $result;
 827         }
 828
 829         /**
 830          * Gets the contents of a list of JavaScript files.
 831          *
 832          * @param array $scripts List of file paths to scripts to read, remap and concetenate
 833          * @throws MWException
 834          * @return string Concatenated and remapped JavaScript data from $scripts
 835          */
 836         protected function readScriptFiles( array $scripts ) {
 837                 if ( empty( $scripts ) ) {
 838                         return '';
 839                 }
 840                 $js = '';
 841                 foreach ( array_unique( $scripts, SORT_REGULAR ) as $fileName ) {
 842                         $localPath = $this->getLocalPath( $fileName );
 843                         if ( !file_exists( $localPath ) ) {
 844                                 throw new MWException( __METHOD__ . ": script file not found: \"$localPath\"" );
 845                         }
 846                         $contents = file_get_contents( $localPath );
 847                         if ( $this->getConfig()->get( 'ResourceLoaderValidateStaticJS' ) ) {
 848                                 // Static files don't really need to be checked as often; unlike
 849                                 // on-wiki module they shouldn't change unexpectedly without
 850                                 // admin interference.
 851                                 $contents = $this->validateScriptFile( $fileName, $contents );
 852                         }
 853                         $js .= $contents . "\n";
 854                 }
 855                 return $js;
 856         }
 857
 858         /**
 859          * Gets the contents of a list of CSS files.
 860          *
 861          * @param array $styles List of media type/list of file paths pairs, to read, remap and
 862          * concetenate
 863          * @param bool $flip
 864          * @param ResourceLoaderContext $context (optional)
 865          *
 866          * @throws MWException
 867          * @return array List of concatenated and remapped CSS data from $styles,
 868          *     keyed by media type
 869          */
 870         public function readStyleFiles( array $styles, $flip, $context = null ) {
 871                 if ( empty( $styles ) ) {
 872                         return array();
 873                 }
 874                 foreach ( $styles as $media => $files ) {
 875                         $uniqueFiles = array_unique( $files, SORT_REGULAR );
 876                         $styleFiles = array();
 877                         foreach ( $uniqueFiles as $file ) {
 878                                 $styleFiles[] = $this->readStyleFile( $file, $flip, $context );
 879                         }
 880                         $styles[$media] = implode( "\n", $styleFiles );
 881                 }
 882                 return $styles;
 883         }
 884
 885         /**
 886          * Reads a style file.
 887          *
 888          * This method can be used as a callback for array_map()
 889          *
 890          * @param string $path File path of style file to read
 891          * @param bool $flip
 892          * @param ResourceLoaderContext $context (optional)
 893          *
 894          * @return string CSS data in script file
 895          * @throws MWException If the file doesn't exist
 896          */
 897         protected function readStyleFile( $path, $flip, $context = null ) {
 898                 $localPath = $this->getLocalPath( $path );
 899                 $remotePath = $this->getRemotePath( $path );
 900                 if ( !file_exists( $localPath ) ) {
 901                         $msg = __METHOD__ . ": style file not found: \"$localPath\"";
 902                         wfDebugLog( 'resourceloader', $msg );
 903                         throw new MWException( $msg );
 904                 }
 905
 906                 if ( $this->getStyleSheetLang( $localPath ) === 'less' ) {
 907                         $compiler = $this->getLessCompiler( $context );
 908                         $style = $this->compileLessFile( $localPath, $compiler );
 909                         $this->hasGeneratedStyles = true;
 910                 } else {
 911                         $style = file_get_contents( $localPath );
 912                 }
 913
 914                 if ( $flip ) {
 915                         $style = CSSJanus::transform( $style, true, false );
 916                 }
 917                 $localDir = dirname( $localPath );
 918                 $remoteDir = dirname( $remotePath );
 919                 // Get and register local file references
 920                 $this->localFileRefs = array_merge(
 921                         $this->localFileRefs,
 922                         CSSMin::getLocalFileReferences( $style, $localDir )
 923                 );
 924                 return CSSMin::remap(
 925                         $style, $localDir, $remoteDir, true
 926                 );
 927         }
 928
 929         /**
 930          * Get whether CSS for this module should be flipped
 931          * @param ResourceLoaderContext $context
 932          * @return bool
 933          */
 934         public function getFlip( $context ) {
 935                 return $context->getDirection() === 'rtl';
 936         }
 937
 938         /**
 939          * Get target(s) for the module, eg ['desktop'] or ['desktop', 'mobile']
 940          *
 941          * @return array Array of strings
 942          */
 943         public function getTargets() {
 944                 return $this->targets;
 945         }
 946
 947         /**
 948          * Compile a LESS file into CSS.
 949          *
 950          * Keeps track of all used files and adds them to localFileRefs.
 951          *
 952          * @since 1.22
 953          * @throws Exception If lessc encounters a parse error
 954          * @param string $fileName File path of LESS source
 955          * @param lessc $compiler Compiler to use, if not default
 956          * @return string CSS source
 957          */
 958         protected function compileLessFile( $fileName, $compiler = null ) {
 959                 if ( !$compiler ) {
 960                         $compiler = $this->getLessCompiler();
 961                 }
 962                 $result = $compiler->compileFile( $fileName );
 963                 $this->localFileRefs += array_keys( $compiler->allParsedFiles() );
 964                 return $result;
 965         }
 966
 967         /**
 968          * Get a LESS compiler instance for this module in given context.
 969          *
 970          * Just calls ResourceLoader::getLessCompiler() by default to get a global compiler.
 971          *
 972          * @param ResourceLoaderContext $context
 973          * @throws MWException
 974          * @since 1.24
 975          * @return lessc
 976          */
 977         protected function getLessCompiler( ResourceLoaderContext $context = null ) {
 978                 return ResourceLoader::getLessCompiler( $this->getConfig() );
 979         }
 980
 981         /**
 982          * Takes named templates by the module and returns an array mapping.
 983          * @return array of templates mapping template alias to content
 984          * @throws MWException
 985          */
 986         public function getTemplates() {
 987                 $templates = array();
 988
 989                 foreach ( $this->templates as $alias => $templatePath ) {
 990                         // Alias is optional
 991                         if ( is_int( $alias ) ) {
 992                                 $alias = $templatePath;
 993                         }
 994                         $localPath = $this->getLocalPath( $templatePath );
 995                         if ( file_exists( $localPath ) ) {
 996                                 $content = file_get_contents( $localPath );
 997                                 $templates[$alias] = $content;
 998                         } else {
 999                                 $msg = __METHOD__ . ": template file not found: \"$localPath\"";
1000                                 wfDebugLog( 'resourceloader', $msg );
1001                                 throw new MWException( $msg );
1002                         }
1003                 }
1004                 return $templates;
1005         }
1006 }