Manuel:Extensions/Installation et mise à jour

Une fois installé, MediaWiki est prêt à accepter les extensions. Pour ajouter une extension, suivez les étapes ci-après.

Avant de commencer

• Certaines extensions fournissent des instructions conçues pour l'installation en utilisant les commandes Unix. Vous avez besoin d'un accès au shell (SSH) pour entrer ces commandes listées sur les pages d'aide de l'extension.
• Cette page suppose que les paramètres de votre site sont dans le fichier LocalSettings.php, mais si vous avez un fichier différent, par exemple avec une ferme wiki, suivez les instructions en parallèle.

Télécharger une extension

Obtenir le paquet du fichier

Pour chaque extension, lisez la documentation pour savoir de où la télécharger et comment le faire. Les manières habituelles de télécharger les extensions sont les suivantes :

1. Le distributeur d'extensions vous aide à sélectionner et télécharger la plupart des extensions populaires, bien que tous les développeurs d'extensions ne le recommandent pas nécessairement.
2. Une liste des extensions stockées dans le dépôt Git de Wikimedia se trouve sur git:mediawiki/extensions.
3. Certaines extensions sont également disponibles par :
   1. paquets
   2. Composer , un gestionnaire de dépendances pour les bibliothèques PHP. De nombreuses extensions peuvent ou doivent être installées à l'aide de Composer. Voir Composer/For extensions pour plus d'information.
   3. dépôts pour les paquets
4. Certaines extensions n'utilisent pas de contrôle de version ; elles ne sont pas recommandées.

Ajouter le paquet dans le dossier /extensions

Les extensions sont généralement distribuées sous forme de paquets modulaires. Ils vont habituellement dans leur propre sous-répertoire de $IP /extensions/.

Vous pouvez ajouter le répertoire du fichier manuellement, ou le faire transférer automatiquement en utilisant un équivalent de Git ou de Composer.

Installer une extension

1. Vérifiez toujours les conditions et les instructions qui accompagnent chaque extension. Le résumé suivant s'applique à la plupart des extensions, mais de nombreuses extensions nécessitent des étapes différentes et / ou supplémentaires.
2. Vérifiez que les droits nécessaires sont établis.
3. À la fin du fichier LocalSettings.php , ajoutez :

   wfLoadExtension( 'ExtensionName' );
   

   Cette ligne oblige l'interpréteur PHP à lire le fichier d'extension, et ainsi le rendre accessible à MediaWiki. Pour une méthode d'installation plus ancienne qui utilise require_once et pour faire la migration, voir les instructions ci-dessous.
4. Configurez si nécessaire. Les paramètres de configuration doivent généralement être ajouté après avoir inclus l'extension. Une fois de plus, vérifiez les instructions de l'extension pour plus de détails.
5. Vous devrez peut-être exécuter un script de maintenance pour ajouter les tables nécessaires de base de données.
6. Voila c'est fait !

Problèmes possibles

• Certaines extensions peuvent entrer en conflit avec les scripts de maintenance, par exemple si elles accèdent directement à $_SERVER (non recommandé). Dans ce cas, elles peuvent être conditionnées afin que les scripts de maintenance puissent toujours être exécutés.

  if ( !$wgCommandLineMode ) {
  wfLoadExtension ( 'ExtensionName' );
  }
  

• Le script de maintenance importDump.php échouera pour toute extension qui nécessite des espaces de noms personnalisés inclus dans la condition ci-dessus comme Extension:Semantic MediaWiki , Extension:Page Forms .

Ajouter plusieurs extensions à wfLoadExtensions()

Surtout si vous avez un grand nombre d'extensions, il peut être utile de les ajouter en tant que tableau avec wfLoadExtensions() (avec -s pour le pluriel) au lieu de les ajouter par instances séparées de wfLoadExtension() (au singulier) Par exemple, pour installer Cite, ParserFunctions et SpamBlacklist, vous écrirez :

wfLoadExtensions( [ 'Cite', 'ParserFunctions', 'SpamBlacklist' ] );

Cette méthode a une limite, à savoir que vous ne pouvez pas indiquer des emplacements de fichiers personnalisés, comme expliqué dans cette section.

Mettre à jour une extension

Certaines extensions doivent être mises à jour chaque fois que vous mettez à jour MediaWiki, tandis que d'autres fonctionnent avec plusieurs versions.

Pour mettre à niveau une nouvelle version d'une extension :

1. Télécharger la nouvelle version de l'extension
2. Remplacez tous les fichiers d'extensions du répertoire extensions/<ExtensionName> par les nouveaux fichiers. Ne supprimez pas la configuration des extensions présentes dans LocalSettings.php
3. Si l'extension nécessite des modifications à la base de données MediaWiki, vous devrez exécuter le script de maintenance update.php . La plupart des extensions mentionneront si ce script doit être exécuté ou non. (Faites une sauvegarde de vos données avant d'exécuter le script). Si vous n'avez pas accès à la ligne de commande, vous pouvez aussi utiliser la mise à jour via le web.
4. La documentation de l'extension vous indique généralement ce que vous devez faire en plus.

Désinstaller

1. Pour désinstaller une extension, supprimez les lignes correspondantes de LocalSettings.php (wfLoadExtension avec le nom de l'extension ainsi que toutes les lignes possibles pour des paramètres de configuration associés).
2. Facultativement, vous pouvez supprimer le paquet dans le dossier /extensions.

Utilisation avancée

Utiliser des emplacements personnalisés

Ceci doit être fait avant de charger toute extension ou des habillages à partir des répertoires des sites non standard :

Si vous conservez vos extensions dans un endroit différent de $IP/extensions, vous devez redéfinir $wgExtensionDirectory ,ou utiliser le deuxième paramètre de wfLoadExtension(), pour spécifier le répertoire dans lequel se trouve l'extension.

Si une ou plusieurs de vos extensions sont stockées à d'autres endroits, utilisez le deuxième paramètre de wfLoadExtension() pour spécifier l'emplacement du fichier .json pour chacune de ces extensions.

wfLoadExtensions() (au pluriel) utilise toujours $wgExtensionDirectory et ne peut pas être redéfini.

$wgExtensionDirectory = '/some/path';
wfLoadExtension( 'FooBar' ); // Cherche /some/path/FooBar/extension.json dans $wgExtensionDirectory
wfLoadExtension( 'Hello', '/some/other/path/HelloV2/Hello.json' ); // Cherche /some/other/path/HelloV2/Hello.json

Si vos habillages ne sont pas dans $IP/skins, vous devez redéfinir le nom élémentaire de $wgStyleDirectory , ou utiliser le deuxième paramètre de wfLoadSkin(), pour identifier le répertoire dans lequel se trouve l'habillage.

Si un ou plusieurs de vos habillages sont stockés dans des endroits supplémentaires, utilisez le deuxième paramètre de wfLoadSkin() pour spécifier l'emplacement du fichier .json pour chacun de ces habillages.

wfLoadSkins() (plural) utilise toujours $wgStyleDirectory et ne peut être redéfini.

$wgStyleDirectory = '/my/skins';
wfLoadSkins( [ 'BarBaz', 'BazBar' ] ); // Cherche /my/skins/BarBaz/skin.json et /my/skins/BazBar/skin.json dans $wgStyleDirectory
wfLoadSkin( 'BamBam', '/yet/another/path/BamBam/skin.json' ); // Cherche /yet/another/path/BamBam/skin.json

Migration de require_once

Avant MediaWiki 1.25, la configuration des extensions et des habillages était effectuée dans un fichier PHP en utilisant le nom de l'extension ou de l'habillage, par exemple MyExtension.php ou MySkin.php. Pour installer une extension avec LocalSettings.php, vous utiliserez require_once pour appeler ce fichier PHP :

require_once "$IP/extensions/Hello/Hello.php";
require_once "$IP/extensions/FooBar/FooBar.php";
$wgFooBarEnable = true;
require_once "$IP/skins/Baz/Baz.php";
require_once "/tmp/extension/some/where/else/BarFoo/BarFoo.php";

Si les extensions sont suffisamment récentes pour supporter le système d'enregistrement actuel, convertissez ceci en :

wfLoadExtensions( [ 'Hello', 'FooBar' ] );
$wgFooBarEnable = true;
wfLoadSkin( 'Baz' );
wfLoadExtension( 'BarFoo', '/tmp/extension/some/where/else/BarFoo/extension.json' );