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

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
List of route specifications to be added to the REST API. See API:REST API/Extensions.

SkinOOUIThemes
Map of skin names to OOUI themes to use.

OOUIThemePaths
Map of custom OOUI theme names to paths to load them from.


 * scripts
 * Path to script file.


 * styles
 * Path to style files.  will be replaced with the module's name.


 * images
 * Path to image definition files.  will be replaced with the module's name. If the files don't exist, default theme's images will be used instead.

callback
Sometimes extensions need to do non-standard things during registration, or are just very complex. You can specify a  key in your extension.json if you need to execute some PHP code. The value should be set to a valid PHP callable, for example:. ExtensionRegistry will execute this callback after it processes the extension.json file and sets all the other globals and configuration settings. This happens after LocalSettings, so all user-specified configuration is available, but some defaults set by MediaWiki might not have been initialized yet.

The callback is provided with two parameters, an array containing information about the extension (a subset of extension.json) and an instance of SettingsBuilder.

The callback isn't a normal hook function, it runs in early initialization. See Manual:Extension registration/Limitations for what sort of things may require custom registration.

Manual:$wgExtensionFunctions and the SetupAfterCache, BeforeInitialize and ApiBeforeMain hooks provide other ways of programmatically interacting with configuration.

config
The config section is where you can define configuration settings that sysadmins can change to configure the extension. This section should only be used for things that are configured in LocalSettings.php - if it is supposed to be modified by other extensions, you should use attributes, or if it is just class metadata, use a private static variable or something like that. The format of config changed in manifest_version 2.

Manifest version 1
A simple example:

This is equivalent to writing  in PHP. Note that the typical "wg" prefix is not included, as that will be added by default. If your settings start with a different prefix like, you can use the magic   key:

This is now equivalent to writing  in PHP.

A more complex example:

The first setting,, has keys that are numbers, so PHP will turn them into integers, even though they are strings in JSON. Because of how PHP treats integer keys when merging arrays, we need to use a different type of merge here, so we set a different "merge strategy" using the magic key. In the second example, we have a nested array, which requires a different type of merging, since we want to allow people to continue writing  in their LocalSettings.php.

Changes in manifest version 2
With MediaWiki 1.29, a new manifest_version (2) was introduced. In this version, the config section is improved in several ways. To support these changes, the signature of a set of configuration option and configuration value changed a bit. The key of the config object is still the configuration name; however, the value of that key is an object, which describes this configuration option, where one of the values is the value. You can find information about what the specific keys and values for a configuration option are on the extension registration documentation page. An easy example of the new schema, which simply is one configuration option and its value, would look like:

A more complex one would look like:

Paths
As demonstrated in the example above, a configuration option can have the  key defined. When present and set to, the value of the setting will be interpreted as a path local to the extension. For example, an extension might define its configuration as The value for the configuration option "Setting" will be resolved to.

Merge strategies
The merge strategy defines how to merge the default value of the configuration setting with the global value (the value of the  global variable). This only makes sense for array-valued configuration settings. The following merge strategies are available: When not explicitly set, the merge strategy defaults to. When at least one of the global value and the default is not an array, the merge strategy is ignored and the global value will simply override the default.
 * : Uses the   PHP command: array elements with numeric keys will be interpreted as non-associative list items and concatenated to the array (with the keys renumbered if needed), array elements with non-numeric keys will be interpreted as hashmap items and overwrite items with the same key.
 * : Uses the  PHP operator, so fields of the default value will only be used when the corresponding field is not set in the global value. This is useful for associative arrays with integer keys (such as namespace IDs).
 * : Uses  to handles nested arrays to a depth of 2 properly (e.g. ).
 * : Handles arrays even deeper than 2 with . Given the unintuitive behavior of this method (example), this strategy is not recommended. A configuration setting that is more than 2 levels deep suggests too many things are being configured in one setting, and splitting it into multiple settings might be a good idea.
 * : Uses , basically the recursive version of  . Unlike  , this will handle non-array fields the way one would expect.
 * (since MW 1.35.3): no merging; the default will only be used when no global value is set.

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 :