README

PHP 5.3+ 版本的库，用于创建命令行工具。

示例

在 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();

在壳中

$ php cli.php hello
hello world!

更多示例在 example.php

安装

安装 ConsoleKit 最简单的方法是使用 Composer 并满足以下要求

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

或者，您可以直接下载存档并将 src/ 文件夹添加到 PHP 的 include 路径

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

ConsoleKit 不提供自动加载器，但遵循 PSR-0 协议。
您可以使用以下代码片段来自动加载 ConsoleKit 类

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

使用方法

选项解析器

默认选项解析器解析类似 argv 的数组。项可以是以下形式

--key=value
--key
-a
-ab (相当于 -a -b)

如果一个选项没有值，则使用 true。如果指定了具有相同键的多个键/值对，则 "key" 值将是一个包含所有值的数组。
如果检测到 "--"，则所有后续值将被视为单个参数

示例：字符串 "-a -bc --longopt --key=value arg1 arg2 -- --any text" 将生成以下两个数组

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

创建命令

任何回调都可以是命令。它将接收三个参数：参数数组、选项数组和控制台对象。

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

命令也可以定义为类。在这种情况下，它们必须继承自 ConsoleKit\Command 并覆盖 execute() 方法。

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

ConsoleKit\Command 类提供了辅助方法，请参阅更多信息。

注册命令

需要使用 addCommand() 方法（或 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

注意，在最后一个示例中，我们提供了一个第二个参数，它是命令的别名。由于闭包没有名称，必须指定一个。

函数的命令名称与函数名称相同，只是用短横线代替下划线（例如，my_command 变为 my-command）。

命令类的命令名称是短类名，去掉 Command 后缀并 "短横线化"（例如，HelloWorldCommand 变为 hello-world）。

运行

只需调用控制台对象的 run() 方法。

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

自动帮助生成

自动注册 help 命令并提供基于文档注释的可用方法帮助。
查看 example.php 以获取可用标签的示例。

$ php myscript.php help

格式化文本

颜色

ConsoleKit\Colors::colorize() 方法提供了一个轻松的颜色化文本的方法。颜色可以定义为字符串或整数（通过 Colors 类的常量）。
可用的颜色：black, red, green, yellow, blue, magenta, cyan, white。

前景颜色也有 "bold" 变体。在颜色名称后加 "+bold" 或使用常量的 OR 位运算符。

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

ConsoleKit\TextFormater 类允许您使用以下选项格式化文本：

使用 setIndent() 或 indent 选项设置缩进
使用 setQuote() 或 quote 选项进行引用
使用 setFgColor() 或 fgcolor 选项设置前景色
使用 setBgColor() 或 bgcolor 选项设置背景色

可以使用 setOptions() 或构造函数的第一个参数来定义选项。

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

小部件

对话框

用于与用户交互

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

框

将文本包裹在框中

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

生成

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

进度条

显示进度条

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

maximebf / consolekit

维护者

详细信息