PHP-CS-Fixer 的 @PHPUnit11x0Migration:risky 规则集:PHPUnit 11 测试代码迁移实战指南
PHP-CS-Fixer 的 @PHPUnit11x0Migration:risky 规则集:PHPUnit 11 测试代码迁移实战指南
导读
@PHPUnit11x0Migration:risky 是 PHP-CS-Fixer 为帮助开发者将测试代码迁移至 PHPUnit 11.0 而提供的规则集,它以“继承链”方式聚合了自 PHPUnit 3 以来的全部历史迁移规则,确保测试代码与 PHPUnit 11.0 的 API 完全兼容。本文以该规则集的官方文档(doc/ruleSets/PHPUnit11x0MigrationRisky.rst)为核心,结合仓库源码剖析其规则构成、继承机制、risky 风险语义与配置方法,帮助读者安全地将其接入现有 PHPUnit 测试项目。
规则集概览:为 PHPUnit 11.0 而生
@PHPUnit11x0Migration:risky 规则集的官方定位非常明确:
Rules to improve tests code for PHPUnit 11.0 compatibility.
即用于改进测试代码以兼容 PHPUnit 11.0。该规则集属于 PHP-CS-Fixer 的“迁移规则集”(Migration Rule Set)体系——与纯粹的代码风格规则(如 PSR-12)不同,迁移规则集的目标不是美化代码,而是将测试代码从旧版 PHPUnit 的写法迁移到目标版本(此处为 11.0)所要求的新写法。
从源码看,该规则集定义于 src/RuleSet/Sets/PHPUnit11x0MigrationRiskySet.php,其类继承自 AbstractMigrationSetDefinition(src/RuleSet/AbstractMigrationSetDefinition.php),后者负责从规则集类名中解析出目标实体(PHPUnit)与版本号(11.0),并自动生成如 “Rules to improve tests code for PHPUnit 11.0 compatibility.” 的描述文案:
final class PHPUnit11x0MigrationRiskySet extends AbstractMigrationSetDefinition
{
public function getRules(): array
{
return [
'@PHPUnit10x0Migration:risky' => true,
];
}
}
整个类体极为精简——它的 getRules() 只返回一条规则:'@PHPUnit10x0Migration:risky' => true。但这正是理解该规则集的关键:它是一个聚合型(递进型)迁移规则集,自身并不直接声明具体 fixer,而是通过嵌套引用上一代迁移规则集来“继承”全部历史迁移规则。
规则构成:一条贯穿 PHPUnit 3 至 11 的迁移链
要真正理解 @PHPUnit11x0Migration:risky 包含哪些修复规则,需要沿着它的引用链逐层展开。仓库中的源码清晰地呈现了这条“俄罗斯套娃”式的继承结构:
@PHPUnit11x0Migration:risky→ 引用@PHPUnit10x0Migration:risky(src/RuleSet/Sets/PHPUnit10x0MigrationRiskySet.php)@PHPUnit10x0Migration:risky→ 引用@PHPUnit9x1Migration:risky并追加php_unit_data_provider_static => ['force' => true]@PHPUnit9x1Migration:risky(src/RuleSet/Sets/PHPUnit9x1MigrationRiskySet.php)→ 引用@PHPUnit8x4Migration:risky并追加php_unit_assert_new_names@PHPUnit8x4Migration:risky(src/RuleSet/Sets/PHPUnit8x4MigrationRiskySet.php)→ 引用@PHPUnit7x5Migration:risky并追加php_unit_expectation(target 8.4)@PHPUnit7x5Migration:risky(src/RuleSet/Sets/PHPUnit7x5MigrationRiskySet.php)→ 引用@PHPUnit6x0Migration:risky并追加php_unit_dedicate_assert_internal_type(target 7.5)- 依此类推,最终回溯到
@PHPUnit3x0Migration:risky
这一设计保证了:启用 @PHPUnit11x0Migration:risky 就等于同时启用了历史上所有 PHPUnit 迁移规则的累积集。任何旧版本 API 的用法——从 PHPUnit 3 时代的 assertInternalType,到 PHPUnit 9/10 时代的非静态 data provider——都会被依次修复到 PHPUnit 11.0 的规范写法。
嵌套规则集的展开机制
这种“规则集引用规则集”的写法之所以能生效,依赖 PHP-CS-Fixer 的 RuleSet 解析器。在 src/RuleSet/RuleSet.php 的 resolveSet() 方法中,凡是以 @ 开头的名称都会被识别为嵌套规则集,并递归展开合并:
private function resolveSet(array $rules): array
{
$resolvedRules = [];
// expand sets
foreach ($rules as $name => $value) {
if (str_starts_with($name, '@')) {
if (!\is_bool($value)) {
throw new \UnexpectedValueException(
\sprintf('Nested rule set "%s" configuration must be a boolean.', $name)
);
}
$set = $this->resolveSubset($name, $value);
$resolvedRules = array_merge($resolvedRules, $set);
} else {
$resolvedRules[$name] = $value;
}
}
...
}
也就是说,'@PHPUnit10x0Migration:risky' => true 会被逐层展开为一条条具体 fixer 规则(如 php_unit_data_provider_static、php_unit_assert_new_names 等),最终形成可直接执行的规则清单。嵌套规则集的值只能是布尔值(true/false),这与普通规则可配置数组的约束不同——从 src/RuleSet/RuleSet.php 的校验逻辑可以看出,@ 开头的集合项仅允许布尔开关,其他取值会抛出 InvalidFixerConfigurationException。
为什么它是 RISKY:风险语义与使用警告
该规则集名称中的 risky 后缀不是随意为之。官方文档在 “Warning” 一节明确警告:
This set contains rules that are risky. Using it may lead to changes in your code's logic and behaviour. Use it with caution and review changes before incorporating them into your code base.
翻译过来即:该集合包含有风险的规则,使用它可能导致代码逻辑和行为发生变化,必须谨慎使用,并在合入代码库前审查全部改动。
“risky” 在 PHP-CS-Fixer 中有明确的语义:risky 规则默认不启用,只有在 --risky-allowed(或配置中显式开启)时才会被执行。这源于 src/RuleSet/AbstractRuleSetDefinition.php 中的判断逻辑:
public function isRisky(): bool
{
return str_contains(static::class, 'Risky');
}
类名包含 Risky 即被标记为 risky。对迁移类规则而言,risky 的本质是:修复过程可能改变代码的运行时行为,而非仅仅调整格式。典型的风险场景包括:
- 将非静态 data provider 强制改为静态(见下文
php_unit_data_provider_static); - 改写断言 API(如
assertInternalType→assertIsArray),若被测代码存在边界行为差异,可能导致测试通过/失败状态发生变化; - 重命名/替换断言方法,可能触及通过字符串动态调用方法的代码。
因此官方文档强烈建议:启用前先阅读每一条具体规则的说明,启用后逐个审查 diff 再决定是否合入。
核心规则深挖:php_unit_data_provider_static
虽然 @PHPUnit11x0Migration:risky 本身只嵌套引用上一代规则集,但顺着 @PHPUnit10x0Migration:risky 展开,最重要的增量规则是 php_unit_data_provider_static(配置为 <a href="https://link.gitcode.com/i/2779c47c4af8837e72de4e67e6fbd755" target="_blank">'force' => true])。该规则的完整文档位于 [doc/rules/php_unit/php_unit_data_provider_static.rst,其目标直指 PHPUnit 10 引入的硬性要求:data provider 方法必须是静态的。
force 选项:强制迁移的利与弊
该规则只有一个配置项 force,含义如下:
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
force |
bool |
false |
是否强制将 data provider 转为静态,即使方法体内存在动态类调用($this->...)。强制转换可能引发致命错误 “using $this when not in object context”,需要手动将动态调用改为静态调用(如 self::...)。 |
在 @PHPUnit11x0Migration:risky 中,该规则被配置为 <a href="https://link.gitcode.com/i/b756af7116b38bbdfb1b2de1b3511e23" target="_blank">'force' => true],即无条件强制迁移。这与 @PhpCsFixer:risky 规则集对该规则的配置方式一致(见 [doc/ruleSets/PhpCsFixerRisky.rst)。
三种行为的代码对比
官方文档给出了三个示例,清晰展示 force 取值的差异:
示例 1:默认配置(force=false)下,无 $this 调用的 provider 会被转为静态:
--- Original
+++ New
<?php
class FooTest extends TestCase {
/**
* @dataProvider provideSomethingCases
*/
public function testSomething($expected, $actual) {}
- public function provideSomethingCases() {}
+ public static function provideSomethingCases() {}
}
示例 2:force=true 时,即使方法体内有 $this->getData1() 也会被强制转静态(可能导致致命错误,需手动修):
--- Original
+++ New
<?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(); }
}
示例 3:force=false 时,仅迁移可安全转换的 provider(无 $this 调用的),带动态调用的保持不变:
--- Original
+++ New
<?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(); }
}
这正是该规则被标记为 risky 的直接原因:force => true 的强制转换可能产生语法合法但运行时崩溃的代码,官方文档明确提示“你可能需要手动调整代码,把动态调用转换为静态调用”。
迁移链中的其他关键规则
继续沿迁移链向下展开,@PHPUnit11x0Migration:risky 实际聚合的历史迁移规则还包括(从对应规则集源码可见):
php_unit_assert_new_names(自@PHPUnit9x1Migration:risky引入):将 PHPUnit 9 起废弃的旧断言方法名改写为新命名,例如把assertInternalType风格改写为assertIsArray等新式断言;php_unit_expectation(自@PHPUnit8x4Migration:risky引入,target 为 8.4):将$this->setExpectedException()等旧式“期望异常”写法迁移为$this->expectException()新式写法;php_unit_dedicate_assert_internal_type(自@PHPUnit7x5Migration:risky引入,target 为 7.5):把assertInternalType('array', $value)迁移为专门的assertIsArray($value)等方法;- 更早期的规则还包括
php_unit_namespaced(导入 PHPUnit 的命名空间类名)、php_unit_mock(迁移 mock 相关 API)、php_unit_dedicate_assert、php_unit_no_expectation_annotation等,分布在 doc/rules/php_unit/ 下 23 个规则文档中。
这些规则在 doc/ruleSets/index.rst 的规则集索引中均有登记,且 @PHPUnit10x0Migration:risky 的文档(doc/ruleSets/PHPUnit10x0MigrationRisky.rst)展示了这种“引用上一代集合 + 追加增量规则”的典型写法。
与 @autoPHPUnitMigration:risky 的关系
值得补充的是,PHP-CS-Fixer 还提供了一个“自动化”迁移规则集 @autoPHPUnitMigration:risky(doc/ruleSets/AutoPHPUnitMigrationRisky.rst)。它不固定目标版本,而是读取项目 composer.json 中声明的 PHPUnit 最低版本,自动计算并启用对应的迁移规则集——@PHPUnit11x0Migration:risky 正是其候选规则集之一(候选列表覆盖 @PHPUnit3x0Migration:risky 至 @PHPUnit11x0Migration:risky)。
其实现见 src/RuleSet/Sets/AutoPHPUnitMigrationRiskySet.php:通过 AutomaticMigrationSetTrait 的 calculateTargetSet() 依据 composer.json 推导目标版本,getRulesCandidates() 则枚举全部候选集合。因此两条路径均可触达本主题的迁移能力:
- 固定版本:直接配置
@PHPUnit11x0Migration:risky; - 跟随项目:配置
@autoPHPUnitMigration:risky,由工具自动选择最合适的目标版本规则集。
如何启用 @PHPUnit11x0Migration:risky
在实际项目中使用该规则集,需要编写 PHP-CS-Fixer 的配置文件(php-cs-fixer.php),典型写法如下:
<?php
$finder = PhpCsFixer\Finder::create()
->in(__DIR__.'/tests')
;
return (new PhpCsFixer\Config())
->setFinder($finder)
->setRiskyAllowed(true) // 关键:必须允许 risky 规则
->setRules([
'@PHPUnit11x0Migration:risky' => true,
])
;
需要特别强调的是:
- 必须开启
setRiskyAllowed(true),否则 risky 规则集不会被应用,这也是命令行中--risky-allowed选项对应的配置入口; - 建议将 finder 限定在
tests/目录,避免迁移规则作用于生产代码; - 首次运行建议使用
php-cs-fixer fix --dry-run --diff预览全部改动,人工审查后再正式执行。
执行修复命令:
vendor/bin/php-cs-fixer fix --rules='{"@PHPUnit11x0Migration:risky": true}' --risky-allowed
若想查看该规则集展开后的完整规则清单,可使用 describe 命令:
vendor/bin/php-cs-fixer describe '@PHPUnit11x0Migration:risky'
关于测试覆盖的说明
从仓库的测试结构看,tests/RuleSet/RuleSetsTest.php 将 @PHPUnit11x0Migration:risky 列入“无集成测试”的豁免清单,而 tests/RuleSet/Sets/PHPUnit11x0MigrationRiskySetTest.php 继承自 AbstractSetTestCase 对规则集定义本身做基础校验。此外,tests/RuleSet/RuleSetsTest.php 中的标记表明:@PHPUnit\d+Migration 形式的迁移规则集已标记为 deprecated,计划在下一个 MAJOR 版本(v4)移除,届时建议迁移到 @autoPHPUnitMigration:risky 这类自动规则集或直接配置具体规则。
迁移实践建议与风险规避
结合官方文档的警告与源码实现,使用 @PHPUnit11x0Migration:risky 时建议遵循以下流程:
- 先读文档:逐一阅读 doc/rules/php_unit/ 下各规则文档,重点关注标有 “This rule is RISKY” 的规则;
- dry-run 预览:先以
--dry-run --diff模式运行,输出全部待改动 diff; - 重点审查:特别关注
php_unit_data_provider_static(force=true)对含$this->调用的 data provider 的强制转换,这类改动最可能引入 “using $this when not in object context” 致命错误; - 逐批合入:将迁移改动拆分为独立提交,配合 PHPUnit 测试套件全量回归,确保行为无变化;
- 跟踪版本演进:留意规则集的 deprecation 标记,为 PHP-CS-Fixer v4 的 API 变更(迁移规则集可能被移除)预留升级路径。
通过 @PHPUnit11x0Migration:risky,开发者可以用一条配置完成 PHPUnit 3 到 11 的全部测试代码 API 迁移,但必须始终牢记其 risky 属性——让机器完成重写,让人工完成审查,才是安全使用迁移规则集的正确姿势。