maximebf / consolekit
Library to create command line utilities
Installs: 95 463
Dependents: 10
Suggesters: 2
Security: 0
Stars: 114
Watchers: 16
Forks: 22
Open Issues: 3
Requires
- php: >=5.3.0
This package is not auto-updated.
Last update: 2024-10-26 12:33:40 UTC
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();