Composer

From MediaWiki.org
Jump to: navigation, search

As of MediaWiki 1.22, one can use Composer[1] to install extensions which support it.

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

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

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.

User manual[edit | edit source]

Installing Composer[edit | edit source]

Download Composer. See the instructions on that download page for all options. Important to note is that one can simply get the composer.phar file and run Composer via this file.

wget https://getcomposer.org/composer.phar
php composer.phar someCommand

This is equivalent to doing an actual installation of Composer and then running

composer someCommand

Specify the extensions to be installed[edit | edit source]

Copy the composer-example.json file to a new file named composer.json.

In this file, add the extensions you want to install in the "require" section. See "declaring dependencies" and "package setup". Or have a look at the examples below.

The default contents of the json file specifies nothing should be installed, and looks as follows:

{
    "require": {
        "php": ">=5.3.2"
    }
}

This example specifies that the SubPageList extension should be installed. It also specifies that you want version 1.0 or above.

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

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": {
        "php": ">=5.3.2",
        "mediawiki/sub-page-list": ">=1.0",
        "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 it's dependencies, such as Maps and Semantic MediaWiki, for you.

Installing and upgrading extensions[edit | edit source]

Once you specified the extensions you want to install, run "composer install". 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.json file, and run "composer update".

Installing a single extension can be done in one go using the "composer require" command. This command first adds the extension to composer.json and then does the actual installation.

composer require mediawiki/sub-page-list 1.0

Upgrading extensions not using Composer yet[edit | edit source]

If you are upgrading an extension from a version that does not user 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.

Removing a package[edit | edit source]

You can use the remove command to easily expunge a package from the composer.json and for case where the removal of related dependencies is desired as well, use option --update-with-dependencies.

composer remove mediawiki/myPackage

Common problems[edit | edit source]

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.json file. Example:

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

Developer resources[edit | edit source]

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

On packagist.org[edit | edit source]

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

At first we create the composer.json files in the Translate extension:

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

Similarly for the TranslationNotification extension:

{
	"name": "mediawiki/translation-notifications",
	"type": "mediawiki-extension",
	"description": "Manage communication with translators",
	"homepage": "http://www.mediawiki.org/wiki/Extension:TranslationNotifications",
	"license" : "GPL-2.0+",
 
	"require": {
		"composer/installers": ">=1.0.1",
		"mediawiki/translate" : "dev-master"
	}
}

Then we check the syntax to avoid mistakes:

$ composer validate
./composer.json is valid

Test composer.json[edit | edit source]

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 a local repository of type "artifact" instead of packagist.

First create the composer artifact repository in your main MediaWiki directory:

cd <your main MediaWiki directory>
mkdir composer_artifacts

Next, edit the composer.json file in your main MediaWiki directory and add this repository:

    "repositories": [
        {
            "type": "artifact",
            "url": "composer_artifacts"
        }
    ],

You can then put a zipped version of your extension in this local repository like this:

cd <your extension dir>
zip -r your-extension.zip *
mv your-extension.zip ../../composer_artifacts

There is a catch. When composer uses an artifact type repository you must add the package version in your extension's composer.json (because composer cannot infer the version number from some place like a git tag in this case).

For testing, you may add version information to your extension composer.json like this:

"version": "dev-master",

Since you should not commit your extension's composer.json with version information in it, a good practice is to only add the version information in the zipped version (not the original).

To test your extension's installation:

cd <your main MediaWiki dir>
composer require mediawiki/your-extension 'dev-master'

Publish extension in packagist[edit | edit source]

Then send that in the git repository of your choice. Antoine "hashar" Musso used his GitHub project to hold them:

We then go to the http://packagist.org/ repository and submit the package. You will need to create an account then fill in the GIT repository URL. The packagist website will fetch the composer.json from your repository and happily add the package to the repository.

See also[edit | edit source]

References[edit | edit source]

  1. https://gerrit.wikimedia.org/r/#/c/93120/
  2. http://www.bn2vs.com/blog/2013/10/31/mediawiki-extension-installer/