MediaWiki/Guide/Configure/Extensions
A Guide to installing and configuring MediaWiki Extensions in a hosted environment
This article is part of a series compiled as a guide to encourage and assist those building a MediaWiki-based website in a hosted environment.
Each article links to relevant documentation from the MediaWiki.org website and the Wikimedia.org website. Where the official documentation does not adequately cover the issues for a hosted site, or is too 'advanced', additional information, explanation and advice is provided.
Overview
Extensions add features and functionality to MediaWiki.
Extensions must be downloaded and installed in the /w/extensions directory.
Therefore, to install an extension you should also be familiar with the File Transfer Protocol (FTP) and have FTP access to the root directory of your website.
Each extension must be registered by adding line(s) to LocalSettings.php.
Limitations in a hosted environment
Some MediaWiki Extensions are installed using Composer. This is generally not possible if your website is hosted because access to the command-line is required.
Changes in MediaWiki in versions 1.25+
Some extensions may not be compatible with the current version of MediaWiki. From version 1.25 there were changes to the way extensions were registered, and also a new schema using json files.
Check the extension compatibility before attempting to install it.
Installing an Extension
The basic steps involved are:-
- Locate and Download the Extension
- Search the MediaWiki site for extensions.They can be listed by Category.
- For a specific extension check the Release Status. If it is stable then continue; if it is beta you take a risk.
- Check the compatibility with your version of MediaWiki
- Follow the link to the download page. Save the file locally. The file format is generally .tar.gz. Leave that unchanged
- Extract the files
Use a utility like 7-zip to extract the files on a local computer and read the installation instructions, particularly the directory name and how to register it in LocalSettings.php. - Upload the files to the website
Use an FTP utility like Filezilla to transfer the extension's directory on your local computer to the /w/extensions directory on your website. - Backup LocalSettings.php
To register the extension or customize its' behavior it will be necessary to edit the LocalSettings.php file which is located in the /w directory in the website. Prior to making any changes, make a copy of LocalSettings.php so that you can undo changes or restore the previous configuration. - Register the Extension
Use your hosting interface to edit the LocalSettings.php file. Do not use Notepad. Add the lines required, as specified in the installation instructions or read.me file for the extension. Save the changes.
Check if the installation was successful
From your MediaWiki interface navigate to Special pages.
Under the heading Data and tools open the page titled Version.
If successful the extension will be listed in the section Installed extensions.
Troubleshooting
If the extension is not listed in Special Pages:Version or you get an error message then check for the following:-
- Is the extension directory in /w/extensions named correctly? Check for spelling and case - the software is case-sensitive.
- Is the extension registered in LocalSettings.php? Check for the correct command. The old syntax used require_once but more recently extension are registered with wfLoadExtension
- is the directory name and path correct? The path is where the extension is located. If MediaWiki is installed in /w and extensions are in the directory /w/extensions and you have added an extension Labeled Section Transclusion then the path is likely to be $IP/Extensions/LabeledSectionTransclusion. However, it would have been easy to type labelled instead of labeled, causing an error.
- If using require_once is the file name correct? Note that require_once statements include a .php file but wfLoadExtension does not.
If everything matches, and the extension is compatible with the MediaWiki version, then it should function as described.
If you cannot get it to work, then restore the LocalSettings.php file from the backup copy. MediaWiki should operate as before.
Disclaimer
The information or advice provided in this Guide is based on, or links to, official documentation for MediaWiki and was accurate when this article was created. However, some variation may occur between versions of MediaWiki; and the specifics of web hosting varies by service provider. Consequently, you should always create an effective backup before making any changes; ensure that you can restore your database and website; read the Release Notes before upgrading; and apply best practices to the management of your website. Any action that you take based on information provided here is at your own risk and the author accepts no liability for any loss or damage.
