Structure

Une extension minimale a la structure suivante :

MyExtension/extension.json

Enregistre les instructions de configuration. Le nom du fichier doit être extension.json. (Pour les versions antérieures à MédiaWiki 1.25 les instructions d'installation se trouvent dans un fichier MyExtension/MyExtension.php nommé d'après l'extension. Beaucoup d'extensions ont encore des fonctionnalités rétro-compatibles dans ce fichier PHP.)

MyExtension/includes/ (or MyExtension/src/)

Contient le code PHP d'exécution de l'extension.

MyExtension/resources/ (or MyExtension/modules/)

Contient les ressources client de l'extension telles que le JavaScript, le CSS ou le LESS.

MyExtension/i18n/*.json

Contient les informations d'internationalisation de l'extension.

MyExtension/README.md

La bonne pratique est d'ajouter un fichier README avec les informations de base sur la manière d'installer et de configurer l'extension. Utiliser soit du texte simple ou au format Markdown. Pour l'exemple, voir la page de diffusion de Phabricator pour le Extension:Page Forms . Si le balisage est utilisé, ajoutez l'extension de fichier .md. Pour l'exemple, voir le fichier README.md pour Parsoid sur la Diffusion de Phabricator.

Lorsque vous développez une extension, remplacez MyExtension ci-dessus par le nom de votre extension. Utilisez les noms au format upperCamelCase pour son répertoire et ses fichiers PHP; c'est la convention générale de nommage des fichiers .^[1]

Enregistrement

Le fichier extension.json contient les données de configuration de l'extension. Voici un exemple de extension.json minimal :

{
	"name": "MyExtension",
	"author": "John Doe",
	"url": "https://www.mediawiki.org/wiki/Extension:MyExtension",
	"description": "This extension is an example.",
	"version": "1.5",
	"license-name": "GPL-2.0-or-later",
	"type": "validextensiontype",
	"manifest_version": 2
}

Beaucoup de ces champs sont optionnels, mais il est encore bon de les remplir. Pour un exemple plus complet de extension.json, voir l'extension BoilerPlate.

La manifest_version fait référence à la version du schéma pour lequel le fichier extension.json est écrit. Voir la documentation de cette fonctionnalité. A moins que vous n'ayez besoin de supporter une version plus ancienne de MediaWiki, choisissez la dernière.

Une fois que vous avez configuré un fichier extension.json pour votre extension, celle-ci apparaîtra sur votre page locale Special:Version.

Licence

MediaWiki est un projet à source libre et les utilisateurs sont encouragés à créer les MediaWiki extensions sous licence Open Source Initiative (OSI) approved et compatible avec GPL-2.0-or-later (licence logicielle standard de Wikimedia).

Nous recommandons d'adopter l'une des licences suivantes compatibles pour vos projets dans Gerrit :

• Licence publique générale GNU, version 2 ou plus récente (GPL-2.0-or-later)
• License MIT (MIT)
• Licence BSD (BSD-3-Clause)
• Licence Apache 2.0 (Apache-2.0)

Pour les extensions qui ont une licence compatible, vous pouvez demander un accès développeur aux dépôts des sources MediaWiki concernant les extensions. Pour préciser la licence dans le code et avec « license-name » une clé doit être fournie pour obtenir son nom court, par exemple « GPL-2.0-or-later » ou « MIT » conformémént à la liste des identifiants sur spdx.org.

Rendre votre extension configurable par l'utilisateur

Idéalement les utilisateurs doivent pouvoir installer votre extension en ajoutant uniquement une ligne dans LocalSettings.php :

wfLoadExtension( 'MyExtension' );

Si vous voulez rendre votre extension configurable par l'utilisateur, vous devez définir et documenter certains paramètres de configuration et le setup utilisateur devrait ressembler à ceci :

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

Si vous voulez que l'utilisateur puisse configurer votre extension, vous devrez fournir une ou plusieurs variables de configuration. C'est une bonne idée que de donner à ces variables un nom unique. Elles devront aussi suivre les conventions de nommage de MediaWiki (par exemple les variables globales doivent commencer par $wg).

Par exemple, si votre extension s'appelle MyExtension, vous pouvez nommer toutes vos variables de configurations pour qu'elles commencent par $wgMyExtension. Ce que vous choisissez n'a pas réellement d'importance tant que personne du cœur de MediaWiki ne commence ses variables de cette manière et vous avez fait un travail raisonnable en vérifiant que personne parmi les extensions publiées n'a fait commencer ses variables de la sorte. Les utilisateurs n'apprécieront pas de devoir choisir entre votre extension et d'autres extensions parce que vous avez choisi des noms de variables qui se chevauchent.

Une bonne idée aussi est d'inclure la documentation détaillée de toutes les variables de configuration dans vos informations d'installation.

Voici un exemple sur la manière d'initialiser une variable de configuration dans extension.json :

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

Remarquez qu'après l'appel à wfLoadExtension( 'BoilerPlate' ); la variable globale $wgBoilerPlateEnableFoo n'existe pas. Si vous initialisez la variable, par exemple à LocalSettings.php, la valeur par défaut qui se trouve dans extension.json ne sera pas utilisée.

Pour plus de détails sur la façon d'utiliser une variable globale dans les extensions personnalisées, veuillez vous référer à Configuration pour les développeurs .

Préparer des classes pour l'auto-chargement

Si vous choisissez des classes pour implémenter votre extension, Mediawiki fournit un mécanisme simplifié pour aider PHP à trouver le fichier source dans lequel se trouve votre classe. Dans la plupart des cas cela évite d'écrire votre propre méthode d' __autoload($classname) .

Pour utiliser le mécanisme d'auto-chargement de MediaWiki, ajoutez les entrées dans le champ AutoloadClasses . La clé de chaque entrée est le nom de la classe; la valeur est le fichier qui héberge la définition de la classe. Pour une extension simple ne comportant qu'une seule classe, on donne souvent à la classe le nom de l'extension et donc la section d'auto-chargement pourrait ressembler à ceci (avec une extension appelée MyExtension) :

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

Le nom de fichier est relatif au répertoire dans lequel se trouve le fichier extension.json .

Pour les extensions plus complexes, voir les Espaces de noms. Pour plus de détails voir Manual:Extension.json/Schema#AutoloadNamespaces.

Gérer les dépendances

Supposez qu'une extension nécessite la présence d'une autre extension, par exemple parce que les fonctionnalités des tables de la base de données doivent être utilisées et que l'on ne veut pas voir les messages d'erreur dans le cas où elles sont absentes.

Par exemple l'extension CountingMarker demande la présence de l'extension HitCounters pour certaines fonctions.

Une manière de spécifier cela serait d'utiliser la clé requires dans extension.json .

Une autre option est d'utiliser ExtensionRegistry (disponible depuis MW 1.25) :

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) {
		/* ajouter des actions supplémentaires, si l'extension HitCounters est présente dans les versions 1.1+ */
	}

Actuellement (février 2024 et MediaWiki 1.41.0) le nom de l'extension à vérifier doit correspondre exactement au nom de leur extension.json.^[2][3]

Exemple : si vous souhaitez vérifier l'état de chargement de l'extension OpenIDConnect, vous devez l'utiliser avec une espace

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) {
    ...
	}

Points d'extensions

Le noyau de MediaWiki fournit plusieurs façons pour que les extensions modifient le comportement, la fonctionnalité et l'apparence d'un wiki. La plupart des extensions utilisent plus d'un de ces points d'extension. Pour une liste complète des points d'extension pris en charge dans extension.json, voir la référence du schéma .

Ajouter des tables dans la base de données

Assurez-vous que l'extension ne modifie pas les tables de la base de données du noyau. A la place, l'extension doit créer de nouvelles tables avec des clés externes vers les tables MediaWiki correspondantes.

Avertissement :

Si votre extension est utilisée sur un produit de production quelconque hébergé par la WMF, veuillez suivre le guide de modification du schéma.

Si votre extension a besoin d'ajouter ses propres tables de base de données, utilisez l'accroche LoadExtensionSchemaUpdates . Voir la page du manuel pour davantage d'informations sur l'utilisation.

Enregistrement des attributs pour les autres extensions

Les attributs permettent aux extensions d'enregistrer quelque chose, comme un module, avec une autre extension. Par exemple, les extensions peuvent utiliser des attributs pour enregistrer un module de greffon avec l'extension VisualEditor. Pour d'autres informations, voir Enregistrement des extensions .

Enregistrer les messages dans <clé de langue>.json

Enregistrer les définitions de messages dans un fichier d'internationalisation JSON, un par clé de langue dans laquelle votre extension a été traduite. Les messages sont enregistrés avec une clé de message et le message lui-même, en utilisant le format standard JSON. Chaque identifiant de message doit être en minuscules et ne doit pas contenir d'espaces. Chaque clé doit commencer par le nom de l'extension en minuscules. Exemple que vous pouvez trouver dans l'extension MobileFrontend. Voici un exemple de fichier JSON minimal (dans ce cas en.json:

en.json

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

La documentation concernant les clés des messages peut être mise dans le fichier JSON pour le pseudo langage avec le code qqq. Une documentation de l'exemple ci-dessus peut-être :

qqq.json:

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

Charger le fichier d'internationalisation

Dans votre extension.json définissez l'emplacement de vos fichiers de messages système (par exemple dans le répertoire i18n/) :

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

Utilisation de wfMessage dans PHP

Dans votre code d'installation et d'implémentation, remplacez chaque utilisation littérale du message par un appel à wfMessage( $msgID, $param1, $param2, ... ). Dans les classes qui implémentent IContextSource (tout comme dans quelques autres telles que les sous-classes de SpecialPage), vous pouvez utiliser $this->msg( $msgID, $param1, $param2, ... ) à la place. Exemple:

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Utiliser mw.message sous JavaScript

Il est aussi possible d'utiliser les fonctions i18n en JavaScript. Voir API Messages pour les détails.

Déploiement et enregistrement

Si vous pensez déployer votre extension sur les sites Wikimedia (en incluant éventuellement Wikipedia), un examen supplémentaire est justifié en termes de performances et de sécurité. Consulter Ecrire une extension pour le déploiement .

Si votre extension ajoute des espaces de noms, vous pouvez enregistrer ses espaces de noms par défaut; de manière équivalente, si elle ajoute des tables de bases de données ou des champs, vous pouvez les enregistrer sur Préfixes des champs de base de données .

Veuillez être conscient que la relecture et le déploiement des nouvelles extensions sur les sites Wikimedia peuvent être extrêmement lents, et dans certains cas ont pris plus de deux ans. ^[4][5]

Documentation d'aide

Vous devez fournir la documentation d'aide dans le domaine publique pour les fonctions offertes par votre extension. La convention pour les extensions est d'avoir leurs pages d'aide à destination des utilisateurs sous un pseudo espace de noms du Help:Extension:<<nom de l'extension>>, avec les sous-pages nécessaires (la page de niveau supérieur étant automatiquement liée à partir de la boîte d'information de l'extension, si elle existe). Aide:CirrusSearch est un bon exemple de documentation. Vous devez donner aux utilisateurs un lien vers la documentation à l'aide de la fonction addHelpLink() .

Diffusion des mises à jour

Il existe un certain nombre d'approches communes pour publier les mises à jour des extensions. Définis généralement en fonction de la politique de compatibilité de l'extension (master, rel, ou ltsrel) :

• master – Les versions peuvent être marquées avec des numéros de version sur la branche principale (master) et les documents fournis sur la page d'accueil de l'extension décrivant quelles versions de l'extension sont compatibles avec quelles versions du noyau. Les branches de version seront toujours créées automatiquement et vous pouvez les supprimer si elles ne sont pas destinées à être utilisées.
• rel et ltsrel – Diffuser en reportant les modifications dans les branches REL1_* (soit toutes les modifications, soit uniquement celles qui sont critiques). Les numéros de version ne sont généralement pas nécessaires à moins que l'extension soit une dépendance d'une autre (le numéro de version peut ensuite être fourni dans la configuration de l'autre extension pour s'assurer que les combinaisons incompatibles ne sont pas installées). De nombreuses extensions resteront avec le même numéro de version pendant des années.

Support des autres versions du noyau

Il existe deux conventions largement répandues pour supporter les versions plus anciennes du cœur MediaWiki :

• Master : la branche principale (master) de l'extension est compatible avec autant d’anciennes versions du noyau que possible. Ceci résulte en une lourde charge de maintenance (les développements à compatibilité ascendante doivent être conservés longtemps, et les modifications de l'extension doivent être testées avec plusieurs versions de MediaWiki), mais les sites qui utilisent les anciennes versions de MediaWiki bénéficient des fonctions ajoutées récemment par l'extension.
• Branches de version : les branches de version de l'extension sont compatibles avec les branches correspondantes du noyau, c'est à dire que les sites qui utilisent MediaWiki 1.43 doivent utiliser la branche REL1_43 de l'extension. (pour les extensions qui se trouvent dans gerrit, ces branches sont créées automatiquement lorsque de nouvelles versions de MediaWiki sont diffusées). Le résultat est un code plus propre et un développement plus rapide, mais les utilisateurs qui travaillent avec les anciennes versions du noyau ne bénéficient pas des corrections de bogues ni des nouvelles fonctionnalités, sauf si elles ont été introduites manuellement a posteriori.

Les mainteneurs de l'extension doivent déclarer avec le paramètre compatibility policy du modèle {{Extension }} la convention suivie.

Fournir du support / collaborer

Les développeurs d'extensions doivent ouvrir un compte sur {Phabricator de Wikimedia, et demander un nouveau projet pour l'extension. Cela fournit un espace public où les utilisateurs pourront soumettre les problèmes et les suggestions, et vous pourrez collaborer avec les utilisateurs et les autres développeurs pour trier les bogues et planifier les fonctionnalités de votre extension.

Apprendre par l'exemple

• Extension:Examples – implémente quelques exemples de fonctionnalités avec une documentation en ligne complète
  • exemples de dépôt Git avec cela et d'autres exemples de code
• Extension:BoilerPlate – une extension Boilerplate fonctionnelle, utile comme point de départ pour votre propre extension (dépôt git).
  • Lisez l'extension Example et basez votre propre code sur l'extension BoilerPlate.
• cookiecutter-mediawiki-extension – modèle cookiecutter qui génère une extension standard (avec les variables, etc.)
  • Vous permet d'avancer rapidement avec votre propre extension.
  • Peut aussi générer l'extension BoilerPlate.
• Liste d'extensions simples – recopiez les parties de code spécifique