Composer在开发命令行工具时对其它CLI工具包的集成与依赖（开发实战）-composer-PHP中文网

bin字段必须声明项目根目录下真实存在的可执行脚本路径（如"bin/mytool"），而非类名或命令别名；文件需具备可执行权限、首行含shebang（#!/usr/bin/env php），并手动引入autoload.php，否则无法运行。

composer在开发命令行工具时对其它cli工具包的集成与依赖（开发实战）

bin 字段声明必须指向可执行文件，不是类名或命令别名

很多人在 composer.json 里写 "bin": ["MyTool\Application"] 或 "bin": ["mytool"]，结果装完发现 mytool 命令根本不存在。Composer 的 bin 字段只接受**真实存在的脚本路径**，且该路径必须是相对于项目根目录的文件（如 "bin/mytool"），不能是命名空间、类名或虚构命令。

常见错误现象：composer global require vendor/package 成功，但 which mytool 返回空，mytool 报 command not found。

bin/ 目录下必须存在对应文件（如 bin/mytool），且已设执行权限：chmod +x bin/mytool
文件第一行必须是 shebang：#!/usr/bin/env php，否则 Linux/macOS 下 shell 会拒绝执行
Windows 用户若用 Git Bash 或 WSL 开发，同样要设权限并写 shebang；纯 CMD 不支持 shebang，但 Composer 全局链接后仍依赖此脚本被 PHP 解释器调用

入口脚本必须显式加载 autoload.php，不能靠 PSR-4 自动触发

CLI 脚本是独立进程入口，PHP 不会像 Web 请求那样自动包含 vendor/autoload.php。哪怕你的类已按 PSR-4 正确映射，不手动引入 autoloader，就会报 Fatal error: Class 'MyToolApplication' not found。

正确做法是在 bin/mytool 开头加一行：

#!/usr/bin/env php
<?php require __DIR__.'/../vendor/autoload.php';

use MyToolApplication;

$app = new Application();
$app->run();

关键点：

路径必须写对：__DIR__ 是 bin/ 目录，所以 ../vendor/autoload.php 才能命中（本地安装）；全局安装时，__DIR__ 指向 ~/.composer/vendor/vender/package/bin/，相对路径依然成立
禁用 require_once 'vendor/autoload.php'（少个 ../）或硬编码绝对路径（如 /var/www/project/vendor/autoload.php），否则跨环境失效
不要在入口脚本里写大量业务逻辑 —— 它只负责引导，主逻辑放 src/ 下

集成 sebastian/cli-parser 时要注意参数解析与选项定义顺序

sebastian/cli-parser 是轻量级 CLI 参数解析库，但它的 parse() 方法对短选项和长选项的定义顺序敏感。如果传入顺序错乱，会导致 --help 不被识别或值绑定错误。

示例中这段代码容易出问题：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

$parser->parse($argv, 'hv', ['help', 'version']);

实际含义是：短选项 -h 和 -v 对应长选项 --help 和 --version —— 二者必须一一对应、位置严格一致。如果改成 'vh' 但长选项还是 ['help', 'version']，那 -v 就会绑定到 --help 上。

使用建议：

短选项字符串顺序必须与长选项数组索引顺序完全一致
带参数的选项（如 --file=xxx）需在长选项数组中加 = 后缀：['output=', 'config=']，否则参数会被当作非选项参数（$nonOptions）
避免混用 Symfony Console 等重型框架时再叠加 cli-parser —— 它们底层冲突，优先选一个

全局安装后命令找不到？PATH 和链接有效性比安装本身更关键

composer global require vendor/tool 执行成功 ≠ 命令可用。真正卡住人的，90% 是 PATH 配置或软链接损坏。

Linux/macOS 常见断链场景：

~/.composer/vendor/bin/ 不在 $PATH 中：运行 echo $PATH 确认，缺失就加 export PATH="$HOME/.composer/vendor/bin:$PATH" 到 ~/.zshrc
软链接目标被删（比如你手动删了 ~/.composer/vendor/vendor/tool）：Composer 不会自动修复，得 composer global update 或重装
IDE（如 PHPStorm）不读 shell 的 $PATH：需在 Settings → PHP → CLI Interpreter 里手动指定 PHP 可执行路径，并勾选 “Add content root to include path”