Doctrine Deprecations 库与 PHPUnit 12 的兼容性问题解析

背景介绍

Doctrine Deprecations 是一个用于管理代码废弃(deprecation)通知的 PHP 库，它帮助开发者平滑过渡到新版本的 API。该库提供了一个 PHPUnit 测试特性 VerifyDeprecations，用于在测试中验证废弃警告是否被正确触发。

问题发现

随着 PHPUnit 12 的发布，一个重要的变更影响了 Doctrine Deprecations 库的功能。PHPUnit 12 移除了对 doc-block 注解的支持，而 Doctrine Deprecations 库恰好使用了这种注解方式来标记测试方法。

技术细节分析

在 Doctrine Deprecations 的 VerifyDeprecations trait 中，原本使用了两种 doc-block 注解：

1. @before - 用于标记在测试前执行的方法
2. @after - 用于标记在测试后执行的方法

这些注解在 PHPUnit 12 中不再被识别，导致相关功能失效。具体来说，这会影响测试套件中废弃警告的收集和验证机制。

解决方案

Doctrine 团队已经通过发布 2.0.0 版本解决了这个问题。新版本采用了 PHPUnit 12 推荐的方式来替代 doc-block 注解：

1. 使用 PHPUnit 提供的 #[Before] 和 #[After] 属性(attributes)来替代 @before 和 @after 注解
2. 这些属性是 PHP 8.0 引入的原生特性，提供了更现代、类型安全的注解方式

升级建议

对于使用 Doctrine Deprecations 库的项目，如果需要升级到 PHPUnit 12，应当：

1. 确保项目运行在 PHP 8.0 或更高版本（因为属性需要 PHP 8+）
2. 将 Doctrine Deprecations 升级到 2.0.0 或更高版本
3. 检查项目中是否还有其他地方使用了 PHPUnit 的 doc-block 注解，进行相应替换

总结

这次变更反映了 PHP 生态系统的演进趋势：从传统的 doc-block 注解转向更现代化的属性系统。Doctrine Deprecations 库的及时更新确保了与最新测试工具的兼容性，同时也推动了开发者采用更先进的 PHP 特性。