Symfony Console 是 PHP CLI 应用的事实标准，可单独安装、API 稳定、生态完善；最小运行需三要素：入口文件创建 Application 并 add() 命令、命令类继承 Command 并实现 configure()/execute()、入口加可执行权限。
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，是不同方法的设计意图不同。
-
confirm()：返回布尔值，适合“是否继续？”场景；按y/Y/yes返回true，其他（含空回车）默认false；加true参数可设默认为true -
choice()：提供预设选项列表，用户输数字或关键词匹配；不支持模糊搜索，但可设$default和$attempts（重试次数） -
askHiddenResponse()：专用于密码等敏感输入，自动禁用回显；它不校验内容，需手动判断空值或长度 - 所有交互方法都通过
$input和$output注入，不可在configure()中调用
参数与选项的声明陷阱：argument vs option 的语义边界
错误地把本该是 --env=prod 的配置项写成必需 argument（如 myapp:deploy prod），会导致脚本难以组合调用、帮助信息误导用户、无法设置默认值。
立即学习“PHP免费学习笔记（深入）”；
- Argument 是位置型、必需（除非设
InputArgument::OPTIONAL或InputArgument::IS_ARRAY）、无前缀；适合核心操作对象，比如user:delete <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 组件本身不接管信号，长任务需自行处理中断
交互逻辑越复杂，越要提前想清楚输入路径是否可预测、错误是否可感知、退出码是否可被 Shell 脚本消费。别让“用户按回车就卡住”成为上线后的第一个工单。
