README

© 2010 Jason Frame [ jason@onehackoranother.com / @jaz303 ]
Released under the MIT License.

A wee clone of Ruby's rake for PHP 5.3. Uses closures for ultimate coolness.

Questions abut phake? Come and chat in #phake on Freenode!

Usage

• Download
• Create a Phakefile in the current directory or a parent directory
• Invoke ./phake task:name to invoke task or ./phake -T to list defined tasks

Defining Tasks

Define tasks like this:

task('dependency1', function() { echo "i will run first!\n"; }); task('dependency2', function() { echo "i will run second!\n"; }); task('task_name', 'dependency1', 'dependency2', function() { echo "i will run last!\n"; }); 

This task would be invoked from the command line by ./phake task_name

Task bodies are optional if you want to create some sort of "super-task" that just invokes a bunch of others:

task('foo', 'dep1', 'dep2'); 

And multiple bodies can be added to tasks, all of which will be executed when the task is invoked:

task('foo', function() { echo "task work item 1\n"; }); task('foo', function() { echo "task work item 2\n"; }); 

Grouping Tasks

Like Rake, we can group tasks:

group('db', function() { task('init', function() { echo "i'm initialising the database\n"; }); }); 

This would be invoked by ./phake db:init

Describing Tasks

Call desc() immediately before defining a task to set its description:

desc("Initialises the database"); task('db_init', function() { echo "oh hai it's a database\n"; }); 

Output from ./phake -T:

db_init Initialises the database 

After/Before Blocks

Sometimes you may want to specify that some code should run before or after a task (distinct from dependencies), a bit like Capistrano. Phake supports this:

before('foo', function() { ... }); after('baz:bar', function() { ... }); 

Task Arguments

Phake allows arguments to specified on the command line:

# Execute task `quux` with the given args ./phake quux name=Jason city=Glasgow 

This format must be matched exactly; do not put spaces between = and the argument name/value. If you need to put spaces in the argument value, place the entire assignment in quotes.

Arguments are made available to tasks by the application object's ArrayAccess implementation:

task('task_with_args', function($app) { $name = $app['name']; $city = $app['city']; // do some stuff... }); 

Aborting Execution

To abort execution of a task sequence, simply throw an exception.

desc('Demonstrate failure'); task('fail', function() { throw new Exception; }); 

Running phake fail will yield:

- jason@disco phake % ./bin/phake fail (in /Users/jason/dev/projects/phake) aborted! Exception (See full trace by running task with --trace) 

A Somewhat More Complete Example

This is what a complete Phakefile might look like. It also highlights some of the more complex name resolution issues arising when dealing with groups.

<?php desc('Load the application environment'); task('environment', function() { echo "I am the outer environment. I should run first.\n"; }); desc('Initialises the database connection'); task('database', function() { echo "I am initialising the database...\n"; }); group('test', function() { // 'environment' dependency for this task is resolved locally to // task in same group. There is no 'database' task defined in this // group so it drops back to a search of the root group. desc('Run the unit tests'); task('units', 'environment', ':environment', 'database', function() { echo "Running unit tests...\n"; }); // another level of nesting; application object is passed to all // executing tasks group('all', function() { desc('Run absolutely every test everywhere!'); task('run', 'test:units', function($application) { echo "All tests complete! ($application)\n"; }); }); }); // duplicate group definitions are merged group('test', function() { // duplicate task definitions are merged // (although the first description takes precedence when running with -T) desc("You won't see this description"); task('units', function() { echo "Running a second batch of unit tests...\n"; }); // use ':environment' to refer to task in root group // we currently have no cyclic dependency checking, you have been warned. task('environment', ':environment', function() { echo "I am the inner environment. I should run second.\n"; }); }); task('default', 'test:all:run'); ?> 

Here's the output from ./phake (implied task to run is default):

jason@ratchet phake [master*] $ ./phake (in /Users/jason/dev/projects/phake) I am the outer environment. I should run first. I am the inner environment. I should run second. I am initialising the database... Running unit tests... Running a second batch of unit tests... All tests complete! (<phake\Application>) 

And the corresponding output from phake -T:

jason@ratchet phake [master*] $ ./phake -T (in /Users/jason/dev/projects/phake) database Initialises the database connection environment Load the application environment test:all:run Run absolutely every test everywhere! test:units Run the unit tests 

Bash Autocompletion

Bashkim Isai has created phake-autocomplete, a bash-completion script for phake task names.