Composer/For extensions

From mediawiki.org
Jump to navigation Jump to search
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 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[edit]

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( 'myComposerExtesion' ); 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[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]

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

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[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 at Upgrading an extension that now uses Composer.

Uninstalling extensions[edit]

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

Use release branches[edit]

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

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

See also[edit]

References[edit]