Manual:Extension registration/fr

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é  (respectivement  ) placé dans le dossier racine de votre extension (resp. 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 en PHP dans un fichier portant le nom de l’extension ou de l’habillage, par exemple  ou.

Cela peut être converti en :

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

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

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 : 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 plus un.

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

Exemples de ligne de commande :

Vous pourriez avoir besoin de désinstaller votre extension dans  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) en quelque chose qui ne casse pas les wikis durant le processus de mise à jour.

Ou, pour les habillages :

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 des commentaires. Il est recommandé de déplacer la documentation de la configuration dans un fichier  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. Le système d’enregistrement des extensions ignore toutes les clés dans  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 :

Version 1 of the  format also allowed   in   section, but this is no longer recommended or supported in version 2. field of the config variable should be used instead.

Cette méthode devrait être réservée à de brefs commentaires.

Fonctionnalités
Si vous chargez un grand nombre d’extensions, l’enregistrement d’extensions permettra un gain de performance si vous avez installé APC (ou APCu). Les extensions qui sont chargées ensemble avec  (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 extension. En général, cela signifie que vous avez à charger une extension avant une autre. Par exemple, l’éditeur visuel a  qui permet aux extensions d’ajouter leurs modules. Ainsi, dans le point d’entrée de l’éditeur visuel, il y a :

Cela signifie que si une extension ajoute quelque chose au tableau avant que l’éditeur visuel 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 quelque chose avec. L’enregistrement d’extensions résoud ce problème avec les « attributs ». Dans l’extension Math, son extension.json aurait quelque chose comme :

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

Le noeud  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 !

Quand l’éditeur visuel veut accéder à cet attribut, il utilise :

Prérequis (dépendances)
L'enregistrement d'extension possède une section, qui agit de manière similaire à la section   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/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  :

La clé de l'objet  est le nom de la dépendance (avant MediaWiki 1.29.0 seulement   é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 :

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 travail 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 , 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:

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 :

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 , qui retourne l'information de crédit pour toutes les extensions chargées. Exemple:

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 :

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 :

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é pout 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,  suppose que vos paramètres de configuration commencent avec un préfixe « wg ».

Si ce n'est pas le cas, vous pouvez réécraser le préfixe en utilisant une clé spéciale :

Cela va utiliser le préfixe « eg » et mettre la variable globale  à true.

Starting with manifest version 2, the configuration section of extension registration provides a lot more features and allows you to describe your configuration options much more detailed. Instead of having a single key -> value store for your configuration options, you can also add the following information.

La structure générale de la  change légèrement par la suite, en devenant une version plus orientée objet :

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

Chemin
The boolean value of the  key identifies, if the value of the configuration option should be interpreted as a filesystem path, relative to the extension directory root. E.g., if the value of the configuration is  and the   is true, the actual value will be.

Description
The  key for a configuration option can hold a non-localized string, which can be used to explain the configuration option to other developers or the users (system administrators) of your extension. The value of the description key is usually not exposed to the frontend of the wiki, however, take a look to the outlook for more information how this feature could be used in the future!

There's also the possibility to add a message key of MediaWiki's internal localisation system as a description, which, in the future, will be used to expose the description in the frontend of the MediaWiki installation.

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
The mentioned changes above are also preparation steps for an improved configuration management in MediaWiki. The above changes allow us to, e.g., expose the configuration options of extensions in the MediaWiki UI. For this, the localised description message ( and  ) and the indication, if the configuration option should be exposed or not  is needed.

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, qui ressemblerait à ceci :

(as described on the manual page). However, this code looks the same for a lot of extensions, so you could call it unnecessary code duplication. If your extension uses extension registration and your phpunit tests are located in the  subdirectory of your extension, the phpunit wrapper of MediaWiki will autodiscover the unit tests with the help of extension registration. Therefore, you don't need to register the hook anymore and you don't need to specify, that your unit tests are saved in the default directory.

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 devrait pouvoir être appelé en PHP, comme. exécutera ce callback après qu’il ait traité le fichier extension.json.

Ce callback n’est pas un hook classique, il est exécuté pendant les premières étapes de l’initialisation.

Consultez pour voir quels cas peuvent nécessiter un tel 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, voir. Utilisez le champ  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  et   (discussion dans T89456), dont :
 * et
 * et

Voir aussi

 * Rapportez les bugs dans le projet MediaWiki-Configuration.
 * Les anciennes version de Manual:Developing extensions (avant mai 2015) et décrivent l’ancienne approche de déclaration des informations des extensions dans les variables et le code PHP
 * Schéma pour  et skin.json :.
 * RfC proposant l’implémentation d’un système d’enrgistrement des extensions.
 * Extension registration wall of superpowers! — summary of which extensions are still to be converted.
 * T98668 — Tracking ticket for converting all extensions and skins on Git to use extension registration.
 * RfC proposant l’implémentation d’un système d’enrgistrement des extensions.
 * Extension registration wall of superpowers! — summary of which extensions are still to be converted.
 * T98668 — Tracking ticket for converting all extensions and skins on Git to use extension registration.