Composer/For extensions

From MediaWiki.org
Jump to navigation Jump to search

As of MediaWiki 1.22, you can use Composer[1] to install MediaWiki extensions which include a composer.json manifest and are published on the Packagist package repository.

Composer requires shell access. 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[edit]

Composer is a dependency manager that automates many of the tasks one has to deal with when installing extensions. The following points no longer have to be dealt with if you install extensions with Composer:

  • Where do I download it from, and how? (A: this depends on the extension and can vary a lot)
  • Where do I put it, and how do I load it? (A: editing a PHP file and adding a PHP includes into it)
  • What other extensions or libraries are needed? (A: it depends, and often this is not well documented)
  • What versions of those extensions are compatible? (A: it depends, and rarely is well documented)
  • In what order do I need to include the extensions? (A: indeed, it depends, and is often not well documented)

Current status[edit]

Composer managed extension installation in MediaWiki is only possible since version 1.22. If you have an older version of MediaWiki, you can use the Extension Installer extension to achieve the same capabilities.[2]

In order for an extension to be installable with Composer, it needs to provide certain details. As a result, most MediaWiki extensions are not currently installable with Composer. You can look at the list of packages tagged with "MediaWiki" on Packagist to find the extensions that can already be installed via Composer.

In April 2015[3], an RFC to make Composer based extension management the preferred method of managing all MediaWiki extensions was pulled from discussion. This was motivated by the "seemingly intractable" problem of managing extensions for a Wikifarm when using Composer. Said problem is not inherent to using Composer and most Composer using extensions nowadays are not loaded automatically and instead require a call to wfLoadExtension just like any other extension.

User manual[edit]

Installing Composer[edit]

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[edit]

Since MediaWiki 1.25, MediaWiki itself uses Composer to manage external library dependencies. In order to allow inter-operation with using Composer to install extensions, a special plugin for Composer named composer-merge-plugin was developed.[4] This plugin and the MediaWiki core composer.json configuration allow a local deployment to add required extensions and libraries to a file composer.local.json inside the root MediaWiki directory. When using versions of MediaWiki prior to 1.25 the changes described below should be made to the composer.json file instead.

In this file, add the extensions you want to install in the "require" section. See "basic composer usage" and "version constraints". 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 Maps, Composer will automatically install its dependencies, such as Maps and Semantic MediaWiki, for you.

Installing and upgrading extensions[edit]

Once you specified the extensions you want to install, run "composer update --no-dev". To verify installation was successful, hit Special:Version and see if the desired extensions are listed.

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

Installing extensions that don't use Composer[edit]

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 definea '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.33.0",
				"source": {
					"type": "git",
					"url": "https://gerrit.wikimedia.org/r/mediawiki/extensions/Echo.git",
					"reference": "REL1_33"
				}
			}
		}
	],
	"require": {
		"x-mediawiki/echo": "^1.33"
	}
}

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

Upgrading extensions that have started using Composer[edit]

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

Uninstalling extensions[edit]

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

Common problems[edit]

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

Developer resources[edit]

A more up to date list of instructions can be found in Introduction to Composer for MediaWiki developers.

On packagist.org[edit]

Packagist.org is the central composer package repository.

A "mediawiki" user exists on Packagist to have GitHub notify packagist whenever a new commit land in the repository. The credentials for the mediawiki user are only accessible to Wikimedia Foundation Operations team (they used to be on fenari:/home/wikipedia/doc/packagist.org but got moved RT #6665). Legoktm has access to the account, so poke him if you want a package added.

composer.json[edit]

You want to add a composer.json file in your extension. Here is an example from Translate:

{
	"name": "mediawiki/translate",
	"type": "mediawiki-extension",   
	"description": "Let your user translate any kind of text",
	"homepage": "http://www.mediawiki.org/wiki/Extension:Translate",
	"license" : "GPL-2.0+",

	"require": {
		"composer/installers": ">=1.0.1",
	},
	"suggest": {
		"mediawiki/translation-notifications": "Manage communication with translators"
	}
}

More examples can be found at Manual:composer.json best practices.

Then we check the syntax to avoid mistakes:

$ composer validate
./composer.json is valid

Test composer.json[edit]

Before you commit your composer.json, you should test it. There is a chicken-and-egg problem here. You must commit your extension's composer.json before you publish the extension in packagist. To solve this problem, you can use your local repository instead of packagist.

Add or edit the composer.local.json file in your main MediaWiki directory (your test environment) to add your local repository to composers list of repositories to look for packages.

The following example assumes you are using Git as your VCS. Because composers repository type vcs works with bare git repositories only (and not working trees) you must let the url-attribute point directly to your $GIT_DIR instead of your working tree (this is the .git-subdirectory inside your repository in most cases). Now add the following lines to the composer.local.json file:

...
    "repositories": [
        {
            "type": "vcs",
            "url": "ABSOLUTE_OR_RELATIVE_PATH_TO_YOUR_GIT_REPOSITORY/.git"
        }
    ],
...

Now you can test your extension's installation by specifying an according require-attribute inside your composer.local.json file. Composer will match an according tag or branch name from your local repository then.

Publish extension in packagist[edit]

See Manual:Developing libraries#Packagist guidelines for information on how to add your extension to packagist.org.

See also[edit]

References[edit]