PHP-CS-Fixer 的 @PHPUnit30Migration:risky 规则集：PHPUnit 3.0 兼容测试代码迁移指南

开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载导读PHPUnit30Migration:risky是 PHP-CS-Fixer 内置的一组迁移规则集用于将测试代码中的通用断言写法自动改写为 PHPUnit 3.0 时代引入的专用断言方法从而让测试代码与 PHPUnit 3.0 保持兼容。本文将以 doc/ruleSets/PHPUnit30MigrationRisky.rst 为主线完整讲解该规则集的组成、risky标记的含义、其与PHPUnit3x0Migration:risky的弃用/继承关系以及底层php_unit_dedicate_assert规则的target配置与实现原理。读完本文你将能够在自己的 PHP-CS-Fixer 配置中正确启用该规则集并理解每条改写背后的源码依据。规则集速览核心信息一览根据 doc/ruleSets/PHPUnit30MigrationRisky.rstPHPUnit30Migration:risky的定位非常清晰用途改善测试代码使其兼容 PHPUnit 3.0原文 Rules to improve tests code for PHPUnit 3.0 compatibility状态已弃用DEPRECATED将在下一个主版本 4.0 中移除替代方案应改用PHPUnit3x0Migration:risky风险等级该规则集整体标记为RISKY使用可能改变代码逻辑与行为需要谨慎使用并在合入前审查改动。该规则集的Rules一节只有一条内容即直接引用PHPUnit3x0Migration:risky见 doc/ruleSets/PHPUnit3x0MigrationRisky.rst而后者真正包含的规则是php_unit_dedicate_assert并携带配置[target 3.0]。为什么需要PHPUnit 迁移规则集PHPUnit 在其长期演进中不断调整断言 API早期版本鼓励使用assertTrue(is_float($a))这类通用断言 PHP 类型函数的写法而后续版本3.0 起陆续引入了assertInternalType、assertFileExists、assertNull、assertArrayHasKey等语义更明确的专用断言。当项目需要将测试代码迁移到某个 PHPUnit 版本、或希望统一到更现代的断言风格时手工逐个改写既繁琐又易错。PHP-CS-Fixer 用一套迁移规则集Migration Rule Set解决这个问题每个规则集面向一个目标 PHPUnit 版本自动将旧式断言改写为目标版本可用的新式断言。从源码看这类规则集的骨架统一实现在 src/RuleSet/AbstractMigrationSetDefinition.php 中通过解析类名如PHPUnit3x0MigrationRiskySet提取实体PHPUnit与主/次版本号进而生成规则集名称PHPUnit3x0Migration:risky与描述文案描述文案即getDescription()返回的 Rules to improve tests code for PHPUnit 3.0 compatibility.与 RST 文档首行完全对应。也就是说PHPUnit30Migration:risky与其后继PHPUnit3x0Migration:risky描述的是同一件事面向 PHPUnit 3.0 的测试代码迁移。弃用关系PHPUnit30Migration:risky 如何指向 PHPUnit3x0Migration:risky为什么存在两个几乎同名的规则集这是 PHP-CS-Fixer 针对迁移规则集命名规范化做出的过渡设计旧命名PHPUnit30Migration3 和 0 直接拼接不够清晰新命名PHPUnit3x0Migration用x分隔主版本与次版本更易读。相关实现如下旧规则集类 src/RuleSet/Sets/PHPUnit30MigrationRiskySet.php 继承自AbstractMajorMinorDeprecationSetDefinition类体为空仅作为别名存在新规则集类 src/RuleSet/Sets/PHPUnit3x0MigrationRiskySet.php 继承自AbstractMigrationSetDefinition其getRules()真实返回public function getRules(): array { return [ php_unit_dedicate_assert [ target PhpUnitTargetVersion::VERSION_3_0, // 即 3.0 ], ]; }旧名称到新名称的转换发生在 src/RuleSet/AbstractMajorMinorDeprecationSetDefinition.php 的getRules()中通过正则#(\d)\.?(\d)#把PHPUnit30Migration:risky转换为PHPUnit3x0Migration:risky并委托给它getSuccessorsNames()返回后继规则集名称供工具链在检测到已弃用规则集时提示用户升级。这正是 RST 文档中 You should usePHPUnit3x0Migration:riskyinstead. 这句警示的源码级依据。从源码中的TODO v4 remove me MARKER_deprecated_migration_ruleset注释可以推断这类旧命名规则集将在 4.0 版本被整体移除。理解 RISKY 标记为什么用之前要谨慎规则集名中的:risky后缀并非装饰它对应AbstractRuleSetDefinition::isRisky()的实现见 src/RuleSet/AbstractRuleSetDefinition.php只要类名包含Risky该规则集即被标记为 risky。RST 文档给出的警告原文是This set contains rules that are risky. Using it may lead to changes in your codes logic and behaviour. Use it with caution and review changes before incorporating them into your code base.落到具体规则上php_unit_dedicate_assert的 risky 理由在 doc/rules/php_unit/php_unit_dedicate_assert.rst 中写得很明白Fixer could be risky if one is overriding PHPUnits native methods.——如果你在测试类中覆写了 PHPUnit 的原生断言方法自动改写可能会改变实际调用的方法进而影响行为。因此在集成这类规则集时务必遵循两条纪律先跑--diff或--dry-run审查改动再实际应用对存在自定义断言覆写的测试基类优先单独配置或排除相关文件。规则集的实际内容php_unit_dedicate_assert 与 target 配置PHPUnit30Migration:risky及其后继只包含一条规则php_unit_dedicate_assert配置为[target 3.0]。这条规则的官方定义是PHPUnit assertions likeassertInternalType,assertFileExists, should be used overassertTrue.即当assertTrue/assertFalse的参数是对 PHP 类型/状态函数的调用时改写为对应的专用断言。该规则是可配置的CONFIGURABLE其唯一选项target的含义与取值范围如下来自 doc/rules/php_unit/php_unit_dedicate_assert.rst 及 src/Fixer/PhpUnit/PhpUnitDedicateAssertFixer.php选项值含义说明3.0目标 PHPUnit 3.0仅启用 3.0 已存在的断言3.5目标 PHPUnit 3.5追加assertInternalType、assertEmpty等5.0目标 PHPUnit 5.0追加assertInfinite、assertNan等5.6目标 PHPUnit 5.6追加assertDirectoryExists、assertIsReadable等newest不限定版本默认值启用全部可用改写target的分层逻辑实现在PhpUnitDedicateAssertFixer::configurePostNormalisation()src/Fixer/PhpUnit/PhpUnitDedicateAssertFixer.php中规则十分清晰基础层target ≥ 3.0启用array_key_exists→assertArrayHasKey、file_exists→assertFileExists、is_null→assertNull等以及str_ends_with/str_starts_with的映射追加层target ≥ 3.5加入empty→assertEmpty以及is_array、is_bool、is_float、is_int、is_string等一整套is_*类型检查 →assertInternalType的改写追加层target ≥ 5.0加入is_infinite→assertInfinite、is_nan→assertNan追加层target ≥ 5.6加入is_dir→assertDirectoryExists、is_readable→assertIsReadable、is_writable→assertIsWritable追加层target ≥ 7.5加入str_contains→assertStringContainsString。版本比较由 src/Fixer/PhpUnit/PhpUnitTargetVersion.php 的fulfills()完成目标为newest时恒为true否则使用composer/semver的Comparator::greaterThanOrEqualTo()判断。注意fulfills()对$target newest会抛出LogicException提示调用方必须为特性确定具体目标版本——这从侧面说明该版本分层设计是严谨的。在项目中启用 PHPUnit30Migration:risky虽然官方建议改用新命名但两者在当前版本4.0 之前均可使用。在.php-cs-fixer.php配置文件中启用该规则集?php $finder PhpCsFixer\Finder::create() -in(__DIR__./tests); return (new PhpCsFixer\Config()) -setFinder($finder) -setRules([ PHPUnit30Migration:risky true, ]) ;建议直接使用后继规则集以避免将来升级到 4.0 时的配置失效-setRules([ PHPUnit3x0Migration:risky true, ])命令行方式一次性执行不改动配置文件# 仅查看将发生的改动 php-cs-fixer fix --dry-run --diff --rulesPHPUnit3x0Migration:risky tests/ # 实际应用 php-cs-fixer fix --rulesPHPUnit3x0Migration:risky tests/如果只想在某个测试目录上生效或只想单独使用底层规则并自定义目标版本可以显式配置-setRules([ php_unit_dedicate_assert [target 3.0], ])代码改写效果从 assertTrue 到专用断言默认配置target newest以php_unit_dedicate_assert文档中的示例 #1 为例assertTrue(is_float(...))与assertTrue(is_nan(...))会被改写为assertInternalType(float, ...)与assertNan(...)- $this-assertTrue(is_float( $a), my message); - $this-assertTrue(is_nan($a)); $this-assertInternalType(float, $a, my message); $this-assertNan($a);配置 target 5.6文档示例 #2 展示了 5.6 目标下的目录/文件权限断言改写- $this-assertTrue(is_dir($a)); - $this-assertTrue(is_writable($a)); - $this-assertTrue(is_readable($a)); $this-assertDirectoryExists($a); $this-assertIsWritable($a); $this-assertIsReadable($a);target 3.0 的边界行为这一点常被忽略但至关重要target 为 3.0 时is_dir、is_readable、is_writable不会被改写因为对应的assertDirectoryExists等断言直到 PHPUnit 5.6 才引入。测试用例 tests/Fixer/PhpUnit/PhpUnitDedicateAssertFixerTest.php 明确验证了这一行为在[target 3.0]配置下输入与期望输出完全一致即保持assertTrue(is_dir($a))原样。这提醒我们迁移规则集保证的是改写后的代码在你的目标版本上依然可用而不是改写所有可能改写的代码。实现原理FIX_MAP 与 Token 级处理PhpUnitDedicateAssertFixer的改写能力建立在 PHP-CS-Fixer 的 Tokenizer 之上src/Fixer/PhpUnit/PhpUnitDedicateAssertFixer.php映射表FIX_MAP常量维护了从 PHP 函数名到断言方法的完整映射包括正/反向断言如file_exists→assertFileExists/assertFileNotExists、参数个数要求argument_count以及需要交换参数顺序的映射swap_arguments用于str_contains等断言调用定位applyPhpUnitClassFix()通过getPreviousAssertCall()在测试类范围内逐个定位assertTrue/assertFalse、assertSame/assertEquals等调用正反向判定依据assertTrue还是assertFalse决定采用positive还是negative映射对于没有反向断言的函数如is_nan的 negative 为false则跳过改写Token 级重写对is_*类型函数直接构造assertInternalType(类型, ...)形式——将函数名 token 替换为字符串字面量、括号替换为逗号并清理多余空白与命名空间前缀 tokenfixAssertTrueFalse方法instanceof 支持fixAssertTrueFalseInstanceof()还能处理assertTrue($a instanceof Foo)形式改写为assertInstanceOf(Foo::class, $a)或assertNotInstanceOfcount 断言fixAssertSameEquals()会把assertEquals($n, count($a))改写为assertCount($n, $a)。此外该规则的getPriority()返回-9并注释了执行顺序约束Must run before NoUnusedImportsFixer, PhpUnitAssertNewNamesFixer, PhpUnitDedicateAssertInternalTypeFixer. Must run after ModernizeStrposFixer, NoAliasFunctionsFixer, PhpUnitConstructFixer.——即在正确的 fixer 链条位置上工作避免与其他 PHPUnit 相关规则产生冲突。测试保障官方行为承诺规则文档明确指出测试类定义了官方支持的行为每个测试用例都是向后兼容承诺的一部分。PhpUnitDedicateAssertFixerTesttests/Fixer/PhpUnit/PhpUnitDedicateAssertFixerTest.php通过数据驱动方式覆盖了大量场景包括assertTrue/assertFalse的正反向改写含带消息参数的场景带\前缀的全局函数与命名空间内函数如test\is_nan的区分处理——只有真正的全局函数调用才会被改写is_null改写为assertNull/assertNotNullempty改写为assertEmpty/assertNotEmpty大小写不敏感的断言方法名ASSERTFALSE也能正确识别各target版本下的启用/禁用边界如上述 3.0 目标不改写is_dir的用例负数形式!与instanceof表达式的处理。这些用例是理解该规则精确行为的第一手资料也是你在集成前评估风险的最好参考。延伸完整的 PHPUnit 迁移规则集家族php_unit_dedicate_assert不止属于 3.0 迁移规则集。根据 doc/rules/php_unit/php_unit_dedicate_assert.rst 的 Rule sets 一节它同时是PHPUnit3x2Migration:risky、PHPUnit3x5Migration:risky、PHPUnit4x3Migration:risky乃至PHPUnit11x0Migration:risky等二十余个迁移规则集的一部分只是各自携带不同的target值如 3.5 迁移集用3.55.6 迁移集用5.6。这体现了 PHP-CS-Fixer 迁移规则集的整体设计同一规则按目标版本分层启用各版本规则集按需组合。如果你正在做 PHPUnit 大版本升级可以参考仓库中对应的 RST 文档按序执行迁移例如 doc/ruleSets/PHPUnit3x5MigrationRisky.rst、doc/ruleSets/PHPUnit5x6MigrationRisky.rst、doc/ruleSets/PHPUnit8x4MigrationRisky.rst 等若希望一次性迁移到最新AutoPHPUnitMigrationRisky规则集对应 src/RuleSet/Sets/AutoPHPUnitMigrationRiskySet.php是更省心的选择。小结PHPUnit30Migration:risky是 PHP-CS-Fixer 面向 PHPUnit 3.0 的测试代码迁移规则集核心内容是通过php_unit_dedicate_asserttarget 3.0将assertTrue/assertFalse包装的通用断言改写为 PHPUnit 3.0 可用的专用断言。它已被PHPUnit3x0Migration:risky取代并将在 4.0 移除建议新配置直接使用新名称。由于该规则集整体标记为 RISKY可能改变测试逻辑尤其当测试类覆写了 PHPUnit 原生断言方法时启用前务必通过--dry-run --diff审查改动。理解了target的分层启用机制与源码级映射表之后你就能精准控制迁移范围安全地完成 PHPUnit 版本升级。赞分享开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载相关推荐PHP-CS-Fixer 规则集 PHPUnit9x1Migration:risky 完整指南PHPUnit 9.1 兼容性测试代码自动迁移PHP CS Fixer 规则集 PHPUnit9x1Migration:risky 完整指南PHPUnit 9.1 兼容性测试代码自动迁移 本篇技术指南围开发工具代码质量静态分析Lint格式化打牌记账本如何让好友牌局告别纸笔混乱打牌记账本如何让好友牌局告别纸笔混乱 想象一下这样的场景你和几个好友正在打牌牌局进行到一半有人突然问刚才谁赢了多少钱大家面面相觑有人掏出手机开发工具代码质量静态分析Lint格式化PHP-CS-Fixer 的 PHPUnit11x0Migration:risky 规则集PHPUnit 11 测试代码迁移实战指南PHP CS Fixer 的 PHPUnit11x0Migration:risky 规则集PHPUnit 11 测试代码迁移实战指南 导读 PHPUnit开发工具代码质量静态分析Lint格式化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考