Manuel:Enregistrement des extensions
| Version de MediaWiki : | ≥ 1.25 Gerrit change 166705 |
L’enregistrement des extensions est un mécanisme utilisé par MediaWiki pour charger les extensions et les habillages.
Vous placez les données de configuration dans un fichier nommé extension.json ou skin.json dans le dossier racine de votre extension ou votre habillage et MediaWiki utilise ces données pour enregistrer les extensions et les habillages.
Si vous cherchez des documents sur l'installation des extensions, voir ce guide.
Fonctionnalités
Attributs
« Attributes » vous permet d'enregistrer quelque chose, comme un module, avec une autre extension.
Par exemple, l'extension VisualEditor (VE) offre l'accroche $wgVisualEditorPluginModules, que d'autres extensions peuvent utiliser pour enregistrer un module avec VE.
Si l'extension Math devait enregistrer un module avec VE, elle aurait quelque chose comme ceci dans son extension.json :
| manifest version 2 | manifest version 1 |
|---|---|
Le nœud attributes doit être un objet avec le nom de l'extension comme clé et un objet de paires attributs/valeurs comme valeur. Notez bien que la clé du sous-objet ne doit pas contenir le nom de l'extension !
{
"attributes": {
"VisualEditor": {
"PluginModules": [
"ext.math.visualEditor"
]
}
},
"manifest_version": 2
}
|
Manifest version 1 n'a pas de section spécifique pour attributes :
{
"VisualEditorPluginModules": [
"ext.math.visualEditor"
]
}
|
Quand l’Editeur Visuel veut accéder à cet attribut, il utilise :
ExtensionRegistry::getInstance()->getAttribute( 'VisualEditorPluginModules' );
Prérequis (dépendances)
L'enregistrement d'extension possède une section requires, qui agit de manière similaire à la section require de Composer.
Elle permet à un développeur d'extensions de spécifier plusieurs prérequis pour l'extension, comme une version spécifique de MediaWiki (ou plus récent que, plus ancien que) ou une autre extensions ou habillage.
Par exemple, pour ajouter une dépendance sur une version de MediaWiki plus récente que 1.26.0, vous pouvez ajouter le code suivant dans extension.json : [1]
{
"requires": {
"MediaWiki": ">= 1.26.0"
}
}
La clé de l'objet requires est le nom de la dépendance (avant MediaWiki 1.29.0 seulement MediaWiki était pris en charge), la valeur est une contrainte de version valide (le format doit être compatible avec celui utilisé par Composer).
Dans MediaWiki 1.29.0 et plus récent vous pouvez aussi ajouter des dépendances vers des habillages ou d'autres extensions comme par exemple :
{
"requires": {
"MediaWiki": ">= 1.29.0",
"extensions": {
"ExampleExtension": "*"
},
"skins": {
"ExampleSkin": "*"
}
}
}
- Les extensions et habillages spécifiés ici doivent aussi utiliser le système d'enregistrement des extensions décrit sur cette page pour que cela fonctionne.
- La chaîne ajoutée pour préciser l'extension ou l'habillage doit être la même que la chaîne spécifiée dans le champ « name » du fichier « extension.json » ou « skin.json » respectif.
- Pour les extensions qui utilisent l'intégration continue de Wikimedia, les dépendances doivent également être ajoutées à zuul/parameter_functions.py
Dans MediaWiki 1.33.0 (?) et ultérieur, vous pouvez aussi ajouter des dépendances sur PHP ainsi :
{
"requires": {
"MediaWiki": ">= 1.33.0",
"platform": {
"php": ">= 7.0.3"
}
}
}
Vérifier qu'une extension est chargée alors qu'elle n'est pas nécessaire
Beaucoup d'extensions peuvent apporter des fonctionalités qui ne travaillent que si une autre extension est également chargée, sans que cette fonctionalité ne soit réellement demandée pour que la fonction d'extension du noyau soit opérationnelle. Comme exemple : si l'extension B est chargée, l'extension A peut fournir un éditeur réellement WYSIWYG, sinon on utilisera une simple zone textuelle. L'extension A peut profiter de l'extension B (si elle est chargée), mais n'en n'a pas besoin pour être chargée et fonctionner correctement. Pour cela on regarde habituellement si l'extension est chargée plutôt que de l'ajouter comme dépendance codée en dur.
Pour implémenter une manière standardisée pour vérifier qu'une extension est chargée ou pas (sans avoir besoin de développement supplémentaire dans une extension qui dépend logiciellement d'une autre), on peut utiliser l'enregistrement d'extension.
Il implémente une méthode isLoaded, qui renvoie un simple booléen indiquant si l'extension est chargée ou pas (l'extension doit être chargée avec l'enregistrement d'extension pour que cela fonctionne).
Exemple :
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB' ) ) {
// exécuter seulement si l'extension B est chargée
}
| Version de MediaWiki : | ≥ 1.32 Gerrit change 455752 |
Depuis MediaWiki 1.32 il est également possible de vérifier si une extension est chargée et si elle satisfait une contrainte de version de Composer :
if ( ExtensionRegistry::getInstance()->isLoaded( 'ExtensionB', '>=1.2' ) ) {
// exécuter seulement si l'extension B est chargée et que sa version est 1.2 ou supérieur.
}
Si vous vouliez vérifier qu'une version spécifique d'une extension était chargée dans les précédentes versions de MediaWiki, ce type d'information peut être extrait avec la méthode getAllThings , qui renvoie l'information de crédit pour toutes les extensions chargées. Exemple :
$bVersion = ExtensionRegistry::getInstance()->getAllThings()['ExtensionB']['version'] ?? null;
if ( $bVersion !== null && version_compare( $bVersion, '2.1.0', '>=' ) ) {
// exécuter seulement si l'extension B est chargée et que sa version est 2.1.0 ou supérieur.
}
De la même manière, si l'extension B définit une constante spéciale dans ce but durant le chargement, il est possible de vérifier si elle est définie :
if ( defined( 'ExtensionBVersion' ) ) { // You could also check for a version, if the constant holds the version
// exécuter seulement si l'extension B est chargée
}
Une autre manière parallèle qui doit être évitée est de vérifier si une classe spécifique de l'extension B existe ou pas, par exemple en utilisant le code :
if ( class_exists( 'ExtensionBHooks' ) ) {
// exécuter seulement si l'extension B existe
}
Ceci peut ne pas fonctionner si l'extension existe dans le système de fichiers mais n'est pas chargée, par exemple si Composer a été utilisé pour l'auto-chargement. Si une classe a été renommée ou cesse d'exister (par exemple parce qu'elle ne fait plus partie des paquets publiques) cela va provoquer également la rupture.
En général, il est préférable de partager le code par des composants Composer plutôt que des extensions. Si les classes d'une extension n'ont besoin que d'exister, mais que l'extension n'a pas besoin d'être configurée ni chargée pour ce que vous voulez en faire, c'est une très bonne indication que le code doit être découpé dans un composant Composer duquel vous devez dépendre à la place.
Configurations (vos paramètres d'extensions et d'habillages)
Par défaut, extension.json suppose que vos paramètres de configuration commencent avec le préfixe « wg ».
Si ce n'est pas le cas, vous pouvez réécraser le préfixe en utilisant une clé spéciale :
{
"config": {
"_prefix": "eg",
"MyExtSetting": true
}
}
Cela va utiliser le préfixe « eg » et mettre la variable globale $egMyExtSetting à true.
À partir de manifest version 2, la section de configuration de l'enregistrement des extensions fournit beaucoup plus de fonctionnalités et vous permet de décrire vos options de configuration de manière beaucoup plus détaillée. Au lieu d'avoir enregistré une seule clé → valeur pour vos options de configuration, vous pouvez également ajouter les informations suivantes.
La structure générale de la config change légèrement par la suite, en devenant une version plus orientée objet :
{
"config_prefix": "eg",
"config": {
"MyExtSetting": {
"value": true,
"path": false,
"description": "Description de la configuration",
"descriptionmsg": "myextension-config-myextsetting",
"public": true
}
},
"manifest_version": 2
}
value
La valeur de la configuration a été déplacée à cet endroit. C'est la seule clé obligatoire pour un objet configuration.
path
La valeur booléenne de la clé path indique si la valeur de l'option de configuration doit être interprétée comme un chemin dans le système de fichiers, relativement au répertoire racine de l'extension.
Par exemple, si la valeur de la configuration est myFile.png et que path vaut true, la valeur actuelle sera /path/to/the/wiki/extensions/MyExtension/myFile.png.
description
La clé description pour une option de configuration peut contenir une chaîne non traduite, qui peut être utilisée pour expliquer l'option de configuration de votre extension, aux autres développeurs ou aux utilisateurs (administrateurs système).
Cela peut aussi être utilisé comme texte d'infobulle pour la section des paramètres dans la boîte d'information de l'extension, sur la page de description de l'extension de MediaWiki.org.
La valeur de la clé de decription n'est habituellement pas affichée pour l'IHM du wiki, néanmoins, cherchez sur le sujet pour avoir plus d'informations sur la manière dont cette fonctionalité pourrait être utilisée dans le futur !
descriptionmsg
Il existe aussi la possbilité d'ajouter en tant que description (descriptionmsg), une clé du message dans le sytème de localisation interne de MediaWiki, ce qui dans le futur, sera utilisé pour présenter la description au niveau de l'interface utilisateur de l'installation MediaWiki.
public / private
Cette option est un booléen, qui vaut false par défaut, ce qui signifie que l'option de configuration et la valeur sont marquées "private".
Cette valeur est utilisée nulle part en ce moment, cherchez un peu sur le sujet pour en découvrir plus à propos de cette option.
Perspectives
Les modifications mentionnées ci-dessus sont également des étapes préparatoires pour une gestion améliorée de la configuration dans MediaWiki. Ces changements nous permettent par exemple d'afficher les options de configuration des extensions dans l'IHM MediaWiki. Pour cela, le message de description traduit (descriptionmsg et description) ainsi que l'indication si l'option de configuration peut être affichée ou pas (public) sont nécessaires.
Auto-découverte des tests unitaires
MediaWiki permet à toute extension d'enregistrer des tests unitaires php. Sans l'enregistrement d'extension, vous devriez enregistrer un gestionnaire pour l'accroche UnitTestsList, qui ressemblerait à ceci :
public static function onUnitTestsList( array &$paths ) {
$paths[] = __DIR__ . '/tests/phpunit/';
}
(comme décrit sur la page du manuel). Cependant, ce code a la même apparence pour beaucoup d'extensions, vous pouvez donc appeler cela une duplication inutile du code.
Si votre extension utilise l'enregistrement des extensions et que vos tests phpunit se trouvent dans le sous-répertoire tests/phpunit/ de votre extension, le conteneur phpunit de MediaWiki va découvrir automatiquement les tests unitaires avec l'aide de l'enregistrement des extensions.
C'est pourquoi il n'est plus utile d'enregistrer l'accroche, ni de spécifier que les tests unitaires sont stockés dans le répertoire par défaut.
Catégories de suivi
| Version de MediaWiki : | ≥ 1.25 |
Depuis MediaWiki 1.25, toutes les catégories qu'une extension veut répertorier sur Special:TrackingCategories doivent être enregistrées dans extension.json :
{
"TrackingCategories": [
"myextension-tracking-category"
]
}
myextension-tracking-category est un message système qui contient le nom de la catégorie et qui est ajouté aux pages avec Parser::addTrackingCategory().
Personnaliser l’enregistrement
Et composer.json
Si une extension ou un habillage dépendent de bibliothèques, il peut exister également un fichier composer.json, voir Manuel:Bonnes pratiques pour composer.json. Utilisez le champ load_composer_autoloader pour que MediaWiki se serve de l'auto-chargement de Composer quand c'est possible.
Quelques champs de métadonnées sont les mêmes entre extension.json et composer.json (discussion dans tâche T89456), dont :
urlethomepagelicense-nameetlicense
Gestion du code
- Maintenu par Unknown or Unassigned[Maintainers page].
- Suivi des problèmes : Phabricator MediaWiki-Configuration (rapporter un problème)
Voir aussi
Documentation
- Manuel:Extension.json/Schéma
docs/extension.schema.v2.jsonest le schéma pourextension.json(et skin.json).
- Limitations connues
- Aperçu de l’architecture
- Guide de migration - quelques recommendation sur la mise à jour des extensions plus anciennes
Feedback
- Rapportez les bogues dans le projet MediaWiki-Configuration.
- RfC à propos de l’implémentation d’un système d’enregistrement d'extensions