Composer

Software
Fri Software
PHP

What is Composer

Composer is a dependency manager for PHP. It makes it easy to include 3rd party libraries in your PHP project. It's inspired by npm and aims to bring some of the same ideas to PHP will fixing some of the deficiencies.

But, what about PEAR

It is true. We have had dependency management using PEAR for quite a while. Composer brings some advantages and modernizations to the table:

Pear

  • Requires libraries to follow a specific structure.
  • Installs libraries globally, not per project. Requires all libraries to be installed globally on all servers. Causes trouble with different versions of a library on servers running multiple services.

Composer

  • De-facto standard (everybody does it).
  • Install per-project, or globally, depending on library and needs.
  • Better version handling when following semver. Automatically handling of allowed versions.
  • Lazy-loading autoloader.
  • Even handles pear packages if required.

Installing Composer

Installing composer is easy, go to getcomposer.org for the latest release. Just download and run the installer: 
curl -sS https://getcomposer.org/installer | php
And the move the created composer.phar file to a bin dir, or any directory in your $PATH.

Composer basics

Using composer in your project only requires 2 files: composer.json and composer.lock. composer.json is a json formatted file which describes your project. It contains stuff like your project's dependencies, and how to load your own files, and examples: 
{
    "require": {
        "monolog/monolog": "1.12.0"
    },
    "autoload": {
        "psr-4": {
            "app\\": "src/"
        }
    }
}
This file tells composer 2 things; first is that the project is dependent on the project called monolog/monolog, in the specific version 1.12.0, second that everything in the app namespace should be loaded from the src directory, using a psr-4 autoloader.

To install your dependencies run composer.phar install This will make composer look up the package monolog/monolog in it's default repository, packagist, and try to install the required version. It will then install any requirements the monolog/monolog package might have, as well as any requirements of the required packages etc. it then sets up the required autoloaders making the use of the installed libraries a charm. The last thing it does is to create a composer.lock file, which lists all the installed packages, along with the exact version that has been installed.

Now including your required packages is as easy as including composers autoloader:

<?php

require __DIR__ . '/vendor/autoload.php';
// Your project goes here

Composer best practices

JSON builds upon a very strict syntax, and editing it by hand is error prone, and not recommended. That's where the composer cli tool saves the day.

Instead of installing new packages by adding them to the composer.json manually, it is recommended to install them using: composer.phar require {vendor/package[:version]} The version number is optional, if it isn't specified composer will find the newest version of the library and create a dependency on that version. Unless you require a specific version of a library, omitting the version number is the recommended practice. Ie. to install the newest version of monolog/monolog, run: composer.phar require monolog/monolog At the time of writing, the newest version of monolog/monolog is version 1.16.0, so the above will add the require clause:

...
"require": {
    "monolog/monolog": "~1.16"
},
...

When checking versions, ~1.16 is equivalent to ">=1.16,<2.0.0", but more on specifying versions later.

Daily usage

Daily usage of composer mainly consists of 3 commands; composer require as explained above, composer install and composer update.

composer install

Composer install is the most used of the two. The command first checks if a composer.lock file exists, if it does, it will install all of the exact versions specified in the .lock, if no .lock file exists, it will install the newest versions of the libraries allowed by the package requirements. It will then create it's required autoloaders. If the composer.lock file did not exist, it is then created, or if new packages has been added that wasn't in the previous .lock file, it will be updated.

composer update

Composer update basically does the same as composer install, except that it will ignore any existsing composer.lock file, and just install the newest allowed version. It then creates autoloaders and writes a new composer.lock file.

Bulk-updating all of a projects dependencies is bound to cause a world of pain, so it's recommended to update one dependency at a time, and then running your test suite, to make sure nothing breaks in the update process.

composer update vendor/package

Version control

composer.lock specifies the exact installed versions of all dependencies. This file should be commited to versioning system to make deployment faster and to guarantee that tested versions are installed. The vendor dir is where the actual dependecies are kept. This is a bunch of code that is already hosted on version control systems somewhere else, and should not be included in your version control system. When deploying your project, running composer install will install the required version the project has been tested with, using the composer.lock file.

Versions

Composer allows for a bunch of different ways to specify the allowed versions of each package, by specifying ranges, wildcards etc.

Most of the specifiers are built to support projects using SemVer as a promise of predictability in version numbers, so if you are a library maintainer and not using semver, please do, to make it easier for people to use your library.

Ranges

>, <, >=, <=, !=, ||, ,, (comma and space, logical AND)

Wildcard

* I.e. "2.3.*" == ">=2.3.0 <2.4"

Tilde

Recommended usage! (For libraries following semver). Specifies a min. version, and allows updates to next minor/major version, depending on specificity. I.e. "~3.6" == ">=3.6 <4.0", "~3.6.0" == ">=3.6.0 <3.7.0"

Advanced usage

So far I've went through the basic usage of composer, but it actually does quite a lot. In this last section I'll do a quick run-through of some nice to know features, but I won't be going through everything that is possible with the program.

Neat cli options

--verbose - Prints more information when running commands. --profile - Provides profiling information. --dry-run - Pretend to do install/update, but don't actually touch any files. Useful for getting an idea of what has been changed.

Composer repositories

By default composer installs from packagist, but it is possible to install from other sources like github, SitePoint has a nice tutorial on that.

Cli commands

composer.phar show -i - Show all installed libraries and their version.

composer.phar create-project namespace/project Clones the specified project and runs composer install in the install directory.

If in doubt: composer help

Further study

Some other nice features that I might touch upon in future blog posts includes:
  • Creating your own composer-ready packages
  • Scripts - allows running scripts during various parts of the installation process

References

Some nice references to know about The Composer Homepage Official documentation packagist Interactive composer cheat-sheet Composer on phptherightway.org