What Is Composer?

Strictly speaking, Composer is a dependency manager, rather than a package manger. This, it seems, is because it handles component relationships on a local basis, rather than centrally as Yum and Apt do. If you think that this is an overly fine distinction, you could be right. However we define it, Composer allows you to specify packages. It downloads them to a local directory (vendor), finds and downloads all dependencies, and then makes all this code available to your project via an autoloader.

As always, we need to begin by getting the tool.

Installing Composer

You can download Composer at https://getcomposer.org/download/ . You will find an installer mechanism there, but the phar file should suit most purposes:

$ wget https://getcomposer.org/download/1.2.0/composer.phar .
$ chmod 755 composer.phar
$ sudo mv composer.phar /usr/bin/composer

I download the archive and run chmod to ensure that it is executable. Then I copy it into a central location so that I can run it easily from anywhere in my system. Now I can test the command:

$ composer --version
Composer version 1.2.0 2016-07-19 01:28:52

Installing a (Set of) Package(s)

Why did I do that funky bit with the brackets? Because packages inevitably beget packages—sometimes a lot of packages.

Let’s begin with a library that stands alone, though. Imagine that we’re building an application which needs to communicate with Twitter. A little bit of research leads me to the abraham/twitteroath package. In order to install this, I need to generate a JSON file named composer.json, and then define a require element:

{
    "require": {
        "abraham/twitteroauth": "0.6.*"
    }
}

I begin with a directory that is empty apart from the composer.json file. Once I run a Composer command, though, we’ll see a change:

$ composer install
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing abraham/twitteroauth (0.6.4)
    Downloading: 100%        

Writing lock file
Generating autoload files

So what has been generated? Let’s take a look:

$ ls
composer.json  composer.lock  vendor

Composer installs packages into vendor/. It also generates a file named composer.lock. This specifies the exact versions of all packages installed. If you’re using version control, you should commit this file. If another developer runs composer install with a composer.lock file present, package versions will be installed on her system exactly as specified. In this way, the team can stay in sync with one another, and you can be sure that your production environment exactly matches the development and test environments. You can override the lockfile by running this snippet:

composer update

This will generate a new lock file. Typically, you will run this to keep current with new package versions (if you are using wildcards, as I have, or ranges).

$ composer require abraham/twitteroauth
Using version ^0.6.4 for abraham/twitteroauth
./composer.json has been created
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing abraham/twitteroauth (0.6.4)
    Loading from cache

Writing lock file
Generating autoload files

{
    "require-dev": {
        "phpunit/phpunit": "*"
    },
    "require": {
        "abraham/twitteroauth": "0.6.*",
        "ext-xml": "*"
    }
}

$ composer install
Loading composer repositories with package information
Updating dependencies (including require-dev)
  - Installing abraham/twitteroauth (0.6.4)
    Loading from cache

  - Installing symfony/yaml (v3.1.3)
    Downloading: 100%        

  - Installing sebastian/version (2.0.0)
    Downloading: 100%        
....
  - Installing phpspec/prophecy (v1.6.1)
    Downloading: 100%        

  - Installing myclabs/deep-copy (1.5.1)
    Loading from cache

  - Installing phpunit/phpunit (5.5.0)
    Downloading: 100%        

sebastian/global-state suggests installing ext-uopz (*)
phpunit/phpunit-mock-objects suggests installing ext-soap (*)
phpunit/php-code-coverage suggests installing ext-xdebug (>=2.4.0)
phpunit/phpunit suggests installing phpunit/php-invoker (∼1.1)
Writing lock file
Generating autoload files

$ composer install --no-dev
Loading composer repositories with package information
Updating dependencies
  - Installing abraham/twitteroauth (0.6.4)
    Loading from cache

Writing lock file
Generating autoload files

Composer and Autoload

We covered autoloading in some detail in Chapter 15. For the sake of completeness however, it is worth looking at it briefly. Composer generates a file named autoload.php, which handles class loading for the packages it downloads. You can also leverage this functionality for your own code by including autoload.php (usually with require_once()). Once you have done this, any class you declare in your system will be found automatically when accessed in your code, so long as your directories and filenames mirror your namespaces and class names.

In other words, a class named popp5/megaquiz/command/CommandContext must be placed in a file named CommandContext.php in the popp5/megaquiz/command/ directory.

If you want to mix things up (perhaps by omitting a redundant leading directory or two, or by adding a test directory to the search path), then you can use the autoload element to map a namespace to your file structure, like this:

    "autoload": {
        "psr-4": {
            "popp5\\megaquiz\\": ["src", "test"]
        }
    }

Now, so long as autoload.php is included, my classes are easily discoverable. Thanks to my autoload configuration, the popp5/megaquiz/command/CommandContext class will now be found in src/command/CommandContext.php. Not only that, but because I have referenced more than one target (test as well as src), I can also create test classes that belong to the popp5\megaquiz\ namespace under the test/ directory.

Turn to the “PSR-4 Autoloading” section in Chapter 15 to follow a more in-depth example.

Creating Your Own Package

If you have worked with PEAR in the past, you might expect a section on creating a package here to involve an entirely new package file. In fact, we’ve already been creating a package throughout this chapter. We just have to add some more information, and then find a way to make our code available to others.

    "name": "popp5/megaquiz",
    "description": "a truly mega quiz",
    "authors": [
        {
            "name": "matt zandstra",
            "email": "matt@getinstance.com"
        }
    ],

{
    "require": {
        "abraham/twitteroauth": "0.6.*",
        "ext-xml": "*",
        "ext-gd": "*"
    }
}

$ composer update
Loading composer repositories with package information
Updating dependencies (including require-dev)
Your requirements could not be resolved to an installable set of packages.

  Problem 1
- The requested PHP extension ext-gd * is missing from your system. Install or enable PHP's gd extension.

Distribution Through Packagist

If you’ve been working through this chapter, you might have wondered where the packages we have been installing actually come from. It feels a lot like magic, but (as you might expect) there is a package repository behind the scenes. It is called Packagist, and it can be found at https://packagist.org . So long as your code can be found in a public git repository, it can be made available through Packagist.

Let’s give it a shot. I have pushed my megaquiz project to Github, so now I need to tell Packagist about my repository. Once I have signed up, I simply add the URL of my repository. You can see this in Figure 16-1.

Figure 16-1. Adding a package to Packagist

Once I’ve added megaquiz, Packagist locates the repository, checks the composer.json file, and displays a control panel. You can see that in Figure 16-2.

Figure 16-2. The package control panel

Packagist tells me that I have not set license information. I can fix this at any time by adding a license element to the composer.json file:

"license": "Apache-2.0",

Packagist has also failed to find any version information. I’ll fix this by adding a tag to the Github repository:

$ git tag -a '1.0.1' -m '1.0.1'
$ git push –tags

Now Packagist knows about my version number. You can confirm that in Figure 16-3.

Figure 16-3. Packagist knows the version

Now, anyone can include megaquiz from another package. Here is a minimal composer.json file :

{
    "require": {
        "popp5/megaquiz": "*"
    }
}

I specify the vendor name and the package name. Riskily, I am happy to accept any version at all. Let’s go ahead and install :

$ composer install
Loading composer repositories with package information
Installing dependencies (including require-dev)
  - Installing abraham/twitteroauth (0.6.4)
    Loading from cache

  - Installing popp5/megaquiz (1.0.1)
    Downloading: 100%        

Writing lock file
Generating autoload files

Notice that the dependencies I specified when I set up megaquiz are also downloaded.

Keeping it private

Of course, you don’t always want to publish your code to the world. Sometimes you need to share only with a smaller set of authorized users.

Here is a private package named getinstance/api_util that I use for internal projects:

{
    "name": "getinstance/api_util",
    "description": "core getinstance api code",
    "authors": [
        {
            "name": "matt zandstra",
            "email": "matt@getinstance.com"
        }
    ],  
    "require": {
        "silex/silex": "∼1.3",
        "bshaffer/oauth2-server-php": "∼1.8"
    },  
    "require-dev": {
         "phpunit/phpunit": "∼4.3.0"
    },  
    "autoload": {
        "psr-4": {
            "getinstance\\api_util\\": ["src" , "test/functional"]
        }
    }
}

This is hosted in a private Bitbucket repository, so it’s not available via Packagist. So how would I include it in a project? I simply need to tell Composer where to look. I can do this by creating or adding to the repositories element:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "git@bitbucket.org:getinstance/api_util.git"
        }
    ],
    "require": {
        "popp5/megaquiz": "*",
        "getinstance/api_util": "v1.0.3"
    }
}

So now, so long as I have access to getinstance/api_util, I can install both my private package and megaquiz at once:

$ composer install

Loading composer repositories with package information
Installing dependencies (including require-dev)        
  - Installing abraham/twitteroauth (0.6.4)
    Loading from cache

  - Installing popp5/megaquiz (1.0.1)
    Loading from cache
...
  - Installing silex/silex (v1.3.5)
    Loading from cache

  - Installing getinstance/api_util (v1.0.3)
    Cloning 3cf2988875b824936e6421d0810ceea90b76d139
...
Writing lock file
Generating autoload files

Summary

You should leave this chapter with a sense of how easy it is to leverage Composer packages to add power to your projects. Through the composer.json file, you can also make your code accessible to other users, whether publicly by using Packagist or by specifying your own repository. This approach automates dependency downloads for your users and allows third-party packages to use yours without the need for bundling.