Manual:Configuration for developers
- 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
editTo 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
editConfiguration 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( 'YourExtensionSomeConfigKey' );
If the prefix for your configuration keys is not the default "wg", 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.
It is highly recommended to start the name of the configuration key with the name of your extension (as in the example), to ensure the config key is unique among all keys of all applications. Not doing this is a bad idea, and will probably break the use of attributes.
Configuration using globals
editIf 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
editIn 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
editWhen 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 MediaWikiIntegrationTestCase:
$this->setMwGlobals( [ 'wgFoo' => 'baz' ] );
Programmatically modifying configuration values
editThe only Config implementation that supports modification of values is HashConfig, which is mostly used in tests.
One way to modify values from the MainConfig service is via the MediaWikiServices hook, but this is discouraged. Instead, a hook should be used to allow more controlled and explicit modification of the relevant values.
Upgrading from before MediaWiki 1.23
editMediaWiki version: | ≥ 1.23 |
In MediaWiki 1.23 a new Config
interface was introduced to access configuration options.
This allowed us to abstract the backends in which we store 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 defaultConfig
object. Most contexts implementgetConfig()
. - Rather than checking for "wgFoo", you ask the Config object for "Foo", without any wg prefix.