Manuel:Configuration pour les développeurs

Pour la documentation concernant la configuration de MediaWiki, voir le manuel de Configuration.

Ceci est un guide pour les développeurs du noyau et des extensions à propos de la création et de l'accès aux paramètres de configuration.

Pour le noyau

Pour accéder à un paramètre de configuration tel que $wgFoo :

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

Si vous avez accès à aucun ContextSource, vous pouvez obtenir un objet Config avec :

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

Ceci ne doit pas être utilisé pour récupérer des objets de variable globale comme $wgUser ou $wgRequest .

Pour les extensions

Configuration utilisant `extension.json` (recommandée)

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 
}

En PHP, lorsque vous souhaitez les valeurs de vos paramètres de configuration :

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). Vous devez vous assurer qu'il n'y a pas de collision avec les paramètres d'une autre extension.

Il est très recommandé que le nom de la clé de configuration commence par le nom de votre extension (comme dans l'exemple), pour s'assurer que la clé de configuration est unique, parmi toutes les clés de toutes les applications. Not doing this is a bad idea, and will probably break the use of attributes.

Configuration utilisant les variables globales

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

Préfixes personnalisés

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.

Tests

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

Programmatically modifying configuration values

The 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

Version de MediaWiki :

≥ 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
		}
	}
}

Suivi dans Phabricator
Tâche T71084

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.