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. Cette méthode est obsolète et les développeurs d’extensions ou d’habillages devrait commencer une transition vers le nouveau format.

Migrer, pour les administrateurs système
Auparavant, votre fichier LocalSettings.php aurait inclus quelque chose comme :

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.

Migrer, pour les développeurs d’extensions
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 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) en quelque chose qui ne casse pas les wikis durant le processus de mise à jour. Si vous avez besoin de garder la compatibilité pre-1.25, retirez la ligne die et conservez l’ancienne configuration en PHP.

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, qui est utile et ne devrait pas être perdue. 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. Vous devriez aussi documenter votre extension sur ce wiki dans la page Extension:MonExtension. Il est de plus possible d’inclure un peu de documentation dans le fichier  : le système d’enregistrement des extensions ignore les propriétés de   dont les noms commencent par le caractère   pour l’objet principal et l’objet   ; vous pouvez ainsi y insérer les commentaires. Par exemple :

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 :

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

Requirements (Dependencies)
Extension registration has a  section, which acts similar to composer's   section. It allows an extension developer to specify several requirements for the extension, such as a specific MediaWiki version (or greater/less than) or another extension (not implemented yet, see ). To, e.g., add a dependency of an extension to a MediaWiki version, that is greater than 1.26.0, you can add the following code to :

The key of the  object is the name of the dependency (currently only MediaWiki supported), the value is a valid version constraint (the format has to match the one used by composer).

As of, you can now also enter hard dependencies for skins and extensions like so:

Check, if an extension is loaded without actually require it
Many extensions may provide features that work only if another extension is loaded too, without really needing this feature for the core extension function to work. As an example: If extension B is loaded, extension A can provide a real WYSIWYG editor, otherwise it will use a simple textarea. Extension A can profit from extension B (if it is loaded), but doesn't require it to be loaded to work properly. For this, you generally check, if the extension is loaded, rather than adding it as a hard dependency.

To implement a standardized way of checking, if an extension is loaded or not (without the need of extra work in an extension that is a soft-dependency in another one), extension registration can be used. It implements an  method, which returns a simple boolean, if the extension is loaded or not (the extension needs to be loaded with extension registration for this to work). Example:

Alternatively, if the extension B defines a special constant meant for this purpose during loading, it is possible to check, if it is defined:

A more brittle way, that should be avoided is to check if a specific class of extension B exists or not, e.g. using this code:

This might break if the extension exists in the file system but is not loaded, e.g. if composer was used for autoloading. If the class was renamed or ceases to exist (e.g. because it is not package public) this will also break.

In general it is preferred to share code via composer components instead of extensions. If the classes of an extension only need to exist, but the extension does not need to be configured nor loaded, for what you want to do, that is a strong indicator that that code should be split off into a composer component you should depend on instead.

Configs (Your extension/skins settings)
By default, extension.json assumes that your config settings start with a "wg" prefix. If that's not the case, you can override the prefix by using a special key:

That would use a prefix of "eg", and set the global variable  to 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 mor edetailed. Instead of having a single key -> value store for your configuration options, you can also add the following information.

The general structure of the  changes slightly to the following, more object-oriented version:

Value
The value of the configuration moved to this place. This is the only required key for a configuration object.

Path
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 feature!

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.

Public / private
This option is a boolean, which defaults to false, which means, that the configuration option and the value is marked as "private". This value si not used anywhere at the moment, take a look to the outlook to find out more about this option.

Outlook
The mentioned changes above are also preparation steps for an improved configuration management in MediaWiki. The above changes allows 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.

Unit tests auto-discovery
MediaWiki allows any extension to register phpunit tests. Without extension registration, you would need to register a hook handler for the UnitTestsList hook, which would look something like: (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 wil 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</tt>.

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

Et composer.json
Si une extension ou un habillage dépend de bibliothèques, il peut y avoir également un fichier composer.json</tt>, voir les bonnes pratiques pour composer.json. Quelques champs de métadonnées sont les mêmes (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 : docs/extension.schema.v2.json</tt>. Un outil permet de générer de la documentation à partir de celui-ci.
 * RfC proposant l’implémentation d’un système d’enrgistrement des extensions.
 * Schéma pour  et skin.json : docs/extension.schema.v2.json</tt>. Un outil permet de générer de la documentation à partir de celui-ci.
 * RfC proposant l’implémentation d’un système d’enrgistrement des extensions.
 * RfC proposant l’implémentation d’un système d’enrgistrement des extensions.