View source for Composer

<languages />
[[File:Logo-composer-transparent.png|{{dir|{{PAGELANGUAGE}}|left|right}}]]
<translate><!--T:1--> '''[[w:Composer (software)|Composer]]''' is a dependency manager for PHP libraries.</translate>
<translate><!--T:3--> Starting with <tvar name=ver>{{ll|MediaWiki 1.25}}</tvar>, MediaWiki core's external library dependencies are being managed with Composer.</translate>
<translate><!--T:2--> In addition, it can be used to manage the installation of MediaWiki extensions (available since <tvar name=ver>{{ll|MediaWiki 1.22}}</tvar>).</translate>
<translate><!--T:48--> However, this is currently not well-supported.</translate>
<translate><!--T:49--> This may change in the future.</translate>

<translate>
== Installing Composer == <!--T:4-->
</translate>
{{note|1=<translate><!--T:40--> MediaWiki supports Composer 2.x (as of {{<tvar name=1>ll|MediaWiki 1.35</tvar>|MediaWiki 1.35.2}} and later).</translate>}}

<translate>
=== On Unix/Linux and macOS === <!--T:35-->

<!--T:5-->
There are multiple ways to [<tvar name=url>https://getcomposer.org/download</tvar> install Composer], besides the most obvious way, <tvar name=1><code>sudo apt install composer</code></tvar>.
</translate>

<translate><!--T:51--> Composer 2.x is supported by MediaWiki >= 1.35.2.</translate>
<translate><!--T:52--> To grab the latest Composer 2.x stable release:</translate>

<syntaxhighlight lang=bash>
wget -cO - https://getcomposer.org/composer-2.phar > composer.phar
</syntaxhighlight>

<translate><!--T:47--> Composer 1.x is EOL. It is supported by MediaWiki 1.31, >= 1.35.0 < 1.42.</translate>
<translate><!--T:6--> To grab the latest Composer 1.x stable release:</translate>

<syntaxhighlight lang=bash>
wget -cO - https://getcomposer.org/composer-1.phar > composer.phar
</syntaxhighlight>

<translate><!--T:9--> For users on macOS, you can use [<tvar name=url>http://brew.sh/</tvar> Homebrew] to install Composer.</translate>
<translate><!--T:46--> Note this will install version Composer 2.x, so depending on the version of MediaWiki you are using, you may need to follow the <tvar name=1><code>wget</code></tvar> instructions above instead to download Composer 1.x.</translate>
<translate><!--T:62--> To install using <tvar name=2><code>brew</code></tvar>:</translate>

<syntaxhighlight lang=bash>
brew install composer
</syntaxhighlight>

<translate>
<!--T:10-->
If that doesn't work, or you do not have Homebrew installed, you can try:
</translate>

<syntaxhighlight lang=bash>
php -r "readfile('https://getcomposer.org/installer');" | php
</syntaxhighlight>

<translate>
<!--T:11-->
Toolforge and the extension distributor use the copy of Composer contained in the "<tvar name=composer>integration/composer</tvar>" git repo.

<!--T:12-->
Once Composer is installed, you can run commands via the downloaded <tvar name=1><code>.phar</code></tvar>:
</translate>

<syntaxhighlight lang=bash>
php composer.phar someCommand
</syntaxhighlight>

<translate>
<!--T:13-->
You may want to move the <tvar name=1><code>.phar</code></tvar> into your path so it can be used as a normal executable:
</translate>

<syntaxhighlight lang=bash>
mv composer.phar /usr/local/bin/composer
composer someCommand
</syntaxhighlight>

<translate>
<!--T:14-->
If the <tvar name=1><code>mv</code></tvar> command fails due to permissions, execute it again with <tvar name=2><code>sudo</code></tvar>.
</translate>

<syntaxhighlight lang=bash>
sudo mv composer.phar /usr/local/bin/composer
composer someCommand
</syntaxhighlight>

<translate>
=== On Windows === <!--T:36-->
</translate>
<translate><!--T:37--> Just download and run the installer from the [<tvar name=url>https://getcomposer.org/download</tvar> download page].</translate>
<translate><!--T:38--> If you prefer manual installation, you can follow the above steps except that Windows doesn’t have <tvar name=2><code>wget</code></tvar> (or APT or Homebrew) by default, and there is no <tvar name=1><code>/usr/local/bin</code></tvar> directory.</translate>
<translate><!--T:41--> In these cases, you can just download <tvar name=1>[https://getcomposer.org/composer-1.phar composer-1.phar]</tvar> in your web browser and then rename it to <tvar name=2><code>composer.phar</code></tvar>.</translate>

<translate>
=== Local installation === <!--T:57-->
</translate>
<translate><!--T:58--> You're not out of luck if you don't have permissions to run Composer on the server.</translate>
<translate><!--T:59--> It is also possible to download the MediaWiki folder to your local machine, install and run Composer, and transfer the files back to the server.</translate>

<translate>
== Upgrading Composer == <!--T:42-->

=== Composer 1.x === <!--T:53-->

<!--T:43-->
If you want to upgrade Composer to the latest 1.x stable (or downgrade from 2.x stable), you can use:
</translate>

<syntaxhighlight lang=bash>
composer self-update --1
</syntaxhighlight>

<translate>
<!--T:44-->
If the update command fails due to permissions, execute it again with <tvar name=1><code>sudo</code></tvar>.
</translate>

<syntaxhighlight lang=bash>
sudo composer self-update --1
</syntaxhighlight>

<translate><!--T:45--> If you are on a really old version of Composer, it may not have the <tvar name=1><code>--1</code></tvar> parameter.</translate>
<translate><!--T:60--> In this case, you might want to run <tvar name=2><code>self-update</code></tvar> twice.</translate>
<translate><!--T:61--> The first may update it to 2.x, so the second will downgrade it to the latest version of 1.x.</translate>

<syntaxhighlight lang=bash>
composer self-update
composer self-update --1
</syntaxhighlight>

<translate>
=== Composer 2.x === <!--T:54-->

<!--T:55-->
If you are using Composer 1.x, and want to upgrade to Composer 2.x (and are using an appropriate version of MediaWiki, such as >= 1.35.2), you can use:
</translate>

<syntaxhighlight lang=bash>
composer self-update --2
</syntaxhighlight>

<translate>
<!--T:56-->
If the update command fails due to permissions, execute it again with <tvar name=1><code>sudo</code></tvar>.
</translate>

<syntaxhighlight lang=bash>
sudo composer self-update --2
</syntaxhighlight>

<translate>
== Usage in MediaWiki core == <!--T:15-->
</translate>
<translate><!--T:16--> MediaWiki 1.25+ depends on some external libraries which are managed with Composer.</translate>
<translate><!--T:17--> Composer creates an autoloader at <tvar name=1><code>vendor/autoload.php</code></tvar>, which is included by <tvar name=2><code>{{ll|Manual:WebStart.php|WebStart.php}}</code></tvar>. </translate>

<translate><!--T:18--> Composer managed dependencies are bundled into tarball distributions of MediaWiki and extensions so system administrators do not need to use Composer directly.</translate>
<translate><!--T:19--> When [[<tvar name=download>Special:MyLanguage/Download from Git#Fetch_external_libraries</tvar>|installing MediaWiki using Git]], dependencies declared in <tvar name=json><code>{{ll|Manual:$IP|$IP}}/composer.json</code></tvar> can either be installed locally by running <tvar name=update><code>composer update --no-dev</code></tvar> or the <tvar name=vendor><code>[https://gerrit.wikimedia.org/g/mediawiki/vendor mediawiki/vendor.git]</code></tvar> repository can be cloned to provide the same libraries used on the Wikimedia production cluster.</translate>

<translate>
== Using composer-merge-plugin == <!--T:20-->
</translate>

{{$IP}}
<translate><!--T:21--> MediaWiki core "owns" <tvar name=json><code>$IP/composer.json</code></tvar> and will change the contents of that file in both tarball and Git managed updates.</translate>
<translate><!--T:22--> In order to allow local installs to use Composer to load optional libraries and/or [[<tvar name=ext>Special:MyLanguage/Composer/For extensions</tvar>|manage extensions with Composer]], a special plugin for Composer named [<tvar name=url>https://github.com/wikimedia/composer-merge-plugin</tvar> composer-merge-plugin] was developed.</translate><ref>{{phabricator|T67188}}</ref>
<translate><!--T:23--> This plugin and the MediaWiki core <tvar name=json><code>composer.json</code></tvar> configuration allow a local deployment to add required extensions and libraries to a file <tvar name=local><code>composer.local.json</code></tvar> inside the root MediaWiki directory.</translate>

<translate><!--T:24--> <tvar name=local><code>composer.local.json</code></tvar> can also be used to install Composer managed libraries that are needed by extensions that are not installed using Composer themselves.</translate>
<translate><!--T:25--> This is only needed when the extensions are '''not''' installed from tarballs generated by [[<tvar name=special>Special:ExtensionDistributor</tvar>|Extension Distributor]].</translate>

<translate>
<!--T:26-->
To enable Composer to discover and process the <tvar name=json><code>composer.json</code></tvar> files that may be included in any and all of your locally installed extensions, add something like this to <tvar name=local><code>$IP/composer.local.json</code></tvar>:
</translate>

<syntaxhighlight lang="json" highlight="5-6">
{
    "extra": {
        "merge-plugin": {
            "include": [
                "extensions/*/composer.json",
                "skins/*/composer.json"
            ]
        }
    }
}
</syntaxhighlight>

<translate>
<!--T:39-->
After any changes to <tvar name=1><code>composer.local.json</code></tvar>, you need to run <tvar name=3><code>composer update</code></tvar> so that Composer will recalculate the dependencies and the changes will take effect.

== Resources == <!--T:27-->
</translate>
* {{ll|Composer/For extensions|2=<translate><!--T:28--> How to install extensions through Composer</translate>}}
** [https://packagist.org/search/?type=mediawiki-extension <translate><!--T:30--> List of extensions that can or must be installed with Composer</translate>]
** {{ll|Category:Extensions supporting Composer}}
* {{ll|Manual:External libraries|2=<translate><!--T:31--> How to add external libraries to MediaWiki core or extensions</translate>}}
* {{ll|Manual:Composer.json best practices|2=<translate><!--T:32--> Best practices when creating a <tvar name=1>composer.json</tvar></translate>}}
* {{ll|Composer/packagist.org|2=<translate><!--T:33--> Information about adding packages to <tvar name=1>packagist.org</tvar></translate>}}
* [[w:Composer (software)]]

<translate>
== References == <!--T:34-->
</translate>
<references/>

[[Category:MediaWiki development{{#translation:}}]]
[[Category:Composer{{#translation:}}]]