README

优雅的 PHP CLI 库

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

为什么选择 Commando？

PHP 的 $argv 魔术变量和全局 $_SERVER['argv'] 让我感到不适，getopt 也没有好到哪里去，而且大多数其他的 PHP CLI 库在许多情况下都过于臃肿。Commando 没有太多的开销就直奔主题，在处理 CLI 输入时消除了常见的样板代码，同时提供了一个干净且易于阅读的接口。

安装

Commando 要求您正在运行 PHP 8.1 或更高版本。

Commando 遵循 PSR-0 标准，并可以使用 Composer 安装。将 nategood/commando 添加到您的 composer.json

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

如果您是 Composer 新手...

下载并构建 Composer
使其全局可用
在您将要编写 Commando 脚本的目录下执行 cd 并运行 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();

// Define an incremental flag "-e" aka "--educate"
$hello_cmd->option('e')
    ->aka('educate')
    ->map(function($value) {
        $postfix = array('', 'Jr', 'esq', 'PhD');
        return $postfix[$value] === '' ? '' : " {$postfix[$value]}";
    })
    ->count(4);

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

echo "Hello {$hello_cmd['title']}$name{$hello_cmd['educate']}!", 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!

> php hello.php -ceet Mr 'nate good'
Hello, Mr. Nate Good esq!

注意事项

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

内置帮助

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

错误消息

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

命令方法

这些选项在“命令”级别上起作用。

`useDefaultHelp (bool help)`

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

`setHelp (string help)`

帮助页面前面要添加的文本。使用此功能描述命令的总体情况，也许还可以提供一些命令的示例用法。

`printHelp()`

打印命令的默认帮助。如果您希望在没有传递任何参数的情况下输出帮助，则很有用。

`beepOnError (bool beep=true)`

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

`getOptions`

返回每个提供给命令的选项的选项数组。

`getFlags`

仅返回提供给命令的标志的选项数组。

`getArguments`

仅返回提供给命令的参数的选项数组。数组的顺序与参数的顺序相同。

`getFlagValues`

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

`getArgumentValues`

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

命令选项定义方法

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

`option (mixed $name = null)`

别名：o

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

`flag (string $name)`

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

`argument ()`

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

`alias (string $alias)`

别名：a，aka

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

`description (string $description)`

别名：d，describe，describedAs

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

`require (bool $require)`

别名：r，required

要求指定此标志。

`needs (string|array $options)`

别名：无

要求设置其他选项才能使用此选项。

`must (Closure $rule)`

别名：N/A

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

`map (Closure $map)`

别名：cast，castTo

对此选项的值执行映射操作。接受一个接受字符串$value并返回混合（你可以映射到任何你想要的）的函数。

`reduce (Closure $reducer [, mixed $seed])`

别名：list，each，every

在命令中的每个选项实例上执行累积/归约函数。接受一个累积函数，并返回混合（你可以返回任何值）。如果您还为选项提供了映射，则映射将在传递给累积函数之前对每个值执行。如果提供了$seed值，则将其用作默认值。

签名：function(mixed $accumulated, mixed $value) : mixed

$accumulated：null|Option::default|mixed（函数最后返回的值，选项默认值或null。）
$value：mixed（选项后面的值。如果提供了映射，则映射函数返回的值。）
return：mixed（任何你想要的。最后返回的值成为解析后的Option的值。）

`referToAs (string $name)`

别名：title，referredToAs

添加一个名称来通过名称引用参数选项。使帮助文档对匿名“参数”选项更清晰。

`boolean ()`

别名：N/A

指定标志是布尔类型标志。

`增量（int $max）`

别名：i、count、repeats、repeatable

指定标志为计数类型标志。每次在命令中使用标志时，标志的值将增加到$max的值。将选项设置为increment或boolean类型的选项可以一起分组。

`默认值（mixed $defaultValue）`

别名：defaultsTo

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

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

`文件（file）`

别名：expectsFile

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

`boolean ()`

别名：N/A

指定标志是布尔类型标志。

`默认值（mixed $defaultValue）`

别名：defaultsTo

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

`文件（file）`

别名：expectsFile

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

贡献

Commando强烈鼓励提交拉取请求。在提交拉取请求时，请

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

灵感

在MIT许可证下发布。

变更日志

v1.0.1

添加对负数的支持，以防止将其误解释为无效选项。

v1.0.0

停止支持PHP 8.1之前的版本

v0.4.0

停止支持5.4和5.5，增加次要版本号
PR #93 特性：添加reducer选项
PR #95 修复：在Windows OS上删除tput调用
PR #101 修复：仅当该选项实际使用时才评估选项的'needs'约束
PR #76 修复：使用匿名参数时，修复非空getArgumentValues数组的问题

v0.3.0

删除PHP 5.3

v0.2.9

PR #63 特性：增量标志
PR #60 次要：getDescription方法

v0.2.8

修复#34的bug

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()来返回所有“标志”的值数组
命令现在实现了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

nategood / commando

维护者

详细信息

README

优雅的 PHP CLI 库

为什么选择 Commando？

安装

示例

内置帮助

错误消息

命令方法

useDefaultHelp (bool help)

setHelp (string help)

printHelp()

beepOnError (bool beep=true)

getOptions

getFlags

getArguments

getFlagValues

getArgumentValues

命令选项定义方法

option (mixed $name = null)

flag (string $name)

argument ()

alias (string $alias)

description (string $description)

require (bool $require)

needs (string|array $options)

must (Closure $rule)

map (Closure $map)

reduce (Closure $reducer [, mixed $seed])

referToAs (string $name)

boolean ()

增量（int $max）

默认值（mixed $defaultValue）

文件（file）

boolean ()

默认值（mixed $defaultValue）

文件（file）

贡献

灵感

变更日志

v1.0.1

v1.0.0

v0.4.0

v0.3.0

v0.2.9

v0.2.8

v0.2.7

v0.2.6

v0.2.5

v0.2.4

v0.2.3

v0.2.2

v0.2.1

v0.2.0

v0.1.4

v0.1.3

v0.1.2

`useDefaultHelp (bool help)`

`setHelp (string help)`

`printHelp()`

`beepOnError (bool beep=true)`

`getOptions`

`getFlags`

`getArguments`

`getFlagValues`

`getArgumentValues`

`option (mixed $name = null)`

`flag (string $name)`

`argument ()`

`alias (string $alias)`

`description (string $description)`

`require (bool $require)`

`needs (string|array $options)`

`must (Closure $rule)`

`map (Closure $map)`

`reduce (Closure $reducer [, mixed $seed])`

`referToAs (string $name)`

`boolean ()`

`增量（int $max）`

`默认值（mixed $defaultValue）`

`文件（file）`

`boolean ()`

`默认值（mixed $defaultValue）`

`文件（file）`