PHP-CS-Fixer 的 @PHPUnit10x0Migration:risky 规则集:PHPUnit 10.0 测试代码迁移实战指南
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 规则集的完整内容为:
@PHPUnit9x1Migration:risky(嵌套引用,展开后包含@PHPUnit8x4Migration:risky等更早迁移集的全部规则);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 的实现看,修复流程是:
- 使用
DataProviderAnalyzer定位类范围内所有被@dataProvider引用的方法定义索引; - 找到每个数据提供者方法体的
{起止区间; - 关键判断:当
force为false时,若方法体内存在$this变量序列(findSequence([[T_VARIABLE, '$this']])),则跳过该方法(保留原样); - 通过
TokensAnalyzer::getMethodAttributes()检查方法是否已是static,是则跳过; - 否则在
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 withforcedisabled");force开启时即使含$this也强制静态化("fix when containing dynamic calls and withforceenabled");- 抽象方法、已有
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,启用后必须执行:
- 审查 diff:重点检查被静态化方法体内是否含
$this、$this->...调用; - 手动修正:将动态调用改为
self::...、静态属性/常量,或将数据生成逻辑重构为静态辅助函数; - 跑全量测试:确认无 "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 预览、以全量测试兜底,把自动化收益建立在可审查的基础之上。