Build Automation with Composer Scripts

Following Alexander Cogneau’s introduction to dependency management with Composer, you now know that Composer is a resolver for managing external project dependencies and versioning constraints. But is that all it does? In this article I’ll show you how Composer can also be used as a basic build automation tool.

Composer Scripts

Any build automation tool worth its salt must provide the ability to script a range of automated tasks – from building, packaging, and running test suites, to deployment on staging and production systems. Phing, for example, is based on Ant and permits you to define such tasks in XML build files.

Composer differs in this regard in that it makes no assumptions as to what these tasks are, or if they are to be performed at all. What Composer does instead is expose its pre- and post- install/update/uninstall event hooks during execution which you can callback using “scripts”, much the same way that Pyrus provides the ability to define custom commands in the package.xml via the --plugin option to its install, upgrade, and uninstall commands.

The scripts property is defined in the root JSON object of your root package’s composer.json file. You can define any number of PHP static methods (which must be autoloadable by Composer’s autoloader mechanism), command-line executables, or a combination of both.

Any custom code or package-specific commands defined by these scripts are then called during Composer’s execution process. The caveat is that only the scripts defined in the root package’s composer.json are executed. Composer will not execute any scripts specified in a dependency of the root package.

The following events are fired during the Composer execution process:

• pre-install-cmd – occurs before the install command is executed
• post-install-cmd – occurs after the install command is executed
• pre-update-cmd – occurs before the update command is executed
• post-update-cmd – occurs after the update command is executed
• pre-package-install – occurs before a package is installed
• post-package-install – occurs after a package is installed
• pre-package-update – occurs before a package is updated
• post-package-update – occurs after a package is updated
• pre-package-uninstall – occurs before a package is uninstalled
• post-package-uninstall – occurs after a package is uninstalled

These are fairly self-explanatory, and I think you will agree, that beauty lies in its simplicity. But to illustrate, here’s an example root package composer.json:

{
    "name": "MyProject",
    "description": "An example to demonstrate the use of Composer scripts",
    "version": "1.0.0",
    "require": {
        "php": ">=5.3",
        "ext-xsl": "*",
        "ext-imap": "*",
        "ext-gd": "*"
      },

    "autoload": {
        "psr-0": {
            "MyProject": "src/"
        }
    },

    "scripts": {
        "pre-install-cmd": "MyProject\Installer::preInstall",
        "post-install-cmd": [
            "MyProject\Installer::postInstall"
        ],
        "post-package-install": [
            "MyProject\Installer::postPackageInstall",
            "phpunit -c /tests",
            "./bin/install.sh"
        ]
    }
}

I’ve defined some scripts for the pre-install-cmd, post-install-cmd, and post-package-install events. As you can see, we can define any combination of static PHP methods and command-line executables. In the case of the post-package-install event, it also executes some unit tests and a custom install script.

Here’s what our example script looks like:

<?php
namespace MyProject;
use ComposerScriptEvent;

class Installer
{
    public static function preInstall(Event $event) {
        // provides access to the current ComposerIOConsoleIO
        // stream for terminal input/output
        $io = $event->getIO();
        if ($io->askConfirmation("Are you sure you want to proceed? ", false)) {
            // ok, continue on to composer install
            return true;
        }
        // exit composer and terminate installation process
        exit;
    }

    public static function postInstall(Event $event) {
        // provides access to the current Composer instance
        $composer = $event->getComposer();
        // run any post install tasks here
    }

    public static function postPackageInstall(Event $event) {
        $installedPackage = $event->getComposer()->getPackage();
        // any tasks to run after the package is installed?
    }
}

When each of these events are fired, Composer’s internal event handler passes a ComposerScriptEvent object as the first (and only) argument to each of the callbacks. The Event object exposes the following getters for other Composer objects to your callback:

• getComposer() – returns the current instance of ComposerComposer
• getName() – returns the name of the event being fired
• getIO() – returns the current input/output stream which implements ComposerIOIOInterface for reading/writing to the console

You can refer to the Composer API documentation for each of the method signatures and for the other methods that each of these objects expose – in particular, the Composer instance and the IO interface.

While this seemingly rudimentary implementation may not appear as “powerful” as Phing definitions, its simplicity belies its incredible flexibility. It leverages your existing knowledge investment in PHP, and with a little creativity and imagination you can use Composer’s dependency resolver and native PHP scripting to create some fairly complex build and take-down tasks. You could even integrate this into Jenkins for continuous integration.

Summary

In this article, I’ve introduced a rudimentary example of how Composer scripts can be used to perform build automation. These tasks can be as simple or as complex as you require, since they leverage your existing knowledge investment in PHP. And hopefully, this article will inspire you to use Composer for more than just dependency management. For more information on how to use Composer scripts, see getcomposer.org/doc/articles/scripts.md.

Image via Fotolia