先完成 README 的 GreetCommand。本页介绍独立命令以外的用法;缓存示例的完整文件已经放在 examples/Cache。
README 中的 greet 是独立命令:
php console.php greet --name=张三它没有 Action,选项和位置参数直接添加到 CommandDefinition。执行时:
$input->command(); // 'greet'
$input->action(); // null定义中的名称只写 greet,不包含 php、脚本名称或完整命令路径。
希望支持下面两种调用时,用一个 CommandDefinition 加两个 ActionDefinition:
php examples/cache.php cache clear --store=default
php examples/cache.php cache warmup --store=redis定义逻辑放在命令类中。以下是 CacheCommand::createDefinition() 的基本组织方式;文件顶部引入这些类:
use EasySwoole\Command\Definition\ActionDefinition;
use EasySwoole\Command\Definition\CommandDefinition;
use EasySwoole\Command\Definition\Option;先建立各个 Action,再组装命令,避免多层嵌套:
$store = Option::string('store', '缓存存储名称', required: true);
$clear = ActionDefinition::create('clear');
$clear->description('清理缓存');
$clear->option($store);
$warmup = ActionDefinition::create('warmup');
$warmup->description('预热缓存');
$warmup->option($store);
$definition = CommandDefinition::create('cache');
$definition->description('缓存管理');
$definition->action($clear);
$definition->action($warmup);
return $definition;create() 只接收一个名称:写 create('cache') 和 create('clear'),不要写 create('cache clear')。
命令类仍然只实现一个 execute(),用 $input->action() 分发。下面是该方法的主体;clear() 和 warmup() 是同一命令类中的私有业务方法:
return match ($input->action()) {
'clear' => $this->clear($input),
'warmup' => $this->warmup($input),
default => throw new LogicException('未定义的缓存操作'),
};完整的分发及业务方法见 CacheCommand,入口和依赖组装见 cache.php。
一个顶层命令只注册一次,它的 Action 随定义一起注册。Action 的名称、选项及校验相互独立,未知 Action 返回退出码 2。
有 Action 的命令,参数和整组校验都放到 Action 上;独立命令才直接放到 CommandDefinition 上。 两种模式不能混用。
输入未知命令或 Action 时,组件会提示相近的已注册名称。Action 建议只来自当前命令。比如输错 clear 时:
php examples/cache.php cache celar
# unknown action: celar on cache. Did you mean cache clear?退出码仍为 2,用户需要按正确名称重新执行。没有相近名称时只显示原错误。
不需要单独实现 help 命令。组件从注册的定义读取名称、描述、参数类型及默认值:
php examples/cache.php
php examples/cache.php cache
php examples/cache.php cache clear --help
php examples/cache.php help cache clear四种形式分别显示命令列表、Action 列表、指定 Action 的详细帮助,以及同一份详细帮助。
可以在定义中增加使用示例。例如在缓存命令的 createDefinition() 中,创建 $clear 之后、加入命令之前添加:
$clear->example(
'php examples/cache.php cache clear --store=redis',
'清理 Redis 缓存',
);详细帮助会显示 Usage、类型、实际必填标记、默认值、隐式值和示例。分组列表保持简洁。各层级的帮助请求都会检查选项名,未知选项会返回退出码 2。根级和命令分组帮助只接受内置的 --help,独立命令和 Action 的帮助可接受各自声明的选项。以 help 开头的入口遵循同样的规则。帮助请求会跳过必填项、类型转换和值校验,也不会创建延迟业务实例或执行中间件。
终端中的命令及 Action 名称为红色,标题为绿色,参数名称为黄色。重定向输出、设置 NO_COLOR 或 TERM=dumb 时使用纯文本。
命令、Action 和参数名称区分大小写。名称以英文字母开头,可包含字母、数字、下划线和横线。顶层名称 help、选项名称 help 为保留入口;Action 可以命名为 help。
execute() 返回 CommandResult。下面这些写法相互独立,放在业务方法结束的位置:
return CommandResult::success('操作完成');return CommandResult::success('已处理', data: ['count' => 3]);return CommandResult::failure('目标不存在');要显式指定「输入错误」,先在命令文件顶部引入 EasySwoole\Command\Result\ExitCode,再在业务方法中返回结果。
return CommandResult::failure('参数不合法', exitCode: ExitCode::INVALID_INPUT);message 用于展示,data 保存结构化业务结果。普通文本模式只自动输出 message;程序调用或 JSON 模式可以读取 data。
标准退出码定义在 EasySwoole\Command\Result\ExitCode 整数枚举中。
| 枚举 | 数值 | 含义 |
|---|---|---|
ExitCode::SUCCESS |
0 |
命令成功,或成功显示帮助 |
ExitCode::FAILURE |
1 |
一般执行失败、未指定退出码的 CommandResult::failure(),或命令结果编码、写入失败 |
ExitCode::INVALID_INPUT |
2 |
未知命令或 Action,以及输入解析、类型转换或参数校验失败 |
ExitCode::forSignal($signal) |
128 + 信号编号 |
原始终端会话中捕获到的外部信号。例如 SIGTERM(15)对应 143 |
CommandResult 的构造函数和 failure() 接受枚举值或整数。例如业务可以用 CommandResult::failure('目标暂不可用', exitCode: 10) 返回自定义退出码。通过 Shell 启动时,调用者应使用 0 到 255 之间的整数。Shell 可能截断越界值,例如 256 会被读成成功码 0。
$result->exitCode、run() 的返回值和 JSON 中的 exitCode 都是整数。PHP 代码可用 ExitCode::SUCCESS->value 比较,Shell 脚本可用 $? 读取命令的退出码。
实时视图中的 q、Esc、Ctrl+C 用于退出视图,最终退出码由命令返回的结果决定。
入口脚本一般用 run(),它输出结果并返回退出码。如果另一个 PHP 组件只想取得结果,使用 dispatch()。
下面代码放在 README 的 console.php 中、注册命令之后,替换原来的 exit(...):
use EasySwoole\Command\Result\ExitCode;
$result = $app->dispatch(['greet', '--name=张三']);
if ($result->exitCode === ExitCode::SUCCESS->value) {
echo $result->message; // 你好,张三!
}dispatch() 不自动输出返回结果的 message,但业务主动调用 Console 的输出仍会发生。两种入口传入的数组都不含脚本名称。
需要由调用方决定输出流和格式时,可将同一个 Console 传入,再显式输出结果:
use EasySwoole\Command\Console\Console;
$console = new Console(json: true);
$result = $app->dispatch(['greet', '--name=张三'], $console);
$console->writeResult($result);JSON 模式的流分离和数据要求见自动化输出。