README

PHP 7.2+ CLI管理器

CommandoX是一个PHP命令行界面库，它美化了PHP脚本（用于命令行使用）的编写，并简化了这一过程。这是Nate Good废弃的Commando项目的PHP 7.2+版本，可在此处找到：(https://www.github.com/nategood/commando)

为什么？

应避免使用PHP的$argv魔法变量和全局$_SERVER['argv']，封装或抽象它们以实现适当的OOP设计。PHP的getopt并没有显著改进，而大多数其他PHP CLI库都过于OOP膨胀。CommandoX在处理CLI输入时提供了一个干净且可读的接口，没有过多的开销或常见的样板代码。

安装

CommandoX需要您运行PHP 7.2或更高版本。

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

"require": {
    "tolidano/commandox": "*"
}

如果您是Composer的新手...

下载并构建Composer
使其全局可用
转到您将编写CommandoX脚本的目录，并运行composer install

通过Composer安装是唯一支持的方法。

示例

以下是一个PHP CommandoX脚本的示例，它展示了CommandoX的功能

<?php declare(strict_types = 1);

require_once 'vendor/autoload.php';

$hello_cmd = new CommandoX\Command();

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

// Define a flag "-t" aka "--title"
$hello_cmd->option('t')
    ->aka('title')
    ->describedAs('When set, use this title to address the person')
    ->must(function($title) {
        $titles = ['Mister', 'Mr', 'Misses', 'Mrs', 'Miss', 'Ms'];
        return in_array($title, $titles);
    })
    ->map(function($title) {
        $titles = ['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 = ['', 'Jr.', 'Esq.', 'PhD'];
        return $postfix[$value];
    })
    ->count(4);

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

print("Hello {$hello_cmd['title']} $name {$hello_cmd['educate']}!" . PHP_EOL);

运行它（将上面的脚本保存为hello.php）

> php hello.php Shawn
Hello, Shawn!

> php hello.php --capitalize shawn
Hello, Shawn!

> php hello.php -c -t Mr 'shawn tolidano'
Hello, Mr. Shawn Tolidano!

> php hello.php -ceet Mr 'shawn tolidano'
Hello, Mr. Shawn Tolidano Esq.!

注意事项

CommandoX实现了\ArrayAccess，因此当您从其中检索值时，它表现得像一个数组
对于“匿名”（即非命名选项）参数，根据它们的数字索引访问它们
我们可以通过标志的名称或别名来访问选项值
我们可以在选项定义中使用闭包来执行验证（->must()）和映射操作（->map()）

自动帮助

CommandoX内置了自动-h/--help支持。使用此标志调用您的脚本（无论是-h还是--help）将打印出一个基于您的选项定义和CommandoX设置的帮助页面。如果您定义了一个名为或别名为h或help的选项，它将覆盖此内置支持。

错误消息

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

命令方法

以下选项在“命令”级别上起作用。

`useDefaultHelp (bool help)`

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

`setHelp (string help)`

将附加到帮助页面上的文本。使用此功能来描述命令的高级内容，并提供一些命令的用法示例。

`printHelp()`

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

`beepOnError (bool beep=true)`

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

`getOptions`

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

`getFlags`

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

`getArguments`

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

`getFlagValues`

返回一个关联数组，其中包含命令提供的参数的值。例如：['f' => 'value1']。

`getArgumentValues`

返回一个数组，其中包含命令提供的参数的值。例如：['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)`

别名：无

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

`must (Closure $rule)`

别名：无

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

`map (Closure $map)`

别名：cast、castTo

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

`referToAs (string $name)`

别名：title、referredToAs

添加一个名称来通过该名称引用一个参数选项。这使得匿名“参数”选项的帮助和错误消息更清晰。

`boolean ()`

别名：无

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

`increment (int $max)`

别名：i、count、repeats、repeatable

指定标志是计数器标志。标志的值将在命令中每次使用标志时递增，直到达到$max的值。可以将在increment或boolean类型中设置的选项组合为一个单一选项。

`default (mixed $defaultValue)`

别名：defaultsTo

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

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

`file ()`

别名：expectsFile

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

贡献

CommandoX鼓励提交拉取请求。

运行composer install以拉取require-dev依赖项（composer update）
安装pre-commit钩子（使用./scripts/installHook.sh自动检查您的代码）
在PR中针对master分支
遵循PSR-1和PSR-2编码标准
为您的更改添加适当的测试覆盖率（覆盖率必须超过90%）
通过phpunit从tests目录运行所有单元测试（使用composer全局安装phpunit 8+）
在适当的地方添加注释
添加描述性的PR消息，最好引用GitHub问题

灵感/原始

在MIT许可证下发布。

更改日志

v0.7.2（多个破坏性更改）

最低版本现在是PHP 7.2
从travis CI yaml / 测试中删除所有低于7.2的PHP版本
升级测试到PHPUnit 8标准
添加方法参数和返回类型提示

v0.5.4（多个破坏性更改）

升级到PHP 5.4，支持到7.1
从travis CI yaml / 测试中删除PHP 5.3
添加didShowHelp方法
删除所有die/exit语句，改用返回有效的退出代码
移植到新的packagist under tolidano/commandox
移植到新的GitHub仓库 under tolidano/commandox
修复dedupeFlags错误（确保每个选项/别名只被看到一次）
当为匿名参数定义标题时，在帮助和错误消息中使用标题
常量重构
省略增量选项的帮助文本
修复非空的getArgumentValues数组
允许Command子类化
使tput具有操作系统意识
帮助现在也支持-h（与现有的-h标志冲突）

v0.2.9

PR #63 特性：增量标志
PR #60 微调getDescription方法

v0.2.8

修复#34的错误

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

修复了打印双帮助的错误 PR #10

v0.2.1

添加了对要求选项必须是有效文件路径或glob的支持
返回完全限定的文件路径名称（例如，转换相对路径）
在globbing的情况下返回文件路径数组
请参阅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 示例）
清理了生成的帮助文档
修复了显示错误时额外彩色红色线条的问题

v0.1.4

修复了具有多词的选项值问题

v0.1.3

为终端添加了蜂鸣声支持
添加了 Commando::beepOnError()

v0.1.2

更新了终端以正确使用 tput

tolidano / commandox

维护者

详细信息

README

PHP 7.2+ CLI管理器

为什么？

安装

示例

自动帮助

错误消息

命令方法

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)

referToAs (string $name)

boolean ()

increment (int $max)

default (mixed $defaultValue)

file ()

贡献

灵感/原始

更改日志

v0.7.2（多个破坏性更改）

v0.5.4（多个破坏性更改）

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)`

`referToAs (string $name)`

`boolean ()`

`increment (int $max)`

`default (mixed $defaultValue)`

`file ()`