Manual:Configuration for developers

From MediaWiki.org
Jump to navigation Jump to search
For documentation about configuring MediaWiki, see Manual:Configuration.

This is a guide for core and extension developers about creating and accessing configuration settings.

For core[edit]

To access a configuration variable such as $wgFoo:

$config = $this->getConfig(); // this is a Config object
$foo = $config->get( 'Foo' );

If you don't have access to any ContextSources, you can get a Config object with

$config = MediaWikiServices::getInstance()->getMainConfig();

This should not be used to fetch global variable objects such as $wgUser or $wgRequest.

For extensions[edit]

Configuration using extension.json (recommended)[edit]

Extensions that have an extension.json file should set up configuration variables as described in this section.

If your extension is called YourExtension, in extension.json you'd write:

{
	"config": {
		"YourExtensionSomeConfigKey": {
			"value": "SomeValue",
			"description": "The description for the configuration",
		}
	},
	"ConfigRegistry": {
		"yourextension": "GlobalVarConfig::newInstance"
	},
	"manifest_version": 2 
}

In PHP, whenever you want your configuration values:

use MediaWiki\MediaWikiServices;
$config = MediaWikiServices::getInstance()->getConfigFactory()->makeConfig( 'yourextension' );
$user = $config->get( 'SomeConfigKey' );

If the prefix for your configuration keys is not the full extension name (e.g. is an abbreviation) you can specify it with the config_prefix or _prefix key, depending on the schema version (see docs). You should make sure it doesn't collide with any existing extension. Generally this is a bad idea though, and will probably break the use of attributes.

Configuration using globals[edit]

If you can, use the extension.json file for configuration (see above). If you can't, use this snippet (only works with wg prefixed variables):

$wgConfigRegistry['yourextension'] = 'GlobalVarConfig::newInstance';

// Now, whenever you want your config object
$config = ConfigFactory::getDefaultInstance()->makeConfig( 'yourextension' );

Custom prefixes[edit]

In the past, some extensions used "eg" instead of "wg". We want to move away from prefixes, but you can still continue to use them:

// In your extension's setup file (ExtName.php)
wfExtNameConfigBuilder() {
	return new GlobalVarConfig( 'eg' ); // replace "eg" with whatever your custom prefix is
}
$wgConfigRegistry['ext-name'] = 'wfExtNameConfigBuilder';

If you use extension registration, there is a prefix or config_prefix (depending on the schema version) field you can use instead.

Testing[edit]

When debugging, you use the following to test that you are accessing the right Config instance. You should do this in place of the $wgConfigRegistry shown in the for extensions section above.

$wgConfigRegistry['ext-name'] = function() { 
	return new HashConfig( array( 
		// Array of config variables and values
		'Foo' => 'baz'
	) );
};

If you are accessing the wrong Config instance, a ConfigException will be produced.

For modifying configuration variables in PhpUnit tests in extensions using manifest version 1 (or in MediaWiki core), you can do the following in test cases that extend MediaWikiTestCase:

$this->setMwGlobals( [ 'wgFoo' => 'baz' ] );

Upgrading from before MediaWiki 1.23[edit]

MediaWiki version: 1.23

Starting with MediaWiki 1.23, there a new Config interface was introduced to access configuration options. This allowed us to abstract the backend in which we stored configuration options.

Pre-1.23 code would look like:

class ApiMyModule extends ApiBase {
	public function execute() {
		global $wgFoo;
		if ( $wgFoo ) {
			// do stuff
		}
	}
}

1.23+ code should look like this:

class ApiMyModule extends ApiBase {
	public function execute() {
		$config = $this->getConfig(); // this is a Config object
		if ( $config->get( 'Foo' ) ) {
			// do stuff
		}
	}
}

You'll notice a few changes here:

  • We use $this->getConfig() to get the default Config object. Most contexts implement getConfig().
  • Rather than checking for "wgFoo", you ask the Config object for "Foo", without any wg prefix.

See also[edit]