README

由于看起来已废弃并且我需要一个新版本进行标记，所以从 https://github.com/nategood/commando 分支出来。

优雅的 PHP CLI 库

Commando 是一个 PHP 命令行界面库，它美化和简化了编写用于命令行使用的 PHP 脚本。

为什么？

PHP 的 $argv 魔术变量和全局 $_SERVER['argv'] 让我感到恶心，getopt 也不是很好，而且大多数其他的 PHP CLI 库都过于 OOP 肥胖。Commando 在没有大量开销的情况下直接处理业务，在处理 CLI 输入时移除了常见的样板代码，同时提供了一个干净且易于阅读的接口。

安装

Commando 需要您运行 PHP 5.3 或更高版本。

Commando 遵循 PSR-0 规范，并可以使用 Composer 进行安装。将 nategood/commando 添加到您的 composer.json 文件中。

"require": {
    "nategood/commando": "*"
}

如果您是 Composer 的初学者...

• 下载并构建 Composer
• 使其 全局可用
• 切换到您将要编写 Commando 脚本的目录，然后运行 composer install

目前，通过 Composer 安装是唯一支持的方式。

示例

以下是一个 PHP Commando 脚本的示例，它详细介绍了 Commando 的功能。假设它在一个名为 hello.php 的文件中。

<?php

require_once 'vendor/autoload.php';

$hello_cmd = new Commando\Command();

// Define first option
$hello_cmd->option()
    ->require()
    ->describedAs('A person\'s name');

// Define a flag "-t" a.k.a. "--title"
$hello_cmd->option('t')
    ->aka('title')
    ->describedAs('When set, use this title to address the person')
    ->must(function($title) {
        $titles = array('Mister', 'Mr', 'Misses', 'Mrs', 'Miss', 'Ms');
        return in_array($title, $titles);
    })
    ->map(function($title) {
        $titles = array('Mister' => 'Mr', 'Misses' => 'Mrs', 'Miss' => 'Ms');
        if (array_key_exists($title, $titles))
            $title = $titles[$title];
        return "$title. ";
    });

// Define a boolean flag "-c" aka "--capitalize"
$hello_cmd->option('c')
    ->aka('capitalize')
    ->aka('cap')
    ->describedAs('Always capitalize the words in a name')
    ->boolean();

$name = $hello_cmd['capitalize'] ? ucwords($hello_cmd[0]) : $hello_cmd[0];

echo "Hello {$hello_cmd['title']}$name!", PHP_EOL;

运行它

> php hello.php Nate
Hello, Nate!

> php hello.php --capitalize nate
Hello, Nate!

> php hello.php -c -t Mr 'nate good'
Hello, Mr. Nate Good!

注意事项

• Commando 实现了 ArrayAccess，因此当您需要检索它的值时，它表现得就像一个数组
• 对于“匿名”（即未命名的标志）参数，我们根据它们的数字索引来访问它们
• 我们可以通过标志的名称或别名来访问选项值
• 我们可以在选项定义中直接使用闭包来执行验证和映射操作

内建的帮助

Commando 内置了自动 --help 支持。使用此标志调用您的脚本将根据您的选项定义和 Commando 设置打印出一个美观的帮助页面。如果您定义了一个别名名为 'help' 的选项，它将覆盖内置支持。

错误消息

默认情况下，Commando 将捕获在解析过程中发生的异常。取而代之的是，Commando 将将格式化、用户友好的错误消息打印到标准错误，并以代码 1 退出。如果您希望 Commando 在这些情况下抛出异常，请调用您的 Command 实例上的 doNotTrapErrors 方法。

命令方法

这些选项在“命令”级别上工作

useDefaultHelp (bool help)

Commando的默认行为是提供--help选项，该选项会输出一个有用的帮助页面，该页面基于您的选项定义生成。通过调用useDefaultHelp(false)禁用此功能。

setHelp (string help)

附加到帮助页面的文本。使用此文本来描述命令的高级功能和命令的一些示例用法。

beepOnError (bool beep=true)

当发生错误时，打印字符以使终端发出“哔哔”声。

getOptions

返回一个数组，其中包含命令提供的每个选项的Option。

getFlags

返回一个数组，其中只包含命令提供的Option的标志。

getArguments

返回一个数组，其中只包含命令提供的Options的参数。数组的顺序与参数的顺序相同。

getFlagValues

返回命令提供的参数的值关联数组。例如：array('f' => 'value1')。

getArgumentValues

返回命令提供的参数的值数组。例如：array('value1', 'value2')。

命令选项定义方法

尽管这些选项链接到一个Command实例，但它们在“选项”级别上工作。

option (mixed $name = null)

别名：o

定义一个新的选项。当设置name时，该选项将是一个命名的“标志”选项。可以是短形式选项（例如，选项-f的f）或长形式（例如，选项--foo的foo）。如果没有定义name，则该选项是一个匿名参数，并且将来通过其位置引用。

flag (string $name)

与option相同，但它只能用于定义“标志”类型选项（即那些必须在命令行上使用-flage指定的选项）。

argument ()

与option相同，但它只能用于定义“参数”类型选项（即那些在命令行上不使用-flage指定的选项）。

alias (string $alias)

别名：a，aka

为命名选项添加别名。此方法可以多次调用以添加多个别名。

description (string $description)

别名：d，describe，describedAs

描述此选项的文本。此文本将用于构建“帮助”页面，因此它是面向最终用户的。

require (bool $require)

别名：r，required

要求指定此标志

needs (string|array $options)

别名：无

要求设置其他 $options，以便使用此选项。

must (Closure $rule)

别名：无

定义一个规则来验证输入。接受一个字符串 $value 作为参数的函数，并返回一个布尔值，表示 $value 是否有效。

map (Closure $map)

别名：cast，castTo

对此选项的值执行映射操作。接受一个字符串 $value 作为参数的函数，并返回 mixed（可以映射到任何内容）。

referToAs (string $name)

别名：title，referredToAs

为通过名称引用的参数选项添加一个名称。使帮助文档对于匿名的“参数”选项更加整洁。

boolean ()

别名：无

指定标志为布尔类型。

default (mixed $defaultValue)

别名：defaultsTo

如果未指定值，则默认为 $defaultValue。

在 boolean() 类型标志的情况下，当标志存在时，此选项的值将是 $defaultValue 的否定。也就是说，如果您有一个默认值为 true 的 -b 标志，当 -b 作为命令行标志存在时，选项的值将是 false。

file ()

别名：expectsFile

为此选项指定的值必须是一个有效的文件路径。当使用相对路径时，将转换为完全限定的文件路径，并且也支持globbing。请参阅 file.php 示例。

贡献

Commando 高度鼓励提交拉取请求。当提交拉取请求时，请

• 所有拉取请求都应该针对 dev 分支（而不是 master）
• 确保您的代码遵循在 PSR-1 和 PSR-2 中规定的编码标准
• 确保您为更改添加了适当的测试覆盖率
• 通过 phpunit ./tests 在测试目录中运行所有单元测试
• 在适当的位置添加注释，并添加描述性的拉取请求消息

灵感

• Commander
• Optimist

在 MIT 许可下发布。

变更日志

v0.2.7

• getOptions 添加（以及一些更好的文档）

v0.2.6

• 添加对 "needs" 的支持，以定义选项之间的依赖关系（感谢 @enygma） PR #31
• 修复了长参数名称的问题 问题 #30

v0.2.5

• 修复了布尔选项的默认值，自动将布尔选项默认设置为false（不太可能，但可能是破坏性更改） PR #19

v0.2.4

• 添加了定义选项默认值的功能

v0.2.3

• 改进了帮助格式 PR #12

v0.2.2

• 修复了打印重复帮助信息的bug PR #10

v0.2.1

• 添加了对要求选项为有效文件路径或通配符的支持
• 返回完全限定的文件路径名（例如，将相对路径转换为绝对路径）
• 在通配符的情况下返回文件路径数组
• 请参阅examples目录中的file.php示例

v0.2.0

本次更新的主要目标是更好地区分标志选项和参数选项。在Commando中，标志是我们定义的选项，在命令行指定时需要名称。参数是没有这样命名的选项。以下示例中，'-f'和'--long'在Commando术语中被描述为“标志”类型的选项，分别具有'value1'和'value2'的值，而value3、value4和value5被描述为“参数”类型的选项。

php command.php -f value1 --long value2 value3 value4 value5

• 添加了Command::getArguments()以返回一个“参数”类型的Option数组（参见argumentsVsFlags.php示例）
• 添加了Command::getFlags()以返回一个“标志”类型的Option数组（参见argumentsVsFlags.php示例）
• 添加了Command::getArgumentValues()以返回“参数”的所有值的数组
• 添加了Command::getFlagValues()以返回“标志”的所有值的数组
• 现在Command实现了Iterator接口，并将遍历所有选项，从参数开始，然后按字母顺序继续到标志
• 现在可以使用Command::flag($name)和Command::argument()定义选项，除了Command::option($name)
• 添加了为参数添加“标题”的功能，以便通过标题引用参数，使帮助文档更加简洁（运行help.php示例）
• 清理了生成的帮助文档
• 修复了显示错误时附加的颜色化红色线条的bug

v0.1.4

• 修复了具有多个单词的选项值bug

v0.1.3

• 在终端中添加了蜂鸣声支持
• 添加了Commando::beepOnError()

v0.1.2

• 更新了终端以正确使用tput