Installing MediaWiki Extensions 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.

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"