README

使用 PHP 创建出色的 CLI 应用程序的框架。

安装

将以下内容添加到 composer.json

"require": {
	"adeptoas/sweet-cli": "^1.4.0"
}

确保合并您的 require-blocks！

示例

有关示例，请查看 /example。在那里您将找到创建 CLI 应用程序的逐步教程。

概念

您的 CLI 应用程序将包括主入口点和您的子命令。每个子命令都可以有选项和参数，并可以自由执行所需的任何操作。命令看起来像这样

• cli subcommand -o -n 2 --long-opt --long-opt-string Example
• cli subcommand -on 2 --long-opt "Some Argument"
• cli -vv subcommand -on 2
• …

如何构建应用程序

1. 创建一个您想要用作“二进制”并运行的文件。我建议使用 cli。

2. 将以下内容放在文件顶部（之前没有任何内容！）

   #!/usr/bin/env php
   <?php

3. 包含 composer 自动加载器

   require 'vendor/autoload.php';

4. 从 Adepto\SweetCLI\Base\CLIApplication 继承并重写这些方法

   • public static function getTitle(): string
   • public static function getShortTitle(): string

5. 为每个需要的子命令继承 Adepto\SweetCLI\Subcommands\SubCommand 并重写这些方法

   • public static function getOptions(): array（请参阅选项语法）
   • public static function getCommand(): string
   • public static function getDescription(): string

6. 实例化您的应用程序（其中 Application 是您的类名。如果您使用了 PHP 匿名类，则不需要此步骤。）

   $app = new Application(__FILE__);

7. 将您创建的新子命令类添加到您的应用程序中（不要创建实例！）

   $app->addSubCommand(SomeSubCommand::class);
   $app->addSubCommand(SomeOtherSubCommand::class);

8. （可选）添加别名

   $app->addAlias('npm');
   $app->addAlias('php', '/usr/local/bin/php');

   别名是特殊的子命令，它们收集所有传递的参数并调用另一个应用程序，例如 cli composer -v -> composer -v。如果将路径传递给应用程序的构造函数，则将在应用程序的工作目录中运行命令。

9. 调用 $app->run($argv)。

10. 使您的脚本可执行： chmod +x cli

11. 您现在可以运行它： ./cli --help

选项语法

创建子命令时，必须重写 getOptions(): array 方法。这必须返回一个数组，其中包含该子命令可用的选项。每个项目的键必须是选项规范，值是另一个数组，包含修饰符。

这是选项规范

• o → -o [布尔值]
• option → --option [布尔值]
• o|option → -o 和 --option [布尔值]
• o: → -o [布尔值，必需]
• o+ → -o value [字符串值]
• o:+ → -o value -o value2 [字符串值，必需]

简而言之

• : → 必需
• + → 允许值
• | → 替代

这是可用的修饰符列表

• "desc" => "Some Description" → 帮助页面上的描述。留空以使选项不可见。
• "default" => "Some Value" → 如果未提供选项，则默认为 "Some Value"。
• "validValues" => [1, 2, 3] → 只允许 1、2 或 3 作为选项。
• "type" => "number" → 只允许数字。

用法

子命令

这是您将用于在子命令中执行操作的公共 API 的描述。

checkConflictingOptions()

检查 hasConflictingOptions() 是否返回 true，如果是，则抛出异常。

hasDuplicateBoolean(bool $bool, array $values): bool

如果 $bool 在 $values 中出现多次，则返回 true。

hasOptions(): bool

检查是否给出了此子命令的选项。

hasOption(string $option): bool

检查是否给出了特定的 $option。

getOption(string $option): mixed

获取特定选项的值，如果未设置则返回 null。

setOption(string $option, mixed $value)

设置选项的值。请谨慎使用！

requireOption(string $option, string $message)

要求设置选项，如果未设置则使用 $message 终止。

getApp(): CLIApplication

获取子命令被调用的应用程序。如果您有多个应用程序使用相同的子命令，这可以帮助您根据应用程序决定要做什么。

检查 $option 是否已设置，如果未设置则抛出一个包含 $message 的异常。