如何在Composer中集成代码质量扫描工具

如何在Composer中集成代码质量扫描工具

想把PHPStan、Psalm这些代码质量工具集成到Composer工作流里，听起来是个标准操作，对吧？但实际操作过的人都知道，这里面的坑可不少。依赖冲突、配置不生效、CI环境里耗时翻倍……这些问题，几乎每个团队都踩过。今天，我们就来把这些问题掰开揉碎了讲清楚。

为什么 composer.json 的 require-dev 不适合放 PHPStan/PSALM？

直接把 phpstan/phpstan 或 vimeo/psalm 写进项目的 require-dev，是很多人的第一反应。但这么做，后患无穷。最直接的问题就是依赖膨胀——尤其是当你维护的是一个包含多个子包的Monorepo时，每个子包都这么干，vendor/ 目录里就会重复安装好几个不同版本的扫描器。这还不算完，autoload冲突导致的 Class not found 错误，更是让人头疼。

更关键的是，在CI/CD流程里，代码扫描工具需要的是版本固定和配置统一。你肯定不希望扫描器的版本随着开发依赖的更新而随意浮动，导致今天能过，明天就报一堆新错误。

那正确的做法是什么？答案是：把它们当作独立的工具来管理。

• 首先，在项目根目录创建独立的配置文件，比如 phpstan.neon，确保它不会被装进 vendor/ 里。
• 然后，使用Composer的 create-project 命令，将指定版本的扫描器安装到一个独立的目录，例如：composer create-project --no-install phpstan/phpstan:1.10.5 tools/phpstan。
• 最后，在 composer.json 的 scripts 里定义一条清晰的命令："phpstan": "php tools/phpstan/bin/phpstan"。这样一来，版本、路径、配置，全都清晰可控。

如何让 psalm 在 Composer 脚本中自动加载项目 autoloader？

接下来是另一个经典问题：你兴冲冲地运行 vendor/bin/psalm，结果它对着你的测试类报错 Cannot resolve stub class。怎么回事？

问题根源在于，Psalm默认只认自己的 psalm.xml 和内置的autoloader，它并不会自动去识别你项目 composer.json 里定义的 autoload 或 autoload-dev 规则。所以，那些在 tests/ 目录下的类，它自然就找不到了。

解决之道，就是必须显式地告诉Psalm该去哪里加载文件：

• 第一步，检查你的 psalm.xml，确保 部分明确包含了 和 。
• 第二步，在 composer.json 的脚本命令里，加上关键参数："psalm": "vendor/bin/psalm --load-from=."。这个 --load-from=. 就是让Psalm从当前项目根目录加载配置的钥匙。
• 如果项目还使用了自定义的PSR-4映射（比如 "MyLib\": "library/"），那还得在 psalm.xml 里通过 vendor/autoload.php 把路径写死，确保万无一失。

php-cs-fixer 配置文件不生效？检查 .php-cs-fixer.dist 和工作目录

代码风格修复工具PHP-CS-Fixer的配置问题，同样颇具迷惑性。你明明配好了规则，运行命令却静默失败——没有错误提示，但文件丝毫未变。这种问题，十有八九出在工作目录上。

要知道，php-cs-fixer 在执行时，默认只会在当前工作目录下寻找 .php-cs-fixer.dist 文件（注意它默认找的是 .dist 后缀，而不是 .php）。如果你在项目根目录配置了它，但CI脚本或Makefile是先 cd 到某个子目录再调用 composer run fix，那么工具自然就找不到配置文件了。

一个安全又省心的做法是强制指定配置路径：

• 建议统一使用 .php-cs-fixer.php 这种PHP格式的配置文件，灵活性更高。
• 在 composer.json 的脚本命令中，把配置文件的绝对路径写清楚："cs-fix": "php-cs-fixer fix --config=.php-cs-fixer.php --path-mode=intersection"。
• 这里有个关键参数 --path-mode=intersection，它能确保工具只处理那些既在配置文件规则范围内、又在当前命令指定路径下的文件，有效避免误扫 vendor/ 目录。

CI 中并行跑多个扫描器，怎么避免 composer install 重复耗时？

最后，我们来优化CI流程的效率。在GitHub Actions或GitLab CI里，如果为PHPStan、Psalm、PHP-CS-Fixer每个任务都单独执行一次 composer install，那光是依赖解析和生成autoload文件，就可能白白浪费好几十秒。其实完全没必要，因为这些扫描器共享的是同一套 vendor/autoload.php。

最优解是分两步走：

• 依赖安装阶段：用一个独立的Job，运行 composer install --no-progress --prefer-dist --optimize-autoloader，并将安装好的 vendor/ 目录缓存起来。
• 扫描执行阶段：后续所有扫描任务，都直接使用缓存中的 vendor/bin/xxx 来执行命令，不再重复安装。如果采用了前面提到的独立 tools/ 目录安装法，甚至可以直接缓存 tools/ 目录，跳过 composer install。
• 另外有个小提示：PHPStan 1.10+ 版本默认启用了结果缓存以提升速度，但在CI的多Job并行环境下，这可能引发缓存状态不一致的问题。稳妥起见，可以在CI命令中加上 --no-cache 参数。

说到底，集成这些底层工具链，难点从来不在安装，而在配置。路径、autoload、缓存，这三个点就是最常见的“暗礁”。别相信“装上就能用”的神话，多花一分钟，确认它到底加载了哪些文件、用的是哪个autoloader、缓存写在了哪里，后续就能省下一小时的调试时间。