DoctrineExtensions 从 v2.4 升级到 v3.0 指南

DoctrineExtensions 从 v2.4 升级到 v3.0 指南

DoctrineExtensions Doctrine2 behavioral extensions, Translatable, Sluggable, Tree-NestedSet, Timestampable, Loggable, Sortable 项目地址: https://gitcode.com/gh_mirrors/do/DoctrineExtensions

升级概述

DoctrineExtensions v3.0 版本主要聚焦于工具集和依赖项的升级，旨在提升与现代 PHP 版本的兼容性，并为未来的开发工作奠定更好的基础。对于大多数用户来说，这次升级不会带来显著的开发工作量。

主要变更点

1. MongoDB ODM 2.0 映射驱动问题

影响范围：使用 YAML 或 XML 映射驱动的 MongoDB 用户

ODM 2.0 对其映射器进行了重大修改，这可能导致以下问题：

• YAML 驱动已被完全移除
• XML 驱动增加了模式验证，不允许混合使用原生 ODM 和扩展元素

解决方案：

• 如果使用注解(Annotations)或 PHP 映射驱动，则不受影响
• YAML 和 XML 映射用户可能需要考虑迁移到其他映射方式

2. PHP 版本要求

影响范围：所有用户

• 最低 PHP 版本要求提升至 7.2
• PHP 7.1 已于 2019 年 12 月停止维护

3. MongoDB 扩展变更

影响范围：使用 MongoDB 的项目

• 必须安装 ext-mongodb PHP 扩展
• ext-mongo 扩展已被弃用，将在下一个主要版本中移除
• 最低 Doctrine MongoDB ODM 版本要求为 2.0

4. SoftDeleteable 变更

影响范围：实现了自定义 SoftDeleteableAdapter 的项目

SoftDeleteableAdapter 接口新增了一个用于生成 DateTime 值的方法。如果你有自定义实现，需要相应地进行更新。

升级建议

1. 环境检查：

   • 确保 PHP 版本 ≥ 7.2
   • MongoDB 用户需确认已安装 ext-mongodb 扩展

2. 映射驱动评估：

   • YAML/XML 用户应评估迁移到注解或 PHP 驱动的可行性

3. 依赖更新：

   • 更新 composer.json 中的版本约束
   • 运行 composer update 前备份项目

4. 测试验证：

   • 升级后应进行全面测试，特别是涉及软删除功能的部分

常见问题解答

Q: 为什么 YAML 驱动被移除了？ A: 这是 Doctrine MongoDB ODM 2.0 的决定，主要出于维护成本和现代 PHP 项目更倾向于使用注解或 PHP 驱动的考虑。

Q: 升级到 PHP 7.2 有兼容性问题怎么办？ A: 建议先解决 PHP 版本兼容性问题，再考虑升级 DoctrineExtensions。PHP 7.2 本身向后兼容性较好，主要注意废弃函数的替代方案。

Q: 自定义 SoftDeleteableAdapter 需要做什么修改？ A: 需要实现新的 DateTime 生成方法，具体实现可参考官方接口定义。

总结

DoctrineExtensions v3.0 是一个以现代化和兼容性为主要目标的版本升级。大多数用户只需关注 PHP 版本和依赖项的更新，而使用特定 MongoDB 映射驱动的用户可能需要额外的工作量。建议在测试环境中先行验证升级效果，确保生产环境平稳过渡。

DoctrineExtensions Doctrine2 behavioral extensions, Translatable, Sluggable, Tree-NestedSet, Timestampable, Loggable, Sortable 项目地址: https://gitcode.com/gh_mirrors/do/DoctrineExtensions