Composer/For extensions

This workflow is the subject of an ongoing RFC discussion

You can use Composer to install MediaWiki extensions which include a composer.json manifest and optionally are published on the Packagist package repository.

Composer requires shell access on the respective server. If you do not have shell access to the server of your website, it is also possible to set up MediaWiki and Composer on a local computer, for instance using an AMP package, and transfer the installed files to the remote server.

What is Composer

Composer is a dependency manager that automates many of the tasks one has to deal with when installing extensions. In MediaWiki's current use of composer, some work that had to be done by hand has been automated:

• Composer handles downloading the extension,
• Composer puts the extension's files in the right place,
• Composer verifies that any PHP extensions needed (e.g. swoole or LuaSandbox) are installed.
• Composer can install some extension dependencies,
• Composer automatically installs any extra PHP libraries that are needed into MediaWiki's top-level vendor directory.

Because composer handles so much of the grunt work of installation, it is important to remember that you will still need to add wfLoadExtension( 'myComposerExtension' ); to your "LocalSettings.php" file to use the extension.

MediaWiki's use of Composer does not enable extensions by default so that separate wikis can run from the same installation of MediaWiki and only those wikis that want to use, say, Semantic MediaWiki will have it available.

User manual

Installing Composer

Follow the official download instructions to install Composer. Nothing extra needs to be done for it to work with MediaWiki.

Specify the extensions to be installed

If you want to install the SubPageList extension automatically, composer can handle this automatically:

COMPOSER=composer.local.json php composer.phar require --no-update mediawiki/sub-page-list

Otherwise, read on.

MediaWiki ships with a "composer.json" file that you should not change. This means that you cannot use composer require from the command line. Instead, copy the "composer.local.json.sample" file to "composer.local.json" and modify it for your needs.

In this file, add the extensions you want to install in the "require" section. Or have a look at the examples below.

This example specifies that the SubPageList extension should be installed. It also specifies that you want version 1.4 or above, up to, but excluding, version 2.0.

{
    "require": {
        "mediawiki/sub-page-list": "~1.4"
    }
}

For each additional extension you need, a new line is added. This example also adds Semantic MediaWiki, and specifies that you are happy with the latest version compatible with your setup.

{
    "require": {
        "mediawiki/sub-page-list": "~1.4",
        "mediawiki/semantic-media-wiki": "*"
    }
}

Each line, except the last one, should have a comma at the end. Also note that you only need to specify the extensions you need, and do not have to bother with their dependencies. For instance, if you want to install Semantic Glossary, Composer will automatically install its dependencies, such as Lingo and Semantic MediaWiki, for you.

Also, see "basic composer usage" and "version constraints"

Installing extensions that don't use Composer

Many extensions are not registered on Packagist, but can still be installed with Composer. There are two situations: one is that the extension's composer.json file is complete and contains a name key; the other is that composer.json file is not complete, and we have to locally re-define it ourselves. For both of these, we have to set up the Repositories section of our composer.local.json.

1. If a composer.json file does have a name key and does tag its releases but is not registered on Packagist, you need to add a 'VCS' repository to your composer.local.json file, to tell Composer where to find the source code for the extension. For example, if the UnRegisteredExt extension's composer.json contains "name": "somevendor/unregistered-extension", and there is a 1.2.x release tagged then you need to add the following:

{
	"require": {
		"somevendor/unregistered-extension": "^1.2"
	},
	"repositories": [
		{
			"type": "vcs",
			"url": "https://gerrit.wikimedia.org/r/mediawiki/extensions/UnRegistereExt.git"
		}
	]
}

2. The second and more common scenario is that the extension's composer.json file does not contain a name, and so you need to define a 'Package' repository that contains everything about it (basically reproducing what would otherwise be defined in the extension). For example, to install the Echo extension, add the following to your composer.local.json:

{
	"repositories": [
		{
			"type": "package",
			"package": {
				"name": "x-mediawiki/echo",
				"type": "mediawiki-extension",
				"version": "1.39.0",
				"source": {
					"type": "git",
					"url": "https://gerrit.wikimedia.org/r/mediawiki/extensions/Echo.git",
					"reference": "REL1_39"
				}
			}
		}
	],
	"require": {
		"x-mediawiki/echo": "^1.39"
	}
}

Run composer update --no-dev and the extension will be installed to $IP/extensions/Echo/ and can be activated in the normal way.

To upgrade an extension installed in this way is slightly annoying: the version number that appears three times in the above JSON needs to be updated in a couple of different ways:

• To upgrade within the same branch, increment the patch number in "version": "1.39.0". Note that this is just an invented version number and doesn't have to match anything other than within your composer.local.json; you could equally just use incrementing integers here.
• To upgrade to a new branch (i.e. when upgrading MediaWiki), change the reference branch name as well as the package version number.
• If an extension uses the 'master' compatibilty policy rather than 'rel', you need to use "reference": "master" and will only need to update the version number (you can just increment it to anything when you want to upgrade).

Installing extensions

Once you specified the extensions you want to install, run "composer update --no-dev". At this point, Composer will download and place the extension and its dependencies in the correct place.

In order to allow multiple wikis with different extensions to run from the same set of files (i.e. a Wiki farm), the extension is not enabled automatically when it is installed. To enable the extension, you will need to add wfLoadExtension() to your "LocalSettings.php" file.

For example if you install Page Forms with composer, you would add the following to your LocalSettings.php:

wfLoadExtension( 'PageForms' );

To verify the extension was installed and enabled correctly, got to page "Special:Version" and see if the desired extensions are listed.

When you want to get a new version of an extension, update the versions in the "composer.local.json" file, and run "composer update --no-dev".

Upgrading extensions

If you are upgrading an extension from a version that does not use Composer to one that does, you will first need to (partially) remove the extension, and then follow the standard installation instructions. A step by step tutorial can be found at Upgrading an extension that now uses Composer.

Uninstalling extensions

Remove the extension from your "composer.local.json" file, and run composer update --no-dev.

If you enabled the extension, you will need to remove the appropriate wfLoadExtension() from your "LocalSettings.php" file.

Best practices for using composer to manage extensions

Use release branches

Most MediaWiki extension do not have semantic versioning. The Wikimedia Foundation (WMF) as well as some extension authors support certain release branches. Using a release branch as version constraint will therefore ensure compatibility to your MediaWiki Core version.

Example:

{
    "require": {
        "mediawiki/visual-editor": "dev-REL1_35"
    }
}

Be aware that usually only the current LTS branch(es) as well as the branch of the latest release receive patches.

Use third-party package repositories

Not all MediaWiki extensions are listed on <packagist.org>. But you can add additional repositories to your "composer.local.json"

{
    "repositories": [{
        "type": "composer",
        "url": "https://packages.bluespice.com/"
    }]
}

Common problems

Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Installation request for mediawiki/semantic-mediawiki dev-master -> satisfiable by mediawiki/semantic-mediawiki[dev-master].
    - mediawiki/semantic-mediawiki dev-master requires param-processor/param-processor dev-master -> no matching package found.

If you run into this error, first double check that there is no typo in any of the package names. In case the names are all correct, there might be a dependency that has no matching stable release. You can specify that Composer is allowed to install packages still in development state by adding the "minimum-stability" flag to your composer.local.json file. Example:

{
    "require": {
        "php": ">=5.3.2",
        "mediawiki/sub-page-list": ">=1.0"
    },
    "minimum-stability" : "dev"
}

See also

• List of extensions that can be installed for MediaWiki with Composer
• Installing MediaWiki extensions with Composer
• Category listing extensions that support Composer
• Manual on "composer.json" best practices
• Manual page on Composer for extension developers