PHP项目代码质量如何自动化检测扫描

本文目录导读：

1. 推荐工具组合
2. 自动化集成方案
3. 本地开发环境配置
4. 高级集成方案
5. 实战建议
6. 安全检查补充

为PHP项目实现自动化代码质量检测,可以采用以下工具和流程组合，覆盖语法规范、潜在错误、复杂度、安全漏洞等多个维度。

推荐工具组合

自动化集成方案

GitHub Actions 示例（.github/workflows/code-quality.yml）

name: Code Quality Check
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Setup PHP
      uses: shivammathur/setup-php@v2
      with:
        php-version: '8.2'
        tools: composer:v2
        coverage: xdebug
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress
    - name: Run PHP CodeSniffer (PSR-12)
      run: vendor/bin/phpcs --standard=PSR12 --extensions=php src/
    - name: Run PHPMD
      run: vendor/bin/phpmd src/ text cleancode,codesize,controversial,design,naming,unusedcode
    - name: Run PHPStan (Level 6+)
      run: vendor/bin/phpstan analyse --level=6 src/ --no-progress
    - name: Run PHPCPD (重复代码检测)
      run: vendor/bin/phpcpd src/ --min-lines=5 --min-tokens=70

GitLab CI 配置（.gitlab-ci.yml）

stages:
  - quality
code_quality:
  stage: quality
  image: php:8.2-cli
  script:
    - apt-get update && apt-get install -y git unzip
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
    - composer install --no-interaction
    - vendor/bin/phpcs --standard=PSR12 --report=checkstyle src/ > phpcs-report.xml
    - vendor/bin/phpmd src/ xml cleancode,codesize,naming --reportfile phpmd-report.xml
    - vendor/bin/phpstan analyse --level=6 --error-format=checkstyle src/ > phpstan-report.xml
  artifacts:
    reports:
      codequality: [phpcs-report.xml, phpmd-report.xml, phpstan-report.xml]

本地开发环境配置

Composer 脚本配置（composer.json）

{
  "scripts": {
    "cs-check": "phpcs --standard=PSR12 --extensions=php src/ tests/",
    "cs-fix": "phpcbf --standard=PSR12 --extensions=php src/ tests/",
    "md-check": "phpmd src/ text cleancode,codesize,controversial,design,naming,unusedcode",
    "stan-check": "phpstan analyse --level=6 src/ --no-progress",
    "cpd-check": "phpcpd src/ --min-lines=5 --min-tokens=70",
    "qa": [
      "@cs-check",
      "@md-check",
      "@stan-check",
      "@cpd-check"
    ]
  }
}

PHPStan 配置文件（phpstan.neon）

parameters:
  level: 8
  paths:
    - src
    - tests
  excludePaths:
    - vendor/*
    - var/*
  checkMissingIterableValueType: true
  checkGenericClassInNonGenericObjectType: true

PHPMD 规则配置（phpmd.xml）

<?xml version="1.0"?>
<ruleset name="Custom PHPMD Rules"
         xmlns="http://pmd.sf.net/ruleset/1.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pmd.sf.net/ruleset/1.0.0 
                           http://pmd.sf.net/ruleset_xml_schema.xsd">
    <description>My custom PHPMD ruleset</description>
    <rule ref="rulesets/cleancode.xml">
        <exclude name="BooleanArgumentFlag"/>
    </rule>
    <rule ref="rulesets/codesize.xml"/>
    <rule ref="rulesets/design.xml"/>
    <rule ref="rulesets/naming.xml">
        <exclude name="ShortVariable"/>
        <exclude name="LongVariable"/>
    </rule>
    <rule ref="rulesets/unusedcode.xml"/>
</ruleset>

高级集成方案

结合 SonarQube（docker-compose）

version: '3.8'
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - "9000:9000"
    environment:
      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions

配合 sonar-project.properties：

sonar.projectKey=php_project
sonar.sources=src
sonar.tests=tests
sonar.php.coverage.reportPaths=coverage.xml
sonar.php.cs_reportPaths=phpcs-report.xml
sonar.php.pmd_reportPaths=phpmd-report.xml
sonar.phpstan.reportPaths=phpstan-report.xml

Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit
echo "Running code quality checks..."
vendor/bin/phpcs --standard=PSR12 --extensions=php src/ || exit 1
vendor/bin/phpmd src/ text cleancode,codesize,naming || exit 1
vendor/bin/phpstan analyse --level=6 src/ --no-progress || exit 1
echo "All checks passed!"

实战建议

1. 渐进式引入：先从 PHPCodeSniffer（格式规范）开始，逐步加入 PHPStan（TypeScript 级别分析）
2. 分阶段设置：
   • 初始阶段：PHPCS + PHPMD（基础规范）
   • 进阶阶段：增加 PHPStan（L4~6）+ PHPCPD（重复代码）
   • 成熟阶段：PHPStan L8 + 安全检查 + SonarQube
3. 忽略遗留代码：在配置文件中排除历史遗留的旧代码目录，避免阻塞开发流程
4. 持续反馈机制：在 CI 失败时，自动在代码提交的评论中报告具体违规位置

安全检查补充

如需安全扫描,可以在上述流程中加入：

composer require --dev psecio/parse
vendor/bin/parse --format=checkstyle src/ > security-report.xml

或者使用商业方案如 RIPS、Snyk 等。

这套方案覆盖了代码质量检测的各个关键维度,能够帮助团队保持统一规范并提前发现潜在问题。