Debian如何进行PHP代码质量检查

在 Debian 上进行 PHP 代码质量检查

一 环境准备

工欲善其事，必先利其器。想在 Debian 上顺畅地进行代码质量检查，第一步就是把基础环境搭建好。这里以 Debian 12 为例，具体版本请根据你的项目实际情况调整。

• 安装 PHP 与常用扩展：这是所有工作的起点。
  • sudo apt-get update
  • sudo apt-get install -y php php-cli php-fpm php-mysql php-zip php-gd php-mbstring php-curl php-xml php-bcmath
• 安装 Composer：作为 PHP 的依赖管理工具，它几乎是现代项目的标配。
  • 下载并安装：curl -sS https://getcomposer.org/installer | php
  • 移动到 PATH：sudo mv composer.phar /usr/local/bin/composer
• 建议将 Composer 全局 bin 加入 PATH：如果你全局安装过像 phpunit/phpunit 这样的工具，这一步能让调用更方便。
  • echo ‘export PATH=$HOME/.composer/vendor/bin:$PATH’ >> ~/.bashrc && source ~/.bashrc

需要说明的是，本文推荐的工具大多通过 Composer 进行项目级安装。这样做的好处显而易见：便于版本控制和团队协作，避免因环境差异导致的问题。

二 静态分析与代码规范

代码质量的第一道防线，就是静态分析。它能帮你发现那些运行时才会暴露的潜在问题，以及统一团队的编码风格。

• 基础语法快速检查：最基础也最常用，先确保代码能“跑起来”。
  • 单文件：php -l path/to/file.php
  • 项目目录：find src tests -name “*.php” -exec php -l {} ;
• 代码风格与规范（PSR-12 等）：统一的代码风格是团队协作的基石。PHP_CodeSniffer 是这方面的权威工具。
  • 安装：composer require --dev squizlabs/php_codesniffer
  • 检查：vendor/bin/phpcs --standard=PSR12 src tests
  • 自动修复：vendor/bin/phpcbf --standard=PSR12 src tests
• 代码坏味道与潜在缺陷：代码能运行，不代表写得好。PHPMD 专门用来揪出那些“坏味道”，比如过于复杂的类、未使用的参数等。
  • 安装：composer require --dev phpmd/phpmd
  • 检查：vendor/bin/phpmd src text cleancode,codesize,controversial,design,naming,unusedcode
• 静态分析（类型、未定义、死代码等）：想进行更深度的代码体检？Phan 是个强大的选择，它能分析类型、发现未定义的变量和方法，甚至找出死代码。
  • 安装：composer require --dev phan/phan
  • 依赖：Phan 需要 Debian 上的 php-ast 扩展支持。
    • sudo apt-get install -y php-ast
    • 或 pecl install ast && echo “extension=ast.so” | sudo tee /etc/php/*/cli/conf.d/20-ast.ini
  • 初始化配置：vendor/bin/phan --init
  • 分析：vendor/bin/phan --allow-polyfill-parser

一个实用的建议是，尽早将这些工具集成到你的编辑器（比如 PHPStorm）中。边写代码边获得提示，能将大部分问题扼杀在摇篮里，避免它们流入提交阶段。

三 单元测试与覆盖率

如果说静态分析是“体检”，那么单元测试就是“实战演练”。它能确保你的代码在修改后，原有功能依然完好。而覆盖率报告则告诉你，这场“演练”到底覆盖了多大范围。

• 安装 PHPUnit（项目级）：PHP 单元测试的事实标准。
  • composer require --dev phpunit/phpunit
• 基本运行：配置好之后，运行测试就是一句话的事。
  • vendor/bin/phpunit
• 生成 HTML 覆盖率报告：光跑通测试还不够，还得知道测试得充不充分。生成可视化的覆盖率报告是关键一步（需要先在 phpunit.xml 中配置 白名单）。
  • 示例 phpunit.xml 片段：
    • - tests/- src/-
  • 执行：vendor/bin/phpunit --coverage-html report/

执行完毕后，详细的 HTML 覆盖率报告会生成在 report/ 目录下。直接用浏览器打开 index.html，就能直观地看到哪些代码被测试覆盖，哪些还是“盲区”。

四 提交前与 CI 自动化

到了这一步，你已经拥有了强大的本地检查工具。但如何确保每次提交的代码都符合标准呢？答案是自动化。将质量检查流程自动化，是保障项目长期健康的核心手段。

• 本地 Git 提交前自动检查（使用 GrumPHP）：它就像一个守在 Git 提交门口的“质量门卫”，不符合规则的代码别想混进去。
  • 安装：composer require --dev grumphp/grumphp
  • 初始化：vendor/bin/grumphp init（按向导生成 grumphp.yml）
  • 常用任务示例（可写入配置）：phpcs, phpmd, phpunit, phan
  • 测试钩子：vendor/bin/grumphp git:pre-commit
• 持续集成示例（GitHub Actions）：将质量检查扩展到云端和团队协作流程中，确保任何人的提交都经过同一套标准检验。
  • 示例步骤：
    • 安装 PHP 与 Composer
    • 缓存 Composer 依赖
    • 运行：phpcs、phpmd、phan、phpunit --coverage-text
    • 可结合 Codecov 上传覆盖率

最后需要说明的是，像 Lara vel 这样流行的框架项目，其测试核心同样是 PHPUnit。只要配置好项目的 phpunit.xml 文件，就可以直接在 CI 环境中通过执行 vendor/bin/phpunit 来运行完整的测试套件，实现无缝集成。