README

PHP 5.3+ library to create command line utilities.

Example

In cli.php:

<?php class HelloCommand extends ConsoleKit\Command { public function execute(array $args, array $options = array()) { $this->writeln('hello world!', ConsoleKit\Colors::GREEN); } } $console = new ConsoleKit\Console(); $console->addCommand('HelloCommand'); $console->run(); 

In the shell:

$ php cli.php hello hello world! 

More examples in example.php

Installation

The easiest way to install ConsoleKit is using Composer with the following requirement:

{ "require": { "maximebf/consolekit": ">=1.0.0" } } 

Alternatively, you can download the archive and add the src/ folder to PHP's include path:

set_include_path('/path/to/src' . PATH_SEPARATOR . get_include_path()); 

ConsoleKit does not provide an autoloader but follows the PSR-0 convention.
You can use the following snippet to autoload ConsoleKit classes:

spl_autoload_register(function($className) { if (substr($className, 0, 10) === 'ConsoleKit') { $filename = str_replace('\\', DIRECTORY_SEPARATOR, trim($className, '\\')) . '.php'; require_once $filename; } }); 

Usage

Options parser

The default options parser parses an argv-like array. Items can be of the form:

• --key=value
• --key
• -a
• -ab (equivalent of -a -b)

When an option has no value, true will be used. If multiple key/value pairs with the same key are specified, the "key" value will be an array containing all the values.
If "--" is detected, all folowing values will be treated as a single argument

Example: the string "-a -bc --longopt --key=value arg1 arg2 -- --any text" will produce the following two arrays:

$args = array('arg1', 'arg2', '--any text'); $options = array('a' => true, 'b' => true, 'c' => true, 'longopt' => true, 'key' => 'value'); 

Creating commands

Any callbacks can be a command. It will receive three parameters: the arguments array, the options array and the console object.

function my_command($args, $opts, $console) { $console->writeln("hello world!"); } 

Commands can also be defined as classes. In this case, they must inherit from ConsoleKit\Command and override the execute() method.

class MyCommand extends ConsoleKit\Command { public function execute(array $args, array $opts) { $this->writeln("hello world!"); } } 

The ConsoleKit\Command class offers helper methods, check it out for more info.

Registering commands

Commands need to be registered in the console object using the addCommand() method (or addCommands()).

$console = new ConsoleKit\Console(); $console->addCommand('my_command'); // the my_command function $console->addCommand('MyCommand'); // the MyCommand class $console->addCommand(function() { echo 'hello!'; }, 'hello'); // using a closure // or: $console->addCommand('hello', function() { echo 'hello!'; }); // alternative when using a closure 

Notice that in the last example we have provided a second argument which is an alias for a command. As closures have no name, one must be specified.

The command name for functions is the same as the function name with underscores replaced by dashes (ie. my_command becomes my-command).

The command name for command classes is the short class name without the Command suffix and "dashized" (ie. HelloWorldCommand becomes hello-world).

Running

Simply call the run() method of the console object

$console->run(); $console->run(array('custom arg1', 'custom arg2')); // overrides $_SERVER['argv'] 

Automatic help generation

The help command is automatically registered and provides help about available methods based on doc comments.
Check out example.php for example of available tags

$ php myscript.php help 

Formating text

Colors

The ConsoleKit\Colors::colorize() method provides an easy way to colorize a text. Colors are defined as either a string or an integer (through constants of the Colors class).
Available colors: black, red, green, yellow, blue, magenta, cyan, white.

Foreground colors are also available in a "bold" variant. Suffix the color name with "+bold" or use the OR bit operator with constants.

echo Colors::colorize('my red text', Colors::RED); echo Colors::colorize('my red text', 'red'); echo Colors::colorize('my red bold text', Colors::RED | Colors::BOLD); echo Colors::colorize('my red bold text', 'red+bold'); echo Colors::colorize('my red text over yellow background', Colors::RED, Colors::YELLOW); 

TextFormater

The ConsoleKit\TextFormater class allows you to format text using the following options:

• indentation using setIndent() or the indent option
• quoting using setQuote() or the quote option
• foreground color using setFgColor() or the fgcolor option
• background color using setBgColor() or the bgcolor option

Options can be defined using setOptions() or as the first parameter of the constructor.

$formater = new ConsoleKit\TextFormater(array('quote' => ' > ')); echo $formater->format("hello!"); // produces: " > hello" 

Widgets

Dialog

Used to interact with the user

$dialog = new ConsoleKit\Widgets\Dialog($console); $name = $dialog->ask('What is your name?'); if ($dialog->confirm('Are you sure?')) { $console->writeln("hello $name"); } 

Box

Wraps text in a box

$box = new ConsoleKit\Widgets\Box($console, 'my text'); $box->write(); 

Produces:

******************************************** * my text * ******************************************** 

Progress bar

Displays a progress bar

$total = 100; $progress = new ConsoleKit\Widgets\ProgressBar($console, $total); for ($i = 0; $i < $total; $i++) { $progress->incr(); usleep(10000); } $progress->stop();