Manual/Extensions

<translate> An extension lets you customise how MediaWiki looks and works. </translate>

<translate> System administrators can [[<tvar name=1>#Installing an extension</tvar>|install]] (or remove) extensions on the MediaWiki installations that they manage.</translate>
<translate> Developers can [[<tvar name=1>#Developing extensions</tvar>|write new extensions]] or contribute to existing extensions.</translate>

Selecting extensions[edit]

Bundled extensions[edit]

Several extensions are as standard. </translate>

<translate> These extensions should generally be of high utility, perform efficiently, be stable, be well-written, and have no known major security issues.</translate> <translate> They should also be compatible with the latest versions of MediaWiki, and with each other (i.e. one extension shouldn't block the functions of another).</translate> <translate> A bundled extension may have a dependency on one or more other extensions, as long as those are also bundled.</translate>

<translate> Site admins get these automatically when installing or upgrading MediaWiki.</translate> <translate> When upgrading MediaWiki, any extension upgrades will be automatically applied as well.</translate> <translate> Site admins may choose to uninstall any of these, if they wish.</translate>

<translate> There are open, ongoing discussions about which extensions should be part of this group.</translate> <translate> You can .</translate> <translate> Extensions will be bundled once the developers reach a consensus to do so.</translate>

<translate> An extension may be removed from bundling if its functionality is merged into , it is replaced by an alternative, or in the unlikely event of any unsolvable major security vulnerabilities being discovered.

Browsing extensions[edit]

Browse <tvar name=1></tvar>, or <tvar name=2></tvar> to see the full range of extensions that are available.

Checking installed extensions[edit]

</translate> <translate> Which extensions are active on an instance of MediaWiki can be checked by accessing the <tvar name=1>Special:Version</tvar> page, and scrolling down to the heading Installed extensions (anchor <tvar name=2>#mw-version-ext</tvar>).</translate> <translate> For example, [[<tvar name=1>Special:Version#mw-version-ext</tvar>|these extensions]] are installed on this wiki, and [[<tvar name=2>W:Special:Version#mw-version-ext</tvar>|these extensions]] are active in the English Wikipedia.</translate>

Popular extensions[edit]

</translate> <translate> <tvar name="1"></tvar> counts wikis that extensions are installed on.</translate> <translate> This represents actual installations and not just downloads (i.e. it queries the wiki's APIs), but it is also (as of 2023) not completely up-to-date.</translate> <translate> It also doesn't count installations on private wikis.</translate>

Installing an extension[edit]

</translate>

<translate> For further guidance, see also <tvar name=1></tvar></translate>

<translate> MediaWiki is ready to accept extensions just after [[<tvar name=man>Special:MyLanguage/Manual:Installation</tvar>|installation]] is finished.</translate> <translate> To add an extension follow these steps:</translate>

<translate> Before you start</translate>
<translate> Many extensions provide instructions designed for installation using Unix commands.</translate> <translate> You require shell access (SSH) to enter these commands listed on the extension help pages.</translate>
<translate> Download your extension</translate>
<translate> [[<tvar name=special>Special:ExtensionDistributor</tvar>|Extension Distributor]] helps you to select and download most of the popular extensions.</translate>

<translate> Extensions are usually distributed as modular packages.</translate> <translate> They generally go in their own subdirectory of <tvar name=IP>/extensions/</tvar>.</translate> <translate> A list of extensions stored in the Wikimedia [[<tvar name=gerrit>Special:MyLanguage/Gerrit</tvar>|Git repository]] is located at <tvar name=extensions>git:mediawiki/extensions</tvar>.</translate> <translate> Some extensions [[<tvar name=cat>Special:MyLanguage/Category:Extensions which host their code in-wiki</tvar>|don't use version control]] and are not recommended.</translate>

<translate> Some extensions are also available in [[<tvar name=1>Special:MyLanguage/Software bundles</tvar>|bundles]], <tvar name=composer></tvar> or [[<tvar name=2>Special:MyLanguage/Comparison of extensions in distributions</tvar>|package repositories]].</translate>

<translate> It's recommended to read the <tvar name=1>README</tvar> file before installation.</translate> <translate> It usually contains important info about configuration.</translate>
<translate> Install your extension</translate>
<translate> At the end of the <tvar name=LocalSettings></tvar> file, add:</translate>

<syntaxhighlight lang="php">

wfLoadExtension( 'ExtensionName' ); </syntaxhighlight>

<translate> This line forces the PHP interpreter to read the extension file, and thereby make it accessible to MediaWiki.</translate>

<translate> Some extensions can conflict with maintenance scripts, for example if they directly access <tvar name=1>$_SERVER</tvar> (not recommended).</translate> <translate> In this case, they can be wrapped in the conditional so maintenance scripts can still run.</translate>

<syntaxhighlight lang="php">

if ( !$wgCommandLineMode ) {

  wfLoadExtension ( 'ExtensionName' );

} </syntaxhighlight>

<translate> The maintenance script <tvar name=ImportDump></tvar> will fail for any extension which requires customised namespaces which is included inside the conditional above such as <tvar name=1></tvar>, <tvar name=2></tvar>.</translate>

Template:Note

Upgrading an extension[edit]

</translate> <translate> Some extensions require to be updated whenever you update MediaWiki, while others work with multiple versions.</translate> <translate> To upgrade to a new version of an extension:</translate>

<translate> Download the new version of the extension</translate>
<translate> Replace all the extension files in the <tvar name=1>extensions/ExtensionName</tvar> directory with the new files.</translate> <translate> Do not remove the extension configuration present in <tvar name=1>LocalSettings.php</tvar></translate>
<translate> If the extension requires changes to the MediaWiki database, you will need to run the <tvar name=1></tvar> maintenance script.</translate> <translate> Most extensions will mention if this script needs to be run or not.</translate> <translate> (Perform backup of your data before executing the script).</translate> <translate> If you don't have command line access, you can also use the [[<tvar name=man>Special:MyLanguage/Manual:Upgrading#Web_updater</tvar>|web updater]].</translate>

Template:Note

Uninstalling an extension[edit]

Remove the line from <tvar name=1>LocalSettings.php</tvar> with the extension name to uninstall it: </translate>

<syntaxhighlight lang="php"> wfLoadExtension( 'ExtensionName' ); </syntaxhighlight>

You must also remove any lines pertaining to the configuration of the extension.

Developing extensions[edit]

</translate> <translate> MediaWiki core provides several ways for extensions to change the behavior and appearance of a wiki.</translate> <translate> Various give extensions flexibility to add features and functionality, such as displaying a special page or defining an API module.</translate> <translate> To get started, see the .</translate> <translate> Before writing a new extension, consider contributing to an or helping with an .</translate>

<translate> Users can also make a general request on Phabricator, and hope that your good idea is picked up by a developer.</translate> <translate> See <tvar name=1>https://phabricator.wikimedia.org/tag/mediawiki-extension-requests/</tvar></translate>