asar/silly

Silly is a PHP-based tool for quickly creating command line scripts.

This documentation can be found at the Silly PHP CLI Website., _(*1)

Silly: The silly little CLI tool

Silly is a PHP-based tool for quickly creating command line scripts., _(*2)

Silly makes creating command line scripts as simple as writing a PHP class definition. It’s so easy, it’s silly!, _(*3)

Requirements

• PHP 5.3+
• PHP CLI

Quick Guide

Install

Through Pear, _(*4)

$ pear channel-discover pear.brainchildprojects.org
$ pear install brainchild/Silly

OR clone source, _(*5)

$ git clone git://github.com/asartalo/Silly.git

Write Tasks

<?php
// my-silly-test.php
require_once 'Silly\Silly.php'; // or wherever you placed Silly

// Define some tasks
class MyCoolTasks implements \Silly\Tasks
{
    private $controller;

    function getTaskNamespace() {
        return '';
    }

    function setController(\Silly\Controller $controller) {
        $this->controller = $controller;
    }

    function taskSayHello() {
        $this->controller->out('Hello!');
    }
}

// Get the silly little controller
$controller = \Silly\Silly::getController(new MyCoolTasks);
// Okay, run it!
$controller->execute($argv);

Run!

$ php my-silly-test.php say-hello
Hello!

Tasks

Script commands are defined in your task list. A task list is a PHP class that implements the Silly\Tasks interface which defines a method for obtaining the controller object (Silly\Controller), and a method for setting the Task List’s namespace. When you register a task, the controller is passed before any task method is executed., _(*6)

<?php
use Silly\Tasks;

// A sample task list
class FooTasks implements Tasks {

    private $controller;

    function getTaskNamespace() {
        return '';
    }

    function setController(Silly\Controller $controller) {
        $this->controller = $controller;
    }

    function taskFoo() {
        $this->controller->out('foo');
    }
}

To be useful, task lists need to define some task methods. These are simply public methods that start with 'task'. So to define a 'foo' task:, _(*7)

<?php
use Silly\Tasks;

// A sample task list
class FooTasks implements Tasks {

    //...snip...//

    function taskFoo() {
        $this->controller->out('foo');
    }

    function taskFooBar() {
        $this->controller->out('foo-bar');
    }
}

In the previous example, you can call taskFoo by typing in the terminal:, _(*8)

$ myscript.php foo

And you can call taskFooBar by:, _(*9)

$ myscript.php foo-bar

If you want to pass some arguments to the task method, just define them as method parameters., _(*10)

<?php
use Silly\Tasks;

// A sample task list
class FooTasks implements Tasks {

    //...snip...//

    function taskHello($name) {
        $this->controller->out("Hello $name!");
    }
}

$ myscript.php hello Guwapo
Hello Guwapo!

Please note that task methods can only take scalar values from the cli. Also, there is no argument validation so not passing an argument to the hello task will issue some InvalidArgument exception or the like., _(*11)

Do You Want Flags with That?

Sometimes you’ll want to pass some flags to modify the behavior of a task. Flags can be defined by writing flag methods --methods that start with 'flag'. Like:, _(*12)

<?php
use Silly\Tasks;

class FooTasks implements Tasks {

    private $suffix = '';
    private $annoy;

    //...snip...//

    function taskFoo() {
        $output = "Foo{$this->suffix}";
        if ($this->annoy) {
            for ($i=0; $i < 3; $i++) {
                $output .= $output;
            }
        }
        $this->controller->out($output);
    }

    function flagSuffix($suffix) {
        $this->suffix = $suffix;
    }

    function flagAnnoyMe() {
        $this->annoy = true;
    }

}

$ myscript.php foo
Foo
$ myscript.php foo --suffix Bar
FooBar
$ myscript.php foo --suffix Bar --annoy-me
FooBar
FooBar
FooBar
FooBar

Namespaces

When you have a lot of tasks, a good way to make them more manageable is to group them into namespaces. Each task list can specify a namespace. To set the namespace for a task list, Tasks::getTaskNamespace() must return the namespace. For example..., _(*13)

<?php
use Silly\Tasks;

class FooTasks implements Tasks {
    //...snip...//

    function getTaskNamespace() {
        return ''; // This is the default namespace
    }

    function taskFoo() {
        $this->controller->out('Foo!');
    }

}

class BarTasks implements Tasks {
    //...snip...//

    function getTaskNamespace() {
        return 'bar';
    }

    function taskFoo() {
        $this->controller->out('Bar!');
    }
}

$controller = \Silly\Silly::getController(new FooTasks); // this registers FooTasks
$contorller->register(new BarTasks)
// Okay, run it!
$controller->execute($argv);

$ myscript.php foo
Foo!
$ myscript.php bar:foo
Bar!

Roadmap

• Argument validation
• Add shortcut flags like -f -s
• Add documentation through doc comments