Composer脚本定制：编写PHP脚本增强Composer原生功能-composer-PHP中文网

自定义脚本必须定义在composer.json的scripts键下，支持字符串、数组或php回调；路径须相对于项目根目录，php脚本需显式调用php并require autoload，参数传递须用--分隔，退出码需显式处理。

composer脚本定制：编写php脚本增强composer原生功能

Composer 本身不运行 PHP 代码，它只调用命令行程序；所谓“PHP 脚本”，本质是让 Composer 执行 php 命令去运行你写的 PHP 文件。关键不是“写脚本”，而是“让 Composer 正确触发它”。

必须把脚本路径写进 composer.json 的 scripts 段，并确保路径相对于项目根目录（即 composer.json 所在位置）：

{
    "scripts": {
        "post-install-cmd": "php scripts/post-install.php",
        "check-env": "php scripts/validate-env.php"
    }
}

路径不能用 ./scripts/... —— Composer 不做 shell 展开，. 会被当字面量处理，导致文件找不到
脚本文件需有可执行权限（Linux/macOS），或显式调用 php（Windows 也建议统一加 php 前缀）
如果脚本依赖 Composer 自动加载，需在脚本开头 require 'vendor/autoload.php';，否则类会报 Class not found

常见现象：你在 post-autoload-dump 钩子里实例化一个类，却提示 Class 'App\Utils\Checker' not found。这不是自动加载没生效，而是 Composer 在触发钩子时，**尚未把新生成的 autoload 文件写入磁盘**。

此时 vendor/autoload.php 还是旧版本，而你的类可能刚被添加、命名空间刚改过。解决办法只有两个：

改用 post-dump-autoload（注意不是 post-autoload-dump）—— 这个钩子在 autoload 文件真正写完后才触发
手动 require 新生成的 autoload 文件：require __DIR__ . '/vendor/composer/autoload_classmap.php';（仅限调试，不推荐生产）

官方文档里写的 post-autoload-dump 是误导性命名，实际行为就是“dump 过程中”，不是“dump 完毕后”。

Workflow Decomposer

工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。

下载

Composer 默认不透传参数给脚本，composer run-script check-env -- --env=prod 中的 --env=prod 会被忽略。必须显式启用参数透传：

在 scripts 中用 @php 替代 php，并加上 -- 占位符："check-env": "@php scripts/validate-env.php --"
然后运行：composer run-script check-env -- --env=prod，此时 $argv 才能拿到 --env=prod
别用 symfony/console 直接解析 —— 它默认从 $_SERVER['argv'] 读，但 Composer 会重置这个数组；应直接操作 $argv

漏掉 -- 或写成 @php ... -- --（多一个横杠）都会导致参数丢失，且无任何错误提示。

默认情况下，即使你的 PHP 脚本 exit(1)，Composer 也认为执行成功，不会中断后续流程（比如 install）。必须显式配置 script-isolation 或使用 process-timeout 等机制来约束。

最简单可靠的方式：在 scripts 里用 php -f 包一层，并检查返回值："check-env": "php -f scripts/validate-env.php || exit 1"
避免用 exec() 或 shell_exec() 调用其他命令 —— 它们的退出码不会自动冒泡到 Composer
如果脚本本身含 die() 或未捕获异常，Composer 会收到非零退出码，但最好统一用 exit($code) 显式控制

很多人卡在“脚本明明报错了，Composer 却继续往下走”，根本原因是没意识到 Composer 对子进程退出码的默认容忍策略 —— 它只关心自己主进程是否 crash，不关心你调的 php 是否成功。