Composer代码质量：在依赖安装时自动运行静态检查

很多开发者都希望能在执行 composer install 或 update 时，自动触发代码质量检查，比如跑一遍 PHPStan 或 PHPCS。但这里有个常见的误解：Composer 本身并不会、也不可能“自动运行”这些静态分析工具。它只管依赖的解析、下载和安装。所谓的“安装时自动检查”，其本质是把检查命令挂载到 Composer 的生命周期事件上，借助 post-install-cmd 或 post-update-cmd 这类事件来触发执行。

为什么不能直接在 install 阶段做静态分析？

想把检查塞进安装流程，想法很好，但时机不对。Composer 的安装过程可以粗略分为三步：解析依赖关系、下载依赖包、最后将文件写入 vendor 目录。像 PHPStan 这类静态分析工具，需要完整的项目源码和一个可用的自动加载器（autoloader）才能正常工作。

问题就出在这里。当 post-install-cmd 事件被触发时，vendor/autoload.php 文件确实刚刚生成，但项目自身的源代码（尤其是那些定义在 autoload-dev 部分下的）很可能还没有被 Composer 的自动加载机制完全覆盖。这时候你急吼吼地执行 phpstan analyse，很大概率会碰到一堆 “Class not found” 的错误，或者分析工具干脆跳过了你的 src 目录。

这里有几个细节值得注意：

• PHPStan 默认不会主动加载项目的 autoload 文件，除非你在配置里显式指定 parameters.autoload_files 或设置 bootstrap 脚本。
• post-install-cmd 只在首次执行 composer install（即 vendor 目录为空）时触发。如果 vendor/ 目录已经存在，且 composer.lock 文件没变，再次运行 install 时这个事件会被跳过。
• 在 CI/CD 环境中，为了构建的确定性和避免副作用，常常会加上 --no-scripts 参数，这会导致所有脚本事件（包括你的检查命令）静默失效。

应该绑定到哪个事件才真正可靠？

那么，哪个事件更靠谱呢？经验表明，使用 post-update-cmd 通常比 post-install-cmd 更稳定，特别是在团队协作和持续集成的场景下。

原因有三：首先，post-update-cmd 在每次执行 composer update 或 composer require（添加新包）后都必定会触发，不依赖于 vendor/autoload.php 是否已经存在。其次，在 Composer 的内部执行顺序中，它会确保在 autoloader 被重建（通过 post-autoload-dump 事件）之后才运行，这就保证了所有类都能被正确加载。最后，将检查命令绑定到这个事件，可以无缝覆盖本地开发、CI 构建乃至 Docker 镜像构建等多个阶段。

一个典型的 composer.json 配置示例如下：

"scripts": {
    "post-update-cmd": [
        "@phpstan",
        "@phpcs"
    ],
    "phpstan": "phpstan analyse --no-progress",
    "phpcs": "phpcs --standard=PHPCompatibility --runtime-set testVersion 8.1 src/"
}

如何避免检查失败导致 install/update 中断？

这里有个潜在的“坑”：默认情况下，如果 scripts 里定义的任何命令以非零状态码退出，整个 composer update 过程就会宣告失败。这在 CI 环境中是我们期望的行为——检查不通过，构建就应中止。但在本地开发时，这可能就有点过于严格了，毕竟你或许只是想快速更新个包，暂时不想处理代码风格警告。

有几点需要澄清：添加 --no-interaction 参数并不会影响脚本的退出码，真正决定是否“容错”的是脚本命令本身。虽然可以用一些技巧，比如让 PHPStan 输出原始格式再用 grep -v 过滤误报，但这本质上是在掩盖问题，并非上策。

更合理的做法是区分场景：在 CI 流程中保持严格校验，失败即阻断；在本地开发时，则可以通过单独运行 composer run phpstan -- --no-progress 来手动触发检查，或者虽然将检查配置在 post-update-cmd 中，但不将其作为阻塞性环节。另外要注意，如果 PHPCS 配置了 --report=checkstyle 等格式，其警告也可能导致非零退出，此时与其用 || true 强行忽略，不如考虑先用 phpcbf 自动修复那些可修正的项。

真实部署时最常被忽略的兼容性陷阱

最后，还有一个高级但极其关键的陷阱：很多人以为装了 PHPStan 就高枕无忧了，结果代码在本地 PHP 8.2 下跑得好好的，一部署到线上 PHP 7.4 环境就崩了。这是因为 PHPStan 的核心工作是类型推导和静态分析，它不检查语法兼容性。那些在低版本 PHP 中不存在的语法，比如 match 表达式、str_contains() 函数或者空合并赋值运算符 ??=，PHPStan 默认是不会报错的。

真正能拦住这些兼容性问题的，是 PHP_CodeSniffer 配合 phpcompatibility/php-compatibility 规则集。使用时必须注意：

• 一定要显式传递 --runtime-set testVersion 7.4 这样的参数，指明你的目标运行环境版本，否则工具默认只扫描 PHP 5.6 级别的兼容性问题。
• 这里的 testVersion 指的是你代码需要支持的最低 PHP 版本，不是你本地开发机的 PHP 版本。在 CI 配置中，这个值应该被固定，而不是动态读取 PHP_VERSION_ID。
• 千万别把语法兼容性检查和代码质量/类型检查混为一谈。PHPStan 的 level 8 要求完备的类型注解，而 PHPCompatibility 只关心某个语法或函数在目标版本中是否存在——这是两个完全不同的维度，无法相互替代。

说到底，自动化检查的目标，从来不是“有没有执行”这个动作本身，而是确保检查在正确的时机、针对正确的目标、以可控的方式发生。否则，所谓的自动化，很可能就变成了自动推卸责任的工具。