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é  ou   dans le dossier racine de votre extension ou habillage et MediaWiki utilise ces données pour enregistrer les extensions et les habillages.

Migration for site administrators
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  ou.

Cela peut être converti en :

Si vous conservez vos extensions dans un endroit autre que, vous devez modifier. Si vos habillages ne sont pas situés dans le dossier, 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
Depuis MediaWiki 1.30, les IDs des espaces de noms définis dans  peuvent être remplacés localement, en définissant la constante respective dans   avant de charger l'extension. Consider for instance the following namespace declaration in a  file:

Par défaut, cela fera que la constante NS_FOO sera définie avec la valeur 1212. However, this can be overwritten by defining the respective constant in LocalSettings.php:

Cela entraînerait l'enregistrement de l'espace de noms « Foo » avec l'ID 6688 au lieu de 1212. When overriding namespace IDs, don't forget that all talk namespaces must have odd IDs, and the ID of the talk namespace must always be the subject namespace's ID plus one.


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

Le script  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  jusqu’à ce que vous retiriez le support pour ces anciennes versions.

Exemple de lignes 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) par 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 de 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 :

La version 1 du format  autorise aussi   dans la section , mais cela n'est plus recommandé ni pris en charge dans la version 2. Utilisez le champ  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  (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  qui permet aux extensions d’ajouter leurs modules. Ainsi, dans le point d’entrée de l’Editeur Visuel, il y a :

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. L’enregistrement d’extensions résoud ce problème avec les « attributs ». Dans l’extension Math, son  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’Editeur 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 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  :

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 :

In MediaWiki 1.33.0(?!??) and above you can also add dependencies on PHP like so:

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

Cela va utiliser le préfixe « eg » et mettre la variable globale  à 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é &rarr; valeur pour vos options de configuration, vous pouvez également ajouter les informations suivantes.

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
La valeur booléenne de la clé  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  et que   vaut true, la  valeur actuelle sera.

Description
La clé  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, 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 ( et  ) ainsi que l'indication si l'option de configuration peut être affichée ou pas  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, qui ressemblerait à ceci :

(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  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  si vous avez besoin d’exécuter du code PHP. La valeur doit pouvoir être appelable en PHP, comme par exemple. exécutera ce callback après avoir traité le fichier.

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

Consultez pour voir quels cas peuvent nécessiter un enregistrement spécialisé.

Voir les accroches et,  et  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 bogues dans le projet MediaWiki-Configuration.
 * Les anciennes versions de Manual:Developing extensions#Setup (avant mai 2015) et décrivent l’ancienne approche de déclaration des informations des extensions dans les variables et le code PHP
 * est le schéma pour  (et skin.json).
 * RfC à propos de l’implémentation d’un système d’enregistrement d'extensions
 * Mur d'enregistrement d'extensions de super pouvoirs ! — résumé des extensions qui doivent encore être converties.
 * T98668 — Ticket pour le suivi de la conversion de toutes les extensions et habillages sur Git afin qu'ils utilisent l'enregistrement d'extension.
 * RfC à propos de l’implémentation d’un système d’enregistrement d'extensions
 * Mur d'enregistrement d'extensions de super pouvoirs ! — résumé des extensions qui doivent encore être converties.
 * T98668 — Ticket pour le suivi de la conversion de toutes les extensions et habillages sur Git afin qu'ils utilisent l'enregistrement d'extension.