如何使用PHP构建CLI工具-php教程-PHP中文网

应先用 php script.php 验证 php cli 环境是否可用，因其配置文件（如 /etc/php/8.3/cli/php.ini）与 web 模式独立，需检查扩展、内存限制、时区等设置，并用 php --ini、php -m 和最小验证脚本确认。

如何使用php构建cli工具

直接用 php script.php 运行，别急着加 shebang 或 chmod +x —— 大部分本地调试失败，都是因为跳过了这一步验证环境是否真能跑通。

怎么确认 PHP CLI 环境可用

不是看 php -v 有输出就万事大吉。CLI 模式用的是独立的配置文件（比如 /etc/php/8.3/cli/php.ini），和 Web 模式完全不共享。常见问题包括：

extension=mbstring 在 CLI 的 php.ini 里被注释了，导致脚本一用中文就报 Call to undefined function mb_strlen()
memory_limit 默认是 128M，但处理 CSV 导入时瞬间爆内存，而 Web 模式下你可能早调高了
date.timezone 未设置，date() 返回 Warning: date(): It is not safe to rely on the system's timezone settings

实操建议：

运行 php --ini 查看 CLI 实际加载的 php.ini 路径
用 php -m 确认扩展已启用（注意：CLI 和 FPM 的扩展列表可能不同）
写个最小验证脚本：php -r "echo date('c') . "\n"; echo extension_loaded('pdo_mysql') ? 'OK' : 'MISSING';"

参数解析：什么时候该用 `getopt()`，什么时候必须上 `symfony/console`

getopt() 适合单命令、无子命令、选项不超过 5 个的脚本（比如 php backup.php -d /data -c gzip --dry-run）。它原生支持短选项（-h）、长选项（--help）和带值参数（-f file.txt），但不处理：

参数顺序无关性（php cmd.php --file a.json --verbose 和 php cmd.php --verbose --file a.json 结果应一致，但 getopt() 不保证）
自动帮助文本生成（得自己 echo 一堆格式化文字）
类型校验（比如把 --port=abc 当成整数报错）
Windows cmd 下长选项被截断（--config 变成 --confi）

一旦出现以下任一情况，立刻切到 symfony/console：

需要子命令（php app.php user:create / user:delete）
参数含必填/可选/默认值/数组（如 --tag=prod --tag=staging）
要集成到 Laravel/Symfony 项目中复用服务容器

示例（symfony/console 注册一个带选项的命令）：

btpanel phpsite 宝塔面板PHP网站

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

下载

protected function configure(): void
{
    $this->setName('process:import')
         ->setDescription('Import users from CSV')
         ->addOption('file', 'f', InputOption::VALUE_REQUIRED, 'CSV path')
         ->addOption('batch-size', null, InputOption::VALUE_OPTIONAL, 'Rows per transaction', 100);
}

输入输出必须分流：别让错误信息混进正常结果

CLI 工具常被管道调用（如 php extract.php | grep "active"），如果错误也走 echo，会污染 STDIN 流，导致下游命令解析失败。

正常输出用 fwrite(STDOUT, ...) 或 echo（CLI 下 echo 默认写 STDOUT）
错误/警告必须走 fwrite(STDERR, ...)，例如：fwrite(STDERR, "Failed to connect: {$e->getMessage()} ");
用户交互（如确认删除）用 fgets(STDIN)，记得 rtrim($input, " ") 去掉换行符
彩色输出前先检测终端支持：function_exists('posix_isatty') && posix_isatty(STDOUT)，否则 ANSI 序列会变成乱码

退出码不能省：exit(0) 表示成功；exit(1) 是通用错误；自定义错误建议用 exit(2)（参数错误）、exit(3)（连接失败）等，方便 Shell 脚本判断。

为什么简单脚本也建议用 Composer + `symfony/console`

不是为了“重”，而是避免重复踩坑：

$argv 在某些 SAPI（如 HHVM 旧版）下索引行为不一致，symfony/console 封装层做了兼容
帮助文本自动对齐选项、描述、默认值，手写容易错位或漏空格
参数绑定后，$input->getArgument('file') 直接返回字符串，不用再 isset($argv[1]) ? $argv[1] : null
异常未捕获时，symfony/console 自动输出堆栈并返回非零退出码，而裸脚本可能静默失败

最小初始化只需三步：