Composer: Difference between revisions

(13 intermediate revisions by 2 users not shown)

Line 1:

~~== Intro ==~~

Composer is one of many [[Dependency managers]]. Composer makes it easier to distribute PHP code that relies on other code.

Composer ~~is one of many~~ [[~~Dependency managers]~~]. ~~Composer makes it easier to distribute PHP code that relies on other code~~.

To use [https://getcomposer.org/ Composer] in your PHP project, see

* this [http://daylerees.com/composer-primer primer],

* plus Matthieu Moquet's "''[https://moquet.net/blog/5-features-about-composer-php/ 5 Features About Composer]''",

* and also this handy-dandy [http://composer.json.jolicode.com/ cheatsheet] (with mouseovers!)

== in MediaWiki ==

<ol>

<li> [[mw:Composer]] is used in the MediaWiki engine to manage all core libraries and dependencies since version 1.25 (including composer-local.json)

<~~source~~ lang="bash">

cd $IP

cp composer.local.json-sample composer.local.json

composer update --no-dev --dry-run

</~~source~~>

</syntaxhighlight>

<li> [[mw:Composer/For extensions]] on using Composer to manage extensions

<li> [[mw:Manual:composer.json best practices]] for how to add Composer support to your extensions (including extension.json and skin.json)

Line 16:

Line 19:

</ol>

=== ~~Use~~ git ~~checkouts~~ ===

=== With Meza ===

Say you installed Semantic Mediawiki with <code>composer require</code> and then when you went to your 'extensions' directory you were <i class="fa fa-frown-o"></i> because it wasn't a git checkout. You can rectify that by redoing the command, but with the <code>--prefer-source</code> option. nb. You first have to move the existing directory out of the way: <code>mv SemanticMediaWiki unused/</code> <code>cd ../ composer require --update-no-dev --sort-packages --optimize-autoloader -vvv mediawiki/semantic-media-wiki "~2.4" --prefer-source</code> But, it's still a bit different than you might expect, ~~but composer~~ leaves you with a detached head owing to the specific version that it checks out.

=== MezaLocalExtensions.yml ===

If the extension should be '''installed''' by Composer, then use a stanza like:

- name: Mermaid

composer: "mediawiki/mermaid"

version: ~2.2

config: |

wfLoadExtension( 'Mermaid' );

$mermaidgDefaultTheme = 'neutral';

</syntaxhighlight>

If the extension source is controlled by [[git]], and you want to have the extension's <tt>composer.json</tt> file "seen" (merged) by MediaWiki, then simply add the line:

composer_merge: true

to the 'normal' extension stanza specifying the source.

=== Install libraries ===

In general, if you want to install something into your MediaWiki instance, you can do the following from the '$IP' (Install Path) directory:

# add the library to composer.local.json

COMPOSER=composer.local.json composer require --no-update mwstake/mediawiki-component-events:~4

# install it to 'vendor' without dev requirements and optimize the autoloader

composer update mwstake/mediawiki-component-events --no-dev -o

# check to see that it's installed

composer show |grep mwstake

</syntaxhighlight>

=== Test an upgrade ===

IP=/opt/htdocs/mediawiki/

cd $IP

COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~11.0

composer update mediawiki/maps --no-dev -o

# Depending on other settings, you may need to restart php-fpm

sudo systemctl restart php-fpm

</syntaxhighlight>

=== Check / Overwrite Local Modifications ===

If you're using [[Meza]] to deploy your MediaWiki platform, you may wonder whether there are local modifications that a new deploy could overwrite.

<code>composer status -v</code> will show you where you have modified any extensions installed by composer.

To overwrite changes, there isn't any 'force' option to composer. In the situation where you would like to overwrite local modifications with an unattended composer (aka <code>--no-interaction</code>) then you should add to composer's configuration (composer.local.json)

"config": {

"discard-changes": true

},

</syntaxhighlight>

This feature is now enabled in Meza 43, and controlled by the default config <tt>config/defaults.yml</tt> <code>overwrite_local_changes: false</code> which in turn sets the config section of <tt>composer.local.json</tt>

=== Prefer Source ===

Say you installed Semantic Mediawiki with <code>composer require</code> and then when you went to your 'extensions' directory you were <i class="fa fa-frown-o"></i> because it wasn't a git checkout. You can rectify that by redoing the command, but with the <code>--prefer-source</code> option. nb. You first have to move the existing directory out of the way: <code>mv SemanticMediaWiki unused/</code> <code>cd ../ composer require --update-no-dev --sort-packages --optimize-autoloader -vvv mediawiki/semantic-media-wiki "~2.4" --prefer-source</code> But, it's still a bit different than you might expect, because Composer leaves you with a detached head owing to the specific version that it checks out (see composer.lock).

<pre>

Dependency resolution completed in 0.002 seconds

Line 42:

Line 98:

Installing it on your own host would look something like this

<~~source~~ lang="bash">

curl -sS https://getcomposer.org/installer | php

sudo mv composer.phar /usr/local/bin/composer

Line 49:

Line 105:

# now you can use it to do things like install the latest version of Drush

composer global require drush/drush:dev-master

</~~source~~>

</syntaxhighlight>

while installing it on a shared host like WebFaction would be slightly modified

<~~source~~ lang="bash">

ln -s `which php54` ~/bin/php

curl -sS https://getcomposer.org/installer | php54

Line 63:

Line 119:

composer global require drush/drush:dev-master

drush --version

</~~source~~>

</syntaxhighlight>

== Semantic Versioning ==

Using Composer correctly means that you understand and follow [[Semantic Versioning]]

== Commands ==

<code>composer show -a mediawiki/semantic-media-wiki</code> will show you the available versions of the package.

<code>composer --help</code> will show you something like this:

<pre>

______

Line 74:

Line 136:

\____/\____/_/ /_/ /_/ .___/\____/____/\___/_/

/_/

~~</pre>~~

Composer version 2.8.4 2024-12-11 11:57:47

Composer version 1.2.~~2 2016~~-11~~-03 17~~:43:15

Usage:

Line 81:

Line 142:

Options:

-h, --help Display ~~this~~ help ~~message~~

-h, --help Display help for the given command. When no command is given display help for the list command

-q, --quiet Do not output any message

-V, --version Display this application version

--ansi Force ~~ANSI output~~

--ansi|--no-ansi Force (or disable --no-ansi) ANSI output

--no-ansi ~~Disable~~ ANSI output

-n, --no-interaction Do not ask any interactive question

--profile Display timing and memory usage information

--no-plugins Whether to disable plugins.

--no-scripts Skips the execution of all scripts defined in composer.json file.

-d, --working-dir=WORKING-DIR If specified, use the given directory as working directory.

--no-cache Prevent use of the cache

-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:

about ~~Short~~ information about Composer

about Shows a short information about Composer

archive ~~Create~~ an archive of this composer package

archive Creates an archive of this composer package

browse Opens the package's repository URL or homepage in your browser.

audit Checks for security vulnerability advisories for installed packages

clear-cache Clears composer's internal package cache.

browse [home] Opens the package's repository URL or homepage in your browser

~~clearcache Clears composer's internal package cache.~~

bump Increases the lower limit of your composer.json requirements to the currently installed versions

config ~~Set~~ config options

check-platform-reqs Check that platform requirements are satisfied

create-project ~~Create~~ new project from a package into given directory.

clear-cache [clearcache|cc] Clears composer's internal package cache

depends Shows which packages cause the given package to be installed

completion Dump the shell completion script

diagnose Diagnoses the system to identify common errors.

config Sets config options

dump-autoload ~~Dumps the autoloader~~

create-project Creates new project from a package into given directory

dumpautoload Dumps the autoloader

depends [why] Shows which packages cause the given package to be installed

exec ~~Execute~~ a vendored binary/script

diagnose Diagnoses the system to identify common errors

global Allows running commands in the global composer dir ($COMPOSER_HOME).

dump-autoload [dumpautoload] Dumps the autoloader

help ~~Displays~~ help for a command

exec Executes a vendored binary/script

~~home Opens the package's repository URL or homepage in your browser.~~

fund Discover how to help fund the maintenance of your dependencies

~~info Show information about packages~~

global Allows running commands in the global composer dir ($COMPOSER_HOME)

init Creates a basic composer.json file in current directory.

help Display help for a command

install Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json.

init Creates a basic composer.json file in current directory

licenses ~~Show~~ information about licenses of dependencies

install [i] Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json

~~lint Run the lint script as defined in composer.json.~~

licenses Shows information about licenses of dependencies

list ~~Lists~~ commands

list List commands

outdated Shows a list of installed packages that have updates available, including their latest version.

outdated Shows a list of installed packages that have updates available, including their latest version

~~phpcs Run the phpcs script as defined in composer.json.~~

prohibits [why-not] Shows which packages prevent the given package from being installed

prohibits Shows which packages prevent the given package from being installed

reinstall Uninstalls and reinstalls the given package names

remove Removes a package from the require or require-dev

remove [rm|uninstall] Removes a package from the require or require-dev

require Adds required packages to your composer.json and installs them

require [r] Adds required packages to your composer.json and installs them

run-script ~~Run~~ the scripts defined in composer.json.

run-script [run] Runs the scripts defined in composer.json

search ~~Search~~ for packages

search Searches for packages

self-update ~~Updates composer.phar to the latest version.~~

self-update [selfupdate] Updates composer.phar to the latest version

selfupdate Updates composer.phar to the latest version.

show [info] Shows information about packages

show ~~Show~~ information about packages

status Shows a list of locally modified packages

status ~~Show~~ a list of locally modified packages

suggests Shows package suggestions

suggests ~~Show~~ package suggestions

update [u|upgrade] Updates your dependencies to the latest version according to composer.json, and updates the composer.lock file

~~test Run the test script as defined in composer.json.~~

validate Validates a composer.json and composer.lock

update Updates your dependencies to the latest version according to composer.json, and updates the composer.lock file.

</pre>

validate Validates a composer.json and composer.lock

~~why Shows which packages cause the given package to be installed~~

~~why-not Shows which packages prevent the given package from being installed~~

~~== More ==~~

~~To use [https:/~~/getcomposer.org/ Composer] in your PHP project, see this [http://daylerees.com/composer-primer primer], plus Matthieu Moquet's "''[https://moquet.net/blog/5-features-about-composer-php/ 5 Features About Composer]''", and also this handy-dandy [http://composer.json.jolicode.com/ cheatsheet] (with mouseovers!)

== See Also ==

[[Composer/autoloading]]

[[Category:Development]]

[[Category:Tools]]

[[Category:PHP]]

@@ Line 1: / Line 1: @@
-== Intro ==
+Composer is one of many [[Dependency managers]].  Composer makes it easier to distribute PHP code that relies on other code.
-Composer is one of many [[Dependency managers]].  Composer makes it easier to distribute PHP code that relies on other code.
+To use [https://getcomposer.org/ Composer] in your PHP project, see
+* this [http://daylerees.com/composer-primer primer],
+* plus Matthieu Moquet's "''[https://moquet.net/blog/5-features-about-composer-php/ 5 Features About Composer]''",
+* and also this handy-dandy [http://composer.json.jolicode.com/ cheatsheet] (with mouseovers!)
 == in MediaWiki ==
 <ol>
 <li> [[mw:Composer]] is used in the MediaWiki engine to manage all core libraries and dependencies since version 1.25 (including composer-local.json)
-<source lang="bash">
+<syntaxhighlight lang="bash">
 cd $IP
 cp composer.local.json-sample composer.local.json
 composer update --no-dev --dry-run
-</source>
+</syntaxhighlight>
 <li> [[mw:Composer/For extensions]] on using Composer to manage extensions
 <li> [[mw:Manual:composer.json best practices]] for how to add Composer support to your extensions (including extension.json and skin.json)
@@ Line 16: / Line 19: @@
 </ol>
-=== Use git checkouts ===
+=== With Meza ===
-Say you installed Semantic Mediawiki with <code>composer require</code> and then when you went to your 'extensions' directory you were <i class="fa fa-frown-o"></i> because it wasn't a git checkout.  You can rectify that by redoing the command, but with the <code>--prefer-source</code> option.  nb. You first have to move the existing directory out of the way: <code>mv SemanticMediaWiki unused/</code> <code>cd ../ composer require --update-no-dev --sort-packages --optimize-autoloader -vvv mediawiki/semantic-media-wiki "~2.4" --prefer-source</code>  But, it's still a bit different than you might expect, but composer leaves you with a detached head owing to the specific version that it checks out.
+=== MezaLocalExtensions.yml ===
+If the extension should be '''installed''' by Composer, then use a stanza like:
+<syntaxhighlight lang="yaml">
+- name: Mermaid
+  composer: "mediawiki/mermaid"
+  version: ~2.2
+  config: |
+    wfLoadExtension( 'Mermaid' );
+    $mermaidgDefaultTheme = 'neutral';
+</syntaxhighlight>
+If the extension source is controlled by [[git]], and you want to have the extension's <tt>composer.json</tt> file "seen" (merged) by MediaWiki, then simply add the line:
+    composer_merge: true
+to the 'normal' extension stanza specifying the source.
+=== Install libraries ===
+In general, if you want to install something into your MediaWiki instance, you can do the following from the '$IP' (Install Path) directory:
+<syntaxhighlight lang="bash">
+# add the library to composer.local.json
+COMPOSER=composer.local.json composer require --no-update mwstake/mediawiki-component-events:~4
+# install it to 'vendor' without dev requirements and optimize the autoloader
+composer update mwstake/mediawiki-component-events --no-dev -o
+# check to see that it's installed
+composer show |grep mwstake
+</syntaxhighlight>
+=== Test an upgrade ===
+<syntaxhighlight lang="bash">
+IP=/opt/htdocs/mediawiki/
+cd $IP
+COMPOSER=composer.local.json composer require --no-update mediawiki/maps:~11.0
+composer update mediawiki/maps --no-dev -o
+# Depending on other settings, you may need to restart php-fpm
+sudo systemctl restart php-fpm
+</syntaxhighlight>
+=== Check / Overwrite Local Modifications ===
+If you're using [[Meza]] to deploy your MediaWiki platform, you may wonder whether there are local modifications that a new deploy could overwrite.
+<code>composer status -v</code> will show you where you have modified any extensions installed by composer.
+To overwrite changes, there isn't any 'force' option to composer.  In the situation where you would like to overwrite local modifications with an unattended composer (aka <code>--no-interaction</code>) then you should add to composer's configuration (composer.local.json)
+<syntaxhighlight lang="yaml">
+    "config": {
+        "discard-changes": true
+    },
+</syntaxhighlight>
+This feature is now enabled in Meza 43, and controlled by the default config <tt>config/defaults.yml</tt> <code>overwrite_local_changes: false</code> which in turn sets the config section of <tt>composer.local.json</tt>
+=== Prefer Source ===
+Say you installed Semantic Mediawiki with <code>composer require</code> and then when you went to your 'extensions' directory you were <i class="fa fa-frown-o"></i> because it wasn't a git checkout.  You can rectify that by redoing the command, but with the <code>--prefer-source</code> option.  nb. You first have to move the existing directory out of the way: <code>mv SemanticMediaWiki unused/</code> <code>cd ../ composer require --update-no-dev --sort-packages --optimize-autoloader -vvv mediawiki/semantic-media-wiki "~2.4" --prefer-source</code>  But, it's still a bit different than you might expect, because Composer leaves you with a detached head owing to the specific version that it checks out (see composer.lock).
 <pre>
 Dependency resolution completed in 0.002 seconds
@@ Line 42: / Line 98: @@
 Installing it on your own host would look something like this
-<source lang="bash">
+<syntaxhighlight lang="bash">
 curl -sS https://getcomposer.org/installer | php
 sudo mv composer.phar /usr/local/bin/composer
@@ Line 49: / Line 105: @@
 # now you can use it to do things like install the latest version of Drush
 composer global require drush/drush:dev-master
-</source>
+</syntaxhighlight>
 while installing it on a shared host like WebFaction would be slightly modified
-<source lang="bash">
+<syntaxhighlight lang="bash">
 ln -s `which php54` ~/bin/php
 curl -sS https://getcomposer.org/installer | php54
@@ Line 63: / Line 119: @@
 composer global require drush/drush:dev-master
 drush --version
-</source>
+</syntaxhighlight>
+== Semantic Versioning ==
+Using Composer correctly means that you understand and follow [[Semantic Versioning]]
 == Commands ==
+<code>composer show -a mediawiki/semantic-media-wiki</code> will show you the available versions of the package.
+<code>composer --help</code> will show you something like this:
 <pre>
     ______
@@ Line 74: / Line 136: @@
 \____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                      /_/
-</pre>
+Composer version 2.8.4 2024-12-11 11:57:47
-Composer version 1.2.2 2016-11-03 17:43:15
 Usage:
@@ Line 81: / Line 142: @@
 Options:
-   -h, --help                     Display this help message
+   -h, --help                     Display help for the given command. When no command is given display help for the list command
    -q, --quiet                    Do not output any message
    -V, --version                  Display this application version
-       --ansi                     Force ANSI output
+       --ansi|--no-ansi           Force (or disable --no-ansi) ANSI output
-      --no-ansi                  Disable ANSI output
    -n, --no-interaction           Do not ask any interactive question
        --profile                  Display timing and memory usage information
        --no-plugins               Whether to disable plugins.
+      --no-scripts               Skips the execution of all scripts defined in composer.json file.
    -d, --working-dir=WORKING-DIR  If specified, use the given directory as working directory.
+      --no-cache                 Prevent use of the cache
    -v|vv|vvv, --verbose           Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
 Available commands:
-   about           Short information about Composer
+   about                Shows a short information about Composer
-   archive         Create an archive of this composer package
+   archive              Creates an archive of this composer package
-   browse          Opens the package's repository URL or homepage in your browser.
+  audit                Checks for security vulnerability advisories for installed packages
-   clear-cache     Clears composer's internal package cache.
+   browse               [home] Opens the package's repository URL or homepage in your browser
-   clearcache      Clears composer's internal package cache.
+  bump                 Increases the lower limit of your composer.json requirements to the currently installed versions
-   config          Set config options
+  check-platform-reqs  Check that platform requirements are satisfied
-   create-project  Create new project from a package into given directory.
+   clear-cache          [clearcache|cc] Clears composer's internal package cache
-   depends         Shows which packages cause the given package to be installed
+   completion           Dump the shell completion script
-   diagnose        Diagnoses the system to identify common errors.
+   config               Sets config options
-   dump-autoload   Dumps the autoloader
+   create-project       Creates new project from a package into given directory
-  dumpautoload    Dumps the autoloader
+   depends              [why] Shows which packages cause the given package to be installed
-   exec            Execute a vendored binary/script
+   diagnose             Diagnoses the system to identify common errors
-   global          Allows running commands in the global composer dir ($COMPOSER_HOME).
+   dump-autoload        [dumpautoload] Dumps the autoloader
-   help            Displays help for a command
+   exec                 Executes a vendored binary/script
-  home            Opens the package's repository URL or homepage in your browser.
+  fund                 Discover how to help fund the maintenance of your dependencies
-  info            Show information about packages
+   global               Allows running commands in the global composer dir ($COMPOSER_HOME)
-   init            Creates a basic composer.json file in current directory.
+   help                 Display help for a command
-   install         Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json.
+   init                 Creates a basic composer.json file in current directory
-   licenses        Show information about licenses of dependencies
+   install              [i] Installs the project dependencies from the composer.lock file if present, or falls back on the composer.json
-  lint            Run the lint script as defined in composer.json.
+   licenses             Shows information about licenses of dependencies
-   list            Lists commands
+   list                 List commands
-   outdated        Shows a list of installed packages that have updates available, including their latest version.
+   outdated             Shows a list of installed packages that have updates available, including their latest version
-  phpcs           Run the phpcs script as defined in composer.json.
+   prohibits            [why-not] Shows which packages prevent the given package from being installed
-   prohibits       Shows which packages prevent the given package from being installed
+  reinstall            Uninstalls and reinstalls the given package names
-   remove          Removes a package from the require or require-dev
+   remove               [rm|uninstall] Removes a package from the require or require-dev
-   require         Adds required packages to your composer.json and installs them
+   require              [r] Adds required packages to your composer.json and installs them
-   run-script      Run the scripts defined in composer.json.
+   run-script           [run] Runs the scripts defined in composer.json
-   search          Search for packages
+   search               Searches for packages
-   self-update     Updates composer.phar to the latest version.
+   self-update          [selfupdate] Updates composer.phar to the latest version
-  selfupdate      Updates composer.phar to the latest version.
+   show                 [info] Shows information about packages
-   show            Show information about packages
+   status               Shows a list of locally modified packages
-   status          Show a list of locally modified packages
+   suggests             Shows package suggestions
-   suggests        Show package suggestions
+   update               [u|upgrade] Updates your dependencies to the latest version according to composer.json, and updates the composer.lock file
-  test            Run the test script as defined in composer.json.
+   validate             Validates a composer.json and composer.lock
-   update          Updates your dependencies to the latest version according to composer.json, and updates the composer.lock file.
+</pre>
-   validate        Validates a composer.json and composer.lock
-  why             Shows which packages cause the given package to be installed
-  why-not         Shows which packages prevent the given package from being installed
-== More ==
-To use [https://getcomposer.org/ Composer] in your PHP project, see this [http://daylerees.com/composer-primer primer], plus Matthieu Moquet's "''[https://moquet.net/blog/5-features-about-composer-php/ 5 Features About Composer]''", and also this handy-dandy [http://composer.json.jolicode.com/ cheatsheet] (with mouseovers!)
+== See Also ==
+[[Composer/autoloading]]
 [[Category:Development]]
 [[Category:Tools]]
 [[Category:PHP]]