Build Automation with Composer Scripts

Share this article

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

Frequently Asked Questions (FAQs) about Build Automation with Composer Scripts

What is the primary function of Composer in PHP development?

Composer is a dependency management tool in PHP. It allows you to declare the libraries your project depends on, and it will manage (install/update) them for you. Composer is not a package manager in the same sense as Yum or Apt are. Yes, it deals with “packages” or libraries, but it manages them on a per-project basis, installing them in a directory (e.g., vendor) inside your project.

How can I automate tasks using Composer scripts?

Composer scripts are a way to automate tasks in PHP development. They are defined in the composer.json file and can be run from the command line using the ‘composer run-script’ command. Scripts can be used to automate tasks such as testing, building, and deployment. They can also be used to run custom PHP code.

Can I use Composer scripts for testing?

Yes, Composer scripts can be used for testing. You can define a script in your composer.json file that runs your tests. For example, you could define a script called ‘test’ that runs PHPUnit. Then, you can run your tests from the command line using the ‘composer run-script test’ command.

How can I use Composer scripts for deployment?

Composer scripts can be used for deployment by defining a script in your composer.json file that performs the necessary steps to deploy your application. This could include tasks such as compiling assets, optimizing code, and uploading files to a server. Once the script is defined, you can run it from the command line using the ‘composer run-script’ command.

Can Composer scripts run custom PHP code?

Yes, Composer scripts can run custom PHP code. You can define a script in your composer.json file that runs a PHP file. The PHP file can contain any code you want. When you run the script using the ‘composer run-script’ command, the PHP code will be executed.

How can I manage scripts in Composer?

Scripts in Composer are managed in the composer.json file. Each script is defined as a key-value pair, with the key being the name of the script and the value being the command to run. You can add, modify, or remove scripts by editing the composer.json file.

Can I use Composer scripts to automate build processes?

Yes, Composer scripts can be used to automate build processes. By defining scripts in your composer.json file, you can automate tasks such as compiling code, minifying assets, and generating documentation. These scripts can then be run from the command line using the ‘composer run-script’ command.

What are the benefits of using Composer scripts for automation?

Using Composer scripts for automation can make your development process more efficient. By automating repetitive tasks, you can save time and reduce the risk of errors. Composer scripts also make your build process more consistent, as the same tasks are performed in the same way every time.

Can I use Composer scripts in conjunction with other tools?

Yes, Composer scripts can be used in conjunction with other tools. For example, you could use a Composer script to run a Gulp task, or to run a PHPUnit test suite. This allows you to leverage the capabilities of other tools while still benefiting from the automation provided by Composer scripts.

How can I learn more about using Composer scripts for automation?

There are many resources available to help you learn more about using Composer scripts for automation. The official Composer documentation is a great place to start. There are also many tutorials and blog posts available online that provide examples and best practices for using Composer scripts.

Ignatius TeoIgnatius Teo
View Author

Ignatius Teo is a freelance PHP programmer and has been developing n-tier web applications since 1998. In his spare time he enjoys dabbling with Ruby, martial arts, and playing Urban Terror.

Expert
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week