Manual:Extension.json/Schema/fr

Cette page documente le schéma utilisé par extension.json. Tous les champs sont optionnels sauf contre-indication. Il est actuellement incomplet.

Pour la première version de ce schéma voir (MW 1.25+), pour la seconde version voir  (MW 1.29+).

manifest_version
Ce champ est obligatoire.

Ceci spécifie la version du format de fichier extension.json qui sera utilisé. A l'avenir, si des modifications viennent à changer le format du fichier, ce nombre sera incrémenté pour continuer à prendre en charge les extensions qui utilisent l'ancien format.

Actuellement les valeurs suivantes sont acceptées :
 * : 1.25+
 * : 1.29+

v2 fournit des fonctionnalités de validation plus fortes pour le développeur, et elle est recommandée si votre extension nécessite déjà MediaWiki 1.29+. Il est recommandé de supprimer la compatibilité avec les anciennes versions, simplement pour forcer la mise à jour vers un nouveau manifest_version.

Actuellement de nouvelles fonctionnalités sont ajoutées dans v1 et v2, mais il a été demandé de geler v1 et de le rendre obsolète dans la version MediaWiki 1.38 (discussion sur Phabricator).

Exemple :

name
Ce champ est obligatoire.

Il s'agit du nom canonique de l'extension. Il ne doit pas être modifié une fois qu'il a été défini parce qu'il est utilisé comme API pour que les autres extensions puissent détecter qu'elle a été installée. Le champ  ne doit pas forcément correspondre au nom du répertoire d'une extension ni au nom de sa page dans l'espace de noms Extension de MediaWiki.org.

namemsg
Version traduite du nom de l'extension. Typiquement la clé du message est nommée selon le format &lt;name>-nomDeLextension ou &lt;name>-nomDeLhabillage.

type
Type de l'extension, sert à trier sur Special:Version. Les types suivants sont acceptés :
 * &mdash; extensions de l'API
 * &mdash; extensions anti-pourriel
 * &mdash; extensions qui modifient le contenu (depuis la 1.31, )
 * &mdash; gestionnaires de médias
 * &mdash; extensions qui modifient, ajoutent ou remplacent des fonctionnalités de l'analyseur syntaxique de MediaWiki.
 * &mdash; extensions qui modifient les habillages
 * &mdash; extensions qui ajoutent des pages spéciales
 * &mdash; crée une nouvelle variable
 * &mdash; fait autre chose

Vous pouvez ajouter des types personnalisés en utilisant l'accroche. Les valeurs connues comprennent : Si non initialisé, l'extension est affectée à la section other, et si la valeur assignée est non valide l'extension n'apparaîtra pas dans Special:Version.
 * &mdash; extensions Semantic MediaWiki
 * &mdash; extensions Wikibase

author
Auteurs de l'extension, peut contenir du texte wiki. Ceci peut être soit une chaîne unique, soit un tableau de chaînes. En plus, la chaîne spéciale  peut être utilisée pour ajouter un suffixe générique «  » en utilisant le message.

version
Version actuelle de l'extension. Doit être dans un format pris en charge par Composer.

url
URL de la page d'accueil de l'extension ou la documentation. Pointe typiquement vers.

description
Description de l'extension, peut contenir du wikicode. Il est recommandé d'utiliser descriptionmsg à la place.

descriptionmsg
Clé du message traduit correspondant à la description de l'extension, typiquement dans le format &lt;extensionname>-desc. Ceci prévaut sur description.

license-name
Identifiant de la licence SPDX (Software Package Data Exchange) du code source. Si vous créez un fichier  ou   (avec une extension facultative  ) dans le répertoire racine de l'extension avec le contenu de la licence, il sera aussi lié et visible de Special:Version.

requires
La section requires vous permet de documenter les dépendances sur les versions du noyau MediaWiki (1.26+) et des autres extensions (1.29+).

Vous pouvez utiliser tout format de version accepté par Composer. Pour MediaWiki, la meilleure méthode est de spécifier  pour la version minimale prise en charge, sauf si vous connaissez d'avance la version où cela ne sera plus vrai. Pour les extensions, si elles ne disposent pas d'un indicateur de version initialisé, ou si elles n'utilisent pas de système de gestion des versions, mettre une étoile  pour indiquer que toutes les versions sont acceptées.

Si votre extension utilise l'intégration continue de Wikimedia, vous devez aussi ajouter ses dépendances à dans le projet.

platform
Vous pouvez aussi exprimer la dépendance entre les paramètres d'une plateforme, elle est actuellement limitée aux versions et aux extensions PHP. Notez que la plupart des extensions sont supposées suivre les contraintes de version PHP pour les versions du noyau MediaWiki qu'elles supportent, et que vous ne pouvez spécifier de contrainte plus restrictive sur la version PHP que dans les cas exceptionnels. La vérification de la version des extensions PHP n'est pas encore prise en charge.

Dans cet exemple, l'extension nécessite la version 1.32 (qui demande PHP 7.0+), et ajoute clairement que la dépendance doit être faite avec une version PHP 7.1+ car elle nécessite certaines fonctionnalités plus récentes de PHP. De plus il faut que l'extension PHP curl soit installée.

suggests
Permet d'afficher la liste des dépendances suggérées mais pas celles qui sont nécessaires. Le format est identique à.

ResourceFileModulePaths
Chemins par défaut à utiliser pour tous les modules des fichiers ResourceLoader.

Les propriétés autorisées sont :
 * (must not point to other extension folders)
 * (must not point to other extension folders)

Il s'agit des mêmes options pour chacune des définitions de module de. Si une valeur n'est pas spécifiée dans la définition du module, c'est la valeur par défaut indiquée ici qui est utilisée.

SkinLessImportPaths
Chemin du répertoire d'import LESS propre à l'habillage, la clé étant le nom de cet habillage. Peut être utilisé pour définir les variables LESS propres à l'habillage.

QUnitTestModule
Module de fichier ResourceLoader à charger lors de l'exécution des tests unitaires JavaScript. A la même syntaxe que ResourceModules.

En interne, quand vaut , ce module est automatiquement enregistré sous le nom  .

MessagePosterModule
Permet aux extensions d'ajouter des fichiers supplémentaires ou des dépendances au paquet du module. A la même syntaxe que ResourceModules.

AuthManagerAutoConfig
Les propriétés suivantes sont disponibles :
 * &mdash; Fournisseurs de pré-authentification.
 * &mdash; Fournisseurs d'authentification primaire.
 * &mdash; Fournisseurs d'authentification secondaire.

namespaces
Méthode pour ajouter des espaces de noms supplémentaires.

Les propriétés suivantes sont disponibles :


 * &mdash; Nombre entier. Identifiant numérique de l'espace de noms, tel qu'il est utilisé dans la base de données. Depuis MediaWiki 1.30, les IDs des espaces de noms peuvent être remplacés localement, en définissant la constante respective dans LocalSettings.php avant de charger l'extension. C'est pourquoi le code des extensions doit toujours utiliser la constante de l'ID de l'espace de noms et jamais l'ID en tant que littéral dans le code PHP. Faites en sorte que le numéro utilisé pour votre ID figure dans l'espace de noms par défaut des extensions pour éviter les conflits avec les autres extensions.
 * &mdash; Chaîne de caractères. Nom de la constante utilisée par le code de l'extension quand il référence l'ID de l'espace de noms.
 * &mdash; Chaîne de caractères. Nom de l'espace de noms, tel qu'utilisé dans les titres.
 * &mdash; Objet Gender. Les propriétés sont soit  soit  . Voir la prise en charge du gendre.
 * &mdash; Booléen. La valeur par défaut est . Voir .
 * &mdash; Booléen. La valeur par défaut est . Voir .
 * &mdash; Chaîne de caractères. Voir .
 * &mdash; Droits utilisateur nécessaires pour modifier cet espace de noms. Tableau ou chaîne de caractères.
 * &mdash; Fixer $wgCapitalLinks avec une valeur qui est fonction de l'espace de noms. Booléen.
 * &mdash; Indique si l'espace de noms est conditionnel dans la configuration et ne doit pas être enregistré (nécessite un enregistrement séparé via une accroche telle que ). Booléen. La valeur par défaut est.
 * &mdash; Indique s'il est possible de renommer des pages dans cet espace de noms. Booléen. La valeur par défaut est.

ExtensionFunctions
Notez que les fonctions de l'extension ne peuvent pas être utilisées pour mettre à jour par programme les paramètres de configuration ou les accroches des registres. Dans ce but, remplacer par un appel à une fonction de rappel enregistrée.

MessagesDirs
Si vous utilisez la structure par défaut des répertoires avec les messages traduits dans le répertoire, vous pouvez écrire :

AutoloadClasses
Exemple :

AutoloadNamespaces
Tableau définissant la correspondance entre les espaces de noms et les répertoires sous une forme compatible PSR-4. Voici un exemple :

Dans ce cas, toutes les classes PHP appartiennent à l'espace de noms, et le nom de la classe correspond directement au fichier se trouvant dans le répertoire   (relativement au fichier extension.json). Notez que la portion de l'espace de noms doit se terminer par.

Les extensions qui utilisent cette fonctionnalité doivent mentionner MediaWiki 1.31 (au moins) dans le fichier  :

Pour l'exemple, voir la modification 468385 de Gerrit.

TestAutoloadClasses and TestAutoloadNamespaces
Les deux sont similaires à AutoloadClasses et AutoloadNamespaces, sauf qu'ils ne sont utilisés que lors des tests.

Pour l'exemple, voir la modification Gerrit 556240.

Hooks
Il est possible d'enregistrer plusieurs fonctions de rappel pour le même événement d'accroche :

HookHandlers
Spécifications de ObjectFactory pour les gestionnaires d'accroches nouveau style.

DeprecatedHooks
Accroches obsolètes (voir les Règles des interfaces stables). Déclare la correspondance entre le nom de l'accroche et un tableau avec la version obsolète de MediaWiki   et le composant    (optionnel, habituellement omis).

RestRoutes
Liste de spécifications de routes à ajouter à l'API REST. Voir API:REST API/Extensions.

SkinOOUIThemes
Correspondance des noms d'habillages et des thèmes OOUI à utiliser.

OOUIThemePaths
Correspondance entre les noms des thèmes personnalisés OOUI et les chemins correspondants permettant de les charger.


 * scripts
 * Chemin vers le fichier de script.


 * styles
 * Chemin vers les fichiers de style.  sera remplacé par le nom du module.


 * images
 * Chemin des fichiers de définition des images.  sera remplacé par le nom du module. Si les fichiers n'existent pas, les images du thème par défaut seront utilisées à la place.

ForeignResourceDirs
Répertoire contenant les ressources externes de l'extension (et le fichier  qui les définit). Exprimé relativement à la racine de l'extension.

callback
Quelques fois les extensions ont besoin de réaliser des opérations non standards pendant l'enregistrement, ou sont simplement très complexes. Vous pouvez indiquer une clé  dans votre extension.json si vous avez besoin d'exécuter du code PHP. La valeur doit être initialisée sur quelque chose que l'on peut appeler comme par exemple. ExtensionRegistry va exécuter ce rappel après qu'il ait traité le fichier extension.json et avoir fixé toutes les variables globales et les paramères de configuration. Ceci se produit après LocalSettings, où toutes les paramètres de configuration spécifiées utilisateur sont disponibles, mais certaines valeurs par défaut de MediaWiki peuvent ne pas être encore initialisées.

Deux paramètres sont fournis à la fonction de rappel, un tableau contenant les informations à propos de l'extension (un sous-ensemble de extension.json) et une instance de SettingsBuilder.

La procédure de rappel n'est pas une fonction d'accroche normale, elle s'exécute dans les initialisations précédentes. Voir les limites de l'enregistrement des extensions pour avoir une idée sur ce qui peut nécessiter un enregistrement.

$wgExtensionFunctions avec les accroches SetupAfterCache, BeforeInitialize et ApiBeforeMain fournissent d'autres manières d'interagir par programme avec la configuration.

config
La section config est l'endroit où vous pouvez définir les paramètres de configuration modifiables par les administrateurs système pour configurer l'extension. Cette section ne doit être utilisée que pour les éléments configurés dans LocalSettings.php - si elle doit être modifiée par d'autres extensions, vous devez utiliser les attributs, ou si ce ne sont que des métadonnées de classe, utilisez une variable statique privée ou un équivalent. Le format de config a été modifié dans manifest_version 2.

Manifest version 1
Exemple simple :

C'est équivalent à écrire  en PHP. Notez que le préfixe wg typique n'est pas inclus, car il sera ajouté par défaut. Si vos paramètres commencent avec un préfixe différent tel que, vous pouvez utiliser la clé magique   :

Maintenant c'est équivalent à écrire  en PHP.

Exemple plus complexe :

Le premier paramètre, a des clés qui sont des nombres, donc PHP va les transformer en entiers, même si ce sont des chaînes de caractères en JSON. Dû à la manière dont PHP traite les clés entières quand il fusionne les tableaux, nous devons utiliser un type différent de fusion ici; nous définissons un ensemble différent merge strategy en utilisant la clé magique. Dans le deuxième exemple, nous avons un tableau imbriqué qui nécessite un type différent de fusion, car nous voulons autoriser les utilisateurs à continuer à écrire  dans leur LocalSettings.php.



Modifications dans Manifest version 2
Avec MediaWiki 1.29, un nouveau manifest_version (2) a été introduit. Dans cette version, la section config est amériorée de diverses manières. Pour prendre en charge ces modifications, la signature d'un ensemble d'options de configuration avec leur valeurs a un peu changé. La clé de l'objet config est encore le nom du paramètre; néanmoins la valeur de cette clé est un objet, décrivant cette option de configuration, où l'une des valeurs est sa valeur. Sur la page de documentation de l'enregistrement des extensions vous trouverez les informations concernant les clés spécifiques (avec les valeurs) des options de configuration. Un exemple facile dans le nouveau schéma, qui est simplement une option de configuration avec sa valeur, ressemblerait à :

Un exemple plus complexe serait :

path
Comme montré dans l'exemple ci-dessus, vous pouvez définir une option de configuration ayant la clé. Lorsqu'il vaut, la valeur du paramètre sera interprétée comme étant le chemin local de l'extension. Par exemple une extension peut définir ses paramètres par : La valeur de l'option de configuration Setting sera résolue avec.

merge strategy
La stratégie de fusion définit la manière de fusionner la valeur par défaut du paramètre de configuration avec la valeur globale (valeur de la variable globale ). Cela n'a de sens que si les paramètres de configuration sont des tableaux de valeurs. Les stratégies de fusion suivantes sont disponibles : Lorsqu'elle n'est pas définie explicitement, la stratégie de fusion par défaut est. Lorsqu'au moins une des valeurs globales ainsi que la valeur par défaut ne sont pas des tableaux, la stratégie de fusion est ignorée et la valeur globale va simplement remplacer la valeur par défaut.
 * &mdash; Utilise la commande PHP  : les éléments de tableaux avec des clés numériques seront interprétés comme des éléments de liste non associatifs et seront concaténés au tableau (en renumérotant les clés si nécessaire), les éléments de tableaux avec des clés non numériques seront interprétés comme les éléments d'un tableau associatif et réécrits avec la même clé.
 * &mdash; Utilise l'opérateur PHP, donc les champs de la valeur par défaut ne seront utilisés que si le champ correspondant de la valeur globale n'est pas initialisé. C'est intéressant pour les tableaux associatifs dont les clés sont des entiers (comme les IDs des espaces de noms).
 * &mdash; Utilise  pour gérer proprement les tableaux imbriqués jusqu'à une profondeur de 2 (par exemple ).
 * &mdash; Gère les tableaux, même de profondeur supérieur supérieure à 2 avec . Etant donné le comportement de cette méthode qui est loin d'être intuitif (exemple), cette stratégie n'est pas recommandée. Un paramètre de configuration d'une profondeur supérieure à 2 obligerait à configurer trop d'éléments dans un passage, et le découper en plusieurs initialisations élémentaires serait une bonne idée.
 * &mdash; Utilise, principalement la version récursive de  . A la différence de  , ceci gère comme on le souhaite les champs qui ne sont pas des tableaux.
 * (depuis la MW 1.35.3) &mdash; sans fusion; la valeur par défaut ne sera utilisée que si la valeur globale n'est pas fixée.

config_prefix
Prefixe à insérer devant les paramètres de configuration lors de l'export vers.

La valeur par défaut est, et une valeur de paramètre correspond à une variable globale PHP. Notez que si vous choisissez un préfixe de paramètre différent il pourra être plus difficile de retrouver le paramètre de l'extension correspondant à la variable globale concernée.

ParsoidModules
Liste de spécifieurs de modules de l'extension Parsoid. Un module d'extension Parsoid est une classe qui implémente ; un spécifieur est un nom de classe ou une spécification de ou encore une spécification de module dédié Parsoid.

attributes
Informations d'enregistrement pour les autres extensions. Cela permet à une extension d'enregistrer des éléments en rapport avec d'autres extensions. Les valeurs des attributs doivent être des tableaux JSON ou des objets, et ils seront fusionnés quand ils seront récupérés dans PHP.

Dans manifest_version 1 il s'agissait des clés de premier niveau que vous pouviez nommer arbitrairement :

Dans manifest_version 2, elles figurent sous la clé  de premier niveau, et sont imbriquées sous le nom de l'extension à laquelle l'attribut appartient. Le nom complet de l'attribut est la concaténation du nom de l'extension et du nom de l'attribut ( dans l'exemple ci-dessous). Si cette extension (EventLogging dans notre cas) n'est pas installée, les attributs ne seront pas chargés dans le registre.

Pour accéder à la valeur d'un attribut en PHP, vous pouvez utiliser ExtensionRegistry :

load_composer_autoloader
Charger le chargeur automatique de composer pour cette extension, s'il en existe un. Ceci doit être utilisé si l'extension a des dépendances sur les bibliothèques spécifiées dans. Ce qui équivaut en gros au code suivant :