构建现代化的 PHP CLI 命令行应用：Symfony Console 组件与交互式命令开发-php教程-PHP中文网

symfony console 是 php cli 应用的事实标准，可单独安装、api 稳定、生态完善；最小运行需三要素：入口文件创建 application 并 add() 命令、命令类继承 command 并实现 configure()/execute()、入口加可执行权限。

构建现代化的 php cli 命令行应用：symfony console 组件与交互式命令开发

Symfony Console 是目前 PHP CLI 应用最成熟、最可控的选择，不是“之一”，而是事实标准。 它不依赖完整 Symfony 框架，可单独安装，且 API 稳定、文档清晰、生态完善——如果你要写一个真正需要长期维护、支持多环境、带参数校验和交互逻辑的 CLI 工具，别绕弯，直接上 symfony/console。

安装与最小可运行命令结构

从 Composer 引入后，一个能跑起来的命令只需三要素：入口文件、命令类、注册调用。常见错误是把 Application 实例和命令类耦合在同一个文件里，导致无法单元测试或复用命令逻辑。

执行 composer require symfony/console
入口文件（如 bin/myapp）只负责创建 Application 并 add() 命令实例，不写业务逻辑
命令类继承 Command，重写 configure() 和 execute()；configure() 里定义 setName()、setDescription()、addArgument()、addOption()
务必给 bin/myapp 加可执行权限：chmod +x bin/myapp

处理交互式输入：confirm、choice、question 的实际差异

很多人以为 ask() 就够了，结果遇到密码输入明文回显、选项列表没默认值、确认提示不支持 Ctrl+C 中断等问题——这些不是 bug，是不同方法的设计意图不同。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

confirm()：返回布尔值，适合“是否继续？”场景；按 y/Y/yes 返回 true，其他（含空回车）默认 false；加 true 参数可设默认为 true
choice()：提供预设选项列表，用户输数字或关键词匹配；不支持模糊搜索，但可设 $default 和 $attempts（重试次数）
askHiddenResponse()：专用于密码等敏感输入，自动禁用回显；它不校验内容，需手动判断空值或长度
所有交互方法都通过 $input 和 $output 注入，不可在 configure() 中调用

参数与选项的声明陷阱：argument vs option 的语义边界

错误地把本该是 --env=prod 的配置项写成必需 argument（如 myapp:deploy prod），会导致脚本难以组合调用、帮助信息误导用户、无法设置默认值。

Argument 是位置型、必需（除非设 InputArgument::OPTIONAL 或 InputArgument::IS_ARRAY）、无前缀；适合核心操作对象，比如 user:delete <id></id>
Option 是键值型、可选、带 -- 或 - 前缀；适合配置开关或上下文，比如 --force、--timeout=30
addOption('format', 'f', InputOption::VALUE_REQUIRED, 'Output format', 'text')：第三个参数决定是否接受值，第四个是描述，第五个才是默认值——漏掉第五个不会报错，但默认值就是 null
使用 InputOption::VALUE_IS_ARRAY 时，传参必须重复写选项，如 --tag=a --tag=b，不能写成 --tag=a,b

调试与异常处理：为什么你的命令静默失败？

CLI 应用没有 Web 页面的错误页面兜底，execute() 中抛出未捕获异常时，默认行为是打印堆栈并退出码 1——但如果你在 try/catch 里吞掉了异常又没输出任何提示，用户只会看到空白返回，误以为成功。

不要在 execute() 里用 die() 或 exit()；应返回整数退出码：return Command::SUCCESS（0）或 Command::FAILURE（1）
自定义异常建议继承 RuntimeException，并在 Application 创建后调用 setCatchExceptions(true)（默认开启，但显式声明更安全）
调试时加 -v（verbose）或 -vv 可看到完整异常堆栈；生产环境可通过 --no-ansi 关闭颜色，避免日志解析失败
注意信号处理：pcntl_signal(SIGINT, ...) 不会自动触发，需手动调用 pcntl_signal_dispatch()；Console 组件本身不接管信号，长任务需自行处理中断