[PHP] PHP CS Fixer 配置与使用指南：集成 PSR-12 标准与 GitHub Actions

维护一致的代码风格是软件开发，尤其是Web开发中的重要环节。它能显著提升代码的可读性，降低团队成员的认知负担，并确保所有人都遵循统一的编码规范。

然而，手动调整代码格式不仅耗时耗力，还容易出错。虽然集成开发环境（IDE）或文本编辑器通常内置了格式化功能，但这并非最佳解决方案。因为团队成员使用的工具各不相同，IDE的配置也可能千差万别。因此，采用一个独立、环境一致的代码格式化工具，并将其集成到持续集成（CI）流程中，是更可靠的选择。

PHP CS Fixer 正是这样一款专注于格式化PHP代码的工具。它广受欢迎，截至目前，其在 Packagist 上的下载量已超过2.14亿次。

本文将详细介绍如何安装和配置 PHP CS Fixer，并演示如何在本地及并行模式下运行它。最后，我们将探讨如何创建一个 GitHub Actions 工作流，以在拉取请求中自动化执行代码风格检查，这是现代 DevOps 实践中保障代码质量的重要一环。

安装 PHP CS Fixer

通过 Composer 将 PHP CS Fixer 作为开发依赖安装到项目中：

composer require friendsofphp/php-cs-fixer --dev

创建配置文件

安装完成后，需要在项目根目录创建一个配置文件来定义编码标准和规则。通常，这个文件被命名为 .php-cs-fixer.dist.php。

下面是一个基础配置示例：

<?php
// .php-cs-fixer.dist.php
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

return (new Config())
    ->setRules([
        '@PSR12' => true,
    ])
    ->setFinder(
        (new Finder())
            ->in(__DIR__)
    );

此配置指定使用 PSR-12 编码标准，并扫描当前目录及其所有子目录下的文件。

如果需要限定扫描范围，例如仅检查 src 和 tests 目录，可以修改 setFinder 方法：

->setFinder(
    (new Finder())
        ->in([
            __DIR__ . '/src',
            __DIR__ . '/tests',
        ])
)

PHP CS Fixer 提供了极其丰富的规则集，您可以查阅其 官方文档 来定制符合团队需求的规则组合。

使用 PHP CS Fixer 格式化代码

配置妥当后，即可对代码库执行格式化操作。主要使用以下两个命令：

• ./vendor/bin/php-cs-fixer check：检查代码风格问题，并列出不符合规则的文件。
• ./vendor/bin/php-cs-fixer fix：自动修复发现的代码风格问题。

运行检查命令：

./vendor/bin/php-cs-fixer check

输出示例如下：

❯ ./vendor/bin/php-cs-fixer check
PHP CS Fixer 3.89.1 Folding Bike by Fabien Potencier, Dariusz Ruminski and contributors.
PHP runtime: 8.4.2
Running analysis on 1 core sequentially.
...
Found 2 of 20 files that can be fixed in 0.026 seconds, 20.00 MB memory used

运行修复命令自动修正问题：

./vendor/bin/php-cs-fixer fix

在并行模式下运行 PHP CS Fixer

对于大型代码库，启用并行模式可以大幅提升检查与修复的速度。在配置文件中添加 setParallelConfig 方法即可启用。

示例配置：

<?php
// .php-cs-fixer.dist.php
declare(strict_types=1);

use PhpCsFixer\Config;
use PhpCsFixer\Finder;

return (new Config())
    ->setRules([
        '@PSR12' => true,
    ])
    ->setFinder(
        (new Finder())
            ->in(__DIR__)
    )
    ->setParallelConfig(
        PhpCsFixer\Runner\Parallel\ParallelConfigFactory::detect()
    );

示例中使用了 ParallelConfigFactory::detect() 来自动检测系统的最佳并行配置，您也可以手动指定参数。之后运行 fix 或 check 命令将会启用多核处理。

使用 GitHub Actions 运行 PHP CS Fixer

将代码风格检查自动化是确保团队协作一致性的有效手段。通过 GitHub Actions，我们可以在每个拉取请求上自动运行检查。由于 php-cs-fixer check 在发现问题时会返回非零退出码，我们可以利用这一点使工作流失败。

以下是一个典型的工作流配置文件示例（.github/workflows/ci-code-style.yml）：

name: Code Style
on:
  pull_request:
jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none
      - name: Install dependencies
        run: composer install
      - name: Run PHP CS Fixer
        run: ./vendor/bin/php-cs-fixer check

此工作流会在创建或更新拉取请求时触发，执行代码风格检查。如果发现问题，工作流将标记为失败，提醒开发者修复。

关于自动修复的考量

您可能会考虑在工作流中直接运行 fix 命令并自动提交修复。但通常不建议这样做，因为这可能在不经意间引入意外的更改。更稳妥的做法是运行 check 命令，让开发者在本地环境手动执行修复，从而保持对代码变更的完全控制。当然，如果团队有特定流程，也可以设计为自动创建包含修复的拉取请求以供审查。

结论

本文介绍了如何在 PHP 项目中集成和使用 PHP CS Fixer 来统一代码风格。我们从安装、配置讲起，覆盖了本地执行、并行加速以及通过 GitHub Actions 实现自动化检查的全流程。遵循 PSR-12 等编码规范，并借助此类工具将其自动化，是提升项目代码质量和团队开发效率的关键实践。将其纳入您的开发工作流，能有效确保代码库的整洁与规范。