Share this page

Learn X in Y minutes

Where X=Composer

Get the code: LearnComposer.sh

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you.

Installing

# Installs the composer.phar binary into the current directory
curl -sS https://getcomposer.org/installer | php
# If you use this approach, you will need to invoke composer like this:
php composer.phar about

# Installs the binary into ~/bin/composer
# Note: make sure ~/bin is in your shell's PATH environment variable
curl -sS https://getcomposer.org/installer | php -- --install-dir=~/bin --filename=composer

Windows users should follow the Windows installation instructions

Confirming installation

# Check version and list options
composer

# Get more help for options
composer help require

# Check if Composer is able to do the things it needs, and if it's up to date
composer diagnose
composer diag # shorthand

# Updates the Composer binary to the latest version
composer self-update
composer self # shorthand

Usage

Composer stores your project dependencies in composer.json. You can edit this file, but it is best to let Composer manage it for you.

# Create a new project in the current folder
composer init
# runs an interactive questionnaire asking you for details about your project.  Leaving them blank is fine unless you are making other projects dependent on this one.

# If a composer.json file already exists, download the dependencies
composer install

# To download the just the production dependencies, i.e. excluding development dependencies
composer install --no-dev

# Add a production dependency to this project
composer require guzzlehttp/guzzle
# will figure out what the latest version of guzzlehttp/guzzle is, download it, and add the new dependency to composer.json's require field.

composer require guzzlehttp/guzzle:6.0.*
# will download the latest version matching the pattern (eg. 6.0.2) and add the dependency to composer.json's require field

composer require --dev phpunit/phpunit:~4.5.0
# will require as a development dependency. Will use the latest version >=4.5.0 and < 4.6.0

composer require-dev phpunit/phpunit:^4.5.0
# will require as a development dependency. Will use the latest version >=4.5.0 and < 5.0

# For more information on Composer version matching, see [Composer's documentation on Versions](https://getcomposer.org/doc/articles/versions.md) for more details

# To see what packages are available to install and currently installed
composer show

# To see what packages are currently installed
composer show --installed

# To find a package with 'mailgun' in its name or description
composer search mailgun

Packagist.org is the main repository for Composer packages. Search there for existing third-party packages.

composer.json vs composer.lock

The composer.json file stores your project's floating version preferences for each dependency, along with other information.

The composer.lock file stores exactly which version it has downloaded for each dependency. Never edit this file.

If you include the composer.lock file in your git repository, every developer will install the currently used version of the dependency. Even when a new version of a dependency is released, Composer will continue to download the version recorded in the lock file.

# If you want to update all the dependencies to their newest version still matching your version preferences
composer update

# If you want the new version of a particular dependency:
composer update phpunit/phpunit

# If you wish to migrate a package to a newer version preference, you may need to remove the older package and its dependencies first.
composer remove --dev phpunit/phpunit
composer require --dev phpunit/phpunit:^5.0

Autoloader

Composer creates an autoloader class you can require from your application. You can make instances of classes via their namespace.

require __DIR__ . '/vendor/autoload.php';

$mailgun = new Mailgun\Mailgun("key");

PSR-4 Autoloader

You can add your own namespaces to the autoloader.

In composer.json, add a 'autoload' field:

{
  "autoload": {
    "psr-4": {"Acme\\": "src/"}
  }
}

This will tell the autoloader to look for anything in the \Acme\ namespace within the src folder.

You can also use PSR-0, a Classmap or just a list of files to include. There is also the autoload-dev field for development-only namespaces.

When adding or modifying the autoload key, you will need to rebuild the autoloader:

composer dump-autoload
composer dump # shorthand

# Optimizes PSR0 and PSR4 packages to be loaded with classmaps too. Slow to run, but improves performance on production.
composer dump-autoload --optimize --no-dev

Composer's Cache

# Composer will retain downloaded packages to use in the future. Clear it with:
composer clear-cache

Troubleshooting

composer diagnose
composer self-update
composer clear-cache

Topics not (yet) covered in this tutorial

References

Got a suggestion? A correction, perhaps? Open an Issue on the GitHub Repo, or make a pull request yourself!

Originally contributed by Brett Taylor, and updated by 2 contributors.