在 Debian 上使用 Composer 进行 PHP 代码质量检查
一 环境准备
- 在 Debian 上安装 PHP 与 Composer（系统级或项目级均可），确保命令行可运行 php 与 composer。
- 建议将质量工具安装为开发依赖（–dev），便于团队协作与 CI/CD 复用；Composer 仅负责依赖管理与脚本编排，代码质量检查由具体工具执行。
二 常用工具与安装
- 风格与规范
- PHP_CodeSniffer（检查是否符合 PSR-12 等规范）：composer require --dev squizlabs/php_codesniffer
- PHP-CS-Fixer（自动修复风格问题）：composer require --dev friendsofphp/php-cs-fixer
- 静态分析
- PHPStan（发现潜在错误与类型问题）：composer require --dev phpstan/phpstan
- Psalm（类型与错误检测）：composer require --dev vimeo/psalm
- Phan（静态分析器，强调低误报）：composer require --dev phan/phan
- 代码异味与复杂度
- PHPMD（检测过长方法、未使用参数等）：composer require --dev phpmd/phpmd
- 以上工具均通过 Composer 安装到 vendor/bin，便于统一调用与版本管理。
三 配置与脚本集成
- 生成或创建各工具配置文件（示例）：
- PHPStan：vendor/bin/phpstan init-config 生成 phpstan.neon
- Psalm：vendor/bin/psalm --init 生成 psalm.xml
- PHP_CodeSniffer：创建 phpcs.xml，如
- PHPMD：创建 phpmd.xml，引入需要的规则集
- PHP-CS-Fixer：创建 .php-cs-fixer.dist.php，配置规则与扫描路径
- 在 composer.json 中定义脚本（便于本地与 CI 统一执行）：
- 示例：
{
“scripts”: {
“phpstan”: “phpstan analyse -c phpstan.neon src”,
“psalm”: “psalm --config=psalm.xml”,
“lint”: “phpcs --standard=PSR12 src tests”,
“lint-fix”: “phpcbf --standard=PSR12 src tests”,
“cs-fix”: “php-cs-fixer fix --config=.php-cs-fixer.dist.php”,
“phpmd”: “phpmd src text phpmd.xml”,
“qa”: [
“composer lint”,
“composer phpstan”,
“composer psalm”,
“composer phpmd”
]
}
}
- 运行方式：
- 单个工具：composer phpstan、composer lint
- 组合检查：composer qa（可在 CI 中作为质量门禁）
四 本地与 CI 执行
- 本地开发
- 日常开发先执行风格检查与自动修复：composer lint-fix 或 composer cs-fix
- 提交前运行完整质量检查：composer qa
- 持续集成（GitHub Actions 示例）
- 示例步骤：
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2 with { php-version: ‘8.2’ }
- run: composer install --no-progress --prefer-dist
- run: composer qa
- 覆盖率与增量检查（可选）
- 单元测试与覆盖率：使用 PHPUnit 生成覆盖率报告（如 --coverage-html report/），用于质量门禁或可视化查看。
- 增量质量门禁：使用 exussum12/coverage-checker 的 diffFilter 仅对新增/修改代码执行 phpcs/phpstan/phpmd 等检查，逐步提升标准而不阻塞整体演进。
五 常见问题与建议
- 工具不冲突可并行：如同时使用 PHPStan 与 Psalm，通过 Composer 脚本组合运行，互补提升问题发现率。
- 速度与精度：静态分析级别与扫描范围会影响速度与结果，建议从较低级别起步，随项目成熟度逐步提高。
- 误报处理：优先通过配置规则解决，必要时在配置中谨慎忽略，避免过度抑制。
- 扩展依赖：如 Phan 需要启用 php-ast 扩展；在 Debian 可通过包管理器或 PECL 安装后启用。