MediaWiki REL1_30
ResourceLoaderModule.php
Go to the documentation of this file.
1<?php
26use Psr\Log\LoggerAwareInterface;
27use Psr\Log\LoggerInterface;
28use Psr\Log\NullLogger;
29use Wikimedia\ScopedCallback;
30
34abstract class ResourceLoaderModule implements LoggerAwareInterface {
35 # Type of resource
36 const TYPE_SCRIPTS = 'scripts';
37 const TYPE_STYLES = 'styles';
38 const TYPE_COMBINED = 'combined';
39
40 # Desired load type
41 // Module only has styles (loaded via <style> or <link rel=stylesheet>)
42 const LOAD_STYLES = 'styles';
43 // Module may have other resources (loaded via mw.loader from a script)
44 const LOAD_GENERAL = 'general';
45
46 # sitewide core module like a skin file or jQuery component
48
49 # per-user module generated by the software
51
52 # sitewide module generated from user-editable files, like MediaWiki:Common.js, or
53 # modules accessible to multiple users, such as those generated by the Gadgets extension.
55
56 # per-user module generated from user-editable files, like User:Me/vector.js
58
59 # an access constant; make sure this is kept as the largest number in this group
60 const ORIGIN_ALL = 10;
61
62 # script and style modules form a hierarchy of trustworthiness, with core modules like
63 # skins and jQuery as most trustworthy, and user scripts as least trustworthy. We can
64 # limit the types of scripts and styles we allow to load on, say, sensitive special
65 # pages like Special:UserLogin and Special:Preferences
67
68 /* Protected Members */
69
70 protected $name = null;
71 protected $targets = [ 'desktop' ];
72
73 // In-object cache for file dependencies
74 protected $fileDeps = [];
75 // In-object cache for message blob (keyed by language)
76 protected $msgBlobs = [];
77 // In-object cache for version hash
78 protected $versionHash = [];
79 // In-object cache for module content
80 protected $contents = [];
81
85 protected $config;
86
90 protected $deprecated = false;
91
95 protected $logger;
96
97 /* Methods */
98
105 public function getName() {
106 return $this->name;
107 }
108
115 public function setName( $name ) {
116 $this->name = $name;
117 }
118
126 public function getOrigin() {
127 return $this->origin;
128 }
129
134 public function getFlip( $context ) {
135 global $wgContLang;
136
137 return $wgContLang->getDir() !== $context->getDirection();
138 }
139
145 protected function getDeprecationInformation() {
146 $deprecationInfo = $this->deprecated;
147 if ( $deprecationInfo ) {
148 $name = $this->getName();
149 $warning = 'This page is using the deprecated ResourceLoader module "' . $name . '".';
150 if ( is_string( $deprecationInfo ) ) {
151 $warning .= "\n" . $deprecationInfo;
152 }
153 return Xml::encodeJsCall(
154 'mw.log.warn',
155 [ $warning ]
156 );
157 } else {
158 return '';
159 }
160 }
161
170 // Stub, override expected
171 return '';
172 }
173
179 public function getTemplates() {
180 // Stub, override expected.
181 return [];
182 }
183
188 public function getConfig() {
189 if ( $this->config === null ) {
190 // Ugh, fall back to default
191 $this->config = MediaWikiServices::getInstance()->getMainConfig();
192 }
193
194 return $this->config;
195 }
196
201 public function setConfig( Config $config ) {
202 $this->config = $config;
203 }
204
210 public function setLogger( LoggerInterface $logger ) {
211 $this->logger = $logger;
212 }
213
218 protected function getLogger() {
219 if ( !$this->logger ) {
220 $this->logger = new NullLogger();
221 }
222 return $this->logger;
223 }
224
240 $resourceLoader = $context->getResourceLoader();
241 $derivative = new DerivativeResourceLoaderContext( $context );
242 $derivative->setModules( [ $this->getName() ] );
243 $derivative->setOnly( 'scripts' );
244 $derivative->setDebug( true );
245
246 $url = $resourceLoader->createLoaderURL(
247 $this->getSource(),
248 $derivative
249 );
250
251 return [ $url ];
252 }
253
260 public function supportsURLLoading() {
261 return true;
262 }
263
273 // Stub, override expected
274 return [];
275 }
276
287 $resourceLoader = $context->getResourceLoader();
288 $derivative = new DerivativeResourceLoaderContext( $context );
289 $derivative->setModules( [ $this->getName() ] );
290 $derivative->setOnly( 'styles' );
291 $derivative->setDebug( true );
292
293 $url = $resourceLoader->createLoaderURL(
294 $this->getSource(),
295 $derivative
296 );
297
298 return [ 'all' => [ $url ] ];
299 }
300
308 public function getMessages() {
309 // Stub, override expected
310 return [];
311 }
312
318 public function getGroup() {
319 // Stub, override expected
320 return null;
321 }
322
328 public function getSource() {
329 // Stub, override expected
330 return 'local';
331 }
332
339 public function getPosition() {
340 return 'top';
341 }
342
350 public function isRaw() {
351 return false;
352 }
353
367 // Stub, override expected
368 return [];
369 }
370
376 public function getTargets() {
377 return $this->targets;
378 }
379
386 public function getType() {
387 return self::LOAD_GENERAL;
388 }
389
404 public function getSkipFunction() {
405 return null;
406 }
407
417 $vary = $context->getSkin() . '|' . $context->getLanguage();
418
419 // Try in-object cache first
420 if ( !isset( $this->fileDeps[$vary] ) ) {
422 $deps = $dbr->selectField( 'module_deps',
423 'md_deps',
424 [
425 'md_module' => $this->getName(),
426 'md_skin' => $vary,
427 ],
428 __METHOD__
429 );
430
431 if ( !is_null( $deps ) ) {
432 $this->fileDeps[$vary] = self::expandRelativePaths(
433 (array)FormatJson::decode( $deps, true )
434 );
435 } else {
436 $this->fileDeps[$vary] = [];
437 }
438 }
439 return $this->fileDeps[$vary];
440 }
441
452 $vary = $context->getSkin() . '|' . $context->getLanguage();
453 $this->fileDeps[$vary] = $files;
454 }
455
463 protected function saveFileDependencies( ResourceLoaderContext $context, $localFileRefs ) {
464 try {
465 // Related bugs and performance considerations:
466 // 1. Don't needlessly change the database value with the same list in a
467 // different order or with duplicates.
468 // 2. Use relative paths to avoid ghost entries when $IP changes. (T111481)
469 // 3. Don't needlessly replace the database with the same value
470 // just because $IP changed (e.g. when upgrading a wiki).
471 // 4. Don't create an endless replace loop on every request for this
472 // module when '../' is used anywhere. Even though both are expanded
473 // (one expanded by getFileDependencies from the DB, the other is
474 // still raw as originally read by RL), the latter has not
475 // been normalized yet.
476
477 // Normalise
478 $localFileRefs = array_values( array_unique( $localFileRefs ) );
479 sort( $localFileRefs );
480 $localPaths = self::getRelativePaths( $localFileRefs );
481
482 $storedPaths = self::getRelativePaths( $this->getFileDependencies( $context ) );
483 // If the list has been modified since last time we cached it, update the cache
484 if ( $localPaths !== $storedPaths ) {
485 $vary = $context->getSkin() . '|' . $context->getLanguage();
486 $cache = ObjectCache::getLocalClusterInstance();
487 $key = $cache->makeKey( __METHOD__, $this->getName(), $vary );
488 $scopeLock = $cache->getScopedLock( $key, 0 );
489 if ( !$scopeLock ) {
490 return; // T124649; avoid write slams
491 }
492
493 $deps = FormatJson::encode( $localPaths );
494 $dbw = wfGetDB( DB_MASTER );
495 $dbw->upsert( 'module_deps',
496 [
497 'md_module' => $this->getName(),
498 'md_skin' => $vary,
499 'md_deps' => $deps,
500 ],
501 [ [ 'md_module', 'md_skin' ] ],
502 [
503 'md_deps' => $deps,
504 ]
505 );
506
507 if ( $dbw->trxLevel() ) {
508 $dbw->onTransactionResolution(
509 function () use ( &$scopeLock ) {
510 ScopedCallback::consume( $scopeLock ); // release after commit
511 },
512 __METHOD__
513 );
514 }
515 }
516 } catch ( Exception $e ) {
517 wfDebugLog( 'resourceloader', __METHOD__ . ": failed to update DB: $e" );
518 }
519 }
520
531 public static function getRelativePaths( array $filePaths ) {
532 global $IP;
533 return array_map( function ( $path ) use ( $IP ) {
534 return RelPath\getRelativePath( $path, $IP );
535 }, $filePaths );
536 }
537
545 public static function expandRelativePaths( array $filePaths ) {
546 global $IP;
547 return array_map( function ( $path ) use ( $IP ) {
548 return RelPath\joinPath( $IP, $path );
549 }, $filePaths );
550 }
551
560 if ( !$this->getMessages() ) {
561 // Don't bother consulting MessageBlobStore
562 return null;
563 }
564 // Message blobs may only vary language, not by context keys
565 $lang = $context->getLanguage();
566 if ( !isset( $this->msgBlobs[$lang] ) ) {
567 $this->getLogger()->warning( 'Message blob for {module} should have been preloaded', [
568 'module' => $this->getName(),
569 ] );
570 $store = $context->getResourceLoader()->getMessageBlobStore();
571 $this->msgBlobs[$lang] = $store->getBlob( $this, $lang );
572 }
573 return $this->msgBlobs[$lang];
574 }
575
585 public function setMessageBlob( $blob, $lang ) {
586 $this->msgBlobs[$lang] = $blob;
587 }
588
603 final public function getHeaders( ResourceLoaderContext $context ) {
604 $headers = [];
605
606 $formattedLinks = [];
607 foreach ( $this->getPreloadLinks( $context ) as $url => $attribs ) {
608 $link = "<{$url}>;rel=preload";
609 foreach ( $attribs as $key => $val ) {
610 $link .= ";{$key}={$val}";
611 }
612 $formattedLinks[] = $link;
613 }
614 if ( $formattedLinks ) {
615 $headers[] = 'Link: ' . implode( ',', $formattedLinks );
616 }
617
618 return $headers;
619 }
620
660 protected function getPreloadLinks( ResourceLoaderContext $context ) {
661 return [];
662 }
663
671 protected function getLessVars( ResourceLoaderContext $context ) {
672 return [];
673 }
674
682 public function getModuleContent( ResourceLoaderContext $context ) {
683 $contextHash = $context->getHash();
684 // Cache this expensive operation. This calls builds the scripts, styles, and messages
685 // content which typically involves filesystem and/or database access.
686 if ( !array_key_exists( $contextHash, $this->contents ) ) {
687 $this->contents[$contextHash] = $this->buildContent( $context );
688 }
689 return $this->contents[$contextHash];
690 }
691
699 final protected function buildContent( ResourceLoaderContext $context ) {
700 $rl = $context->getResourceLoader();
701 $stats = MediaWikiServices::getInstance()->getStatsdDataFactory();
702 $statStart = microtime( true );
703
704 // Only include properties that are relevant to this context (e.g. only=scripts)
705 // and that are non-empty (e.g. don't include "templates" for modules without
706 // templates). This helps prevent invalidating cache for all modules when new
707 // optional properties are introduced.
708 $content = [];
709
710 // Scripts
711 if ( $context->shouldIncludeScripts() ) {
712 // If we are in debug mode, we'll want to return an array of URLs if possible
713 // However, we can't do this if the module doesn't support it
714 // We also can't do this if there is an only= parameter, because we have to give
715 // the module a way to return a load.php URL without causing an infinite loop
716 if ( $context->getDebug() && !$context->getOnly() && $this->supportsURLLoading() ) {
717 $scripts = $this->getScriptURLsForDebug( $context );
718 } else {
719 $scripts = $this->getScript( $context );
720 // Make the script safe to concatenate by making sure there is at least one
721 // trailing new line at the end of the content. Previously, this looked for
722 // a semi-colon instead, but that breaks concatenation if the semicolon
723 // is inside a comment like "// foo();". Instead, simply use a
724 // line break as separator which matches JavaScript native logic for implicitly
725 // ending statements even if a semi-colon is missing.
726 // Bugs: T29054, T162719.
727 if ( is_string( $scripts )
728 && strlen( $scripts )
729 && substr( $scripts, -1 ) !== "\n"
730 ) {
731 $scripts .= "\n";
732 }
733 }
734 $content['scripts'] = $scripts;
735 }
736
737 // Styles
738 if ( $context->shouldIncludeStyles() ) {
739 $styles = [];
740 // Don't create empty stylesheets like [ '' => '' ] for modules
741 // that don't *have* any stylesheets (T40024).
742 $stylePairs = $this->getStyles( $context );
743 if ( count( $stylePairs ) ) {
744 // If we are in debug mode without &only= set, we'll want to return an array of URLs
745 // See comment near shouldIncludeScripts() for more details
746 if ( $context->getDebug() && !$context->getOnly() && $this->supportsURLLoading() ) {
747 $styles = [
748 'url' => $this->getStyleURLsForDebug( $context )
749 ];
750 } else {
751 // Minify CSS before embedding in mw.loader.implement call
752 // (unless in debug mode)
753 if ( !$context->getDebug() ) {
754 foreach ( $stylePairs as $media => $style ) {
755 // Can be either a string or an array of strings.
756 if ( is_array( $style ) ) {
757 $stylePairs[$media] = [];
758 foreach ( $style as $cssText ) {
759 if ( is_string( $cssText ) ) {
760 $stylePairs[$media][] =
761 ResourceLoader::filter( 'minify-css', $cssText );
762 }
763 }
764 } elseif ( is_string( $style ) ) {
765 $stylePairs[$media] = ResourceLoader::filter( 'minify-css', $style );
766 }
767 }
768 }
769 // Wrap styles into @media groups as needed and flatten into a numerical array
770 $styles = [
771 'css' => $rl->makeCombinedStyles( $stylePairs )
772 ];
773 }
774 }
775 $content['styles'] = $styles;
776 }
777
778 // Messages
779 $blob = $this->getMessageBlob( $context );
780 if ( $blob ) {
781 $content['messagesBlob'] = $blob;
782 }
783
784 $templates = $this->getTemplates();
785 if ( $templates ) {
786 $content['templates'] = $templates;
787 }
788
789 $headers = $this->getHeaders( $context );
790 if ( $headers ) {
791 $content['headers'] = $headers;
792 }
793
794 $statTiming = microtime( true ) - $statStart;
795 $statName = strtr( $this->getName(), '.', '_' );
796 $stats->timing( "resourceloader_build.all", 1000 * $statTiming );
797 $stats->timing( "resourceloader_build.$statName", 1000 * $statTiming );
798
799 return $content;
800 }
801
824 public function getVersionHash( ResourceLoaderContext $context ) {
825 // The startup module produces a manifest with versions representing the entire module.
826 // Typically, the request for the startup module itself has only=scripts. That must apply
827 // only to the startup module content, and not to the module version computed here.
829 $context->setModules( [] );
830 // Version hash must cover all resources, regardless of startup request itself.
831 $context->setOnly( null );
832 // Compute version hash based on content, not debug urls.
833 $context->setDebug( false );
834
835 // Cache this somewhat expensive operation. Especially because some classes
836 // (e.g. startup module) iterate more than once over all modules to get versions.
837 $contextHash = $context->getHash();
838 if ( !array_key_exists( $contextHash, $this->versionHash ) ) {
839 if ( $this->enableModuleContentVersion() ) {
840 // Detect changes directly
841 $str = json_encode( $this->getModuleContent( $context ) );
842 } else {
843 // Infer changes based on definition and other metrics
844 $summary = $this->getDefinitionSummary( $context );
845 if ( !isset( $summary['_cacheEpoch'] ) ) {
846 throw new LogicException( 'getDefinitionSummary must call parent method' );
847 }
848 $str = json_encode( $summary );
849
850 $mtime = $this->getModifiedTime( $context );
851 if ( $mtime !== null ) {
852 // Support: MediaWiki 1.25 and earlier
853 $str .= strval( $mtime );
854 }
855
856 $mhash = $this->getModifiedHash( $context );
857 if ( $mhash !== null ) {
858 // Support: MediaWiki 1.25 and earlier
859 $str .= strval( $mhash );
860 }
861 }
862
863 $this->versionHash[$contextHash] = ResourceLoader::makeHash( $str );
864 }
865 return $this->versionHash[$contextHash];
866 }
867
877 public function enableModuleContentVersion() {
878 return false;
879 }
880
925 return [
926 '_class' => static::class,
927 '_cacheEpoch' => $this->getConfig()->get( 'CacheEpoch' ),
928 ];
929 }
930
939 return null;
940 }
941
950 return null;
951 }
952
965 if ( !is_string( $this->getModifiedHash( $context ) ) ) {
966 return 1;
967 }
968 // Dummy that is > 1
969 return 2;
970 }
971
981 if ( $this->getDefinitionSummary( $context ) === null ) {
982 return 1;
983 }
984 // Dummy that is > 1
985 return 2;
986 }
987
998 return false;
999 }
1000
1012 return $this->getGroup() === 'private';
1013 }
1014
1016 private static $jsParser;
1017 private static $parseCacheVersion = 1;
1018
1027 protected function validateScriptFile( $fileName, $contents ) {
1028 if ( !$this->getConfig()->get( 'ResourceLoaderValidateJS' ) ) {
1029 return $contents;
1030 }
1031 $cache = ObjectCache::getMainWANInstance();
1032 return $cache->getWithSetCallback(
1033 $cache->makeGlobalKey(
1034 'resourceloader',
1035 'jsparse',
1036 self::$parseCacheVersion,
1037 md5( $contents ),
1038 $fileName
1039 ),
1040 $cache::TTL_WEEK,
1041 function () use ( $contents, $fileName ) {
1043 try {
1044 $parser->parse( $contents, $fileName, 1 );
1045 $result = $contents;
1046 } catch ( Exception $e ) {
1047 // We'll save this to cache to avoid having to re-validate broken JS
1048 $err = $e->getMessage();
1049 $result = "mw.log.error(" .
1050 Xml::encodeJsVar( "JavaScript parse error: $err" ) . ");";
1051 }
1052 return $result;
1053 }
1054 );
1055 }
1056
1060 protected static function javaScriptParser() {
1061 if ( !self::$jsParser ) {
1062 self::$jsParser = new JSParser();
1063 }
1064 return self::$jsParser;
1065 }
1066
1074 protected static function safeFilemtime( $filePath ) {
1075 MediaWiki\suppressWarnings();
1076 $mtime = filemtime( $filePath ) ?: 1;
1077 MediaWiki\restoreWarnings();
1078 return $mtime;
1079 }
1080
1089 protected static function safeFileHash( $filePath ) {
1090 return FileContentsHasher::getFileContentsHash( $filePath );
1091 }
1092}
wfGetDB( $db, $groups=[], $wiki=false)
Get a Database object.
wfDebugLog( $logGroup, $text, $dest='all', array $context=[])
Send a line to a supplementary debug log file, if configured, or main debug log if not.
Allows changing specific properties of a context object, without changing the main one.
static getFileContentsHash( $filePaths, $algo='md4')
Get a hash of the combined contents of one or more files, either by retrieving a previously-computed ...
MediaWikiServices is the service locator for the application scope of MediaWiki.
Object passed around to modules which contains information about the state of a specific loader reque...
Abstraction for ResourceLoader modules, with name registration and maxage functionality.
isKnownEmpty(ResourceLoaderContext $context)
Check whether this module is known to be empty.
getModifiedHash(ResourceLoaderContext $context)
Helper method for providing a version hash to getVersionHash().
getScript(ResourceLoaderContext $context)
Get all JS for this module for a given language and skin.
getDependencies(ResourceLoaderContext $context=null)
Get a list of modules this module depends on.
getFileDependencies(ResourceLoaderContext $context)
Get the files this module depends on indirectly for a given skin.
getSkipFunction()
Get the skip function.
validateScriptFile( $fileName, $contents)
Validate a given script file; if valid returns the original source.
getMessageBlob(ResourceLoaderContext $context)
Get the hash of the message blob.
static safeFileHash( $filePath)
Compute a non-cryptographic string hash of a file's contents.
static expandRelativePaths(array $filePaths)
Expand directories relative to $IP.
supportsURLLoading()
Whether this module supports URL loading.
getMessages()
Get the messages needed for this module.
setName( $name)
Set this module's name.
isRaw()
Whether this module's JS expects to work without the client-side ResourceLoader module.
getPosition()
From where in the page HTML should this module be loaded?
getStyles(ResourceLoaderContext $context)
Get all CSS for this module for a given skin.
getScriptURLsForDebug(ResourceLoaderContext $context)
Get the URL or URLs to load for this module's JS in debug mode.
getGroup()
Get the group this module is in.
setLogger(LoggerInterface $logger)
getDefinitionSummary(ResourceLoaderContext $context)
Get a list of resources that web browsers may preload.
static JSParser $jsParser
Lazy-initialized; use self::javaScriptParser()
getHashMtime(ResourceLoaderContext $context)
Back-compat dummy for old subclass implementations of getModifiedTime().
getOrigin()
Get this module's origin.
getTargets()
Get target(s) for the module, eg ['desktop'] or ['desktop', 'mobile'].
getType()
Get the module's load type.
setFileDependencies(ResourceLoaderContext $context, $files)
Set in-object cache for file dependencies.
getStyleURLsForDebug(ResourceLoaderContext $context)
Get the URL or URLs to load for this module's CSS in debug mode.
setMessageBlob( $blob, $lang)
Set in-object cache for message blobs.
shouldEmbedModule(ResourceLoaderContext $context)
Check whether this module should be embeded rather than linked.
getModifiedTime(ResourceLoaderContext $context)
Get this module's last modification timestamp for a given context.
static safeFilemtime( $filePath)
Safe version of filemtime(), which doesn't throw a PHP warning if the file doesn't exist.
getSource()
Get the origin of this module.
static getRelativePaths(array $filePaths)
Make file paths relative to MediaWiki directory.
getDeprecationInformation()
Get JS representing deprecation information for the current module if available.
saveFileDependencies(ResourceLoaderContext $context, $localFileRefs)
Set the files this module depends on indirectly for a given skin.
getName()
Get this module's name.
getHeaders(ResourceLoaderContext $context)
Get headers to send as part of a module web response.
getDefinitionMtime(ResourceLoaderContext $context)
Back-compat dummy for old subclass implementations of getModifiedTime().
getTemplates()
Takes named templates by the module and returns an array mapping.
static makeHash( $value)
static filter( $filter, $data, array $options=[])
Run JavaScript or CSS data through a filter, caching the filtered result for future calls.
if(! $regexes) $dbr
Definition cleanup.php:94
Some information about database access in MediaWiki By Tim January Database layout For information about the MediaWiki database such as a description of the tables and their contents
Definition database.txt:9
this class mediates it Skin Encapsulates a look and feel for the wiki All of the functions that render HTML and make choices about how to render it are here and are called from various other places when and is meant to be subclassed with other skins that may override some of its functions The User object contains a reference to a and so rather than having a global skin object we just rely on the global User and get the skin with $wgUser and also has some character encoding functions and other locale stuff The current user interface language is instantiated as and the local content language as $wgContLang
Definition design.txt:57
namespace being checked & $result
Definition hooks.txt:2293
do that in ParserLimitReportFormat instead $parser
Definition hooks.txt:2572
do that in ParserLimitReportFormat instead use this to modify the parameters of the image all existing parser cache entries will be invalid To avoid you ll need to handle that somehow(e.g. with the RejectParserCacheValue hook) because MediaWiki won 't do it for you. & $defaults also a ContextSource after deleting those rows but within the same transaction you ll probably need to make sure the header is varied on and they can depend only on the ResourceLoaderContext $context
Definition hooks.txt:2780
usually copyright or history_copyright This message must be in HTML not wikitext & $link
Definition hooks.txt:2989
null means default in associative array with keys and values unescaped Should be merged with default with a value of false meaning to suppress the attribute in associative array with keys and values unescaped noclasses just before the function returns a value If you return an< a > element with HTML attributes $attribs and contents $html will be returned If you return $ret will be returned and may include noclasses after processing & $attribs
Definition hooks.txt:1984
do that in ParserLimitReportFormat instead use this to modify the parameters of the image all existing parser cache entries will be invalid To avoid you ll need to handle that somehow(e.g. with the RejectParserCacheValue hook) because MediaWiki won 't do it for you. & $defaults also a ContextSource after deleting those rows but within the same transaction you ll probably need to make sure the header is varied on and they can depend only on the ResourceLoaderContext such as when responding to a resource loader request or generating HTML output & $resourceLoader
Definition hooks.txt:2787
returning false will NOT prevent logging $e
Definition hooks.txt:2146
$IP
Definition update.php:3
$cache
Definition mcc.php:33
const DB_REPLICA
Definition defines.php:25
const DB_MASTER
Definition defines.php:26
if(!isset( $args[0])) $lang