Manual:Configuration for developers

From MediaWiki.org
Jump to: navigation, 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 are registered should set up configuration variables as described in this section. if it's not the full extension name (e.g. is an abbreviation) then you should make sure it doesn't collide with any existing extension.

In extension.json:

{
	"config": {
		"YourExtensionUser": {
			"value": "SomeUser",
			"description": "The description for the configuration",
		}
	},
	"ConfigRegistry": {
		"yourextension": "GlobalVarConfig::newInstance"
	}
}

In PHP, whenever you want your configuration values:

$config = MediaWikiServices::getInstance()->getConfigFactory()->makeConfig( 'yourextension' );
$user = $config->get( 'YourExtensionUser' );

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';

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 core, you can use MediaWikiTestCase::setMwGlobals()

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]