Composer在线学习地址：学习地址
告别命令行脚本的混乱：从痛点到解决方案
作为php开发者，我们经常需要编写各种命令行脚本来执行自动化任务、数据处理或系统维护。然而，构建一个功能完善、用户友好的cli工具远非易事。
你可能遇到过以下问题：
-
参数解析的噩梦： 每次都要手动从
$argv数组中解析各种选项（options）和参数（arguments），并处理它们的短格式（-h）和长格式（--help）。 - 缺乏帮助文档： 用户不知道你的脚本支持哪些参数，每次都要去翻代码或文档。如果能自动生成漂亮的帮助信息，那该多好！
- 恼人的输入验证： 用户输入了错误类型的参数，或者遗漏了必填参数，你的脚本直接报错退出，体验极差。你不得不编写大量条件判断来处理这些情况。
-
单命令的局限： 随着项目复杂度的提升，你可能需要像
git pull、git push那样，一个入口脚本支持多个子命令。手动实现这种逻辑，简直是自找麻烦。
PHP内置的getopt()函数虽然能提供一些基础功能，但在面对上述挑战时显得力不从心。它功能单一，缺乏灵活性，并且对用户输入的微小错误都可能导致整个命令失败。
幸运的是，PHP社区的强大生态为我们提供了完美的解决方案——vanilla/garden-cli。结合Composer，这个库能让你告别getopt()的噩梦，轻松构建功能强大、结构清晰的命令行应用程序。
引入 vanilla/garden-cli：命令行开发的利器
vanilla/garden-cli是一个功能完备且设计极其简洁的PHP命令行解析库。它提供了一套流畅的API，让你能够以声明式的方式定义命令、选项和参数，而无需与底层的getopt()或其他复杂的解析逻辑搏斗。
立即学习“PHP免费学习笔记（深入）”；
它的核心优势包括：
-
自动生成帮助信息： 无需额外编写，你的命令自动支持
--help选项，并输出格式优美的帮助文档。 - 支持单命令或多命令模式： 无论是简单的单功能脚本，还是像Git那样拥有多个子命令的复杂工具，它都能轻松应对。
- 强大的参数解析与验证： 自动解析选项，支持各种数据类型（字符串、整数、布尔、数组），并提供自动验证和清晰的错误提示。
- 简洁优雅的API： 学习成本低，即使是基本的命令行脚本也能轻松实现鲁棒的参数解析。
vanilla/garden-cli要求PHP 8.1或更高版本，并通过Composer进行安装。
第一步：安装 vanilla/garden-cli
使用Composer，安装vanilla/garden-cli非常简单：
composer require vanilla/garden-cli:"~4.0"
这会将库及其依赖项添加到你的项目中。
第二步：定义你的第一个CLI应用
让我们通过一个简单的例子来感受vanilla/garden-cli的魔力。假设我们要编写一个dbdump.php脚本，用于从数据库中导出一些信息。
创建一个dbdump.php文件：
description('从数据库中导出一些信息。')
->opt('host:h', '要连接的主机。', true) // host 是长选项名，h 是短选项名，true 表示必填
->opt('port:P', '要使用的端口号。', false, 'integer') // false 表示可选，'integer' 指定类型
->opt('user:u', '连接数据库的用户。', true)
->opt('password:p', '连接数据库的密码。') // 默认类型为 string，默认可选
->opt('database:d', '要导出的数据库名称。', true);
// 解析并返回 CLI 参数
// 第二个参数 true 表示如果解析失败（如缺少必填项），则自动显示帮助或错误信息并退出
$args = $cli->parse($argv, true);
// 成功解析后，通过 Args 对象获取参数值
$host = $args->getOpt('host', '127.0.0.1'); // 获取 host，如果未提供则使用默认值 '127.0.0.1'
$user = $args->getOpt('user');
$database = $args['database']; // 也可以像数组一样访问
$port = $args->getOpt('port', 3306); // 获取 port，默认 3306
echo "正在连接到数据库：\n";
echo " 主机: {$host}\n";
echo " 端口: {$port}\n";
echo " 用户: {$user}\n";
echo " 数据库: {$database}\n";
// 实际的数据库导出逻辑将在这里...
echo "数据库导出逻辑将在这里执行。\n";运行与效果：
-
查看帮助信息： 运行
php dbdump.php --help，你将看到自动生成的帮助文档：usage: dbdump.php [
] 从数据库中导出一些信息。 OPTIONS --database, -d 要导出的数据库名称。 --help, -? Display this help. --host, -h 要连接的主机。 --password, -p 连接数据库的密码。 --port, -P 要使用的端口号。 --user, -u 连接数据库的用户。 必填选项会自动加粗显示，非常直观！
-
参数验证与错误提示： 尝试运行
php dbdump.php -P foo(端口号类型错误) 或php dbdump.php(缺少必填参数)：The value of --port (-P) is not a valid integer. Missing required option: host Missing required option: user Missing required option: database
vanilla/garden-cli会自动检测参数类型和必填项，并给出清晰的错误提示，省去了你大量的验证代码。 -
成功运行： 运行
php dbdump.php -h localhost -P 3306 -u root -d my_db：正在连接到数据库： 主机: localhost 端口: 3306 用户: root 数据库: my_db 数据库导出逻辑将在这里执行。
进阶：构建多命令CLI应用（如 Git 风格）
对于更复杂的工具，你可能需要像git pull或git push那样，通过子命令来组织功能。vanilla/garden-cli也提供了优雅的解决方案。
创建一个nit.php文件（模拟一个简单的版本控制工具）：
command('push')
->description('将数据推送到远程服务器。')
->opt('force:f', '强制覆盖。', false, 'boolean')
->opt('set-upstream:u', '添加对上游仓库的引用。', false, 'boolean')
// 定义第二个命令: pull
->command('pull')
->description('从远程服务器拉取数据。')
->opt('commit', '执行合并并提交结果。', false, 'boolean')
// 定义全局选项 (适用于所有命令)
->command('*')
->opt('verbose:v', '输出详细信息。', false, 'integer') // integer 类型可用于统计选项出现的次数 (如 -vvv)
->arg('repo', '要同步的仓库地址。', true); // 定义一个参数，它不是选项，而是命令后的字符串
$args = $cli->parse($argv);
// 获取当前执行的命令名称
$command = $args->getCommand();
echo "执行命令: " . ($command ?: '无命令') . "\n";
echo "仓库地址: " . $args->getArg('repo') . "\n";
echo "详细级别: " . $args->getOpt('verbose', 0) . "\n";
switch ($command) {
case 'push':
echo "正在执行 push 操作...\n";
if ($args->getOpt('force')) {
echo " - 强制覆盖已启用。\n";
}
if ($args->getOpt('set-upstream')) {
echo " - 设置上游引用已启用。\n";
}
break;
case 'pull':
echo "正在执行 pull 操作...\n";
if ($args->getOpt('commit')) {
echo " - 提交合并结果已启用。\n";
}
break;
default:
// 如果没有指定命令，或者命令不存在，则显示帮助
if (!$command) {
echo "请指定一个命令 (push 或 pull)。\n";
} else {
echo "未知命令: {$command}\n";
}
// 自动显示帮助信息
$cli->parse(['--help']);
break;
}运行与效果：
-
列出可用命令： 运行
php nit.php或php nit.php --help：usage: nit.php
[ ] [ ] COMMANDS push 将数据推送到远程服务器。 pull 从远程服务器拉取数据。 -
执行子命令： 运行
php nit.php push --force -v https://github.com/user/repo.git：执行命令: push 仓库地址: https://github.com/user/repo.git 详细级别: 1 正在执行 push 操作... - 强制覆盖已启用。
注意这里的
-v，因为在command('*')中将其定义为integer类型，多次使用-v（如-vvv）可以自动累加其值，非常适合定义详细级别。
更高级的应用：CliApplication 和日志
vanilla/garden-cli还提供了CliApplication类，它进一步减少了命令行应用的样板代码，并支持依赖注入，非常适合大型或模块化的CLI项目。此外，它内置了TaskLogger和StreamLogger，可以帮助你以更结构化、更美观的方式输出日志信息，尤其适合长时间运行的任务或安装脚本。
总结与展望
通过vanilla/garden-cli，我们彻底摆脱了手动解析命令行参数的繁琐工作，并获得了以下核心优势：
- 开发效率大幅提升： 声明式API让命令定义变得简单直观。
- 用户体验显著改善： 自动帮助信息和清晰的错误提示让你的CLI工具更易于使用。
- 代码质量和可维护性增强： 结构化的参数定义和验证减少了潜在的bug。
- 轻松应对复杂需求： 从简单的单命令到复杂的Git风格多命令应用，都能游刃有余。
如果你还在为PHP命令行脚本的开发而挣扎，那么现在是时候拥抱vanilla/garden-cli了。它将让你的CLI应用开发体验焕然一新，并帮助你构建出更加专业和高效的工具。立即尝试，感受它的强大吧！
