Manuel:Configuration pour les développeurs
- Pour la documentation concernant la configuration de MediaWiki, voir Manual: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(); // ceci est un objet Config
$foo = $config->get( 'Foo' );
Si vous avez accès à aucun objet 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)
Les extensions qui ont un fichier extension.json doivent initialiser les paramètres de configuration tel qu'il est écrit dans cette section.
Si votre extension s'appelle YourExtension, dans extension.json vous écrirez :
{
"config": {
"YourExtensionSomeConfigKey": {
"value": "SomeValue",
"description": "The description for the configuration",
}
},
"ConfigRegistry": {
"yourextension": "GlobalVarConfig::newInstance"
},
"manifest_version": 2
}
Naming conventions:
- 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. Si vous ne le faites pas, c'est mal car vous risquez de casser le fonctionnement des attributs.
- It is customary to make the name for the ConfigRegistry, here "yourextension", lowercase and without spaces.
Custom prefixes
Si le préfixe des clés de votre configuration n'est pas la valeur par défaut wg, vous pouvez l'indiquer avec la clé config_prefix ou _prefix, en fonction de la version du schéma (voir la documentation).
Vous devez vous assurer qu'il n'y a pas de collision avec les paramètres d'une autre extension.
Retrieve configuration option
En PHP, lorsque vous souhaitez les valeurs de vos paramètres de configuration, vous pouvez écrire :
use MediaWiki\MediaWikiServices;
$config = MediaWikiServices::getInstance()->getConfigFactory()->makeConfig( 'yourextension' );
$myConfigOption = $config->get( 'YourExtensionSomeConfigKey' ); // without prefix!
If the above does not work, you can call it as a global:
global $wgYourExtensionSomeConfigKey;
Configuration utilisant les variables globales
Si vous le pouvez, utilisez le fichier extension.json pour la configuration (voir ci-dessus).
Sinon, utilisez le code suivant (ne fonctionne qu'avec des variables préfixées par wg) :
$wgConfigRegistry['yourextension'] = 'GlobalVarConfig::newInstance';
// Et à chaque fois que vous voudrez utiliser votre objet 'Config'
$config = ConfigFactory::getDefaultInstance()->makeConfig( 'yourextension' );
Préfixes personnalisés
Dans le passé, certaines extensions utilisaient eg au lieu de wg. Nous voulons nous débarrasser des préfixes, mais il est toujours possible de les utiliser :
// Dans le fichier de configuration de votre extension (ExtName.php)
wfExtNameConfigBuilder() {
return new GlobalVarConfig( 'eg' ); // remplacer 'eg' par votre préfixe personnalisé
}
$wgConfigRegistry['ext-name'] = 'wfExtNameConfigBuilder';
Si vous utilisez l'enregistrement des extensions, il existe un champ prefix ou config_prefix (fonction de la version du schéma) dont vous pouvez vous servir à la place.
Tests
En phase de débogage, utilisez ce qui suit pour tester que vous accédez bien à la bonne instance de Config. Vous devez le faire en remplacement du $wgConfigRegistry évoqué dans la section concernant les extensions ci-dessus.
$wgConfigRegistry['ext-name'] = function() {
return new HashConfig( array(
// tableau de variables config et valeurs
'Foo' => 'baz'
) );
};
Si vous accédez à la mauvaise instance de Config, un ConfigException sera généré.
Pour modifier les paramètres de configuration dans les tests PhpUnit des extensions en utilisant manifest version 1 (ou dans le noyau MediaWiki), vous pouvez écrire ceci dans les cas de tests qui étendent MediaWikiIntegrationTestCase :
$this->setMwGlobals( [ 'wgFoo' => 'baz' ] );
Modification des paramètres de configuration par programme
La seule implémentation de Config qui supporte la modification of values est HashConfig, qui est principalement utilisée lors des tests.
Une façon de modifier les valeurs à partir du service MainConfig est d'utiliser l'accroche MediaWikiServices, mais cela n'est pas recommandé. A la place, utiliser une accroche qui permette la modification plus étendue et plus explicite des valeurs correspondantes.
Mise à jour d'une version antérieure à MediaWiki 1.23
| Version de MediaWiki : | ≥ 1.23 |
En MediaWiki 1.23 une nouvelle interface Config a été introduite pour accéder aux options de configuration.
Ceci nous permet de faire abstraction des serveurs sur lesquels les options de configuration sont enregistrées.
Le code d'avant la 1.23 est similaire à :
class ApiMyModule extends ApiBase {
public function execute() {
global $wgFoo;
if ( $wgFoo ) {
// votre code ici...
}
}
}
Le code à partir de la 1.23 doit avoir la forme suivante :
class ApiMyModule extends ApiBase {
public function execute() {
$config = $this->getConfig(); // c'est un objet Config
if ( $config->get( 'Foo' ) ) {
// votre code ici...
}
}
}
Vous remarquerez quelques modifications ici :
- Utiliser
$this->getConfig()pour obtenir l'objetConfigpar défaut. La plupart des contextes implémententgetConfig(). - Plutôt que de vérifier wgFoo, demandez à l'objet Config Foo, sans aucun préfixe wg.