升级doctrine/mongodb-odm至2.x后YamlDriver不存在如何迁移适配

运行报错 #

PHP Fatal error: Uncaught Error: Class "Doctrine\ODM\MongoDB\Mapping\Driver\YamlDriver" not found

项目环境 #

• Zend Framework 版本：1.21.2
• PHP 版本约束：^8.1

问题背景 #

升级应用doctrine/mongodb-odm依赖包时触发上述报错，原依赖版本为1.2.5，升级后锁定版本为^2.4.2。

原有YAML映射配置 #

1. 映射文件存储结构

/configs/doctrinemappings/
├── myFile.dcm.yml
└── myFile1.dcm.yml

2. Bootstrap.php 驱动初始化代码

<?php
$driver = new \Doctrine\ODM\MongoDB\Mapping\Driver\YamlDriver(array(APPLICATION_PATH.'/configs/doctrinemappings/'));
$config->setMetadataDriverImpl($driver);
?>

3. composer.json 相关依赖配置

"require": {
    "php": "^8.1",
    "doctrine/mongodb-odm": "^2.4.2",
    "doctrine/mongodb-odm-bundle": "^4.4"
}

当前现状 #

升级后的doctrine/mongodb-odm版本已完全移除YamlDriver类，仅提供4种可用元数据驱动：

• AnnotationDriver
• SimplifiedXMLDriver
• XMLDriver
• AttributeDriver

方案1：迁移到PHP8原生属性驱动（AttributeDriver，推荐） #

该方案是当前版本官方首推方案，适配PHP8.1+环境，不需要维护额外映射文件，也不依赖注释解析，性能最优、长期维护成本最低，迁移步骤如下：

1. 修改Bootstrap.php中的驱动初始化代码，路径替换为项目实际的模型实体存放目录

<?php
use Doctrine\ODM\MongoDB\Mapping\Driver\AttributeDriver;

$driver = new AttributeDriver([
    APPLICATION_PATH . '/models/'
]);
$config->setMetadataDriverImpl($driver);
?>

2. 逐个对照原有YAML映射文件，给对应实体类、属性添加PHP8原生映射属性，对照示例：
   原有YAML配置片段：

MyProject\Model\User:
  db: mydb
  collection: users
  fields:
    id:
      id: true
    username:
      type: string
      nullable: false
    email:
      type: string
    createdAt:
      type: date

对应添加属性后的实体类代码：

<?php
namespace MyProject\Model;

use Doctrine\ODM\MongoDB\Mapping\Annotations as ODM;

#[ODM\Document(db: 'mydb', collection: 'users')]
class User
{
    #[ODM\Id]
    public string $id;

    #[ODM\Field(type: 'string', nullable: false)]
    public string $username;

    #[ODM\Field(type: 'string')]
    public string $email;

    #[ODM\Field(type: 'date')]
    public \DateTimeInterface $createdAt;
}
?>

3. 全量迁移完成后，直接删除原/configs/doctrinemappings/目录下所有YAML映射文件即可。

方案2：迁移到XML驱动（无需修改实体类代码） #

如果不想改动现有实体类代码，可以选择XML驱动，仅需将原有YAML文件转换为对应格式的XML映射文件即可，步骤如下：

1. 修改Bootstrap.php驱动初始化代码

<?php
use Doctrine\ODM\MongoDB\Mapping\Driver\XmlDriver;

// 指向XML映射文件存放目录
$driver = new XmlDriver([
    APPLICATION_PATH . '/configs/doctrinemappingsxml/'
]);
$config->setMetadataDriverImpl($driver);
?>

2. 将原有YAML映射逐份转换为XML格式，以上述User模型为例，对应XML映射文件内容：

<?xml version="1.0" encoding="UTF-8"?>
<doctrine-mongo-mapping>
    <document name="MyProject\Model\User" db="mydb" collection="users">
        <id field-name="id" />
        <field field-name="username" type="string" nullable="false" />
        <field field-name="email" type="string" />
        <field field-name="createdAt" type="date" />
    </document>
</doctrine-mongo-mapping>

3. 所有XML文件转换完成后，删除原有YAML映射文件即可。如果偏好更简洁的XML语法，可以选择SimplifiedXMLDriver，迁移逻辑与普通XML驱动完全一致，按照对应简化格式编写XML文件即可。

方案3：迁移到注解驱动（AnnotationDriver） #

该方案与AttributeDriver逻辑类似，区别是使用文档块注解而非PHP原生属性，需要额外安装注解解析依赖，步骤如下：

1. 安装依赖：执行命令composer require doctrine/annotations
2. 修改Bootstrap.php驱动初始化代码

<?php
use Doctrine\ODM\MongoDB\Mapping\Driver\AnnotationDriver;

$driver = new AnnotationDriver(
    new \Doctrine\Common\Annotations\AnnotationReader(),
    [APPLICATION_PATH . '/models/']
);
$config->setMetadataDriverImpl($driver);
?>

3. 对照YAML配置给实体类添加文档块注解，示例：

<?php
namespace MyProject\Model;

/**
 * @ODM\Document(db="mydb", collection="users")
 */
class User
{
    /** @ODM\Id */
    public string $id;

    /** @ODM\Field(type="string", nullable=false) */
    public string $username;

    /** @ODM\Field(type="string") */
    public string $email;

    /** @ODM\Field(type="date") */
    public \DateTimeInterface $createdAt;
}
?>

• 迁移完成后先在测试环境验证映射正确性，可以执行vendor/bin/doctrine odm:mapping:info检查所有实体映射是否正常加载
• 原有YAML中配置的索引、关联关系、生命周期回调等特殊规则，在新驱动中都有对应配置项，逐份核对避免遗漏
• PHP8.1环境下优先选择AttributeDriver，相比注解驱动没有额外的注释解析开销，也不会出现注释被opcache丢弃的兼容问题，长期稳定性更好

内容的提问来源于stack exchange，提问作者cookie