Including PHP libraries via Composer

Differences with PEAR

Composer manages libraries on a per-project basis, instead of installing system-wide packages like PEAR does. It manages dependencies, complete of a specified branch or version, more than packages or developers tools. This approach was inspired by the Node Package Manager, npm.

Recursive dependencies (libraries that depends on other libraries) are of course supported on both PEAR and Composer; PEAR has the autodiscover parameter to solve the multiple channels problem, while Composer features every package on packagist.org.

The main package source used by Composer seems more similar to the usage of git submodules at a first glance: a list of dependencies on other projects is specified and stored under version control, and upon a checkout these projects are grabbed directly from their repositories.

Issues

Thus there are potentially two criticisms to Composer's model: the issue of grabbing source instead of a build of the package (containing tests and other machinery along with the source code), and the presence of single point of failure where all packages are listed, Packagist.

The problem of grabbing the whole source of a project is related to simplicity. For example, by acquiring PHPUnit_Selenium with Composer (*composer* repository) you'll take down also its tests suite and unrelated files like a folder full of sample HTML pages. With Composer you have all you need for doing development on a dependency instead of what you need for only using it.

It must be added that Composer does not force you into this, as it now supports also depending on PEAR packages or even simply from zip files. What it lacks is a standard repository for built packages, but if you already have your PEAR channel you can publish your builds on it and we'll be able to install them.

The single point of failure is the Packagist central repository, which continuously rebuilds available packages by scanning the source repositories of the registered projects. It's possible to clone the open source application and host your own (internal or public) package repository. What it's not possible at this time is listing built packages on Packagist; but the single point of failure issue is more pressant as a single website that goes down could take with itself the PHP community.

Installation

The installation of Composer is really easy:

curl -s http://getcomposer.org/installer | php -- --install-dir=bin

I have put it in ~/bin folder since it is on my path; if you do the same, you will be able to just type composer.phar as a command from everywhere.

Example project

One of the common dependency problems to solve is importing an ORM like Doctrine 2. In this example, we define a dependency on doctrine-orm, which depends on doctrine/dbal and ultimately also on doctrine/common.

All metadata should be written in a composer.json file at the top level of the project:

{
    "require": {
        "doctrine/orm": "2.2.1"
    }
}

Being a project supporting Composer, the Doctrine 2 ORM lists its own dependencies and we only have to require the main package we need.

Executing:

$ composer.phar install

will take some seconds to download the packages, with a subjectively faster protocol that PEAR's.

Here's the end result:

$ tree -L 4
.
├── composer.json
├── composer.lock
└── vendor
    ├── bin
    └── doctrine
        ├── common
        │   ├── build.properties
        │   ├── build.xml
        │   ├── composer.json
        │   ├── lib
        │   ├── LICENSE
        │   ├── phpunit.xml.dist
        │   ├── README.md
        │   ├── tests
        │   ├── UPGRADE_TO_2_1
        │   └── UPGRADE_TO_2_2
        ├── dbal
        │   ├── bin
        │   ├── build.properties
        │   ├── build.xml
        │   ├── composer.json
        │   ├── lib
        │   ├── LICENSE
        │   ├── phpunit.xml.dist
        │   ├── README.md
        │   ├── run-all.sh
        │   ├── tests
        │   └── UPGRADE
        └── orm
            ├── bin
            ├── build.properties
            ├── build.properties.dev
            ├── build.xml
            ├── composer.json
            ├── doctrine-mapping.xsd
            ├── lib
            ├── LICENSE
            ├── phpunit.xml.dist
            ├── README.markdown
            ├── run-all.sh
            ├── tests
            ├── tools
            ├── UPGRADE_TO_2_0
            ├── UPGRADE_TO_2_1
            ├── UPGRADE_TO_2_2
            ├── UPGRADE_TO_ALPHA3
            └── UPGRADE_TO_ALPHA4

15 directories, 32 files

Not only composer has downloaded the projects and put them in the vendor/, it also generated autoloading files:

<?php
require_once 'vendor/.composer/autoload.php';
// searches for the class allowing autoloaders to be called
var_dump(class_exists('Doctrine\ORM\EntityManager', true)); // dumps bool(true)

Note that also a composer.lock file is created, containing information about the resolved versions of the dependencies. For example, if you depend on Doctrine 2 by specifying 2.* as the version, the lock file will contain 2.2.1. You can either commit the lock file if you want a reproducible build (my choice for projects) or making your VCS ignore it for simplicity if you do not want to manually update it periodically.