告别命令行脚本的混乱：从痛点到解决方案
作为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文件：
<?php // 引入 Composer 的自动加载器 require_once 'vendor/autoload.php'; use GardenCliCli; // 定义 CLI 选项 $cli = new Cli(); $cli->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>] 从数据库中导出一些信息。 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文件（模拟一个简单的版本控制工具）：
<?php require_once 'vendor/autoload.php'; use GardenCliCli; use GardenCliArgs; // 定义一个带有多个命令的 CLI $cli = Cli::create() // 定义第一个命令: push ->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 <command> [<options>] [<args>] 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应用开发体验焕然一新，并帮助你构建出更加专业和高效的工具。立即尝试，感受它的强大吧！
