PHP-CS-Fixer 的 @PHPUnit10x0Migration:risky 规则集:PHPUnit 10.0 测试代码迁移实战指南

原创2026-09-22 11:11:481,916 阅读
文章标签:开发工具CLI代码质量Lint格式化

PHP-CS-Fixer 的 @PHPUnit10x0Migration:risky 规则集:PHPUnit 10.0 测试代码迁移实战指南

导读

@PHPUnit10x0Migration:risky 是 PHP-CS-Fixer 提供的一组 Risky 迁移规则集,目标是自动改进测试代码,使其与 PHPUnit 10.0 保持兼容。本文以 PHPUnit10x0MigrationRisky.rst 为骨架,结合仓库源码(规则实现、规则集定义与测试)深入拆解该规则集的组成、php_unit_data_provider_static 规则的工作原理、force 配置项的行为边界,并给出真实可运行的配置与迁移流程。读完本文,你将掌握如何在项目中启用该规则集、理解其风险来源,并能在升级 PHPUnit 10 前安全地自动化迁移数据提供者方法。


一、规则集全景:它包含哪些规则

从 PHPUnit10x0MigrationRisky.rst 可见,@PHPUnit10x0Migration:risky 规则集的完整内容为:

  1. @PHPUnit9x1Migration:risky(嵌套引用,展开后包含 @PHPUnit8x4Migration:risky 等更早迁移集的全部规则);
  2. php_unit_data_provider_static,且强制配置为 ['force' => true]。

这与源码 PHPUnit10x0MigrationRiskySet.php 中 getRules() 的返回完全一致:

return [
    '@PHPUnit9x1Migration:risky' => true,
    'php_unit_data_provider_static' => ['force' => true],
];

嵌套的迁移链条

@PHPUnit10x0Migration:risky 并非孤立的规则集合,而是一条按 PHPUnit 版本演进串联起来的迁移链条:

  • PHPUnit9x1MigrationRisky.rst 包含 @PHPUnit8x4Migration:risky 与 php_unit_assert_new_names;
  • PHPUnit8x4MigrationRisky.rst 又包含 @PHPUnit7x5Migration:risky 与 php_unit_expectation(配置为 ['target' => '8.4']);
  • 依此类推,一直追溯到更早的 PHPUnit 迁移集。

从源码结构看,这类规则集统一继承自 AbstractMigrationSetDefinition,它通过解析规则集名称自动生成 getDescription()(形如 "Rules to improve tests code for PHPUnit 10.0 compatibility."),并利用正则 #^@PHPUnit(\d+)x?(\d)Migration.*$# 提取主版本号与次版本号。这解释了为什么文档与描述文本是自动生成的、始终与规则集名称保持一致。

与 @PHPUnit100Migration:risky 的关系

仓库中还保留了旧版命名 @PHPUnit100Migration:risky(见 PHPUnit100MigrationRisky.rst)。该规则集已被标记为 DEPRECATED,将在下一个主版本 4.0 中移除,官方明确建议改用 @PHPUnit10x0Migration:risky。其源码类 PHPUnit100MigrationRiskySet 继承自 AbstractMajorMinorDeprecationSetDefinition,本身不再声明任何规则,只是指向新命名的迁移集。

结论:新项目应直接使用 @PHPUnit10x0Migration:risky;老配置文件中的 @PHPUnit100Migration:risky 应尽快迁移,避免在 4.0 升级时失效。


二、为什么这个规则集是 Risky

文档中明确给出了警告:该规则集包含 risky 规则,使用它可能导致代码逻辑与行为发生变化,必须谨慎使用并在合入前审查改动。

Risky 的本质来自其核心规则 php_unit_data_provider_static:把非静态的数据提供者方法改为 static。一旦方法体内通过 $this 访问实例状态(例如 $this->getData()),强制静态化后运行时就会抛出致命错误:

using $this when not in object context

因此该规则集默认把 force 置为 true,意味着即使数据提供者内部存在动态类调用,也会被强制改造成 static,之后需要你手动把其中的 $this->... 调用转换为静态调用或注入依赖。这是 @PHPUnit10x0Migration:risky 最大的行为风险来源,务必在启用后运行完整测试套件进行回归验证。


三、核心规则拆解:php_unit_data_provider_static

规则的定义文档见 php_unit_data_provider_static.rst,一句话概括:Data providers must be static.(数据提供者必须为静态方法。)

3.1 为什么 PHPUnit 10 要求静态数据提供者

PHPUnit 10 将数据提供者必须为 static 方法从"推荐"提升为强制要求,非静态数据提供者会直接报错。该规则正是为此而设计:自动扫描所有被 @dataProvider 注解引用的方法,并补上 static 关键字,从而让测试代码平滑迁移到 PHPUnit 10。

3.2 配置项 force

配置项 类型 默认值 说明
force bool false 是否强制将数据提供者静态化,即使其方法体内部存在动态类调用($this)。开启后可能引入致命错误 "using $this when not in object context",需要手动将动态调用改为静态调用。

在源码 PhpUnitDataProviderStaticFixer.php 中,force 通过 FixerOptionBuilder 定义为布尔类型、默认 false:

(new FixerOptionBuilder(
    'force',
    'Whether to make the data providers static even if they have a dynamic class call'
    .' (may introduce fatal error "using $this when not in object context",'
    .' and you may have to adjust the code manually by converting dynamic calls to static ones).',
))
    ->setAllowedTypes(['bool'])
    ->setDefault(false)
    ->getOption(),

3.3 修复逻辑与底层实现

从 applyPhpUnitClassFix 的实现看,修复流程是:

  1. 使用 DataProviderAnalyzer 定位类范围内所有被 @dataProvider 引用的方法定义索引;
  2. 找到每个数据提供者方法体的 { 起止区间;
  3. 关键判断:当 force 为 false 时,若方法体内存在 $this 变量序列(findSequence([[T_VARIABLE, '$this']])),则跳过该方法(保留原样);
  4. 通过 TokensAnalyzer::getMethodAttributes() 检查方法是否已是 static,是则跳过;
  5. 否则在 function 关键字前插入 static 标记(insertSlices)。

换言之,force=false 是"安全模式":只静态化不依赖 $this 的方法;force=true 是"全量模式":无视内部调用一律静态化。@PHPUnit10x0Migration:risky 采用后者,因为迁移到 PHPUnit 10 时所有数据提供者都必须静态化,无法选择性地跳过。

3.4 官方示例(来自规则文档)

示例 1:默认配置(force=false)

 <?php
 class FooTest extends TestCase {
     /**
      * @dataProvider provideSomethingCases
      */
     public function testSomething($expected, $actual) {}
-    public function provideSomethingCases() {}
+    public static function provideSomethingCases() {}
 }

示例 2:force=true(@PHPUnit10x0Migration:risky 的默认行为)

 <?php
 class FooTest extends TestCase {
     /**
      * @dataProvider provideSomethingCases1
      * @dataProvider provideSomethingCases2
      */
     public function testSomething($expected, $actual) {}
-    public function provideSomethingCases1() { $this->getData1(); }
-    public function provideSomethingCases2() { self::getData2(); }
+    public static function provideSomethingCases1() { $this->getData1(); }
+    public static function provideSomethingCases2() { self::getData2(); }
 }

注意:provideSomethingCases1 内的 $this->getData1() 在静态化后会触发致命错误,这正是需要人工干预的地方——将其改为 self::getData1() 或把数据来源改为静态/注入方式。

示例 3:force=false(安全模式)

 <?php
 class FooTest extends TestCase {
     /**
      * @dataProvider provideSomething1Cases
      * @dataProvider provideSomething2Cases
      */
     public function testSomething($expected, $actual) {}
     public function provideSomething1Cases() { $this->getData1(); }
-    public function provideSomething2Cases() { self::getData2(); }
+    public static function provideSomething2Cases() { self::getData2(); }
 }

可见 force=false 下,含 $this 调用的 provideSomething1Cases 被跳过,仅静态化安全的 provideSomething2Cases。

3.5 测试证据

该规则的行为由 PhpUnitDataProviderStaticFixerTest.php 完整覆盖,测试用例同时验证了:

  • force 关闭时跳过含动态调用($this)的方法(对应测试数据 "fix when containing dynamic calls and with force disabled");
  • force 开启时即使含 $this 也强制静态化("fix when containing dynamic calls and with force enabled");
  • 抽象方法、已有 static 方法、带属性(attribute)的方法等边界场景。

正如规则文档所述,"The test class defines officially supported behaviour. Each test case is a part of our backward compatibility promise."——这些测试用例构成了该规则的向后兼容承诺,迁移时无需担心行为漂移。


四、如何在项目中启用并执行迁移

4.1 命令行方式(无需配置文件)

在项目根目录执行(仓库根目录下有可执行入口 php-cs-fixer):

php php-cs-fixer fix /path/to/tests --rules='@PHPUnit10x0Migration:risky' --dry-run --diff
  • 先用 --dry-run --diff 预览将被修改的文件与具体 diff,确认风险点;
  • 确认无误后去掉 --dry-run 执行实际修复。

4.2 配置文件方式(推荐用于持续集成)

在 .php-cs-fixer.dist.php 中启用:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in(__DIR__.'/tests');

return (new PhpCsFixer\Config())
    ->setRules([
        '@PHPUnit10x0Migration:risky' => true,
    ])
    ->setFinder($finder);

然后运行:

php php-cs-fixer fix

4.3 迁移后的回归清单

由于该规则集为 Risky,启用后必须执行:

  1. 审查 diff:重点检查被静态化方法体内是否含 $this、$this->... 调用;
  2. 手动修正:将动态调用改为 self::...、静态属性/常量,或将数据生成逻辑重构为静态辅助函数;
  3. 跑全量测试:确认无 "using $this when not in object context" 致命错误,且数据驱动用例数量与结果不变。

五、组合使用建议与注意事项

  • @PHPUnit10x0Migration:risky 适合在正式升级 PHPUnit 10 之前的准备阶段启用,此时测试代码尚未强制报错,迁移风险最低;
  • 该规则集只负责测试代码(php_unit_* 系列规则均作用于测试类),不会改动业务代码;
  • 若你同时使用 @PhpCsFixer:risky,注意该集也包含 php_unit_data_provider_static 且同样配置为 <a href="https://link.gitcode.com/i/30bc529333387199af1deb64b06a4703" target="_blank">'force' => true](见 [PhpCsFixerRisky.rst),二者不会冲突,但规则顺序与配置以显式配置为准;
  • 未来 PHPUnit 11 迁移集 @PHPUnit11x0Migration:risky(见 PHPUnit11x0MigrationRisky.rst)同样复用该规则,说明 php_unit_data_provider_static 是 PHPUnit 10+ 迁移的基础性规则。

六、小结

@PHPUnit10x0Migration:risky 通过一条可追溯的嵌套迁移链与 php_unit_data_provider_static(['force' => true]) 的组合,把 PHPUnit 10 最核心的破坏性变更——数据提供者必须静态化——自动化。理解其 Risky 属性与 force 语义,配合源码中 DataProviderAnalyzer 与 TokensAnalyzer 的修复逻辑,你可以在升级前安全、可控地完成测试代码迁移。建议始终以 --dry-run --diff 预览、以全量测试兜底,把自动化收益建立在可审查的基础之上。

登录后查看全文
PHP-CS-Fixer