一个独立的 PHP 命令行组件,提供命令及 Action 管理、参数校验、分层帮助、表格、实时输出和交互选择。可用于自己的 CLI 工具,也可由其他组件提供命令,再交给宿主应用注册。
需要 PHP 8.1+、mbstring 扩展和 Composer。不依赖 Swoole 或 EasySwoole 主框架。3.x 的 PHP 接口与 2.x 不兼容。
在自己的项目中引入 3.x 开发分支:
composer require easyswoole/command:3.x本地开发时可使用相邻的 command 仓库,见本地依赖配置。
如果已经下载本仓库,在仓库根目录运行下面的命令即可先体验现成示例:
composer install
php examples/cache.php
php examples/cache.php cache
php examples/cache.php cache clear --store=default
php examples/cache.php cache clear --help前两条 PHP 命令分别显示命令列表、Action 列表;第三条执行清理;第四条显示该 Action 的用法和参数。
在自己的项目根目录创建两个文件,和 vendor/ 放在同一级目录:
my-cli/
├── vendor/
├── GreetCommand.php
└── console.php
一个命令实现 CommandInterface 的两个方法:definition() 描述用法,execute() 执行业务。下面是可以直接复制的完整文件:
<?php
use EasySwoole\Command\Console\Console;
use EasySwoole\Command\Contracts\CommandInterface;
use EasySwoole\Command\Definition\CommandDefinition;
use EasySwoole\Command\Definition\Option;
use EasySwoole\Command\Input\Input;
use EasySwoole\Command\Result\CommandResult;
final class GreetCommand implements CommandInterface
{
public function definition(): CommandDefinition
{
$name = Option::string('name', '如何称呼你', default: '世界');
$definition = CommandDefinition::create('greet');
$definition->description('输出一条问候');
$definition->option($name);
return $definition;
}
public function execute(Input $input, Console $console): CommandResult
{
return CommandResult::success('你好,' . $input->option('name') . '!');
}
}Option::string() 把 --name 声明为字符串选项。用户没有提供时,$input->option('name') 返回默认值 世界。
入口只负责加载依赖、注册命令和执行:
<?php
require __DIR__ . '/vendor/autoload.php';
require __DIR__ . '/GreetCommand.php';
use EasySwoole\Command\Application;
$app = new Application('我的命令行');
$app->addCommand(new GreetCommand());
exit($app->run(array_slice($argv, 1)));run() 接收的数组不包含脚本名称,所以这里使用 array_slice($argv, 1)。它负责输出结果并返回退出码,入口再用 exit() 交给 Shell。
php console.php greet
# 你好,世界!
php console.php greet --name=张三
# 你好,张三!
php console.php
# 显示已注册的命令
php console.php greet --help
# 显示 greet 的描述、参数和默认值带值选项使用 --name=张三,也支持旧式的 -name=张三。目前不支持 --name 张三 这种空格分隔的写法。
每份指南都说明代码放在哪里、如何调用以及会得到什么结果;不必先理解内部解析器或状态机。
| 需求 | 从哪里开始 |
|---|---|
一个 cache 命令支持 clear、warmup 等 Action |
命令与 Action |
| 字符串、整数、布尔开关、位置参数 | 定义和读取参数 |
| 必填、不能为空、枚举、数值范围、自定义校验 | 校验参数 |
| 两个参数互斥、至少提供一个参数 | 整组输入校验 |
多次传入 --id=1 --id=2 |
多值选项 |
| 判断用户是否主动传入某个参数 | 输入来源 |
| 输出文字、颜色、表格 | 普通输出 |
| 提问、确认、单选、多选和搜索 | 交互输入 |
| 实时刷新状态表格 | 实时输出 |
| 禁止交互,或输出 JSON 供脚本读取 | 自动化脚本 |
| 注入命令依赖、Provider、延迟工厂、中间件 | 组件接入 |
| 返回结果、设置退出码、捕获异常和写日志 | 结果、异常观察 |
独立命令直接执行,有 Action 的命令先选择操作。以仓库里的缓存示例为例:
| 调用 | 行为 |
|---|---|
php examples/cache.php |
列出顶层命令 |
php examples/cache.php cache |
列出 cache 下的 Action 及各自参数 |
php examples/cache.php cache clear --store=default |
校验参数,然后执行 clear |
php examples/cache.php cache clear --help |
只显示 clear 的帮助 |
php examples/cache.php help cache clear |
同样显示 clear 的帮助 |
帮助和参数校验早于业务工厂、中间件。定义命令时应只描述用法,数据库连接、框架初始化等工作放到执行阶段。
| 示例 | 运行方式 | 可以学到什么 |
|---|---|---|
| 缓存入口、CacheCommand、MemoryCache | php examples/cache.php cache clear --store=default |
构造函数注入、多个 Action、必填与非空校验、帮助示例 |
| 交互入口、DemoProvider、DemoCommand | php examples/console.php demo console |
Provider、搜索、多选、确认 |
| 同一个交互示例 | php examples/console.php demo console --live |
彩色状态表格、定时刷新、键盘退出 |
选择和实时视图请在终端中运行。原始按键交互需要 POSIX 终端和 stty;无法使用原始模式时,选择器可退回编号输入。输入不是终端时,需要显式提供业务参数,组件不会自动选择或确认。
composer test
python3 tests/terminal_test.py测试分工、内部目录与执行流程见开发说明。server、process 等业务命令由宿主框架或其他组件实现。