sebastian/comparator 变更日志深度解析:从 2.1 到 8.4 的 PHP 值相等性比较演进史

原创2026-10-14 14:07:521,976 阅读
文章标签:开发工具测试

sebastian/comparator 变更日志深度解析:从 2.1 到 8.4 的 PHP 值相等性比较演进史

导读

ChangeLog.md 是 PHP 生态中知名的值相等性比较组件 sebastian/comparator(PHPUnit 的断言底层依赖之一)的完整演进档案,遵循 Keep a CHANGELOG](http://keepachangelog.com/) 规范记录。本文以该变更日志为骨架,逐版本梳理 Factory、各类型 Comparator、ComparisonFailure 的核心能力变迁,并深入仓库源码([src/ 与 tests/unit/)验证每一处关键行为,帮助读者掌握该库的版本脉络、比较语义与故障排查技巧。读完本文,你将理解 comparator 如何从简单的数组比较工具成长为覆盖闭包、枚举、BcMath\Number、DateInterval 等现代 PHP 特性的完整比较框架,并能根据变更日志反推源码实现细节。


一、组件定位与版本基线

sebastian/comparator 是一个提供「PHP 值相等性比较」能力的组件,通过 composer.json 可知其当前约束为 php >= 8.4,依赖 sebastian/diff ^9.0.1、sebastian/exporter ^8.2.1 以及 ext-dom、ext-mbstring,并建议(suggest)启用 ext-bcmath 以支持 BcMath\Number 对象比较。它由 PHPUnit 作者 Sebastian Bergmann 维护,是 PHPUnit 断言 assertEquals() 的底层实现基础。

从 ChangeLog.md 可以还原出三条清晰的演进主线:

  1. 支持范围收窄:PHP 版本要求从 PHP 7.0(3.0.0)→ 移除 7.1/7.2(4.0.0)→ 移除 7.3/7.4/8.0(5.0.0)→ 移除 8.1(6.0.0)→ 移除 8.2(7.0.0)→ 移除 8.3(8.0.0),一路收紧到如今的 PHP 8.4+。
  2. 比较器家族扩充:从早期的通用比较器,逐步新增 EnumerationComparator(6.1.0)、NumberComparator(6.3.0)、ClosureComparator(7.1.0)、DateIntervalComparator(8.2.0)。
  3. 工程质量持续加固:diff 输出、序列化、PHP 8.5 兼容性、静态分析工具迁移(6.0.1 从 Psalm 切换为 PHPStan,仓库根目录的 phpstan.neon 即为其配置)等细节被反复打磨。

二、工厂机制:比较器的调度中枢

2.1 Factory 的分派与注册语义

src/Factory.php 是全部比较器的调度中心。getComparatorFor(mixed $expected, mixed $actual) 依次遍历 自定义比较器(customComparators,通过 register() 注册,优先级更高)与 默认比较器(defaultComparators),第一个 accepts() 返回 true 的比较器即被选中,找不到则抛出 RuntimeException:

$factory = new Factory;
$comparator = $factory->getComparatorFor($date1, $date2);

README.md 给出了最小用法:对两个 DateTime 对象调用 assertEquals(),失败时捕获 ComparisonFailure。

从 tests/unit/FactoryTest.php 的 instanceProvider 可以看到默认分派矩阵的全貌:

  • 标量与 null、布尔值 → ScalarComparator
  • 数字与数字字符串混合 → NumericComparator
  • 数组对数组 → ArrayComparator
  • 资源对资源 → ResourceComparator
  • stdClass 对象 → ObjectComparator
  • DateTime/DateTimeImmutable → DateTimeComparator
  • DateInterval → DateIntervalComparator
  • SplObjectStorage → SplObjectStorageComparator
  • Exception → ExceptionComparator
  • DOMDocument → DOMNodeComparator
  • 枚举值对 → EnumerationComparator
  • 闭包对 → ClosureComparator
  • 完全不匹配的类型组合 → TypeComparator(accepts() 恒为 true 的兜底)

2.2 默认比较器注册顺序(源码佐证)

Factory::registerDefaultComparators()(src/Factory.php)的注册顺序即优先级顺序,这一点直接影响行为:

ClosureComparator → MockObjectComparator → DateTimeComparator → DateIntervalComparator
→ DOMNodeComparator → SplObjectStorageComparator → ExceptionComparator → EnumerationComparator
→ NumberComparator(仅当 bcmath 扩展已加载且 PHP >= 8.4)
→ ObjectComparator → ResourceComparator → ArrayComparator → NumericComparator → ScalarComparator → TypeComparator

注意 MockObjectComparator 排在很靠前的位置——这正是 3.0.2 版本「默认情况下 MockObjectComparator 在其他默认比较器之前尝试」这一变更的直接体现。

自定义比较器通过 register() 插入到 customComparators 数组头部(array_unshift),并经由 setFactory() 注入工厂引用;unregister() 移除单个比较器,2.1.0 引入的 reset() 则清空全部自定义比较器。Factory 本身是单例(getInstance()),tests/unit/FactoryTest.php 中有对应断言。

2.3 8.1.0 与 8.4.0:diff 上下文行与 Exporter 的可配置化

  • 8.1.0 引入「diff 上下文行可配置」:Factory::setContextLines() 修改默认 3 行的上下文长度(见 src/Factory.php),该值经由 Comparator::contextLines() 传递给最终生成的 ComparisonFailure;tests/unit/FactoryTest.php 中的 testContextLinesDefaultsToThree / testContextLinesCanBeConfigured 与 tests/unit/ComparisonFailureTest.php 的 testCustomContextLines 分别验证了默认值与自定义值下的 diff 输出差异。
  • 8.4.0 新增 Factory::setExporter() 与 Factory::exporter(),允许为工厂统一配置 SebastianBergmann\Exporter\Exporter 实例。此前每个比较器各自 new Exporter,如今统一从工厂取用(src/Comparator.php),从而可以在比较失败消息中自定义值表示方式。tests/unit/FactoryTest.php 的 testDefaultComparatorUsesExporterConfiguredForFactory 展示了使用 SampleClassExporter 后,失败消息由逐属性表示变为 SampleClass(4) / SampleClass(16) 这样的自定义表示。

2.4 对象表示优先级规则(8.4.0 关键语义)

8.4.0 同时明确了失败消息的表示优先级:当对象 exporter 能提供对象表示时,比较失败消息优先使用该表示而非逐属性表示;但拥有专属比较器的对象(如 DateTimeComparator 比较的 DateTime)除外——专属比较器提供的表示永远优先。

这一规则在源码中处处可见:src/ObjectComparator.php 中,当逐属性比较抛出 ComparisonFailure 且 exporter 对任一对象有自定义表示(hasCustomRepresentationFor())时,直接用 exporter->export() 的结果构造新的失败信息;而 src/DateTimeComparator.php、src/ClosureComparator.php、src/DOMNodeComparator.php、src/DateIntervalComparator.php、src/EnumerationComparator.php、src/NumberComparator.php 的类注释则一致声明「比较器自身提供的表示永远具有优先级」,形成一套严谨的「专属比较器 > 对象 exporter > 逐属性」三级优先链。

三、各类型比较器的行为与修复脉络

3.1 ArrayComparator:规范化比较的不断纠偏

src/ArrayComparator.php 定义数组相等性为「包含相同的键值对,键顺序无关,键值类型无关」。canonicalize 模式下,列表(array_is_list())通过 usort 排序,关联数组通过 ksort 排序,之后按键逐个递归比较(子值比较同样走 Factory::getComparatorFor() 分派)。

ChangeLog 中与本类相关的修复最能体现「规范化的坑」:

  • 6.0.2 / 5.0.2(#112):修复「canonicalize 模式下,键不同但值相同的数组被判为相等」——即排序后丢失键语义的问题。
  • 8.1.1(#140):修复 sort() 对混合类型数组产生非确定性结果。源码改用自定义的 compare()(src/ArrayComparator.php),通过 typeOrder() 引入稳定的类型排序:null(0) < bool(1) < int/float(2) < string(3) < array(4) < object(5) < 其他(6);同类对象再按类名比较,相等对象进一步通过比较器判定,无法判定时退回 serialize() 比较。
  • 8.1.2(#141):修复按 spl_object_id() 排序对象导致「相等对象的数组被判定不等」——当前实现已不再依赖对象 id 排序。
  • 8.2.1(#136 与 #160):其一,修复「规范化列表比较销毁字符串键」——从源码看,列表场景下 usort 后只输出值不输出键(src/ArrayComparator.php),字符串键被销毁的问题由此根除;其二,输出更干净的规范化列表 diff,并对闭包改为按值比较(见 3.4 节)。

3.2 DateTimeComparator 与 DateIntervalComparator:时间比较的时间戳化

DateTimeComparator(src/DateTimeComparator.php)接受 DateTime/DateTimeImmutable 组合,比较语义为「时间差是否落在 delta 容差内」:先归一化到 UTC,再构造 expected ± delta 的区间,实际值越界即失败。其中 delta 被转换为带秒与微秒的 DateInterval($delta->f = $absDelta - floor($absDelta)),这正是 3.0.0 修复「不支持亚秒 delta」(#48)的实现。ChangeLog 相关修复还包括:

  • 2.1.1(phpunit#2923):修复意外失败的日期匹配。
  • 2.1.2:修复 DateTimeImmutable 对象比较。
  • 8.2.0(#115):修复「嵌套结构中未追踪已处理对象对,产生误导性 diff」——当前 assertEquals() 通过 $processed 数组记录 <a href="https://link.gitcode.com/i/ddd764982a59d299cb4f70c06adb572e" target="_blank">$actual, $expected] 对([src/DateTimeComparator.php),与 ObjectComparator 的循环依赖防护机制一致。

DateIntervalComparator(8.2.0 新增,src/DateIntervalComparator.php)支持对 DateInterval 做带 delta 容差的比较。核心技巧是 toSeconds():把区间施加到 Unix 纪元(DateTimeImmutable('@0'))上换算成秒数(含微秒),再比较差值是否超过容差。其注释明确指出:月、年等日历组件是相对固定锚点求值的(一个月不总是 30 天、一年不总是 365 天),因此日历组件不同但换算后时长相同的区间,在容差内仍可能被视为相等。测试(tests/unit/DateIntervalComparatorTest.php)覆盖了 PT1H vs PT3600S、P1D vs PT24H 这类「等价归一化组件」场景,以及 f 微秒字段与 invert 反向区间的容差判定。

3.3 DOMNodeComparator:XML 规范的持久战

src/DOMNodeComparator.php 接受任意 DOMNode 对,通过 nodeToText() 把节点规范化:优先 C14N() 规范化,再重新载入 DOMDocument、设置 UTF-8 编码、formatOutput 并 normalizeDocument() 合并相邻文本节点、移除空文本节点;若 C14N() 失败则退回 saveXML() 序列化(serialize() 方法)。ignoreCase 开关使用 mb_strtolower(..., 'UTF-8')(5.0.0 从 strtolower 迁移而来,对多字节文本更安全)。

ChangeLog 中围绕它的修复几乎构成一部 XML 比较的踩坑史:

  • 3.0.1(#53):修复 $ignoreCase 参数被忽略——当前实现中 nodeToText() 明确接收并应用该参数。
  • 4.0.5(#89):处理 PHP 8 的 ValueError——loadXML() 处有 try/catch (ValueError)。
  • 8.2.0(#70 / #87 / #107):分别修复「XML diff 中非 ASCII 文本被渲染成数字字符引用导致不可读」(nodeToText() 强制 UTF-8 编码解决)、「C14N() 失败时崩溃或误报」(@ 抑制符 + 序列化回退兜底)、「仅注释不同的 XML 文档被误判相等」(C14N + 重新加载规范化的流程消除了注释差异)。

3.4 ClosureComparator:闭包的按值比较(7.1.0 / 8.3.0)

7.1.0 新增闭包比较支持(#127)。8.2.1(#160)把闭包比较从按引用改为按值,8.3.0(#163)则暴露了闭包比较的检测能力。

src/ClosureComparator.php 的实现极具参考价值:assertEquals() 首先调用 $this->factory()->recordClosureComparison() 记录一次闭包比较(该记录机制即 8.3.0 暴露的 API,对应 src/Factory.php 的 recordClosureComparison() / closureComparisonOccurred() / resetClosureComparisonTracking())。随后通过 ReflectionFunction 从三个维度判定闭包相等:

  1. 声明点相等(declarationIsEqual):函数名、文件名、起始行、结束行完全一致;
  2. 绑定相等(bindingIsEqual):作用域类(getClosureScopeClass())一致,且 $this 绑定对象递归相等;
  3. 捕获状态相等(capturedStateIsEqual):getClosureUsedVariables() 捕获的变量递归相等(递归比较同样走工厂分派)。

失败信息会指出两处声明位置:Failed asserting that closure declared at %s:%d is equal to closure declared at %s:%d(src/ClosureComparator.php)。tests/unit/ClosureComparatorTest.php 的测试矩阵非常完整:相同声明点 + 相同捕获值判相等;声明点不同、捕获值不同、作用域类不同(Closure::bind 重绑)、$this 对象不等均判失败;tests/unit/FactoryTest.php 还验证了嵌套在数组、对象中的闭包比较也会被记录,以及比较追踪可被重置。此外 7.1.3(#130)为闭包比较失败时补充了 diff 输出。

3.5 EnumerationComparator、NumberComparator 与 MockObjectComparator

  • EnumerationComparator(6.1.0 新增,src/EnumerationComparator.php):接受同为 UnitEnum 且枚举类相同的值对(accepts() 要求 $expected::class === $actual::class),相等判定直接使用 PHP 枚举的 === 语义,失败消息会带出两个 case 名:... %s does not match expected %s.。
  • NumberComparator(6.3.0 新增,src/NumberComparator.php):支持 BcMath\Number 对象与 int / 数字字符串的混合比较,非 Number 的一方会被转换为 new Number(...),容差 $delta 也按 max($expected->scale, $actual->scale) 的小数位精度构造为 Number 后再做区间判定。由于依赖 ext-bcmath,Factory 仅在扩展已加载且 PHP ≥ 8.4 时才注册它(src/Factory.php)。
  • MockObjectComparator:用于比较 PHPUnit 的 Stub/MockObject。toArray() 会剥掉所有以 __phpunit_ 开头的内部属性(src/MockObjectComparator.php)。5.0.1 修复了两点:其一,此前只对 MockObject 生效而忽略 Stub 实例(当前 accepts() 已改为 instanceof Stub);其二,此前只忽略 $__phpunit_invocationMocker 单个属性,现在按前缀过滤全部 __phpunit_* 属性。

3.6 数值、标量与字符串比较的边界处理

  • NumericComparator(src/NumericComparator.php):接受「数值型但非双字符串」的组合(避免两个数字字符串被重复处理)。7.0.1(#122)修复 INF 被误判等于 -INF——当前实现要求两个无穷值的符号一致才通过(src/NumericComparator.php);同时 NaN 或 abs($actual - $expected) > $delta 都会判失败。4.0.8(#102)修复浮点比较精度问题。
  • ScalarComparator(src/ScalarComparator.php):接受标量、null 以及带 __toString() 的对象与字符串互比。核心技巧是「始终转成字符串再比较,避免 0 == 'Foobar' 这类奇怪行为」(src/ScalarComparator.php)。4.0.7 / 3.0.4(#99)修复弱比较下 '0' 与 false 的误判——注意字符串与布尔值互比时不做字符串转换;4.0.8 / 3.0.5(#102)同样涉及浮点精度。6.2.0(#117)为长字符串比较去掉过长的公共前缀/后缀(removeOverlongCommonPrefix/removeOverlongCommonSuffix,阈值 40 字符、保留 25 字符上下文),让超长字符串的失败输出只展示差异片段;3.0.1(#58)则修复了「极端丑陋的字符串比较边界」。

3.7 其余比较器一览

  • ObjectComparator(src/ObjectComparator.php):先校验类名一致,再通过 $processed 数组防循环比较,然后委托给父类 ArrayComparator 逐属性比较,失败消息把 Array 字样替换为 ClassName Object(substr_replace(..., 0, 5))。5.0.0 起 Comparator::$factory 私有化,子类只能通过 Comparator::factory() 访问。
  • ExceptionComparator(src/ExceptionComparator.php):比较 Exception 时在 toArray() 中剔除 file、line、trace、string、xdebug_message 等易变属性,只比较消息、代码等稳定字段。
  • SplObjectStorageComparator(src/SplObjectStorageComparator.php):双向校验每个对象在两个 storage 中都存在(offsetExists)。
  • ResourceComparator(src/ResourceComparator.php):用弱比较 != 判定资源相等。
  • TypeComparator(src/TypeComparator.php):accepts() 恒 true 的兜底比较器,gettype() 不一致即失败。

四、ComparisonFailure:失败信息的载体

所有比较失败的终点都是抛出 ComparisonFailure(src/ComparisonFailure.php,继承 RuntimeException,4.0.6 起正确实现 \Throwable 链)。它承载 expected/actual 原始值、二者的字符串表示、消息与上下文行数,并提供两个关键方法:

  • getDiff():使用 SebastianBergmann\Diff\Differ 生成统一 diff。8.1.4(#138)从 UnifiedDiffOutputBuilder 切换为 StrictUnifiedDiffOutputBuilder,8.1.3 则透传 sebastian/diff 8.3.0 引入的配置项——当前实现配置了 header(--- Expected / +++ Actual)、关闭行号、按 contextLines 控制上下文、开启行尾警告(src/ComparisonFailure.php)。
  • __serialize() / __unserialize():8.2.0(#158)修复「堆栈追踪含不可序列化对象时 ComparisonFailure 无法序列化」——通过显式序列化六个稳定字段(expected、actual、expectedAsString、actualAsString、message、contextLines)规避整个对象的隐式序列化。

tests/unit/ComparisonFailureTest.php 验证了 diff 头格式(--- Expected / +++ Actual)、空字符串表示时跳过 diff、以及不同上下文行数对 diff 的影响。README 用法示例中正是通过捕获该异常来区分「日期匹配」与「日期不匹配」。

五、工程化与兼容性演进

5.1 PHP 版本支持与依赖演进

版本 关键变更
2.1.0 新增 Factory::reset();支持 phpunit-mock-objects ^5.0
2.1.3 兼容 sebastian/diff 3
3.0.0 移除 PHP 7.0;修复 DateTime 亚秒 delta
3.0.2 MockObjectComparator 默认优先于其他比较器
4.0.0 移除 PHP 7.1 / 7.2
4.0.3 支持 PHP 8
5.0.0 移除 PHP 7.3 / 7.4 / 8.0;方法全面添加参数与返回类型声明;Comparator::$factory 私有化;ComparisonFailure::__construct() 移除 $identical 参数;多个比较器类 final;标量与 DOM 比较改用 mb_strtolower(..., 'UTF-8')
6.0.0 移除 PHP 8.1
6.0.1 静态分析从 Psalm 切换为 PHPStan
6.1.0 新增枚举比较器
6.3.0 新增 BcMath\Number 支持
7.0.0 移除 PHP 8.2
7.1.0 新增闭包比较
7.1.1 / 5.0.4 / 6.3.2 等 不再使用 PHP 8.5 将弃用的 SplObjectStorage 方法
7.1.4 / 6.3.3 / 5.0.5 等(#134) 抑制 PHP 8.5 引入的警告
8.0.0 移除 PHP 8.3

值得注意的是,同一修复经常跨版本分支同步:例如 #134、#122(INF vs -INF)、#136(规范化列表)、#140、#141、#158 等同时在 8.x 与 6.x/5.x/7.x 分支落地,体现出项目对历史分支的持续维护策略。

5.2 静态分析与工具链

6.0.1 之后项目以 PHPStan 为静态分析工具,根目录 phpstan.neon 承载配置;代码中大量 @phpstan-ignore 注释(如 src/ArrayComparator.php、src/NumericComparator.php)是针对具体规则点位的例外声明。仓库同时维护了 tools/php-cs-fixer、tools/phpstan、tools/phive、tools/composer 等工具链(见 tools/),并保留 phpunit.xml 用于本地运行 tests/unit/ 下的测试套件。

5.3 5.0.0 的向后兼容性提示

5.0.0 是一次面向类型的重构:方法全部带上参数与返回类型声明;Comparator::$factory 由公开转私有,外部需改用 Comparator::factory();ComparisonFailure::__construct() 删除了 $identical 参数。若你的代码曾直接实例化 ComparisonFailure 并传入第五个布尔参数,或直接读写 $factory 属性,升级时需相应调整。4.0.2 与 6.1.1 / 5.0.3 也曾因破坏向后兼容而回退过 #113 / #85 相关改动,说明该库对兼容性承诺非常谨慎。

六、从 ChangeLog 反推的实战排查清单

结合 ChangeLog 与源码,这里整理一份可落地的排查清单:

  1. 数组比较结果异常:优先检查是否开启 canonicalize。涉及键语义问题时对照 6.0.2 / 8.2.1(#112 / #136)的修复;涉及混合类型排序时对照 8.1.1(#140)的 typeOrder 排序实现。
  2. 对象比较失败消息不直观:8.4.0 起可通过 Factory::setExporter() 注入自定义 Exporter 定制表示;但要记得专属比较器(DateTime、DOMNode、Closure、Enumeration、DateInterval、BcMath\Number)的表示永远优先。
  3. 时间/区间比较差一点就失败:DateTimeComparator 与 DateIntervalComparator 都支持 $delta 容差,且都做了对象对去重($processed);DateInterval 的月/年换算基于固定锚点,需理解其「日历组件不同但时长相等」的语义。
  4. XML 文档比较异常:DOMNodeComparator 已覆盖 C14N() 失败回退、注释差异、非 ASCII 文本等问题(8.2.0 系列修复),若仍有疑问可结合 ignoreCase 开关(UTF-8 感知的 mb_strtolower)排查。
  5. 闭包比较失败:闭包相等 = 声明点相同 + 作用域/$this 绑定相同 + 捕获变量递归相同;失败消息会给出两处声明位置便于定位。若需要在测试中检测「是否发生过闭包比较」,可借助 8.3.0 暴露的 Factory::closureComparisonOccurred() 与 resetClosureComparisonTracking()。
  6. 序列化问题:ComparisonFailure 的序列化已由 8.2.0(#158)加固,直接 serialize() 它即可安全获得稳定字段。
  7. diff 上下文不满足需求:通过 Factory::setContextLines() 调节统一 diff 的上下文行数(默认 3)。

结语

从 2.1.0 到 8.4.0,ChangeLog.md 记录的不只是版本号,更是一部「PHP 值相等性比较」的工程演进史:类型覆盖面从标量、数组、对象一路扩展到枚举、闭包与任意精度数值;失败信息从简单的字符串逐步进化到可配置上下文、可定制 Exporter 的干净 diff;PHP 兼容策略则随 PHP 官方支持周期坚定前移。对 PHPUnit 用户而言,理解这份变更日志背后的 src/ 实现,就等于掌握了 assertEquals() 底层「为什么相等、为什么不相等」的完整答案。

说明:本文所有源码行为均可在当前仓库对应文件中验证;版本区间与发布日期以 ChangeLog.md 为准。

登录后查看全文
comparator