View source for Manual:Extensions/Installation and upgrade/en

<languages/>
[[Special:MyLanguage/Manual:Installation|Once installed]], MediaWiki is ready to accept [[Special:MyLanguage/Manual:Extensions|extensions]].
To add an extension follow these steps:

==Before you start==

* Some extensions provide instructions designed for installation using Unix commands. You require shell access (SSH) to enter these commands listed on the extension help pages.
* This page assumes your site settings are in a file called [[Special:MyLanguage/Manual:LocalSettings.php|LocalSettings.php]], but if you ase a different file, for instance in a wiki farm, the instructions should be equally relevant.

==Download an extension==

===Get the file package===

For each extension, read its documentation to find out about the appropriate download locations and methods.
Common ways of downloading extensions include:

# [[Special:ExtensionDistributor|Extension Distributor]] helps you to select and download most of the popular extensions, although not all extension developers necessarily recommend it.
# A list of extensions stored in the Wikimedia {{ll|Gerrit|Git repository}} is located at [[phab:diffusion/MEXT/browse/master/|git:mediawiki/extensions]].
# Some extensions are also available through:
## {{ll|Software bundles|2=bundles}}
## {{ll|Composer}}, a dependency manager for PHP libraries. Many extensions can or should be installed using Composer. Proceed to {{ll|Composer/For extensions}} for more information.
## {{ll|Comparison of extensions in distributions|2=package repositories}}
# Some extensions {{ll|Category:Extensions which host their code in-wiki|don't use version control}} and are not recommended.

===Add the package to the <code>/extensions</code> folder===
Extensions are usually distributed as modular packages.
They generally go in their own subdirectory of <code>{{ll|Manual:$IP|$IP}}/extensions/</code>.

You can add the file folder manually or have it transferred automatically if you use something like Git or Composer.

==Install an extension==
# Always check the requirements and instructions that come with each extension. The following summary applies to most extensions, but many extensions require different and/or additional steps to be taken.
# Ensure that required permissions are set.
# At the end of the <code>{{ll|Manual:LocalSettings.php|LocalSettings.php}}</code> file, add:<!--
--><syntaxhighlight lang="php">
wfLoadExtension( 'ExtensionName' );
</syntaxhighlight><!--

-->This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki. For an earlier installation method using <code>require_once</code> and how to migrate, see the instructions below.
# Configure if required or wanted. {{ll|Manual:Configuration settings|Configuration settings}} should typically be added '''after''' including the extension. Again, check the extension's instructions for details.
# You may be required to run a [[Special:MyLanguage/maintenance script|maintenance script]], for instance to add the necessary database tables.
# Done!

===Possible issues===
* Some extensions can conflict with maintenance scripts, for example if they directly access $_SERVER (not recommended). In this case they can be wrapped in the conditional so maintenance scripts can still run.<!--
--><syntaxhighlight lang="php">
if ( !$wgCommandLineMode ) {
wfLoadExtension ( 'ExtensionName' );
}
</syntaxhighlight>
* The maintenance script {{ll|Manual:ImportDump.php|importDump.php}} will fail for any extension which requires customised namespaces which is ''included'' inside the conditional above such as {{ll|Extension:Semantic MediaWiki}}, {{ll|Extension:Page Forms}}.

=== Add multiple extensions to <code>wfLoadExtensions()</code> ===
Especially if you have a large number of extensions, it may be useful to add them as an array to <code>wfLoadExtensions()</code> (with plural -s) instead of adding them to separate instances of <code>wfLoadExtension()</code> (singular).
For instance, to install Cite, ParserFunctions and SpamBlacklist, you could write:

<pre>wfLoadExtensions( [ 'Cite', 'ParserFunctions', 'SpamBlacklist' ] );</pre>

This method comes with one limitation, which is that you cannot point to custom file locations, as explained in [[#Use custom locations|this section]].

==Upgrade an extension==

Some extensions require to be updated whenever you update MediaWiki, while others work with multiple versions.

To upgrade to a new version of an extension:

# Download the new version of the extension
# Replace all the extension files in the <code>extensions/&lt;ExtensionName></code> directory with the new files. Do not remove the extension configuration present in LocalSettings.php
# If the extension requires changes to the MediaWiki database, you will need to run the {{ll|Manual:update.php|update.php}} maintenance script. Most extensions will mention if this script needs to be run or not. (Perform backup of your data before executing the script). If you don't have command line access, you can also use the [[Special:MyLanguage/Manual:Upgrading#Web_updater|web updater]].
# Documentation for an extension usually tells you what else you need to do.

== Uninstall ==

# To uninstall the extension, remove the relevant lines from LocalSettings.php (<code>wfLoadExtension</code> with the extension's name as well as any possible lines for associated configuration settings).
# Optionally, delete the file package from the /extensions folder.

==Advanced==

=== Use custom locations ===

This must be done before you load any extensions or skins from non-standard directory locations:

: If you keep your extensions in a location different from {{phpi|$IP/extensions}}, you need to override {{wg|ExtensionDirectory}}, ''or use the second parameter of <code>wfLoadExtension()</code>'', to specify the directory in which to find the extension.
:: If one or more of your extensions are stored in additional locations, use the second parameter of <code>wfLoadExtension()</code> to specify the location of the <code>.json</code> file for ''each'' of those extensions.
:: {{note|1=<code>wfLoadExtensions()</code> '''(plural)''' always uses {{wg|ExtensionDirectory}} and cannot be overridden.}}

:<syntaxhighlight lang="php">
$wgExtensionDirectory = '/some/path';
wfLoadExtension( 'FooBar' ); // Looks in $wgExtensionDirectory for /some/path/FooBar/extension.json
wfLoadExtension( 'Hello', '/some/other/path/HelloV2/Hello.json' ); // Looks for /some/other/path/HelloV2/Hello.json
</syntaxhighlight>

: If your skins are not in {{phpi|$IP/skins}}, you need to override the poorly named {{wg|StyleDirectory}}, ''or use the second parameter of <code>wfLoadSkin()</code>'', to specify the directory in which to find the skin.
:: If one or more of your skins are stored in additional locations, use the second parameter of <code>wfLoadSkin()</code> to specify the location of the <code>.json</code> file for ''each'' of those skins.
:: {{note|1=<code>wfLoadSkins()</code> '''(plural)''' always uses {{wg|StyleDirectory}} and cannot be overridden.}}

:<syntaxhighlight lang="php">
$wgStyleDirectory = '/my/skins';
wfLoadSkins( [ 'BarBaz', 'BazBar' ] ); // Looks in $wgStyleDirectory for both /my/skins/BarBaz/skin.json and /my/skins/BazBar/skin.json
wfLoadSkin( 'BamBam', '/yet/another/path/BamBam/skin.json' ); // Looks for /yet/another/path/BamBam/skin.json
</syntaxhighlight>

== Migrate from require_once==

Before MediaWiki 1.25, configuration for extensions and skins was done in a PHP file using the extension's or skin's name, for example <code>MyExtension.php</code> or <code>MySkin.php</code>. To install an extension with LocalSettings.php, you would use <code>require_once</code> to call this PHP file:

<syntaxhighlight lang="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";
</syntaxhighlight>

If the extensions are recent enough to support the current registration system, you would convert this to:

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

{{Extensions}}

[[Category:MediaWiki administration]]
[[Category:Extensions]]
[[Category:Customization techniques{{#translation:}}|{{PAGENAME}}]]