使用 PHP CS Fixer 格式化 PHP 代码

Tinywan

发布于 2026-07-01 12:40:29

1510

引言

维护一致的代码风格是软件和 Web 开发的关键方面。它可以提高代码的可读性，减少开发人员的认知负担，并确保团队中的每个人都遵守相同的标准。

但是，手动格式化代码风格既耗时又乏味，而且容易出错。您可以使用集成开发环境 (IDE) 或文本编辑器自动格式化代码，但这种方法有其局限性。并非所有团队成员都使用相同的工具，而且 IDE 配置可能差异很大。因此，通常最好使用一个专用的代码风格工具，它可以在不同环境中一致运行，并在您的持续集成 (CI) 管道中使用。

用于格式化 PHP 代码的工具之一是 PHP CS Fixer。这是一个非常受欢迎的工具，截至本文撰写时，它在 Packagist 上已有超过 2.14 亿次下载。

在本文中，我们将探讨如何安装和配置 PHP CS Fixer。然后，我们将介绍如何在本地和并行模式下运行它。最后，我将向您展示如何创建一个 GitHub Actions 工作流，使用 PHP CS Fixer 在拉取请求上自动化代码风格检查。

安装 PHP CS Fixer

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

创建配置文件

安装完成后，您需要为 PHP CS Fixer 创建一个配置文件。此文件允许您指定要强制执行的编码标准、要运行工具的目录，以及您可能拥有的任何自定义规则。

为此，您需要在项目根目录中创建一个 .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 编码标准，并希望扫描当前目录（及其子目录）中的所有文件以查找代码风格问题。

如果您想针对特定目录运行工具，可以修改 setFinder 方法。例如，假设我们只想针对 src 和 tests 目录运行工具。我们可以通过以下方式更新 setFinder 方法：

<?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__ . '/src',
                __DIR__ . '/tests',
            ])
    );

PHP CS Fixer 有大量的配置选项和规则，我在这里不会全部深入探讨。但我建议查看 GitHub 上的文档，以便找到您可能想使用的任何其他规则：https://github.com/PHP-CS-Fixer/PHP-CS-Fixer/blob/master/doc/rules/index.rst。

使用 PHP CS Fixer 格式化代码

现在我们已经安装并配置了 PHP CS Fixer，就可以针对我们的代码库运行它了。

通常，您会使用两个命令：

• ./vendor/bin/php-cs-fixer check - 此命令根据配置文件中定义的规则检查您的代码是否存在任何风格问题。它将输出不符合指定编码标准的文件列表。
• ./vendor/bin/php-cs-fixer fix - 此命令根据配置文件中定义的规则自动修复代码库中发现的任何代码风格问题。

因此，如果我们想运行 check 命令以查看项目中是否存在任何代码风格问题，我们将运行以下命令：

./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.
You can enable parallel runner and speed up the analysis! Please see usage docs for more information.
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

1) tests/Feature/Email/DomainIsNotTest.php
2) src/Email.php

Found 2 of 20 files that can be fixed in 0.026 seconds, 20.00 MB memory used

同样，为了自动修复发现的问题，我们可以运行以下命令：

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

运行此命令将修复项目中发现的任何代码风格问题，并生成如下输出：

❯ ./vendor/bin/php-cs-fixer fix
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.
You can enable parallel runner and speed up the analysis! Please see usage docs for more information.
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

1) tests/Feature/Email/DomainIsNotTest.php
2) src/Email.php

Fixed 2 of 20 files in 0.029 seconds, 20.00 MB memory use

在并行模式下运行 PHP CS Fixer

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()
    );

在上例中，我们让 PHP CS Fixer 自动检测我们系统的优化并行配置。但如果您愿意，也可以手动指定这些细节。

然后运行 ./vendor/bin/php-cs-fixer fix 将以并行模式运行修复器。您应该会看到类似于以下的输出：

❯ ./vendor/bin/php-cs-fixer fix
PHP CS Fixer 3.89.1 Folding Bike by Fabien Potencier, Dariusz Ruminski and contributors.
PHP runtime: 8.4.2
Running analysis on 7 cores with 10 files per process.
Parallel runner is an experimental feature and may be unstable, use it at your own risk. Feedback highly appreciated!
Loaded config default from "/Users/ashallen/www/open-source/packages/email-utilities/.php-cs-fixer.dist.php".
Using cache file ".php-cs-fixer.cache".
20/20 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

1) src/Email.php

Fixed 1 of 20 files in 0.210 seconds, 20.00 MB memory used

使用 GitHub Actions 运行 PHP CS Fixer

确保团队中代码风格保持一致的一个好方法是自动化代码风格检查。这样做有助于捕获您在推送更改之前忘记在本地运行代码格式化器的任何情况。

为了自动化此过程，我喜欢使用一个在每个拉取请求上运行的 GitHub Actions 工作流。由于 PHP CS Fixer 在发现任何代码风格问题时会返回非零退出码（表示失败），我们可以依赖此来使工作流失败。

让我们看一个您可能想使用的典型 GitHub Actions 工作流：

# .github/workflows/ci-code-style.yml

name: Code Style

on:
  pull_request:

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest

    steps:
      - name: Update apt
        run: sudo apt-get update --fix-missing

      - 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

在上例中，我们可以看到作为工作流的一部分运行 ./vendor/bin/php-cs-fixer check 命令。如果发现任何代码风格问题，该命令将返回非零退出码，导致工作流失败。如果命令通过，它将返回零退出码，工作流将成功。

我应该在工作流中自动修复问题吗？

您可能想运行 fix 命令并自动将更改提交到拉取请求。但是，我通常避免这种方法，因为它可能会在不知情的情况下向代码库引入意外更改。相反，我更喜欢运行 check 命令，然后在本地修复任何问题。这样，我可以完全控制对代码库所做的更改。

这只是我的个人意见，您可能会发现自动在工作流中修复问题对您的团队更有效。如果您确实想在工作流中自动修复问题，您可能想考虑通过工作流打开一个带有更新代码风格更改的拉取请求，而不是直接将它们提交到分支。这样，您可以在更改合并到主代码库之前审查它们。

结论

在本文中，我们探讨了如何在 PHP 项目中设置和使用 PHP CS Fixer 来维护代码风格。我们涵盖了安装、配置、在本地和并行模式下运行它，以及使用 GitHub Actions 自动化代码风格检查。通过将 PHP CS Fixer 集成到您的开发工作流中，您可以确保项目中一致的代码质量和对编码标准的遵守。

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2025-12-19，如有侵权请联系 cloudcommunity@tencent.com 删除

工作流