PHP-CS-Fixer 自定义修复器开发指南

前言

PHP-CS-Fixer 是一个强大的 PHP 代码格式化工具，它能够自动修复代码风格问题。本文将详细介绍如何为 PHP-CS-Fixer 开发自定义修复器（Fixer），帮助开发者扩展其功能以满足特定项目的代码风格需求。

核心概念

什么是修复器（Fixer）

修复器是 PHP-CS-Fixer 的基本功能单元，每个修复器负责处理一种特定的代码风格问题。修复器的工作原理是：

1. 接收有效的 PHP 代码作为输入
2. 分析并修改代码
3. 输出符合规范的 PHP 代码

修复器采用多遍编译（multi-pass compiler）的设计模式，这意味着代码会经过多个修复器的处理，每个修复器专注于解决特定问题。

修复器特性

理想的修复器应该具备以下特性：

• 幂等性（Idempotent）：多次应用修复器不会改变已经符合规范的代码
• 原子性（Atomic）：每个修复器只处理单一类型的代码风格问题
• 高效性：能够快速判断是否需要处理当前代码

开发准备

在开始开发前，请确保：

1. 熟悉测试驱动开发（TDD）方法
2. 了解 PHP 解析器标记（Parser Tokens）
3. 掌握 Tokens 和 Token 类的使用方法
4. 已设置好本地开发环境

实战：开发注释移除修复器

我们将开发一个名为 RemoveCommentsFixer 的修复器，用于移除所有以分号（;）开头的注释。

第一步：创建基础文件

在 src/Fixer/Comment/RemoveCommentsFixer.php 创建修复器类：

<?php

namespace PhpCsFixer\Fixer\Comment;

use PhpCsFixer\AbstractFixer;
use PhpCsFixer\FixerDefinition\FixerDefinition;
use PhpCsFixer\Tokenizer\Tokens;

final class RemoveCommentsFixer extends AbstractFixer
{
    public function getDefinition(): FixerDefinition
    {
        // 定义修复器功能
    }

    public function isCandidate(Tokens $tokens): bool
    {
        // 判断是否需要处理
    }

    protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
    {
        // 实现修复逻辑
    }
}

在 tests/Fixer/Comment/RemoveCommentsFixerTest.php 创建测试类：

<?php

namespace PhpCsFixer\Tests\Fixer\Comment;

use PhpCsFixer\Tests\Test\AbstractFixerTestCase;

final class RemoveCommentsFixerTest extends AbstractFixerTestCase
{
    /**
     * @dataProvider provideFixCases
     */
    public function testFix(string $expected, ?string $input = null): void
    {
        $this->doTest($expected, $input);
    }

    public static function provideFixCases()
    {
        return [
            // 测试用例将在这里添加
        ];
    }
}

第二步：编写测试用例

测试应覆盖两种场景：

1. 不应修改的代码
2. 应该修改的代码

public static function provideFixCases()
{
    return [
        // 不应修改的代码
        ['<?php echo "This should not be changed";'],
        
        // 应该修改的代码
        [
            '<?php echo "This should be changed"; ',
            '<?php echo "This should be changed"; /* Comment */',
        ],
    ];
}

第三步：实现修复逻辑

1. 定义修复器描述：

public function getDefinition(): FixerDefinition
{
    return new FixerDefinition(
        '移除所有以分号开头的注释。',
        [
            new CodeSample("<?php echo 123; /* Comment */\n"),
        ]
    );
}

2. 实现候选判断：

public function isCandidate(Tokens $tokens): bool
{
    return $tokens->isTokenKindFound(T_COMMENT);
}

3. 实现核心修复逻辑：

protected function applyFix(\SplFileInfo $file, Tokens $tokens): void
{
    foreach ($tokens as $index => $token) {
        if (!$token->isGivenKind(T_COMMENT)) {
            continue;
        }

        $prevTokenIndex = $tokens->getPrevMeaningfulToken($index);
        $prevToken = $tokens[$prevTokenIndex];

        if ($prevToken->equals(';')) {
            $tokens->clearAt($index);
        }
    }
}

第四步：代码格式化与提交

使用 PHP-CS-Fixer 格式化代码：

php php-cs-fixer fix

高级主题

修复器优先级

某些修复器需要按特定顺序执行。可以通过重写 getPriority() 方法来控制：

public function getPriority(): int
{
    // 返回一个整数，数值越大优先级越高
    return 0;
}

令牌处理技巧

• getPrevMeaningfulToken() vs getPrevNonWhitespace()：
  • 前者忽略空白和注释
  • 后者仅忽略空白
  • 大多数情况下应该使用前者

常见问题解答

Q：为什么我的修复器没有被合并？

A：PHP-CS-Fixer 作为广泛使用的工具，需要确保稳定性。合并前会进行充分讨论和测试，这可能需要时间。

Q：如何处理复杂的代码转换？

A：对于复杂转换，建议：

1. 分解为多个简单修复器
2. 充分测试边界情况
3. 参考现有修复器的实现

最佳实践

1. 单一职责：每个修复器只处理一个特定问题
2. 全面测试：覆盖各种代码场景
3. 性能优化：isCandidate() 方法应尽可能高效
4. 文档清晰：修复器描述应准确明了

结语

通过本文的指导，您应该已经掌握了为 PHP-CS-Fixer 开发自定义修复器的完整流程。记住，好的修复器应该像隐形的好管家一样，默默改善代码质量而不引人注意。