Installing MediaWiki extensions with Composer


Last updated on 2019-11-08


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 installation of Composer an executing it might 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.


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

You can copy the above example and replace the package names with the ones you want. Note the comma at end end up the first two lines. This is needed for all but the last line inside of the "require" section.

If you have already installed some extensions and are installing additional ones, leave the already installed ones in place. Removing them will cause them to be uninstalled.

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 "*".


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

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 --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.

Please beware that running composer update will not only install extensions you just added to composer.local.json, it will also upgrade extensions already installed with Composer.

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:


            "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.


            "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.