PHP-CS-Fixer `@PHPUnit35Migration:risky` 规则集详解：PHPUnit 3.5 测试代码迁移实战

开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载本篇技术指南以 PHP-CS-Fixer 官方规则集文档doc/ruleSets/PHPUnit35MigrationRisky.rst为核心系统讲解用于改善 PHPUnit 3.5 兼容性的 risky 规则集PHPUnit35Migration:risky它的定位与风险等级、废弃状态与迁移路径、底层规则组成以及在实际项目中如何启用、配置与验证。读完本文你将掌握如何借助该规则集将旧式assertTrue(is_*())断言风格自动改写为 PHPUnit 3.5 专用的assertInternalType等断言并理解规则集继承机制与集成测试的验证方式。规则集定位面向 PHPUnit 3.5 的测试代码改善PHPUnit35Migration:risky是 PHP-CS-Fixer 提供的一组面向 PHPUnit 3.5 兼容性的规则集其官方定义见 PHPUnit35MigrationRisky.rst只有一句话Rules to improve tests code for PHPUnit 3.5 compatibility.即通过自动化的代码风格修复让测试代码更贴近 PHPUnit 3.5 时代推荐的断言 API。这一规则集在仓库中的对应实现是 src/RuleSet/Sets/PHPUnit35MigrationRiskySet.php。从源码可以看到它继承了AbstractMajorMinorDeprecationSetDefinitionfinal class PHPUnit35MigrationRiskySet extends AbstractMajorMinorDeprecationSetDefinition {}类体为空所有规则行为都由基类驱动。基类 src/RuleSet/AbstractMajorMinorDeprecationSetDefinition.php 的核心逻辑是将当前规则集名称中 数字.数字 形式的版本号改写为 数字x数字 形式从而把旧规则集直接委托给对应的新命名规则集public function getRules(): array { $newName Preg::replace(#(\d)\.?(\d)#, \1x\2, $this-getName()); return [ $newName true, ]; } public function getSuccessorsNames(): array { return array_keys($this-getRules()); }以本规则集为例名称PHPUnit35Migration:risky中的35会被转换为3x5最终得到[PHPUnit3x5Migration:risky true]也就是说PHPUnit35Migration:risky本身只是一个兼容性别名真正执行的规则全部来自PHPUnit3x5Migration:risky。getSuccessorsNames()返回的 继任者名称 就是新规则集的名称用于在 CLI 输出和文档中提示用户进行迁移。重大警告该规则集已废弃请改用PHPUnit3x5Migration:risky官方文档在本规则集页面中给出了最醒目的警告This rule set is DEPRECATED and will be removed in the next major version 4.0. You should usePHPUnit3x5Migration:riskyinstead.这包含两条关键信息废弃状态PHPUnit35Migration:risky已被标记为 deprecated并将在下一个主版本4.0中被移除。继续使用它虽然当前仍可工作但会产生废弃警告。替换方案应当改用新命名的PHPUnit3x5Migration:risky。之所以会有新老两套命名可以从文档目录结构看出规则集文档统一收录在 doc/ruleSets 下既有PHPUnit35MigrationRisky.rst这样的老式 数字 命名文档也有PHPUnit3x5MigrationRisky.rst这样的新式 数字x数字 命名文档对应的源码集合同样成对存在PHPUnit35MigrationRiskySet.php 与 PHPUnit3x5MigrationRiskySet.php。新命名用x分隔主次版本号语义更清晰、排序更稳定是后续版本唯一保留的命名方式。因此在实际项目中请直接使用PHPUnit3x5Migration:risky而把PHPUnit35Migration:risky视为历史遗留的别名仅在阅读旧配置或迁移存量配置时理解其含义。Risky 风险声明使用前必须知悉的行为变更与所有以:risky后缀结尾的规则集一样官方文档明确声明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.含义是该规则集包含 risky 规则可能改变代码的逻辑与行为需要谨慎使用并在合入代码库前人工审查每一处改动。这是 PHP-CS-Fixer 对 risky 规则的统一约定——risky 规则通常基于语义等价假设进行改写一旦代码存在特殊用法例如重写了 PHPUnit 的原生断言方法改写就可能破坏原有行为。因此启用本规则集时建议配合以下工程实践在干净的 git 分支上运行方便逐条 diff 审查先在小范围单个测试目录试点确认无行为回归后再全量应用修复后立即运行完整测试套件验证断言改写没有改变测试语义。规则构成从PHPUnit3x5Migration:risky看完整规则链虽然PHPUnit35Migration:risky页面只列出一条链接指向PHPUnit3x5Migration:risky但要让文章信息完整、可落地需要深入其继任者的规则定义。查看 doc/ruleSets/PHPUnit3x5MigrationRisky.rst 与对应源码 src/RuleSet/Sets/PHPUnit3x5MigrationRiskySet.php可以看到它包含两条规则public function getRules(): array { return [ PHPUnit3x2Migration:risky true, php_unit_dedicate_assert [ target PhpUnitTargetVersion::VERSION_3_5, ], ]; }拆解如下PHPUnit3x2Migration:risky规则集嵌套。它本身又包含PHPUnit3x0Migration:risky与php_unit_no_expectation_annotationtarget 3.2。因此整个继承链是PHPUnit35Migration:risky→PHPUnit3x5Migration:risky→PHPUnit3x2Migration:risky→PHPUnit3x0Migration:risky逐级向下兼容、逐级叠加规则。php_unit_dedicate_assert配置[target 3.5]将assertTrue(is_*())这类通用断言改写为 PHPUnit 3.5 时期专用的断言方法是本规则集的核心动作。值得注意target在这里使用PhpUnitTargetVersion::VERSION_3_5常量即字符串3.5。版本常量统一定义在 src/Fixer/PhpUnit/PhpUnitTargetVersion.php从VERSION_3_0到VERSION_11_0覆盖了 PHPUnit 3.011.0 的各个里程碑版本外加VERSION_NEWESTnewest。target决定修复器在改写为哪个版本才存在的断言 API上的取舍——例如assertInternalType在 PHPUnit 3.5 即已存在而assertIsArray、assertDirectoryExists这类命名要到 PHPUnit 5.6 才引入只有target达到对应版本时才会生成相应写法。核心规则深入php_unit_dedicate_assert的原理与改写效果规则文档速览php_unit_dedicate_assert的官方说明见 doc/rules/php_unit/php_unit_dedicate_assert.rst指出像assertInternalType、assertFileExists这类 PHPUnit 断言应当取代通用的assertTrue。该规则属于RISKY规则如果代码中重写了 PHPUnit 的原生方法修复可能产生风险属于CONFIGURABLE规则可通过target选项配置。target选项的可选值为3.0、3.5、5.0、5.6与newest默认值为newest。本规则集将其固定为3.5即只改写为 PHPUnit 3.5 时代可用的断言形式。改写映射表源码级该修复器实现在 src/Fixer/PhpUnit/PhpUnitDedicateAssertFixer.php。它内部维护一张FIX_MAP常量表将 PHP 内置函数/结构映射到对应的 PHPUnit 断言方法PHP 表达式在assertTrue中正断言负断言array_key_existsassertArrayHasKeyassertArrayNotHasKeyemptyassertEmptyassertNotEmptyfile_existsassertFileExistsassertFileNotExistsis_array/is_bool/is_callable/is_float/is_int/is_numeric/is_object/is_resource/is_scalar/is_stringassertInternalType(..., $x)assertNotInternalType(..., $x)is_dirassertDirectoryExistsassertDirectoryNotExistsis_infiniteassertInfiniteassertFiniteis_nanassertNan无负断言is_nullassertNullassertNotNullis_readableassertIsReadableassertNotIsReadableis_writableassertIsWritableassertNotIsWritablestr_contains/str_ends_with/str_starts_withassertStringContainsString等对应否定版本其中is_array、is_float等类型判断在 FIX_MAP 中标记为true表示走通用类型断言分支在target为3.5时生成的是assertInternalType(array, $x)形式assertInternalType正是 PHPUnit 3.5 引入的 API而assertIsArray这类逐类型专名断言要到 PHPUnit 5.6 才出现因此只有target 5.6才会生成。官方示例规则文档给出默认配置target为newest下的改写示例- $this-assertTrue(is_float($a), my message); - $this-assertTrue(is_nan($a)); $this-assertInternalType(float, $a, my message); $this-assertNan($a);以及[target 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的核心影响同样一句assertTrue(is_dir($a))在target3.5时改写结果取决于 3.5 是否具备对应专名断言而target5.6时可以生成assertDirectoryExists等更现代的断言。这也解释了为什么本规则集要把target固定在3.5——它只承诺 PHPUnit 3.5 兼容。集成测试验证改写行为仓库为PHPUnit3x5Migration:risky提供了官方集成测试可以直接看到真实输入输出输入样例 tests/Fixtures/Integration/set/PHPUnit3x5Migration-risky.test-in.phpclass FooTest extends \PHPUnit_Framework_TestCase { public function test_dedicate_assert($foo) { $this-assertTrue(is_null($foo)); $this-assertTrue(is_array($foo)); $this-assertTrue(is_nan($foo)); $this-assertTrue(is_readable($foo)); } /** * Foo. * expectedException FooException * expectedExceptionCode 123 */ function test_php_unit_no_expectation_annotation_32() { bbb(); } }输出样例 tests/Fixtures/Integration/set/PHPUnit3x5Migration-risky.test-out.phpclass FooTest extends \PHPUnit_Framework_TestCase { public function test_dedicate_assert($foo) { $this-assertNull($foo); $this-assertInternalType(array, $foo); $this-assertTrue(is_nan($foo)); $this-assertTrue(is_readable($foo)); } /** * Foo. */ function test_php_unit_no_expectation_annotation_32() { $this-setExpectedException(\FooException::class, null, 123); bbb(); } }这个例子非常直观地展示了规则集的整体行为assertTrue(is_null($foo))→assertNull($foo)assertTrue(is_array($foo))→assertInternalType(array, $foo)这正是target3.5与默认newest的差异所在默认配置下is_array会被改写为assertIsArrayassertTrue(is_nan($foo))与assertTrue(is_readable($foo))未被改写——因为is_nan的assertNan与is_readable的assertIsReadable均为 3.5 时代不存在的断言target3.5时安全地跳过了它们expectedException/expectedExceptionCode注解被转换为$this-setExpectedException(\FooException::class, null, 123);——这是继承自PHPUnit3x2Migration:risky中php_unit_no_expectation_annotation规则target 3.2的作用。这正是 risky 规则语义等价但需要人工确认的典型体现改写的确严格按 target 版本约束执行不会引入目标版本不存在的 API。如何在项目中启用该规则集通过--rules命令行直接指定PHP-CS-Fixer 支持在命令行直接传入规则集vendor/bin/php-cs-fixer fix tests/ --rulesPHPUnit35Migration:risky如果不想触发废弃警告应使用新命名vendor/bin/php-cs-fixer fix tests/ --rulesPHPUnit3x5Migration:risky通过配置文件.php-cs-fixer.dist.php启用在项目根目录的.php-cs-fixer.dist.php中配置?php $finder PhpCsFixer\Finder::create() -in(__DIR__./tests); return (new PhpCsFixer\Config()) -setRules([ PHPUnit3x5Migration:risky true, ]) -setFinder($finder) -setRiskyAllowed(true) // 必须开启否则 risky 规则集不会生效 ;关键点PHPUnit35Migration:risky与PHPUnit3x5Migration:risky均属于 risky 规则集。PHP-CS-Fixer 对 risky 规则采取默认关闭策略只有当配置中显式设置setRiskyAllowed(true)或命令行传入--allow-riskyyes时才会实际执行。因此启用时请务必同时开启 risky 许可否则规则集会被静默忽略。与其他 PHPUnit 迁移规则集的关系PHP-CS-Fixer 的 PHPUnit 迁移规则集构成一个完整的版本阶梯见 doc/ruleSets 目录PHPUnit3x0Migration:risky、PHPUnit3x2Migration:risky、PHPUnit3x5Migration:risky一路延伸到PHPUnit11x0Migration:risky。它们通过低版本规则集嵌套进高版本规则集的方式逐级叠加保证迁移到任意目标版本时所有低版本的兼容性改写都会被包含。PHPUnit35Migration:risky及废弃别名PHPUnit35Migration:risky正位于这条阶梯的第三级是面向 PHPUnit 3.5 目标的聚合入口。总结与使用建议围绕PHPUnit35Migration:risky可以提炼出以下要点本质是别名它在仓库源码中的实现为空壳类通过AbstractMajorMinorDeprecationSetDefinition自动委托给PHPUnit3x5Migration:risky后者才真正聚合规则。已废弃勿在新配置中使用官方明确声明将在 4.0 移除新项目请直接使用PHPUnit3x5Migration:risky存量配置可借助getSuccessorsNames()的提示完成迁移。风险自担risky 规则集可能改变测试代码逻辑与行为务必开启setRiskyAllowed(true)、逐条审查 diff、并在修复后回归完整测试。行为受target约束核心规则php_unit_dedicate_assert在target3.5下只生成 PHPUnit 3.5 已存在的断言如assertInternalType、assertNull不会提前引入更高版本才有的assertIsArray、assertDirectoryExists等 API。集成测试即行为规范tests/Fixtures/Integration/set/PHPUnit3x5Migration-risky.test 系列的输入输出对是官方对规则集行为的权威定义任何对改写结果的疑问都可以在此求证。如果你的测试代码仍停留在 PHPUnit 3.5 时代的assertTrue(is_*())风格且需要在不引入高版本 API 的前提下保持兼容那么PHPUnit3x5Migration:riskyPHPUnit35Migration:risky的继任者正是对口的自动化迁移工具——只需记得启用 risky、审查 diff、跑通测试。赞分享开发工具代码质量静态分析Lint格式化【免费下载链接】PHP-CS-FixerA tool to automatically fix PHP Coding Standards issues项目地址https://gitcode.com/gh_mirrors/ph/PHP-CS-Fixer点击查看免费下载相关推荐PHP-CS-Fixer 规则集详解PHPUnit8x4Migration:risky 与 PHPUnit 8.4 测试代码迁移实战PHP CS Fixer 规则集详解PHPUnit8x4Migration:risky 与 PHPUnit 8.4 测试代码迁移实战 导读 PHPUnit开发工具代码质量静态分析Lint格式化PHP-CS-Fixer 规则集解析PHPUnit32Migration:risky 与 PHPUnit 3.2 测试代码迁移实战PHP CS Fixer 规则集解析PHPUnit32Migration:risky 与 PHPUnit 3.2 测试代码迁移实战 本篇技术指南围绕 PHP开发工具代码质量静态分析Lint格式化打牌记账本如何让好友牌局告别纸笔混乱打牌记账本如何让好友牌局告别纸笔混乱 想象一下这样的场景你和几个好友正在打牌牌局进行到一半有人突然问刚才谁赢了多少钱大家面面相觑有人掏出手机开发工具代码质量静态分析Lint格式化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考