Stam

Simple Task Automator

What?

A way of encapsulating little snippets of stuff that you occasionally need to run within a project, gluing them together and making it easy to pass values into them. Less than Phing or Ant or Grunt, but more than a loose collection of script files.

How?

Make a file called stam.yml and put it in your project directory. If, for example, you put the following into that file...

stam:
    properties:
        build-dir:
            value: build

    tasks:
        test-coverage:
            description: Run unit tests and generate coverage information.
            properties:
                - build-dir
            script: |
                phpunit --bootstrap vendor/autoload.php --coverage-clover $1/logs/clover.xml tests

...and then run stam test-coverage then stam will run phpunit and get it to output coverage data into a directory called ./build.

Stam will warn you if any task exits with a status other than 0. (COMING SOON)

Details

Let's break it down. First we specify the kinds of values we want to pass around. We call these "properties", we describe them as entries directly under the properties section, and we can then specify some more options below each one.

value: # the literal value of the property. The user will be asked if you don't specify one.
default: # a default value to give the user if we ask them. You can't use this if you use `value` above.
description: # a nice description of what the property is for.
ask_once: # (COMING SOON) Ask only on first run, then store the answer for next time.

If you don't want to specify any of those, just use a tilde: my-property: ~

E.g.

stam:
    properties:
        build-dir:
            description: The place to put build artefacts.
            default: build

        environment:
            value: dev

        mode: ~

Next we have the task list. Tasks have the following options:

description: # a nice description of what the task does
interpreter: # the application used to interpret the script. Defaults to /bin/bash, but could be /usr/bin/php or whatever
properties: # a list of the properties the script needs to use. These will be passed into the script as command line arguments in the order they are defined here.
path: # a path to a script file to be run (specify this OR script)
script: # the actual script to be run. Start with a pipe (|) and newline if this needs to be multi-line.
depends: # (COMING SOON) A list of other tasks that must be run befoe this one. Stam will halt if any dependencies exit with a status other than 0.

Example

Some useful tasks for a Symfony 2 application

stam:
    properties:

        environment:
            default: dev
            ask_once: true
            description: The application environment


    tasks:

        cycle-cache:
            description: Clear and warmup the cache
            properties: [environment]
            interpreter: /bin/bash
            script:|
                 app/console cache:clear --env=$1
                 app/console cache:warmup --env=$1

        build:
            description: Full application build
            interpreter: /bin/bash
            properties: [environment]
            script:|
                composer install
                app/console assetic:dump --env=$1

Installation

Add the following to the require-dev section of composer.json

"jezhalford/stam": "dev-master"