Open main menu

Manuel:Enregistrement d’extensions

This page is a translated version of the page Manual:Extension registration and the translation is 99% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎polski • ‎português • ‎português do Brasil • ‎русский • ‎中文 • ‎日本語
Version de MediaWiki : 1.25
Gerrit change 166705

L’enregistrement d’extensions est le 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 habillage et MediaWiki utilise ces données pour enregistrer les extensions et les habillages.

Avant la version 1.25 de MediaWiki, la configuration des extensions et des habillages était réalisée dans un fichier PHP portant le nom de l’extension ou de l’habillage, par exemple MonExtension.php ou MonHabillage.php.

require_once "$IP/extensions/Hello/Hello.php";
require_once "$IP/extensions/FooBar/FooBar.php";
$wgFooBarEnable = true;
require_once "$IP/skins/Baz/Baz.php";

Cela peut être converti en :

wfLoadExtensions( array( 'Hello', 'FooBar' ) );
$wgFooBarEnable = true;
wfLoadSkin( 'Baz' );

Si vous conservez vos extensions dans un endroit autre que $IP/extensions, vous devez modifier $wgExtensionDirectory. Si vos habillages ne sont pas situés dans le dossier $IP/skins, vous devez modifier la variable (mal nommée) $wgStyleDirectory. Cela doit être fait avant tout chargement d’extension ou d’habillage.

$wgExtensionDirectory = '/some/path';
wfLoadExtension( 'FooBar' ); // Looks for /some/path/FooBar/extension.json
$wgStyleDirectory = '/my/skins';
wfLoadSkins( array( 'BarBaz', 'BazBar' ) ); // Looks for /my/skins/BarBaz/skin.json and /my/skins/BazBar/skin.json

Depuis MediaWiki 1.30, les IDs des espaces de noms définis dans extension.json peuvent être remplacés localement, en définissant la constante respective dans LocalSettings.php avant de charger l'extension. Considerez par exemple la déclaration suivante d'espace de noms dans le fichier extension.json :

	"namespaces": [
		{
			"id": 1212,
			"constant": "NS_FOO",
			"name": "Foo"
		},
		{
			"id": 1213,
			"constant": "NS_FOO_TALK",
			"name": "Foo_Talk"
		}
	]

Par défaut, cela fera que la constante NS_FOO sera définie avec la valeur 1212. Néanmoins, ceci peut être modifié en définissant la constante respective dans LocalSettings.php :

define( 'NS_FOO', 6688 );
define( 'NS_FOO_TALK', 6689 );
wfLoadExtension( "Foo" );

Cela entraînerait l'enregistrement de l'espace de noms « Foo » avec l'ID 6688 au lieu de 1212. Lorsque vous redéfinissez des ID d'espaces de noms, n'oubliez pas que tous les espaces de noms de discussion doivent avoir des ID impairs et que l'ID de l'espace de noms de discussion doit toujours correspondre à l'ID du sujet + 1.

Migrer, pour les développeurs d’extensions

Voir aussi le mur d'enregistrement des extension de la tristesse (maintenant superpuissances).

Le script maintenance/convertExtensionToRegistration.php vous aide à migrer vos points d’entrée PHP en un fichier de métadonnées JSON. Si votre extension prend en charge d’anciennes versions de MediaWiki, vous pouvez garder votre point d’entrée PHP FooBar/FooBar.php jusqu’à ce que vous retiriez le support pour ces anciennes versions.

Exemple de lignes de commande :

$ cd core
$ php maintenance/convertExtensionToRegistration.php extensions/MassMessage/MassMessage.php
$ php maintenance/convertExtensionToRegistration.php skins/MonoBook/MonoBook.php --skin

Vous pourriez avoir besoin de désinstaller votre extension dans LocalSettings.php si vous avez des erreurs disant que des fonctions ou des constantes ne peuvent pas être redéfinies. Vous devriez remplacer votre fichier de point d’entrée PHP (FooBar.php) par quelque chose qui ne casse pas les wikis durant le processus de mise à jour.

<?php
if ( function_exists( 'wfLoadExtension' ) ) {
	wfLoadExtension( 'FooBar' );
	// Keep i18n globals so mergeMessageFileList.php doesn't break
	$wgMessagesDirs['FooBar'] = __DIR__ . '/i18n';
	$wgExtensionMessagesFiles['FooBarAlias'] = __DIR__ . '/FooBar.alias.php';
	wfWarn(
		'Deprecated PHP entry point used for the FooBar extension. ' .
		'Please use wfLoadExtension instead, ' .
		'see https://www.mediawiki.org/wiki/Extension_registration for more details.'
	);
	return;
} else {
	die( 'This version of the FooBar extension requires MediaWiki 1.29+' );
}

Ou, pour les habillages :

<?php
if ( function_exists( 'wfLoadSkin' ) ) {
	wfLoadSkin( 'FooBar' );
	// Keep i18n globals so mergeMessageFileList.php doesn't break
	$wgMessagesDirs['FooBar'] = __DIR__ . '/i18n';
	$wgExtensionMessagesFiles['FooBarAlias'] = __DIR__ . '/FooBar.alias.php';
	wfWarn(
		'Deprecated PHP entry point used for the FooBar skin. Please use wfLoadSkin instead, ' .
		'see https://www.mediawiki.org/wiki/Extension_registration for more details.'
	);
	return;
} else {
	die( 'This version of the FooBar skin requires MediaWiki 1.25+' );
}

Conserver la documentation

Les points d’entrée PHP contiennent généralement de la documentation pour les options de configuration, ce qui est utile et ne devrait pas être perdu. Malheureusement, le JSON ne permet pas d’inclure de commentaires. Il est recommandé de déplacer la documentation de la configuration dans un fichier README placé dans le dépôt de l'extension. Vous devriez aussi documenter votre extension sur ce wiki dans la page Extension:MonExtension. Il est en plus possible d’inclure un peu de documentation directement dans le fichier extension.json. Le système d’enregistrement des extensions ignore toutes les clés dans extension.json dont les noms commencent avec le caractère '@' dans la structure de niveau le plus global; vous pouvez ainsi insérer des commentaires à ces endroits du fichier JSON. Par exemple :

{
	"@note": "This file must be kept in sync with LocalisationUpdate.php",
	"@name": ...

La version 1 du format extension.json autorise aussi @note dans la section config, mais cela n'est plus recommandé ni pris en charge dans la version 2. Utilisez le champ description de la variable config à la place.

Ceci ne devrait être utilisé que pour les notes courtes et les commentaires.

Fonctionnalités

Si vous chargez un grand nombre d’extensions, l’enregistrement d’extensions permettra un gain de performance tant que APC (ou APCu) est installé. Les extensions qui sont chargées ensemble avec wfLoadExtensions (avec un suffixe -s marquant le pluriel) seront mises en cache ensemble.

Attributs

Un problème récurrent est la façon « d’enregistrer » quelque chose avec une autre extension. En général, cela signifie que vous avez à charger une extension avant l'autre. Par exemple, l’Editeur Visuel a un $wgVisualEditorPluginModules qui permet aux extensions d’ajouter leurs modules. Ainsi, dans le point d’entrée de l’Editeur Visuel, il y a :

$wgVisualEditorPluginModules = array();

Cela signifie que si une extension ajoute quelque chose au tableau avant que l’Editeur Visuel ne soit chargé, celui-ci effacera l’entrée dans ce tableau. Quelques extensions dépendent d’un ordre de chargement spécifique, d’autres bricolent autour de cela avec $wgExtensionFunctions. L’enregistrement d’extensions résoud ce problème avec les « attributs ». Dans l’extension Math, son extension.json aurait quelque chose comme :

{
	"VisualEditorPluginModules": [
		"ext.math.visualEditor"
	]
}

A partir de manifest version 2, les attributs doivent être définis dans la section séparée attributes.

Le noeud attributes doit être un objet avec le nom de l'extension comme clé et un objet de paires attribut/valeur pour 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
}

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.25.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

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 coeur soit opérationnelle. Par exemple : si l'extension B est chargée, l'extension A peut fournir un vrai éditeur WYSIWYG, sinon elle utilisera une simple zone de texte. L'extension A peut profiter de l'extension B (si elle est chargée), mais en n'a pas besoin pour être chargée et fonctionner correctement. Pour cela, vous vérifiez habituellement, si l'extension est chargée, plutôt que de l'ajouter comme une dépendance 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), l'enregistrement d'extension peut être utilisé. Il implémente une méthode isLoaded , qui retourne un 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' ) ) {
	// do things only, if extension B is loaded
}
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' ) ) {
	// do things only, if extension B is loaded and has a version of 1.2 or greater.
}

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 retourne 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', '>=' ) ) {
	// do things only, if extension B is loaded and has a version number greater than or equal to 2.1.0
}

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
	// do things only, if extension B is loaded
}

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' ) ) {
	// do things only, if extension B its classes exist
}

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": "The description for the configuration",
			"descriptionmsg": "myextension-config-myextsetting",
			"public": true
		}
	},
	"manifest_version": 2
}

Valeur

La valeur de la configuration a été déplacée à cet endroit. C'est la seule clé obligatoire pour un objet configuration.

Chemin

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). 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 !

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.

publique / privé

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 d'extension et que vos tests phpunit se trouvent dans le sous-répertoire tests/phpunit/ de votre extension, le conteneur phpunit de MediaWiki détectera automatiquement les tests unitaires à l'aide de l'enregistrement d'une extension. Par conséquent, vous n'avez plus besoin d'enregistrer l'accroche ni de spécifier que vos tests unitaires sont enregistrés dans le répertoire par défaut.

Personnaliser l’enregistrement

Quelques fois, les extensions ont besoin de faire des choses non-standard au cours de l’enregistrement ou font des choses très complexes. Vous pouvez spécifier une clé 'callback' dans votre extension.json si vous avez besoin d’exécuter du code PHP. La valeur doit pouvoir être appelable en PHP, comme par exemple FooBarHooks::onRegistration. ExtensionRegistry exécutera ce callback après avoir traité le fichier extension.json.

{
	"callback": "FooBarHooks::onRegistration"
}

Le callback n’est pas une fonction d'accroche classique, il est exécuté pendant les premières étapes de l’initialisation.

Consultez Manual:Extension registration/Limitations pour voir quels cas peuvent nécessiter un enregistrement spécialisé.

Voir les accroches ExtensionFunctions et SetupAfterCache, BeforeInitialize et ApiBeforeMain pour les autres manières d'interagir par programmation avec la configuration.

Et composer.json

Si une extension ou un habillage dépendent de bibliothèques, il peut exister également un fichier composer.json, voir Manual: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 nécessaire.

Quelques champs de métadonnées sont les mêmes entre extension.json et composer.json (discussion dans T89456), dont :

  • url et homepage
  • license-name et license

Voir aussi

References