PHP Packages Installing Composer Packages

PHP Packages

Installing Composer Packages

Problem

You want to install packages using Composer.

Solution

Use Composer’s require command:

       % php composer.phar require vendor/package:version

For example, to install the latest 2.x version of the PHP_CodeCoverage library from PHPUnit:

       % php composer.phar require phpunit/php-code-coverage:2.*

Or use a composer.json file:

       {

              "require" : {

                     "phpunit/php-code-coverage": "2.*"

              }

       }

with Composer’s install command:

       % php composer.phar install

Discussion

Composer reads instructions from a file, composer.json, to calculate a set of packages you want it to install.

This file is a simple JSON document. The most important element is the require key. This tells Composer which packages you need to have. For example:

       {

              "require": {

                     "phpunit/php-code-coverage": "2.1.*"

              }

       }

This says you require the package php-code-coverage published by phpunit, and you’re willing to take any version, as long as it’s somewhere in the 2.1s.

Create this file using any text editor, or use Composer itself with the require command:

       % php composer.phar require vendor/package:version

This creates (or edits) the file and adds the necessary JSON.

Composer uses a combination of vendor and package as a simple way to namespace packages. Many people have created packages with the same basic names, such as log or json or db. This lets you specify exactly which one.

In some cases, the vendor and the package have the same name. For example, guzzle/guzzle. That’s okay.

The composer.json file can contain multiple packages with more sophisticated instructions:

       {

              "require": {

                     "phpunit/php-code-coverage": "2.1.*",

                     "guzzle/guzzle": ">=3.7.0",

                     "monolog/monolog": "1.7.0"

              }

       }

This asks for any 2.1.x version of phpunit/php-code-coverage (but less than 2.2.0), any version of guzzle/guzzle 3.7.0 or higher (including 3.8 and 4.0), and only version 1.7.0 of monolog/monolog (and nothing else).

To trigger the install, use the install command:

       % php composer.phar install

These packages may have their own dependencies, which the vendor specifies in its own composer.json file. This includes a version of PHP, specific PHP extensions (such as cURL), and other packages (such as a basic logging class).

During installation, Composer automatically checks your system for these require‐ ments. If you don’t meet them, it will attempt to fix this (by downloading packages) or complain (if you need to upgrade PHP).

By convention, Composer places all installed packages inside a vendor folder in the current working directory. This keeps everything in one place and allows you to easily add this folder to your .gitignore file.

After installation, Composer writes out a file named composer.lock with the exact set of packages and version it installed. This allows you to “lock in” the particular set of packages that work for your application. That way, in case you encounter some unexpected change in one of the packages when you upgrade, you can always recover to a “known good” set.

To use a package, require Composer’s standard autoloader code at the top, then declare the namespace of your package, and instantiate the object. This is the beginning of a script that uses the Guzzle HTTP Client:

       require 'vendor/autoload.php';

       use Guzzle\Http\Client;

  

       // Create a client to work with the LinkedIn API

       $client = new Client('https://api.linkedin.com/{version}', array(

              'version' => 'v1'

       ));

The mystery of how Composer can have a short autoloader class, yet still manage to find all the packages, is solved through standards.

Two separate packages found on Packagist don’t promise any form of similar design or architecture. However, many packages do commit to various levels of interoperability.

They do so by implementing a set of standards defined by a working group of developers of PHP Frameworks.

PSRs, for PHP Standards Recommendation, lets you know how two packages will behave with each other. The most critical one is PSR-0, the autoloading standard. When you have many packages, each with its own file naming and directory syntax, it’s not easy to know how to properly require them into your code.

Packages that implement PSR-0 agree to a common set of conventions for namespaces and how their PHP files, and the directories they’re located in, are named and organized. This allows any PSR-0–compatible package to safely live alongside every other PSR-0 package and to be loaded using one common autoload function.

All packages managed by Composer follow this standard. This allows Composer to make it easy for you to use them.