Installing MediaWiki Extensions with Composer


Last updated on 2024-04-02. Written by Jeroen De Dauw


Nowadays many MediaWiki extensions can or should be installed via Composer. While this simplifies things once you know how it works, it also adds to the learning curve. This post covers the basics you need to know plus some tips that might be news to long time users.

This living article contains to the point and up-to-date instructions and is more comprehensive than the instructions specific to any extension. It is also a more understandable alternative to the instructions on MediaWiki.org.

What is Composer

Composer is tool for installing PHP packages. It can be used to install MediaWiki extensions and any PHP libraries required by those extensions. Composer also allows easy upgrading of extensions installed with it.

Modern versions of MediaWiki (1.25+) require using Composer during installation. So you most likely already have Composer installed. In that case you can skip the next section. If you are using an older version of MediaWiki or do not have console access then the instructions on this page won't work for you.

Installing composer

These instructions assume you have already set up MediaWiki and are using Linux. If you are using another operating system then installation of Composer and execution of commands can be slightly different.

You can install Composer globally with your package manager.


        sudo apt install composer
        composer --version
    

Alternatively you can download the Composer executable. This is really simple and does not require sudo rights:


        wget https://getcomposer.org/composer.phar
        php composer.phar --version
    

For more details and ways to install Composer, see the Composer download instructions.

Installing extensions with Composer

There are 3 steps to installing MediaWiki extensions with Composer:

  • Find the package names (and versions)
  • Specify the package names (and versions)
  • Run the update command

Note that some extensions require further setup unrelated to Composer. The most common case is the need to run the MediaWiki maintenance/update.php script that among other things creates database tables. This is done after installation with Composer.

Step 1: Find the package names

Before you can specify which extensions to install, you need to find out what their Composer package names are. Composer works with these package names. Examples are mediawiki/maps for the Maps extension and mediawiki/semantic-media-wiki for Semantic MediaWiki.

If the extension supports installation via Composer, its page on MediaWiki.org likely mentions it in the infobox on the top right. Alternatively if you know where the source code of the extension is, you can look at the contents of the composer.json file, which shows the package name at the top.

Packagist.org also provides a searchable list of MediaWiki extensions that can be installed via Composer.

Optional: once you have the package name you can view the package on Packagist.org. The package page will show you an always-up-to-date list of the extensions versions that you can install via Composer. You can find the package name by using the search feature on Packagist or you can manually construct the URL by adding the package name to the end of https://packagist.org/packages/.

Step 2: Specify the package names

Extensions to be installed (and managed by) Composer are specified in the composer.local.json file located in the root directory of your MediaWiki.

You can look in this file to see which extensions are currently installed via Composer. Note that the file might not exist yet.


            {
                "require": {
                    "mediawiki/maps": "*",
                    "mediawiki/semantic-media-wiki": "*",
                    "mediawiki/semantic-result-formats": "*"
                }
            }
        

You can even edit the file directly if you are comfortable with editing JSON. Alternatively you can use the below command, which will edit the file for you, and create it if need be.


            COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:*"
        

This command needs to be run for each extension you want to install. Replace mediawiki/maps with the package name of your extension.

The "*" after the package name tells Composer to install the latest stable version of the extension. It is good practice to specify the version. This makes upgrading safer. If you don't know the version or do not want to be bothered to look it up, you can stick to using "*".


            COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:~7.8"
        

This example will install the most recent Maps version equal to or more recent than 7.8 but lower than 8.0. This means you might get 7.8.1 or 7.9 but not 8.0 or anything 8.0+. The same will hold true for upgrading.

Step 3: Run the update command

The final step is to run the update command in the MediaWiki root directory. It will look like this:


            composer update mediawiki/maps --no-dev -o
        

Remember that if you downloaded composer.phar, the command will start with php composer.phar instead of composer.

The --no-dev option should be used unless you are working with a development with or otherwise know what you are doing. Many extensions do not mention this flag in their installation instructions but it is safe to add regardless.

The -o flag adds an optimization steps to the installation process, enhancing performance of your wiki.

If you added multiple new extensions, you can install all of them in one go by not specifying the package name. Note that this will also upgrade extensions that are already installed.


            composer update --no-dev -o
        

To see what will happen before you run the update command, run it with the --dry-run flag:


            composer update --no-dev -o --dry-run
        
Step 4: Enable the extensions

Many extensions require an extra step to be enabled after they are installed. This is typically done via a call to wfLoadExtension() in your LocalSettings.php file. Please refer to the installation instructions for the individual extension and to the extension registration documentation.

To see if an extension is enabled, check the Special:Version page of your wiki.

Upgrading Extensions

To upgrade extensions already installed with Composer you need the same command as for installation.


        composer update --no-dev -o
    

While this command can upgrade all extensions, you do have control over which ones get upgraded and to which versions. This is where the versions in composer.local.json come into play.

There are three types of constraints commonly used on production wikis. You can choose between those for extensions individually and you can change the constraints over time as you see fit.

The types of constraints are:

  • No versions with breaking changes, but new features and bug fixes are OK
  • No versions with breaking changes, but bug fixes are OK
  • Only this specific version

The first constraint is the most common and what we recommend to use in case of doubt. If you use any of these constraints Composer will not pull in breaking changes. This is done via the magic of Semantic Versioning. It also means that if you want a new major version of an extension (ie version 5 instead of version 4), you'll need to explicitly update the number in composer.local.json.

Both during installation and upgrades Composer takes care of not installing versions it knows will not work on your system. This means you do not need to worry about PHP versions. Composer will either install the most recent version that works on your system or tell you there is no such version.

Constraint 1: new features and bug fixes

To only get bug fix releases when upgrading, prefix the version with a tilde:


            {
                "require": {
                    "mediawiki/maps": "~7.8",
                    "mediawiki/semantic-media-wiki": "~3.1"
                }
            }
        

Important: the version should have two parts. So 1.0 and 16.35 are both fine, while 1.0.0 and 1 are not.

This example will install the most recent Maps version equal to or more recent than 7.8 but lower than 8.0. This means you might get 7.8.1 or 7.9 but not 8.0 or anything 8.0+.

Constraint 2: Bug fixes only

To only get bug fix releases when upgrading, specify three part versions and prefix them with a tilde:


            COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:~7.8.2"
        

Important: the version should have three parts. So 1.0.0 and 23.34.42 are both fine, while 1.0 and 1.23 are not.

When upgrading you will get the most recent 7.8.x release equal to or higher than 7.8.2.

Constraint 3: Fixed versions

If you do not want ANY updates to happen to an extension, just specify its full version number during installation. If you then run the update command, the extension will not be upgraded. It's possible to then change the version in composer.local.json and run the update command to upgrade to that exact version.


            COMPOSER=composer.local.json composer require --no-update "mediawiki/maps:7.8.2"
        

To get a deeper understanding of how version constraints work, have a look at Semantic Versioning and at Writing Version Constraints in the Composer documentation.

Professional Support

Having problems setting up or upgrading your wiki? We provide professional support. Or avoid dealing with Composer and other technicalities altogether by using one of our fully managed MediaWiki hosting plans.