MediaWiki  1.23.2
ResourceLoader Class Reference

Dynamic JavaScript and CSS resource loading system. More...

Public Member Functions

 __construct ()
 Register core modules and runs registration hooks. More...
 
 addSource ( $id, $properties=null)
 Add a foreign source of modules. More...
 
 getModule ( $name)
 Get the ResourceLoaderModule object for a given module name. More...
 
 getModuleNames ()
 Get a list of module names. More...
 
 getSources ()
 Get the list of sources. More...
 
 getTestModuleNames ( $framework='all')
 Get a list of test module names for one (or all) frameworks. More...
 
 makeModuleResponse (ResourceLoaderContext $context, array $modules, array $missing=array())
 Generate code for a response. More...
 
 preloadModuleInfo (array $modules, ResourceLoaderContext $context)
 Load information stored in the database about modules. More...
 
 register ( $name, $info=null)
 Register a module with the ResourceLoader system. More...
 
 registerTestModules ()
 
 respond (ResourceLoaderContext $context)
 Output a response to a load request, including the content-type header. More...
 

Static Public Member Functions

static formatException ( $e)
 Handle exception display. More...
 
static getLessCompiler ()
 Returns LESS compiler set up for use with MediaWiki. More...
 
static getLESSVars ()
 Get global LESS variables. More...
 
static inDebugMode ()
 Determine whether debug mode was requested Order of priority is 1) request param, 2) cookie, 3) $wg setting. More...
 
static isValidModuleName ( $moduleName)
 Check a module name for validity. More...
 
static makeComment ( $text)
 Generate a CSS or JS comment block. More...
 
static makeConfigSetScript (array $configuration)
 Returns JS code which will set the MediaWiki configuration array to the given value. More...
 
static makeCustomLoaderScript ( $name, $version, $dependencies, $group, $source, $script)
 Returns JS code which calls the script given by $script. More...
 
static makeLoaderConditionalScript ( $script)
 Returns JS code which runs given JS code if the client-side framework is present. More...
 
static makeLoaderImplementScript ( $name, $scripts, $styles, $messages)
 Return JS code that calls mw.loader.implement with given module properties. More...
 
static makeLoaderQuery ( $modules, $lang, $skin, $user=null, $version=null, $debug=false, $only=null, $printable=false, $handheld=false, $extraQuery=array())
 Build a query array (array representation of query string) for load.php. More...
 
static makeLoaderRegisterScript ( $name, $version=null, $dependencies=null, $group=null, $source=null)
 Returns JS code which calls mw.loader.register with the given parameters. More...
 
static makeLoaderSourcesScript ( $id, $properties=null)
 Returns JS code which calls mw.loader.addSource() with the given parameters. More...
 
static makeLoaderStateScript ( $name, $state=null)
 Returns a JS call to mw.loader.state, which sets the state of a module or modules to a given value. More...
 
static makeLoaderURL ( $modules, $lang, $skin, $user=null, $version=null, $debug=false, $only=null, $printable=false, $handheld=false, $extraQuery=array())
 Build a load.php URL. More...
 
static makeMessageSetScript ( $messages)
 Returns JS code which, when called, will register a given list of messages. More...
 
static makePackedModulesString ( $modules)
 Convert an array of module names to a packed query string. More...
 

Protected Member Functions

 filter ( $filter, $data)
 Run JavaScript or CSS data through a filter, caching the filtered result for future calls. More...
 
 sendResponseHeaders (ResourceLoaderContext $context, $mtime, $errors)
 Send content type and last modified headers to the client. More...
 
 tryRespondFromFileCache (ResourceFileCache $fileCache, ResourceLoaderContext $context)
 Send out code for a response from file cache if possible. More...
 
 tryRespondLastModified (ResourceLoaderContext $context, $mtime)
 Respond with 304 Last Modified if appropiate. More...
 

Protected Attributes

bool $hasErrors = false
 
array $moduleInfos = array()
 Associative array mapping module name to info associative array. More...
 
 $modules = array()
 
 $sources = array()
 
array $testModuleNames = array()
 Associative array mapping framework ids to a list of names of test suite modules like array( 'qunit' => array( 'mediawiki.tests.qunit.suites', 'ext.foo.tests', . More...
 

Static Protected Attributes

static $filterCacheVersion = 7
 
static $requiredSourceProperties = array( 'loadScript' )
 

Static Private Member Functions

static makeCombinedStyles (array $stylePairs)
 Combines an associative array mapping media type to CSS into a single stylesheet with "@media" blocks. More...
 

Detailed Description

Dynamic JavaScript and CSS resource loading system.

Most of the documentation is on the MediaWiki documentation wiki starting at: https://www.mediawiki.org/wiki/ResourceLoader

Definition at line 31 of file ResourceLoader.php.

Constructor & Destructor Documentation

◆ __construct()

ResourceLoader::__construct ( )

Register core modules and runs registration hooks.

Definition at line 219 of file ResourceLoader.php.

References $IP, addSource(), array(), global, registerTestModules(), wfProfileIn(), wfProfileOut(), wfRunHooks(), and wfScript().

Member Function Documentation

◆ addSource()

ResourceLoader::addSource (   $id,
  $properties = null 
)

Add a foreign source of modules.

Source properties: 'loadScript': URL (either fully-qualified or protocol-relative) of load.php for this source

Parameters
mixed$idSource ID (string), or array( id1 => props1, id2 => props2, ... )
array$propertiesSource properties
Exceptions
MWException

Definition at line 348 of file ResourceLoader.php.

Referenced by __construct().

◆ filter()

ResourceLoader::filter (   $filter,
  $data 
)
protected

Run JavaScript or CSS data through a filter, caching the filtered result for future calls.

Available filters are:

Parameters
string$filterName of filter to run
string$dataText to filter, such as JavaScript or CSS text
Returns
string Filtered data, or a comment containing an error message

Definition at line 159 of file ResourceLoader.php.

References $cache, $e, array(), CACHE_ANYTHING, formatException(), global, MWExceptionHandler\logException(), JavaScriptMinifier\minify(), CSSMin\minify(), wfDebugLog(), wfGetCache(), wfIncrStats(), wfMemcKey(), wfProfileIn(), and wfProfileOut().

Referenced by makeModuleResponse().

◆ formatException()

static ResourceLoader::formatException (   $e)
static

Handle exception display.

Parameters
Exception$eto be shown to the user
Returns
string sanitized text that can be returned to the user

Definition at line 724 of file ResourceLoader.php.

References $e, global, makeComment(), text, and wfMessage().

Referenced by filter(), WebInstallerOutput\getCSS(), and makeModuleResponse().

◆ getLessCompiler()

static ResourceLoader::getLessCompiler ( )
static

Returns LESS compiler set up for use with MediaWiki.

Since
1.22
Returns
lessc

Definition at line 1290 of file ResourceLoader.php.

References $name, as, and global.

Referenced by ResourceLoaderFileModule\compileLESSFile(), WebInstallerOutput\getCSS(), ResourceLoaderLESSTest\testLessFile(), and LessFileCompilationTest\testLessFileCompilation().

◆ getLESSVars()

static ResourceLoader::getLESSVars ( )
static

Get global LESS variables.

$since 1.22

Returns
array: Map of variable names to string CSS values.

Definition at line 1316 of file ResourceLoader.php.

References global.

Referenced by ResourceLoaderFileModule\getLESSCacheKey().

◆ getModule()

ResourceLoader::getModule (   $name)

Get the ResourceLoaderModule object for a given module name.

If an array of module parameters exists but a ResourceLoaderModule object has not yet been instantiated, this method will instantiate and cache that object such that subsequent calls simply return the same object.

Parameters
string$nameModule name
Returns
ResourceLoaderModule|null If module has been registered, return a ResourceLoaderModule instance. Otherwise, return null.

Definition at line 416 of file ResourceLoader.php.

Referenced by preloadModuleInfo().

◆ getModuleNames()

ResourceLoader::getModuleNames ( )

Get a list of module names.

Returns
array List of module names

Definition at line 380 of file ResourceLoader.php.

◆ getSources()

ResourceLoader::getSources ( )

Get the list of sources.

Returns
array Like array( id => array of properties, .. )

Definition at line 448 of file ResourceLoader.php.

◆ getTestModuleNames()

ResourceLoader::getTestModuleNames (   $framework = 'all')

Get a list of test module names for one (or all) frameworks.

If the given framework id is unknkown, or if the in-object variable is not an array, then it will return an empty array.

Parameters
string$frameworkGet only the test module names for one particular framework (optional)
Returns
Array

Definition at line 394 of file ResourceLoader.php.

◆ inDebugMode()

static ResourceLoader::inDebugMode ( )
static

◆ isValidModuleName()

static ResourceLoader::isValidModuleName (   $moduleName)
static

Check a module name for validity.

Module names may not contain pipes (|), commas (,) or exclamation marks (!) and can be at most 255 bytes.

Parameters
string$moduleNameModule name to check
Returns
bool Whether $moduleName is a valid module name

Definition at line 1280 of file ResourceLoader.php.

◆ makeCombinedStyles()

static ResourceLoader::makeCombinedStyles ( array  $stylePairs)
staticprivate

Combines an associative array mapping media type to CSS into a single stylesheet with "@media" blocks.

Parameters
array$stylePairsArray keyed by media type containing (arrays of) CSS strings
Returns
array

Definition at line 978 of file ResourceLoader.php.

References $out, array(), as, and OutputPage\transformCssMedia().

◆ makeComment()

static ResourceLoader::makeComment (   $text)
static

Generate a CSS or JS comment block.

Only use this for public data, not error message details.

Parameters
string$text
Returns
string

Definition at line 713 of file ResourceLoader.php.

Referenced by formatException(), and WebInstallerOutput\getCSS().

◆ makeConfigSetScript()

static ResourceLoader::makeConfigSetScript ( array  $configuration)
static

Returns JS code which will set the MediaWiki configuration array to the given value.

Parameters
array$configurationList of configuration values keyed by variable name
Returns
string

Definition at line 1149 of file ResourceLoader.php.

References array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by MWDebug\getDebugHTML(), OutputPage\getHeadScripts(), and Skin\makeVariablesScript().

◆ makeCustomLoaderScript()

static ResourceLoader::makeCustomLoaderScript (   $name,
  $version,
  $dependencies,
  $group,
  $source,
  $script 
)
static

Returns JS code which calls the script given by $script.

The script will be called with local variables name, version, dependencies and group, which will have values corresponding to $name, $version, $dependencies and $group as supplied.

Parameters
string$nameModule name
int$versionModule version number as a timestamp
array$dependenciesList of module names on which this module depends
string$groupGroup which the module is in.
string$sourceSource of the module, or 'local' if not foreign.
string$scriptJavaScript code
Returns
string

Definition at line 1049 of file ResourceLoader.php.

References $name, $source, $version, array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

◆ makeLoaderConditionalScript()

static ResourceLoader::makeLoaderConditionalScript (   $script)
static

Returns JS code which runs given JS code if the client-side framework is present.

Parameters
string$scriptJavaScript code
Returns
string

Definition at line 1138 of file ResourceLoader.php.

Referenced by ProtectionForm\buildCleanupScript(), MWDebug\getDebugHTML(), OutputPage\getHeadScripts(), OutputPage\getHtmlFromLoaderLinks(), OutputPage\getScriptsForBottomQueue(), OutputPage\makeResourceLoaderLink(), and Skin\makeVariablesScript().

◆ makeLoaderImplementScript()

static ResourceLoader::makeLoaderImplementScript (   $name,
  $scripts,
  $styles,
  $messages 
)
static

Return JS code that calls mw.loader.implement with given module properties.

Parameters
string$nameModule name
mixed$scriptsList of URLs to JavaScript files or String of JavaScript code
mixed$stylesArray of CSS strings keyed by media type, or an array of lists of URLs to CSS files keyed by media type
mixed$messagesList of messages associated with this module. May either be an associative array mapping message key to value, or a JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object.
Exceptions
MWException
Returns
string

Definition at line 933 of file ResourceLoader.php.

References $messages, $name, array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by makeModuleResponse().

◆ makeLoaderQuery()

static ResourceLoader::makeLoaderQuery (   $modules,
  $lang,
  $skin,
  $user = null,
  $version = null,
  $debug = false,
  $only = null,
  $printable = false,
  $handheld = false,
  $extraQuery = array() 
)
static

Build a query array (array representation of query string) for load.php.

Helper function for makeLoaderURL().

Parameters
array$modules
string$lang
string$skin
string$user
string$version
bool$debug
string$only
bool$printable
bool$handheld
array$extraQuery
Returns
array

Definition at line 1241 of file ResourceLoader.php.

References $debug, $modules, $query, $skin, $user, $version, and array().

Referenced by makeLoaderURL(), and OutputPage\makeResourceLoaderLink().

◆ makeLoaderRegisterScript()

static ResourceLoader::makeLoaderRegisterScript (   $name,
  $version = null,
  $dependencies = null,
  $group = null,
  $source = null 
)
static

Returns JS code which calls mw.loader.register with the given parameters.

Has three calling conventions:

Parameters
string$nameModule name
int$versionModule version number as a timestamp
array$dependenciesList of module names on which this module depends
string$groupGroup which the module is in
string$sourceSource of the module, or 'local' if not foreign
Returns
string

Definition at line 1082 of file ResourceLoader.php.

References $name, $source, $version, array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

◆ makeLoaderSourcesScript()

static ResourceLoader::makeLoaderSourcesScript (   $id,
  $properties = null 
)
static

Returns JS code which calls mw.loader.addSource() with the given parameters.

Has two calling conventions:

Parameters
string$idsource ID
array$propertiessource properties (see addSource())
Returns
string

Definition at line 1115 of file ResourceLoader.php.

References array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

◆ makeLoaderStateScript()

static ResourceLoader::makeLoaderStateScript (   $name,
  $state = null 
)
static

Returns a JS call to mw.loader.state, which sets the state of a module or modules to a given value.

Has two calling conventions:

Parameters
string$name
$state
Returns
string

Definition at line 1019 of file ResourceLoader.php.

References $name, array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by OutputPage\getHtmlFromLoaderLinks(), and makeModuleResponse().

◆ makeLoaderURL()

static ResourceLoader::makeLoaderURL (   $modules,
  $lang,
  $skin,
  $user = null,
  $version = null,
  $debug = false,
  $only = null,
  $printable = false,
  $handheld = false,
  $extraQuery = array() 
)
static

Build a load.php URL.

Parameters
array$modulesof module names (strings)
string$langLanguage code
string$skinSkin name
string | null$userUser name. If null, the &user= parameter is omitted
string | null$versionVersioning timestamp
bool$debugWhether the request should be in debug mode
string | null$only&only= parameter
bool$printablePrintable mode
bool$handheldHandheld mode
array$extraQueryExtra query parameters to add
Returns
string URL to load.php. May be protocol-relative (if $wgLoadScript is procol-relative)

Definition at line 1212 of file ResourceLoader.php.

References $debug, $modules, $query, $skin, $user, $version, global, makeLoaderQuery(), PROTO_RELATIVE, wfAppendQuery(), and wfExpandUrl().

Referenced by ResourceLoaderModule\getScriptURLsForDebug(), ResourceLoaderModule\getStyleURLsForDebug(), and OutputPage\makeResourceLoaderLink().

◆ makeMessageSetScript()

static ResourceLoader::makeMessageSetScript (   $messages)
static

Returns JS code which, when called, will register a given list of messages.

Parameters
mixed$messagesEither an associative array mapping message key to value, or a JSON-encoded message blob containing the same data, wrapped in an XmlJsCode object.
Returns
string

Definition at line 963 of file ResourceLoader.php.

References $messages, array(), Xml\encodeJsCall(), and inDebugMode().

Referenced by makeModuleResponse().

◆ makeModuleResponse()

ResourceLoader::makeModuleResponse ( ResourceLoaderContext  $context,
array  $modules,
array  $missing = array() 
)

◆ makePackedModulesString()

static ResourceLoader::makePackedModulesString (   $modules)
static

Convert an array of module names to a packed query string.

For example, array( 'foo.bar', 'foo.baz', 'bar.baz', 'bar.quux' ) becomes 'foo.bar,baz|bar.baz,quux'

Parameters
array$modulesList of module names (strings)
Returns
string Packed query string

Definition at line 1165 of file ResourceLoader.php.

References $modules, array(), and as.

Referenced by ResourceLoaderStartUpModule\getStartupModulesUrl(), and ResourceLoaderTest\testMakePackedModulesString().

◆ preloadModuleInfo()

ResourceLoader::preloadModuleInfo ( array  $modules,
ResourceLoaderContext  $context 
)

Load information stored in the database about modules.

This method grabs modules dependencies from the database and updates modules objects.

This is not inside the module code because it is much faster to request all of the information at once than it is to have each module requests its own information. This sacrifice of modularity yields a substantial performance improvement.

Parameters
array$modulesList of module names to preload information for
ResourceLoaderContext$contextContext to load the information within

Definition at line 79 of file ResourceLoader.php.

References $dbr, $modules, $name, $res, $skin, array(), as, DB_SLAVE, FormatJson\decode(), ResourceLoaderContext\getLanguage(), getModule(), ResourceLoaderContext\getSkin(), TS_UNIX, wfGetDB(), and wfTimestamp().

◆ register()

ResourceLoader::register (   $name,
  $info = null 
)

Register a module with the ResourceLoader system.

Parameters
mixed$nameName of module as a string or List of name/object pairs as an array
array$infoModule info array. For backwards compatibility with 1.17alpha, this may also be a ResourceLoaderModule object. Optional when using multiple-registration calling style.
Exceptions
MWExceptionIf a duplicate module registration is attempted
MWExceptionIf a module name contains illegal characters (pipes or commas)
MWExceptionIf something other than a ResourceLoaderModule is being registered
Returns
boolean False if there were any errors, in which case one or more modules were not registered

Definition at line 256 of file ResourceLoader.php.

References $name, array(), as, wfProfileIn(), and wfProfileOut().

◆ registerTestModules()

ResourceLoader::registerTestModules ( )

Definition at line 300 of file ResourceLoader.php.

Referenced by __construct().

◆ respond()

ResourceLoader::respond ( ResourceLoaderContext  $context)

Output a response to a load request, including the content-type header.

Parameters
ResourceLoaderContext$contextContext in which a response should be formed

Definition at line 457 of file ResourceLoader.php.

◆ sendResponseHeaders()

ResourceLoader::sendResponseHeaders ( ResourceLoaderContext  $context,
  $mtime,
  $errors 
)
protected

Send content type and last modified headers to the client.

Parameters
ResourceLoaderContext$context
string$mtimeTS_MW timestamp to use for last-modified
bool$errorsWhether there are commented-out errors in the response
Returns
void

Definition at line 584 of file ResourceLoader.php.

References ResourceLoaderContext\getDebug(), ResourceLoaderContext\getOnly(), ResourceLoaderContext\getVersion(), global, TS_RFC2822, and wfTimestamp().

Referenced by tryRespondFromFileCache().

◆ tryRespondFromFileCache()

ResourceLoader::tryRespondFromFileCache ( ResourceFileCache  $fileCache,
ResourceLoaderContext  $context 
)
protected

Send out code for a response from file cache if possible.

Parameters
ResourceFileCache$fileCacheCache object for this request URL
ResourceLoaderContext$contextContext in which to generate a response
Returns
bool If this found a cache file and handled the response

Definition at line 661 of file ResourceLoader.php.

References $e, $response, FileCacheBase\cacheTimestamp(), DB_SLAVE, FileCacheBase\fetchText(), ResourceLoaderContext\getDebug(), ResourceLoaderContext\getVersion(), global, FileCacheBase\isCacheGood(), sendResponseHeaders(), tryRespondLastModified(), TS_MW, wfGetDB(), and wfTimestamp().

◆ tryRespondLastModified()

ResourceLoader::tryRespondLastModified ( ResourceLoaderContext  $context,
  $mtime 
)
protected

Respond with 304 Last Modified if appropiate.

If there's an If-Modified-Since header, respond with a 304 appropriately and clear out the output buffer. If the client cache is too old then do nothing.

Parameters
$contextResourceLoaderContext
string$mtimeThe TS_MW timestamp to check the header against
Returns
bool True if 304 header sent and output handled

Definition at line 626 of file ResourceLoader.php.

References ResourceLoaderContext\getDebug(), ResourceLoaderContext\getRequest(), TS_UNIX, wfResetOutputBuffers(), and wfTimestamp().

Referenced by tryRespondFromFileCache().

Member Data Documentation

◆ $filterCacheVersion

ResourceLoader::$filterCacheVersion = 7
staticprotected

Definition at line 36 of file ResourceLoader.php.

◆ $hasErrors

bool ResourceLoader::$hasErrors = false
protected

Definition at line 63 of file ResourceLoader.php.

◆ $moduleInfos

array ResourceLoader::$moduleInfos = array()
protected

Associative array mapping module name to info associative array.

Definition at line 49 of file ResourceLoader.php.

◆ $modules

ResourceLoader::$modules = array()
protected

◆ $requiredSourceProperties

ResourceLoader::$requiredSourceProperties = array( 'loadScript' )
staticprotected

Definition at line 40 of file ResourceLoader.php.

◆ $sources

ResourceLoader::$sources = array()
protected

Definition at line 59 of file ResourceLoader.php.

◆ $testModuleNames

array ResourceLoader::$testModuleNames = array()
protected

Associative array mapping framework ids to a list of names of test suite modules like array( 'qunit' => array( 'mediawiki.tests.qunit.suites', 'ext.foo.tests', .

. ), .. )

Definition at line 54 of file ResourceLoader.php.


The documentation for this class was generated from the following file: