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

Collaboration diagram for ResourceLoader:

Public Member Functions
	__construct (Config $config=null)
	Register core modules and runs registration hooks.
	addSource ($id, $loadUrl=null)
	Add a foreign source of modules.
	createLoaderURL ($source, ResourceLoaderContext $context, $extraQuery=array())
	Build a load.php URL.
	filter ($filter, $data, $cacheReport=true)
	Run JavaScript or CSS data through a filter, caching the filtered result for future calls.
	getConfig ()
	getLoadScript ($source)
	Get the URL to the load.php endpoint for the given ResourceLoader source.
	getModule ($name)
	Get the ResourceLoaderModule object for a given module name.
	getModuleNames ()
	Get a list of module names.
	getSources ()
	Get the list of sources.
	getTestModuleNames ($framework= 'all')
	Get a list of test module names for one (or all) frameworks.
	makeModuleResponse (ResourceLoaderContext $context, array $modules, array $missing=array())
	Generate code for a response.
	preloadModuleInfo (array $modules, ResourceLoaderContext $context)
	Load information stored in the database about modules.
	register ($name, $info=null)
	Register a module with the ResourceLoader system.
	registerTestModules ()
	respond (ResourceLoaderContext $context)
	Output a response to a load request, including the content-type header.
Static Public Member Functions
static	clearCache ()
	Reset static members used for caching.
static	createLoaderQuery (ResourceLoaderContext $context, $extraQuery=array())
	Helper for createLoaderURL()
static	formatException ($e)
	Handle exception display.
static	getLessCompiler (Config $config)
	Returns LESS compiler set up for use with MediaWiki.
static	getLessVars (Config $config)
	Get global LESS variables.
static	inDebugMode ()
	Determine whether debug mode was requested Order of priority is 1) request param, 2) cookie, 3) $wg setting.
static	isValidModuleName ($moduleName)
	Check a module name for validity.
static	makeCombinedStyles (array $stylePairs)
	Combines an associative array mapping media type to CSS into a single stylesheet with "@media" blocks.
static	makeComment ($text)
	Generate a CSS or JS comment block.
static	makeConfigSetScript (array $configuration)
	Returns JS code which will set the MediaWiki configuration array to the given value.
static	makeCustomLoaderScript ($name, $version, $dependencies, $group, $source, $script)
	Returns JS code which calls the script given by $script.
static	makeLoaderConditionalScript ($script)
	Returns JS code which runs given JS code if the client-side framework is present.
static	makeLoaderImplementScript ($name, $scripts, $styles, $messages)
	Return JS code that calls mw.loader.implement with given module properties.
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.
static	makeLoaderRegisterScript ($name, $version=null, $dependencies=null, $group=null, $source=null, $skip=null)
	Returns JS code which calls mw.loader.register with the given parameters.
static	makeLoaderSourcesScript ($id, $properties=null)
	Returns JS code which calls mw.loader.addSource() with the given parameters.
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.
static	makeLoaderURL ($modules, $lang, $skin, $user=null, $version=null, $debug=false, $only=null, $printable=false, $handheld=false, $extraQuery=array())
	Build a load.php URL.
static	makeMessageSetScript ($messages)
	Returns JS code which, when called, will register a given list of messages.
static	makePackedModulesString ($modules)
	Convert an array of module names to a packed query string.
Protected Member Functions
	isFileModule ($name)
	Return whether the definition of a module corresponds to a simple ResourceLoaderFileModule.
	sendResponseHeaders (ResourceLoaderContext $context, $mtime, $errors)
	Send content type and last modified headers to the client.
	tryRespondFromFileCache (ResourceFileCache $fileCache, ResourceLoaderContext $context)
	Send out code for a response from file cache if possible.
	tryRespondLastModified (ResourceLoaderContext $context, $mtime)
	Respond with 304 Last Modified if appropiate.
Protected Attributes
bool	$hasErrors = false
	*
array	$moduleInfos = array()
	Associative array mapping module name to info associative array *.
	$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', .
Static Protected Attributes
static	$debugMode = null
static	$filterCacheVersion = 7
Private Attributes
Config	$config
	$config *

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

ResourceLoader::__construct ( Config $ config = null )

Register core modules and runs registration hooks.

Parameters:

Config | null $config

Definition at line 214 of file ResourceLoader.php.

Member Function Documentation

ResourceLoader::addSource	(	$	id,
		$	loadUrl = `null`
	)

Add a foreign source of modules.

Parameters:

array \| string	$id	Source ID (string), or array( id1 => loadUrl, id2 => loadUrl, ... )
string \| array	$loadUrl	load.php url (string), or array with loadUrl key for backwards-compatibility.

Exceptions:

MWException

Definition at line 399 of file ResourceLoader.php.

static ResourceLoader::clearCache ( ) [static]

Reset static members used for caching.

Global state and $wgRequest are evil, but we're using it right now and sometimes we need to be able to force ResourceLoader to re-evaluate the context because it has changed (e.g. in the test suite).

Definition at line 1313 of file ResourceLoader.php.

Referenced by ResourceLoaderTestCase\setUp().

static ResourceLoader::createLoaderQuery	(	ResourceLoaderContext $	context,
		$	extraQuery = `array()`
	)		`[static]`

Helper for createLoaderURL()

Since:: 1.24

See also:: makeLoaderQuery

Parameters:

ResourceLoaderContext	$context
array	$extraQuery

Returns:: array

Definition at line 1376 of file ResourceLoader.php.

ResourceLoader::createLoaderURL	(	$	source,
		ResourceLoaderContext $	context,
		$	extraQuery = `array()`
	)

Build a load.php URL.

Since:: 1.24

Parameters:

string	$source	Name of the ResourceLoader source
ResourceLoaderContext	$context
array	$extraQuery

Returns:: string URL to load.php. May be protocol-relative (if $wgLoadScript is procol-relative)

Definition at line 1326 of file ResourceLoader.php.

ResourceLoader::filter	(	$	filter,
		$	data,
		$	cacheReport = `true`
	)

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

Available filters are:

minify-js
See also:
JavaScriptMinifier::minify
minify-css
See also:
CSSMin::minify
If $data is empty, only contains whitespace or the filter was unknown, $data is returned unmodified.

Parameters:

string	$filter	Name of filter to run
string	$data	Text to filter, such as JavaScript or CSS text
string	$cacheReport	Whether to include the cache key report

Returns:: string Filtered data, or a comment containing an error message

Definition at line 150 of file ResourceLoader.php.

static ResourceLoader::formatException ( $ e ) [static]

Handle exception display.

Parameters:

Exception $e Exception to be shown to the user

Returns:: string Sanitized text that can be returned to the user

Definition at line 814 of file ResourceLoader.php.

ResourceLoader::getConfig ( )

Returns:: Config

Definition at line 248 of file ResourceLoader.php.

Referenced by ResourceLoaderContext\__construct(), and MessageBlobStore\getFromDB().

static ResourceLoader::getLessCompiler ( Config $ config ) [static]

Returns LESS compiler set up for use with MediaWiki.

Parameters:

Config $config

Exceptions:

MWException

Since:: 1.22

Returns:: lessc

Definition at line 1461 of file ResourceLoader.php.

static ResourceLoader::getLessVars ( Config $ config ) [static]

Get global LESS variables.

Parameters:

Config $config

Since:: 1.22

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

Definition at line 1486 of file ResourceLoader.php.

ResourceLoader::getLoadScript ( $ source )

Get the URL to the load.php endpoint for the given ResourceLoader source.

Since:: 1.24

Parameters:

string $source

Exceptions:

MWException On an invalid $source name

Returns:: string

Definition at line 537 of file ResourceLoader.php.

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 $name Module name

Returns:: ResourceLoaderModule|null If module has been registered, return a ResourceLoaderModule instance. Otherwise, return null.

Definition at line 473 of file ResourceLoader.php.

Referenced by MessageBlobStore\getFromDB(), and ResourceLoaderTest\testRegisteredValidModulesAreAccessible().

ResourceLoader::getModuleNames ( )

Get a list of module names.

Returns:: array List of module names

Definition at line 435 of file ResourceLoader.php.

ResourceLoader::getSources ( )

Get the list of sources.

Returns:: array Like array( id => load.php url, .. )

Definition at line 524 of file ResourceLoader.php.

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 $framework Get only the test module names for one particular framework (optional)

Returns:: array

Definition at line 449 of file ResourceLoader.php.

static ResourceLoader::inDebugMode ( ) [static]

Determine whether debug mode was requested Order of priority is 1) request param, 2) cookie, 3) $wg setting.

Returns:: bool

Definition at line 1296 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations(), ResourceLoaderUserTokensModule\getScript(), and ResourceLoaderUserOptionsModule\getScript().

ResourceLoader::isFileModule ( $ name ) [protected]

Return whether the definition of a module corresponds to a simple ResourceLoaderFileModule.

Parameters:

string $name Module name

Returns:: bool

Definition at line 508 of file ResourceLoader.php.

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 $moduleName Module name to check

Returns:: bool Whether $moduleName is a valid module name

Definition at line 1449 of file ResourceLoader.php.

static ResourceLoader::makeCombinedStyles ( array $ stylePairs ) [static]

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

Parameters:

array $stylePairs Array keyed by media type containing (arrays of) CSS strings

Returns:: array

Definition at line 1081 of file ResourceLoader.php.

Referenced by WebInstallerOutput\getCSS().

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 803 of file ResourceLoader.php.

Referenced by ResourceLoaderWikiModule\getScript(), and ResourceLoaderWikiModule\getStyles().

static ResourceLoader::makeConfigSetScript ( array $ configuration ) [static]

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

Parameters:

array $configuration List of configuration values keyed by variable name

Returns:: string

Definition at line 1257 of file ResourceLoader.php.

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

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	$name	Module name
int	$version	Module version number as a timestamp
array	$dependencies	List of module names on which this module depends
string	$group	Group which the module is in.
string	$source	Source of the module, or 'local' if not foreign.
string	$script	JavaScript code

Returns:: string

Definition at line 1152 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

static ResourceLoader::makeLoaderConditionalScript ( $ script ) [static]

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

Parameters:

string $script JavaScript code

Returns:: string

Definition at line 1246 of file ResourceLoader.php.

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

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

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

Parameters:

string	$name	Module name
mixed	$scripts	List of URLs to JavaScript files or String of JavaScript code
mixed	$styles	Array of CSS strings keyed by media type, or an array of lists of URLs to CSS files keyed by media type
mixed	$messages	List 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 1036 of file ResourceLoader.php.

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 1408 of file ResourceLoader.php.

static ResourceLoader::makeLoaderRegisterScript	(	$	name,
		$	version = `null`,
		$	dependencies = `null`,
		$	group = `null`,
		$	source = `null`,
		$	skip = `null`
	)		`[static]`

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

Has three calling conventions:

ResourceLoader::makeLoaderRegisterScript( $name, $version, $dependencies, $group, $source, $skip ): Register a single module.

ResourceLoader::makeLoaderRegisterScript( array( $name1, $name2 ) ): Register modules with the given names.

ResourceLoader::makeLoaderRegisterScript( array( array( $name1, $version1, $dependencies1, $group1, $source1, $skip1 ), array( $name2, $version2, $dependencies1, $group2, $source2, $skip2 ), ... ) ): Registers modules with the given names and parameters.

Parameters:

string	$name	Module name
int	$version	Module version number as a timestamp
array	$dependencies	List of module names on which this module depends
string	$group	Group which the module is in
string	$source	Source of the module, or 'local' if not foreign
string	$skip	Script body of the skip function

Returns:: string

Definition at line 1190 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

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

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

Has two calling conventions:

ResourceLoader::makeLoaderSourcesScript( $id, $properties ): Register a single source

ResourceLoader::makeLoaderSourcesScript( array( $id1 => $loadUrl, $id2 => $loadUrl, ... ) ); Register sources with the given IDs and properties.

Parameters:

string	$id	Source ID
array	$properties	Source properties (see addSource())

Returns:: string

Definition at line 1223 of file ResourceLoader.php.

Referenced by ResourceLoaderStartUpModule\getModuleRegistrations().

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:

ResourceLoader::makeLoaderStateScript( $name, $state ): Set the state of a single module called $name to $state

ResourceLoader::makeLoaderStateScript( array( $name => $state, ... ) ): Set the state of modules with the given names to the given states

Parameters:

string	$name
string	$state

Returns:: string

Definition at line 1122 of file ResourceLoader.php.

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.

Deprecated:: since 1.24, use createLoaderURL instead

Parameters:

array	$modules	Array of module names (strings)
string	$lang	Language code
string	$skin	Skin name
string \| null	$user	User name. If null, the &user= parameter is omitted
string \| null	$version	Versioning timestamp
bool	$debug	Whether the request should be in debug mode
string \| null	$only	&only= parameter
bool	$printable	Printable mode
bool	$handheld	Handheld mode
array	$extraQuery	Extra query parameters to add

Returns:: string URL to load.php. May be protocol-relative (if $wgLoadScript is procol-relative)

Definition at line 1352 of file ResourceLoader.php.

static ResourceLoader::makeMessageSetScript ( $ messages ) [static]

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

Parameters:

mixed $messages Either 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 1066 of file ResourceLoader.php.

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

Generate code for a response.

Parameters:

ResourceLoaderContext	$context	Context in which to generate a response
array	$modules	List of module objects keyed by module name
array	$missing	List of requested module names that are unregistered (optional)

Returns:: string Response data

Definition at line 832 of file ResourceLoader.php.

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 $modules List of module names (strings)

Returns:: string Packed query string

Definition at line 1273 of file ResourceLoader.php.

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

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	$modules	List of module names to preload information for
ResourceLoaderContext	$context	Context to load the information within

Definition at line 69 of file ResourceLoader.php.

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

Register a module with the ResourceLoader system.

Parameters:

mixed	$name	Name of module as a string or List of name/object pairs as an array
array	$info	Module info array. For backwards compatibility with 1.17alpha, this may also be a ResourceLoaderModule object. Optional when using multiple-registration calling style.

Exceptions:

MWException	If a duplicate module registration is attempted
MWException	If a module name contains illegal characters (pipes or commas)
MWException	If something other than a ResourceLoaderModule is being registered

Returns:: bool False if there were any errors, in which case one or more modules were not registered

Definition at line 265 of file ResourceLoader.php.

Referenced by ResourceLoaderTest\testRegisteredValidModulesAreAccessible().

ResourceLoader::registerTestModules ( )

Definition at line 350 of file ResourceLoader.php.

ResourceLoader::respond ( ResourceLoaderContext $ context )

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

Parameters:

ResourceLoaderContext $context Context in which a response should be formed

Definition at line 549 of file ResourceLoader.php.

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

Send content type and last modified headers to the client.

Parameters:

ResourceLoaderContext	$context
string	$mtime	TS_MW timestamp to use for last-modified
bool	$errors	Whether there are commented-out errors in the response

Returns:: void

Definition at line 674 of file ResourceLoader.php.

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

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

Parameters:

ResourceFileCache	$fileCache	Cache object for this request URL
ResourceLoaderContext	$context	Context in which to generate a response

Returns:: bool If this found a cache file and handled the response

Definition at line 751 of file ResourceLoader.php.

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:

ResourceLoaderContext	$context
string	$mtime	The TS_MW timestamp to check the header against

Returns:: bool True if 304 header sent and output handled

Definition at line 716 of file ResourceLoader.php.

Member Data Documentation

Config ResourceLoader::$config [private]

$config *

Definition at line 43 of file ResourceLoader.php.

ResourceLoader::$debugMode = null [static, protected]

Definition at line 36 of file ResourceLoader.php.

ResourceLoader::$filterCacheVersion = 7 [static, protected]

Definition at line 33 of file ResourceLoader.php.

bool ResourceLoader::$hasErrors = false [protected]

*

Definition at line 53 of file ResourceLoader.php.

array ResourceLoader::$moduleInfos = array() [protected]

Associative array mapping module name to info associative array *.

Definition at line 41 of file ResourceLoader.php.

ResourceLoader::$modules = array() [protected]

Definition at line 39 of file ResourceLoader.php.

ResourceLoader::$sources = array() [protected]

Definition at line 51 of file ResourceLoader.php.

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 48 of file ResourceLoader.php.

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

includes/resourceloader/ResourceLoader.php

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation