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         /**
  38          * @var array List of paths to JavaScript files to always include
  39          * @par Usage:
  40          * @code
  41          * array( [file-path], [file-path], ... )
  42          * @endcode
  43          */
  44         protected $scripts = array();
  45
  46         /**
  47          * @var array List of JavaScript files to include when using a specific language
  48          * @par Usage:
  49          * @code
  50          * array( [language-code] => array( [file-path], [file-path], ... ), ... )
  51          * @endcode
  52          */
  53         protected $languageScripts = array();
  54
  55         /**
  56          * @var array List of JavaScript files to include when using a specific skin
  57          * @par Usage:
  58          * @code
  59          * array( [skin-name] => array( [file-path], [file-path], ... ), ... )
  60          * @endcode
  61          */
  62         protected $skinScripts = array();
  63
  64         /**
  65          * @var array List of paths to JavaScript files to include in debug mode
  66          * @par Usage:
  67          * @code
  68          * array( [skin-name] => array( [file-path], [file-path], ... ), ... )
  69          * @endcode
  70          */
  71         protected $debugScripts = array();
  72
  73         /**
  74          * @var array List of paths to JavaScript files to include in the startup module
  75          * @par Usage:
  76          * @code
  77          * array( [file-path], [file-path], ... )
  78          * @endcode
  79          */
  80         protected $loaderScripts = array();
  81
  82         /**
  83          * @var array List of paths to CSS files to always include
  84          * @par Usage:
  85          * @code
  86          * array( [file-path], [file-path], ... )
  87          * @endcode
  88          */
  89         protected $styles = array();
  90
  91         /**
  92          * @var array List of paths to CSS files to include when using specific skins
  93          * @par Usage:
  94          * @code
  95          * array( [file-path], [file-path], ... )
  96          * @endcode
  97          */
  98         protected $skinStyles = array();
  99
 100         /**
 101          * @var array List of modules this module depends on
 102          * @par Usage:
 103          * @code
 104          * array( [file-path], [file-path], ... )
 105          * @endcode
 106          */
 107         protected $dependencies = array();
 108
 109         /**
 110          * @var string File name containing the body of the skip function
 111          */
 112         protected $skipFunction = null;
 113
 114         /**
 115          * @var array List of message keys used by this module
 116          * @par Usage:
 117          * @code
 118          * array( [message-key], [message-key], ... )
 119          * @endcode
 120          */
 121         protected $messages = array();
 122
 123         /** @var string Name of group to load this module in */
 124         protected $group;
 125
 126         /** @var string Position on the page to load this module at */
 127         protected $position = 'bottom';
 128
 129         /** @var bool Link to raw files in debug mode */
 130         protected $debugRaw = true;
 131
 132         /** @var bool Whether mw.loader.state() call should be omitted */
 133         protected $raw = false;
 134
 135         protected $targets = array( 'desktop' );
 136
 137         /**
 138          * @var bool Whether getStyleURLsForDebug should return raw file paths,
 139          * or return load.php urls
 140          */
 141         protected $hasGeneratedStyles = false;
 142
 143         /**
 144          * @var array Cache for mtime
 145          * @par Usage:
 146          * @code
 147          * array( [hash] => [mtime], [hash] => [mtime], ... )
 148          * @endcode
 149          */
 150         protected $modifiedTime = array();
 151
 152         /**
 153          * @var array Place where readStyleFile() tracks file dependencies
 154          * @par Usage:
 155          * @code
 156          * array( [file-path], [file-path], ... )
 157          * @endcode
 158          */
 159         protected $localFileRefs = array();
 160
 161         /* Methods */
 162
 163         /**
 164          * Constructs a new module from an options array.
 165          *
 166          * @param array $options List of options; if not given or empty, an empty module will be
 167          *     constructed
 168          * @param string $localBasePath Base path to prepend to all local paths in $options. Defaults
 169          *     to $IP
 170          * @param string $remoteBasePath Base path to prepend to all remote paths in $options. Defaults
 171          *     to $wgScriptPath
 172          *
 173          * Below is a description for the $options array:
 174          * @throws MWException
 175          * @par Construction options:
 176          * @code
 177          *     array(
 178          *         // Base path to prepend to all local paths in $options. Defaults to $IP
 179          *         'localBasePath' => [base path],
 180          *         // Base path to prepend to all remote paths in $options. Defaults to $wgScriptPath
 181          *         'remoteBasePath' => [base path],
 182          *         // Equivalent of remoteBasePath, but relative to $wgExtensionAssetsPath
 183          *         'remoteExtPath' => [base path],
 184          *         // Scripts to always include
 185          *         'scripts' => [file path string or array of file path strings],
 186          *         // Scripts to include in specific language contexts
 187          *         'languageScripts' => array(
 188          *             [language code] => [file path string or array of file path strings],
 189          *         ),
 190          *         // Scripts to include in specific skin contexts
 191          *         'skinScripts' => array(
 192          *             [skin name] => [file path string or array of file path strings],
 193          *         ),
 194          *         // Scripts to include in debug contexts
 195          *         'debugScripts' => [file path string or array of file path strings],
 196          *         // Scripts to include in the startup module
 197          *         'loaderScripts' => [file path string or array of file path strings],
 198          *         // Modules which must be loaded before this module
 199          *         'dependencies' => [module name string or array of module name strings],
 200          *         // Styles to always load
 201          *         'styles' => [file path string or array of file path strings],
 202          *         // Styles to include in specific skin contexts
 203          *         'skinStyles' => array(
 204          *             [skin name] => [file path string or array of file path strings],
 205          *         ),
 206          *         // Messages to always load
 207          *         'messages' => [array of message key strings],
 208          *         // Group which this module should be loaded together with
 209          *         'group' => [group name string],
 210          *         // Position on the page to load this module at
 211          *         'position' => ['bottom' (default) or 'top']
 212          *         // Function that, if it returns true, makes the loader skip this module.
 213          *         // The file must contain valid JavaScript for execution in a private function.
 214          *         // The file must not contain the "function () {" and "}" wrapper though.
 215          *         'skipFunction' => [file path]
 216          *     )
 217          * @endcode
 218          */
 219         public function __construct( $options = array(), $localBasePath = null,
 220                 $remoteBasePath = null
 221         ) {
 222                 global $IP, $wgScriptPath, $wgResourceBasePath;
 223                 $this->localBasePath = $localBasePath === null ? $IP : $localBasePath;
 224                 if ( $remoteBasePath !== null ) {
 225                         $this->remoteBasePath = $remoteBasePath;
 226                 } else {
 227                         $this->remoteBasePath = $wgResourceBasePath === null ? $wgScriptPath : $wgResourceBasePath;
 228                 }
 229
 230                 if ( isset( $options['remoteExtPath'] ) ) {
 231                         global $wgExtensionAssetsPath;
 232                         $this->remoteBasePath = $wgExtensionAssetsPath . '/' . $options['remoteExtPath'];
 233                 }
 234
 235                 foreach ( $options as $member => $option ) {
 236                         switch ( $member ) {
 237                                 // Lists of file paths
 238                                 case 'scripts':
 239                                 case 'debugScripts':
 240                                 case 'loaderScripts':
 241                                 case 'styles':
 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 MWException(
 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 MWException(
 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 'group':
 276                                 case 'position':
 277                                 case 'localBasePath':
 278                                 case 'remoteBasePath':
 279                                 case 'skipFunction':
 280                                         $this->{$member} = (string)$option;
 281                                         break;
 282                                 // Single booleans
 283                                 case 'debugRaw':
 284                                 case 'raw':
 285                                         $this->{$member} = (bool)$option;
 286                                         break;
 287                         }
 288                 }
 289                 // Make sure the remote base path is a complete valid URL,
 290                 // but possibly protocol-relative to avoid cache pollution
 291                 $this->remoteBasePath = wfExpandUrl( $this->remoteBasePath, PROTO_RELATIVE );
 292         }
 293
 294         /**
 295          * Gets all scripts for a given context concatenated together.
 296          *
 297          * @param ResourceLoaderContext $context Context in which to generate script
 298          * @return string JavaScript code for $context
 299          */
 300         public function getScript( ResourceLoaderContext $context ) {
 301                 $files = $this->getScriptFiles( $context );
 302                 return $this->readScriptFiles( $files );
 303         }
 304
 305         /**
 306          * @param ResourceLoaderContext $context
 307          * @return array
 308          */
 309         public function getScriptURLsForDebug( ResourceLoaderContext $context ) {
 310                 $urls = array();
 311                 foreach ( $this->getScriptFiles( $context ) as $file ) {
 312                         $urls[] = $this->getRemotePath( $file );
 313                 }
 314                 return $urls;
 315         }
 316
 317         /**
 318          * @return bool
 319          */
 320         public function supportsURLLoading() {
 321                 return $this->debugRaw;
 322         }
 323
 324         /**
 325          * Get loader script.
 326          *
 327          * @return string|false JavaScript code to be added to startup module
 328          */
 329         public function getLoaderScript() {
 330                 if ( count( $this->loaderScripts ) === 0 ) {
 331                         return false;
 332                 }
 333                 return $this->readScriptFiles( $this->loaderScripts );
 334         }
 335
 336         /**
 337          * Get all styles for a given context.
 338          *
 339          * @param ResourceLoaderContext $context
 340          * @return array CSS code for $context as an associative array mapping media type to CSS text.
 341          */
 342         public function getStyles( ResourceLoaderContext $context ) {
 343                 $styles = $this->readStyleFiles(
 344                         $this->getStyleFiles( $context ),
 345                         $this->getFlip( $context )
 346                 );
 347                 // Collect referenced files
 348                 $this->localFileRefs = array_unique( $this->localFileRefs );
 349                 // If the list has been modified since last time we cached it, update the cache
 350                 try {
 351                         if ( $this->localFileRefs !== $this->getFileDependencies( $context->getSkin() ) ) {
 352                                 $dbw = wfGetDB( DB_MASTER );
 353                                 $dbw->replace( 'module_deps',
 354                                         array( array( 'md_module', 'md_skin' ) ), array(
 355                                                 'md_module' => $this->getName(),
 356                                                 'md_skin' => $context->getSkin(),
 357                                                 'md_deps' => FormatJson::encode( $this->localFileRefs ),
 358                                         )
 359                                 );
 360                         }
 361                 } catch ( Exception $e ) {
 362                         wfDebugLog( 'resourceloader', __METHOD__ . ": failed to update DB: $e" );
 363                 }
 364                 return $styles;
 365         }
 366
 367         /**
 368          * @param ResourceLoaderContext $context
 369          * @return array
 370          */
 371         public function getStyleURLsForDebug( ResourceLoaderContext $context ) {
 372                 if ( $this->hasGeneratedStyles ) {
 373                         // Do the default behaviour of returning a url back to load.php
 374                         // but with only=styles.
 375                         return parent::getStyleURLsForDebug( $context );
 376                 }
 377                 // Our module consists entirely of real css files,
 378                 // in debug mode we can load those directly.
 379                 $urls = array();
 380                 foreach ( $this->getStyleFiles( $context ) as $mediaType => $list ) {
 381                         $urls[$mediaType] = array();
 382                         foreach ( $list as $file ) {
 383                                 $urls[$mediaType][] = $this->getRemotePath( $file );
 384                         }
 385                 }
 386                 return $urls;
 387         }
 388
 389         /**
 390          * Gets list of message keys used by this module.
 391          *
 392          * @return array List of message keys
 393          */
 394         public function getMessages() {
 395                 return $this->messages;
 396         }
 397
 398         /**
 399          * Gets the name of the group this module should be loaded in.
 400          *
 401          * @return string Group name
 402          */
 403         public function getGroup() {
 404                 return $this->group;
 405         }
 406
 407         /**
 408          * @return string
 409          */
 410         public function getPosition() {
 411                 return $this->position;
 412         }
 413
 414         /**
 415          * Gets list of names of modules this module depends on.
 416          *
 417          * @return array List of module names
 418          */
 419         public function getDependencies() {
 420                 return $this->dependencies;
 421         }
 422
 423         /**
 424          * Get the skip function.
 425          *
 426          * @return string|null
 427          */
 428         public function getSkipFunction() {
 429                 if ( !$this->skipFunction ) {
 430                         return null;
 431                 }
 432
 433                 global $wgResourceLoaderValidateStaticJS;
 434                 $localPath = $this->getLocalPath( $this->skipFunction );
 435                 if ( !file_exists( $localPath ) ) {
 436                         throw new MWException( __METHOD__ . ": skip function file not found: \"$localPath\"" );
 437                 }
 438                 $contents = file_get_contents( $localPath );
 439                 if ( $wgResourceLoaderValidateStaticJS ) {
 440                         $contents = $this->validateScriptFile( $fileName, $contents );
 441                 }
 442                 return $contents;
 443         }
 444
 445         /**
 446          * @return bool
 447          */
 448         public function isRaw() {
 449                 return $this->raw;
 450         }
 451
 452         /**
 453          * Get the last modified timestamp of this module.
 454          *
 455          * Last modified timestamps are calculated from the highest last modified
 456          * timestamp of this module's constituent files as well as the files it
 457          * depends on. This function is context-sensitive, only performing
 458          * calculations on files relevant to the given language, skin and debug
 459          * mode.
 460          *
 461          * @param ResourceLoaderContext $context Context in which to calculate
 462          *     the modified time
 463          * @return int UNIX timestamp
 464          * @see ResourceLoaderModule::getFileDependencies
 465          */
 466         public function getModifiedTime( ResourceLoaderContext $context ) {
 467                 if ( isset( $this->modifiedTime[$context->getHash()] ) ) {
 468                         return $this->modifiedTime[$context->getHash()];
 469                 }
 470                 wfProfileIn( __METHOD__ );
 471
 472                 $files = array();
 473
 474                 // Flatten style files into $files
 475                 $styles = self::collateFilePathListByOption( $this->styles, 'media', 'all' );
 476                 foreach ( $styles as $styleFiles ) {
 477                         $files = array_merge( $files, $styleFiles );
 478                 }
 479
 480                 $skinFiles = self::collateFilePathListByOption(
 481                         self::tryForKey( $this->skinStyles, $context->getSkin(), 'default' ),
 482                         'media',
 483                         'all'
 484                 );
 485                 foreach ( $skinFiles as $styleFiles ) {
 486                         $files = array_merge( $files, $styleFiles );
 487                 }
 488
 489                 // Final merge, this should result in a master list of dependent files
 490                 $files = array_merge(
 491                         $files,
 492                         $this->scripts,
 493                         $context->getDebug() ? $this->debugScripts : array(),
 494                         self::tryForKey( $this->languageScripts, $context->getLanguage() ),
 495                         self::tryForKey( $this->skinScripts, $context->getSkin(), 'default' ),
 496                         $this->loaderScripts
 497                 );
 498                 if ( $this->skipFunction ) {
 499                         $files[] = $this->skipFunction;
 500                 }
 501                 $files = array_map( array( $this, 'getLocalPath' ), $files );
 502                 // File deps need to be treated separately because they're already prefixed
 503                 $files = array_merge( $files, $this->getFileDependencies( $context->getSkin() ) );
 504
 505                 // If a module is nothing but a list of dependencies, we need to avoid
 506                 // giving max() an empty array
 507                 if ( count( $files ) === 0 ) {
 508                         $this->modifiedTime[$context->getHash()] = 1;
 509                         wfProfileOut( __METHOD__ );
 510                         return $this->modifiedTime[$context->getHash()];
 511                 }
 512
 513                 wfProfileIn( __METHOD__ . '-filemtime' );
 514                 $filesMtime = max( array_map( array( __CLASS__, 'safeFilemtime' ), $files ) );
 515                 wfProfileOut( __METHOD__ . '-filemtime' );
 516
 517                 $this->modifiedTime[$context->getHash()] = max(
 518                         $filesMtime,
 519                         $this->getMsgBlobMtime( $context->getLanguage() ),
 520                         $this->getDefinitionMtime( $context )
 521                 );
 522
 523                 wfProfileOut( __METHOD__ );
 524                 return $this->modifiedTime[$context->getHash()];
 525         }
 526
 527         /**
 528          * Get the definition summary for this module.
 529          *
 530          * @return array
 531          */
 532         public function getDefinitionSummary( ResourceLoaderContext $context ) {
 533                 $summary = array(
 534                         'class' => get_class( $this ),
 535                 );
 536                 foreach ( array(
 537                         'scripts',
 538                         'debugScripts',
 539                         'loaderScripts',
 540                         'styles',
 541                         'languageScripts',
 542                         'skinScripts',
 543                         'skinStyles',
 544                         'dependencies',
 545                         'messages',
 546                         'targets',
 547                         'group',
 548                         'position',
 549                         'skipFunction',
 550                         'localBasePath',
 551                         'remoteBasePath',
 552                         'debugRaw',
 553                         'raw',
 554                 ) as $member ) {
 555                         $summary[$member] = $this->{$member};
 556                 };
 557                 return $summary;
 558         }
 559
 560         /* Protected Methods */
 561
 562         /**
 563          * @param string $path
 564          * @return string
 565          */
 566         protected function getLocalPath( $path ) {
 567                 return "{$this->localBasePath}/$path";
 568         }
 569
 570         /**
 571          * @param string $path
 572          * @return string
 573          */
 574         protected function getRemotePath( $path ) {
 575                 return "{$this->remoteBasePath}/$path";
 576         }
 577
 578         /**
 579          * Infer the stylesheet language from a stylesheet file path.
 580          *
 581          * @since 1.22
 582          * @param string $path
 583          * @return string The stylesheet language name
 584          */
 585         public function getStyleSheetLang( $path ) {
 586                 return preg_match( '/\.less$/i', $path ) ? 'less' : 'css';
 587         }
 588
 589         /**
 590          * Collates file paths by option (where provided).
 591          *
 592          * @param array $list List of file paths in any combination of index/path
 593          *     or path/options pairs
 594          * @param string $option Option name
 595          * @param mixed $default Default value if the option isn't set
 596          * @return array List of file paths, collated by $option
 597          */
 598         protected static function collateFilePathListByOption( array $list, $option, $default ) {
 599                 $collatedFiles = array();
 600                 foreach ( (array)$list as $key => $value ) {
 601                         if ( is_int( $key ) ) {
 602                                 // File name as the value
 603                                 if ( !isset( $collatedFiles[$default] ) ) {
 604                                         $collatedFiles[$default] = array();
 605                                 }
 606                                 $collatedFiles[$default][] = $value;
 607                         } elseif ( is_array( $value ) ) {
 608                                 // File name as the key, options array as the value
 609                                 $optionValue = isset( $value[$option] ) ? $value[$option] : $default;
 610                                 if ( !isset( $collatedFiles[$optionValue] ) ) {
 611                                         $collatedFiles[$optionValue] = array();
 612                                 }
 613                                 $collatedFiles[$optionValue][] = $key;
 614                         }
 615                 }
 616                 return $collatedFiles;
 617         }
 618
 619         /**
 620          * Get a list of element that match a key, optionally using a fallback key.
 621          *
 622          * @param array $list List of lists to select from
 623          * @param string $key Key to look for in $map
 624          * @param string $fallback Key to look for in $list if $key doesn't exist
 625          * @return array List of elements from $map which matched $key or $fallback,
 626          *  or an empty list in case of no match
 627          */
 628         protected static function tryForKey( array $list, $key, $fallback = null ) {
 629                 if ( isset( $list[$key] ) && is_array( $list[$key] ) ) {
 630                         return $list[$key];
 631                 } elseif ( is_string( $fallback )
 632                         && isset( $list[$fallback] )
 633                         && is_array( $list[$fallback] )
 634                 ) {
 635                         return $list[$fallback];
 636                 }
 637                 return array();
 638         }
 639
 640         /**
 641          * Get a list of file paths for all scripts in this module, in order of proper execution.
 642          *
 643          * @param ResourceLoaderContext $context
 644          * @return array List of file paths
 645          */
 646         protected function getScriptFiles( ResourceLoaderContext $context ) {
 647                 $files = array_merge(
 648                         $this->scripts,
 649                         self::tryForKey( $this->languageScripts, $context->getLanguage() ),
 650                         self::tryForKey( $this->skinScripts, $context->getSkin(), 'default' )
 651                 );
 652                 if ( $context->getDebug() ) {
 653                         $files = array_merge( $files, $this->debugScripts );
 654                 }
 655
 656                 return array_unique( $files );
 657         }
 658
 659         /**
 660          * Get a list of file paths for all styles in this module, in order of proper inclusion.
 661          *
 662          * @param ResourceLoaderContext $context
 663          * @return array List of file paths
 664          */
 665         public function getStyleFiles( ResourceLoaderContext $context ) {
 666                 return array_merge_recursive(
 667                         self::collateFilePathListByOption( $this->styles, 'media', 'all' ),
 668                         self::collateFilePathListByOption(
 669                                 self::tryForKey( $this->skinStyles, $context->getSkin(), 'default' ),
 670                                 'media',
 671                                 'all'
 672                         )
 673                 );
 674         }
 675
 676         /**
 677          * Returns all style files used by this module
 678          * @return array
 679          */
 680         public function getAllStyleFiles() {
 681                 $files = array();
 682                 foreach ( (array)$this->styles as $key => $value ) {
 683                         if ( is_array( $value ) ) {
 684                                 $path = $key;
 685                         } else {
 686                                 $path = $value;
 687                         }
 688                         $files[] = $this->getLocalPath( $path );
 689                 }
 690                 return $files;
 691         }
 692
 693         /**
 694          * Gets the contents of a list of JavaScript files.
 695          *
 696          * @param array $scripts List of file paths to scripts to read, remap and concetenate
 697          * @throws MWException
 698          * @return string Concatenated and remapped JavaScript data from $scripts
 699          */
 700         protected function readScriptFiles( array $scripts ) {
 701                 global $wgResourceLoaderValidateStaticJS;
 702                 if ( empty( $scripts ) ) {
 703                         return '';
 704                 }
 705                 $js = '';
 706                 foreach ( array_unique( $scripts ) as $fileName ) {
 707                         $localPath = $this->getLocalPath( $fileName );
 708                         if ( !file_exists( $localPath ) ) {
 709                                 throw new MWException( __METHOD__ . ": script file not found: \"$localPath\"" );
 710                         }
 711                         $contents = file_get_contents( $localPath );
 712                         if ( $wgResourceLoaderValidateStaticJS ) {
 713                                 // Static files don't really need to be checked as often; unlike
 714                                 // on-wiki module they shouldn't change unexpectedly without
 715                                 // admin interference.
 716                                 $contents = $this->validateScriptFile( $fileName, $contents );
 717                         }
 718                         $js .= $contents . "\n";
 719                 }
 720                 return $js;
 721         }
 722
 723         /**
 724          * Gets the contents of a list of CSS files.
 725          *
 726          * @param array $styles List of media type/list of file paths pairs, to read, remap and
 727          * concetenate
 728          *
 729          * @param bool $flip
 730          *
 731          * @throws MWException
 732          * @return array List of concatenated and remapped CSS data from $styles,
 733          *     keyed by media type
 734          */
 735         public function readStyleFiles( array $styles, $flip ) {
 736                 if ( empty( $styles ) ) {
 737                         return array();
 738                 }
 739                 foreach ( $styles as $media => $files ) {
 740                         $uniqueFiles = array_unique( $files );
 741                         $styleFiles = array();
 742                         foreach ( $uniqueFiles as $file ) {
 743                                 $styleFiles[] = $this->readStyleFile( $file, $flip );
 744                         }
 745                         $styles[$media] = implode( "\n", $styleFiles );
 746                 }
 747                 return $styles;
 748         }
 749
 750         /**
 751          * Reads a style file.
 752          *
 753          * This method can be used as a callback for array_map()
 754          *
 755          * @param string $path File path of style file to read
 756          * @param bool $flip
 757          *
 758          * @return string CSS data in script file
 759          * @throws MWException if the file doesn't exist
 760          */
 761         protected function readStyleFile( $path, $flip ) {
 762                 $localPath = $this->getLocalPath( $path );
 763                 if ( !file_exists( $localPath ) ) {
 764                         $msg = __METHOD__ . ": style file not found: \"$localPath\"";
 765                         wfDebugLog( 'resourceloader', $msg );
 766                         throw new MWException( $msg );
 767                 }
 768
 769                 if ( $this->getStyleSheetLang( $path ) === 'less' ) {
 770                         $style = $this->compileLESSFile( $localPath );
 771                         $this->hasGeneratedStyles = true;
 772                 } else {
 773                         $style = file_get_contents( $localPath );
 774                 }
 775
 776                 if ( $flip ) {
 777                         $style = CSSJanus::transform( $style, true, false );
 778                 }
 779                 $dirname = dirname( $path );
 780                 if ( $dirname == '.' ) {
 781                         // If $path doesn't have a directory component, don't prepend a dot
 782                         $dirname = '';
 783                 }
 784                 $dir = $this->getLocalPath( $dirname );
 785                 $remoteDir = $this->getRemotePath( $dirname );
 786                 // Get and register local file references
 787                 $this->localFileRefs = array_merge(
 788                         $this->localFileRefs,
 789                         CSSMin::getLocalFileReferences( $style, $dir )
 790                 );
 791                 return CSSMin::remap(
 792                         $style, $dir, $remoteDir, true
 793                 );
 794         }
 795
 796         /**
 797          * Get whether CSS for this module should be flipped
 798          * @param ResourceLoaderContext $context
 799          * @return bool
 800          */
 801         public function getFlip( $context ) {
 802                 return $context->getDirection() === 'rtl';
 803         }
 804
 805         /**
 806          * Get target(s) for the module, eg ['desktop'] or ['desktop', 'mobile']
 807          *
 808          * @return array Array of strings
 809          */
 810         public function getTargets() {
 811                 return $this->targets;
 812         }
 813
 814         /**
 815          * Generate a cache key for a LESS file.
 816          *
 817          * The cache key varies on the file name and the names and values of global
 818          * LESS variables.
 819          *
 820          * @since 1.22
 821          * @param string $fileName File name of root LESS file.
 822          * @return string Cache key
 823          */
 824         protected static function getLESSCacheKey( $fileName ) {
 825                 $vars = json_encode( ResourceLoader::getLESSVars() );
 826                 $hash = md5( $fileName . $vars );
 827                 return wfMemcKey( 'resourceloader', 'less', $hash );
 828         }
 829
 830         /**
 831          * Compile a LESS file into CSS.
 832          *
 833          * If invalid, returns replacement CSS source consisting of the compilation
 834          * error message encoded as a comment. To save work, we cache a result object
 835          * which comprises the compiled CSS and the names & mtimes of the files
 836          * that were processed. lessphp compares the cached & current mtimes and
 837          * recompiles as necessary.
 838          *
 839          * @since 1.22
 840          * @throws Exception If Less encounters a parse error
 841          * @throws MWException If Less compilation returns unexpection result
 842          * @param string $fileName File path of LESS source
 843          * @return string CSS source
 844          */
 845         protected function compileLESSFile( $fileName ) {
 846                 $key = self::getLESSCacheKey( $fileName );
 847                 $cache = wfGetCache( CACHE_ANYTHING );
 848
 849                 // The input to lessc. Either an associative array representing the
 850                 // cached results of a previous compilation, or the string file name if
 851                 // no cache result exists.
 852                 $source = $cache->get( $key );
 853                 if ( !is_array( $source ) || !isset( $source['root'] ) ) {
 854                         $source = $fileName;
 855                 }
 856
 857                 $compiler = ResourceLoader::getLessCompiler();
 858                 $result = null;
 859
 860                 $result = $compiler->cachedCompile( $source );
 861
 862                 if ( !is_array( $result ) ) {
 863                         throw new MWException( 'LESS compiler result has type '
 864                                 . gettype( $result ) . '; array expected.' );
 865                 }
 866
 867                 $this->localFileRefs += array_keys( $result['files'] );
 868                 $cache->set( $key, $result );
 869                 return $result['compiled'];
 870         }
 871 }