mirror of
https://github.com/inigoflores/ds-codigos-postales-ine-es.git
synced 2024-06-21 04:15:53 +02:00
204 lines
6.4 KiB
Markdown
204 lines
6.4 KiB
Markdown
# ConsoleKit
|
|
|
|
PHP 5.3+ library to create command line utilities.
|
|
|
|
[](http://travis-ci.org/maximebf/ConsoleKit)
|
|
|
|
## 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](https://github.com/maximebf/ConsoleKit/blob/master/example.php)
|
|
|
|
## Installation
|
|
|
|
The easiest way to install ConsoleKit is using [Composer](https://github.com/composer/composer)
|
|
with the following requirement:
|
|
|
|
{
|
|
"require": {
|
|
"maximebf/consolekit": ">=1.0.0"
|
|
}
|
|
}
|
|
|
|
Alternatively, you can [download the archive](https://github.com/maximebf/ConsoleKit/zipball/master)
|
|
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](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md).
|
|
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](https://github.com/maximebf/ConsoleKit/blob/master/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();
|
|
|
|
|