Composer is a dependency-management tool for PHP. It installs and keeps current all library dependencies for a given project. It does so recursively, so not only does it manage all direct dependencies but any dependencies those dependencies have, and so on, and so forth, ad infinitum, ad nauseum.

It’s becoming more popular as an installation method, given the general shift in software licensing from closed to open source, and the increasing prevalence of dependency on separately-maintained libraries.

Installation

The first step is installation. As I use it all the time in my development environment I have it installed globally:

curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

The first line downloads and installs Composer via cURL; the second line makes composer executable without requiring the php interpreter.

If global installation isn’t an option (think shared hosting, like GoDaddy) or typing lots of stuff at the command-line makes you feel like Zero Cool, you can also install it locally. Check Composer’s download page for the most up-to-date install commands, the end result of which is your very own composer.phar file inside the project directory. Use php composer.phar to invoke Composer commands.

Use

Now that Composer’s installed, let’s start using it. The only thing Composer needs, really, is a file inside the project directory named composer.json that contains a list of all dependencies within the require key.

This method is particularly useful if the project employs multiple, non-dependent libraries. (Dependent libraries will be loaded by default and don’t need to be listed.) To install, say, CakePHP the composer.json file would look like this:

{
     "require": {
          "cakephp/cakephp": "~3.0"
     }
}

Note the operator (“~“) on the version number. This will restrict updates to the latest stable releases of 3.x. There are a wide variety of other operators that can be used to modify this range further.

Once this file is saved within the project directory, navigate there via the command-line and run composer install (or, php composer.phar install if Composer was installed locally). Composer will install not only any packages listed but any dependencies at the latest stable version.

The require command can also be run via the command-line to install individual packages (and their dependencies) within the project directory. To install, for example, the current release of Amazon Web Services Software Development Kit (or, AWS SDK), we’d navigate inside the directory where we wanted to install it and run:

composer require aws/aws-sdk-php

Note the lack of version information. If you’re not sure what the most recent version is, leave the verison number off entirely and Composer will grab the current stable distribution by default.

Creating a Project with Composer

If you want to create a new project based on an existing package (like CakePHP) — as opposed to merely downloading and installing the software — the best method is the create-project command. It sets up the project infrastructure then installs the packages (and all dependencies) within.

The syntax is:

composer create-project [flags] [package] [path] [version]

For example, the following command (borrowed from CakePHP’s own install page) will create a new CakePHP project, based on the most recent distribution, within a directory named new_project:

composer create-project --prefer-dist cakephp/app new_project

The target directory (new_project here) will be created if it doesn’t already exist. If it does exist, Composer will confirm it’s empty (returning an error if not) in order to prevent overwriting any existing files.

composer.json and composer.lock

As part of any installation, Composer will create two files within the project directory:

1. composer.json
   As discussed above, this file contains (at minimum) a list of all package dependencies and preferred version ranges (if any). It will only be created if it doesn’t already exist.
2. composer.lock
   This file contains a list of all packages (and exact versions) installed within the project.

Together these two files guide Composer’s response when the install or update commands are run. If the project is under version control (if not, why not?) both of these files should be committed to the repository, so anyone setting up the project will receive the exact same library set (down to the versions) as the most recent commit.

It’s worth noting that the libraries themselves should be excluded from the project repository in order to avoid unnecessary redundancy and to keep the repository size down to the bare minimum.