library droid

droid/droid

Droid: a Taskrunner to Build, Test, CI, deploy your app

, _(*1)

Droid is a task-runner, similar to Apache Ant, Gulp, Grunt, Phing, etc., _(*2)

It helps you to automatically build your project, compile assets, create directory structures, run and validate tests, setup fixtures, and eventually deploy your app., _(*3)

Tasks are implemented as standard Symfony Commands, allowing you to use standard existing commands to script your builds., _(*4)

Installation

Add the following line to your composer.json:, _(*5)

"require": {
   "droid/droid": "~1.0"
}

Then run composer update to install your updated required packages., _(*6)

Configuring droid for your project

Create a droid.yml file in the root of your repository. For example:, _(*7)

targets:
   default:
      name: "Building it"
      tasks:
         - "composer:install":
            prefer: dist
         - "bower:install": ~
   cs:
      requires:
         - default
      tasks:
         - "phpcs:check": ~

   test:
      requires:
         - build
         - cs
      tasks:
         - "phpunit:test": ~

   deploy:
      requires:
         - build
      loop:
         -
            host: app1.example.com
            port: 22
         -
            host: app2.example.com
            port: 2222

      tasks:
         - "deploy:ssh":
            sshkey: "{{ deploy.sshkey }}"
            basepath: "/code/myapp/"

At the top level, you define the "targets". When you run droid, you always pass a target name. It uses target name "default" if none is specified., _(*8)

For each target, you can define a set of "tasks". Each task has a command name (for example "core:echo") and a list of arguments for that command., _(*9)

Running droid

Running a target

vendor/bin/droid run

This will run the "default" target., _(*10)

Alternatively, you can specify which target to run:, _(*11)

vendor/bin/droid run test

Listing available commands

vendor/bin/droid list

This lists the available commands you can use in your droid.yml file., _(*12)

Registering your own custom commands

To register custom commands, you can add the following section to your droid.yml:, _(*13)

register:
    - Haigha\Command\LoadCommand: ~

When you list the available commands, you'll find that Haiga's fixture:load command has been added to the available command list. You can now use it as a command in your target tasks., _(*14)

If you'd like to change the default 'name' for the registered command, simply pass a name parameter:, _(*15)

register:
    - Haigha\Command\LoadCommand:
        name: "haigha:load"

Creating plugins for Droid

Droid plugins are composer packages that can automatically register their commands in droid. The consuming application won't need to use the register key in their droid.yml., _(*16)

You can easily turn your php package into a Droid plugin by including a class called DroidPlugin in the root of your library's PHP namespace. For example, if your project's namespace is 'Acme\MyApp', you can add a file in the root of that namespace called 'DroidPlugin' like this:, _(*17)

<?php

namespace Acme\MyApp;

class DroidPlugin
{
    public function __construct($droid)
    {
        $this->droid = $droid;
    }

    public function getCommands()
    {
        $commands = [];
        $commands[] = new \Acme\MyApp\Command\MyFirstCommand();
        $commands[] = new \Acme\MyApp\Command\MySecondCommand();
        return $commands;
    }
}

The constructor gets access to the Droid\\Application instance. You'll need to implement a method called getCommands that returns a list of Symfony Console Commands., _(*18)

After including both droid/droid and your custom package in a project, you'll have access to all of the default Droid commands, and all the commands returned by your DroidPlugin::getCommands method., _(*19)

Get information about a command

To see how you can use a command, run:, _(*20)

vendor/bin/droid help core:echo

This will list the available arguments and options available in the core:echo command., _(*21)

You can simply add these arguments in your droid.yml file like this:, _(*22)

   tasks:
      - "core:echo":
         message: "Hello world from the echo task!"
      - "core:echo":
         message: "This should be in red"
         color: "red"

When you're trying to use a command, and forget to specify any required arguments, droid will tell you what's missing., _(*23)

TODO:

• [ ] Finish core commands (this is WIP!)
• [ ] Implement a set of commands, for running composer, bower, deploy and other functionality
• [ ] Split core commands into droid-plugin repositories
• [ ] Implement commands for building docker containers

License

MIT. Please refer to the license file for details., _(*24)

Brought to you by the LinkORB Engineering team

Check out our other projects at linkorb.com/engineering., _(*25)

Btw, we're hiring!, _(*26)