sebastian/comparator 变更日志深度解析:从 2.1 到 8.4 的 PHP 值相等性比较演进史
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 可以还原出三条清晰的演进主线:
- 支持范围收窄: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+。
- 比较器家族扩充:从早期的通用比较器,逐步新增
EnumerationComparator(6.1.0)、NumberComparator(6.3.0)、ClosureComparator(7.1.0)、DateIntervalComparator(8.2.0)。 - 工程质量持续加固: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对象 →ObjectComparatorDateTime/DateTimeImmutable→DateTimeComparatorDateInterval→DateIntervalComparatorSplObjectStorage→SplObjectStorageComparatorException→ExceptionComparatorDOMDocument→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 从三个维度判定闭包相等:
- 声明点相等(
declarationIsEqual):函数名、文件名、起始行、结束行完全一致; - 绑定相等(
bindingIsEqual):作用域类(getClosureScopeClass())一致,且$this绑定对象递归相等; - 捕获状态相等(
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 与源码,这里整理一份可落地的排查清单:
- 数组比较结果异常:优先检查是否开启
canonicalize。涉及键语义问题时对照 6.0.2 / 8.2.1(#112 / #136)的修复;涉及混合类型排序时对照 8.1.1(#140)的typeOrder排序实现。 - 对象比较失败消息不直观:8.4.0 起可通过
Factory::setExporter()注入自定义 Exporter 定制表示;但要记得专属比较器(DateTime、DOMNode、Closure、Enumeration、DateInterval、BcMath\Number)的表示永远优先。 - 时间/区间比较差一点就失败:
DateTimeComparator与DateIntervalComparator都支持$delta容差,且都做了对象对去重($processed);DateInterval的月/年换算基于固定锚点,需理解其「日历组件不同但时长相等」的语义。 - XML 文档比较异常:
DOMNodeComparator已覆盖C14N()失败回退、注释差异、非 ASCII 文本等问题(8.2.0 系列修复),若仍有疑问可结合ignoreCase开关(UTF-8 感知的mb_strtolower)排查。 - 闭包比较失败:闭包相等 = 声明点相同 + 作用域/
$this绑定相同 + 捕获变量递归相同;失败消息会给出两处声明位置便于定位。若需要在测试中检测「是否发生过闭包比较」,可借助 8.3.0 暴露的Factory::closureComparisonOccurred()与resetClosureComparisonTracking()。 - 序列化问题:
ComparisonFailure的序列化已由 8.2.0(#158)加固,直接serialize()它即可安全获得稳定字段。 - diff 上下文不满足需求:通过
Factory::setContextLines()调节统一 diff 的上下文行数(默认 3)。
结语
从 2.1.0 到 8.4.0,ChangeLog.md 记录的不只是版本号,更是一部「PHP 值相等性比较」的工程演进史:类型覆盖面从标量、数组、对象一路扩展到枚举、闭包与任意精度数值;失败信息从简单的字符串逐步进化到可配置上下文、可定制 Exporter 的干净 diff;PHP 兼容策略则随 PHP 官方支持周期坚定前移。对 PHPUnit 用户而言,理解这份变更日志背后的 src/ 实现,就等于掌握了 assertEquals() 底层「为什么相等、为什么不相等」的完整答案。
说明:本文所有源码行为均可在当前仓库对应文件中验证;版本区间与发布日期以 ChangeLog.md 为准。