Getting ready for Doctrine MongoDB ODM 2.0

3 min readJun 6, 2019


With the release of Doctrine MongoDB ODM 2.0-RC1, it is time to start thinking about migrating to this new version. 2.0 brings a load of changes and most importantly a switch away from the legacy MongoDB driver, which did not support PHP 7 natively. MongoDB ODM now utilises the new MongoDB driver and will be available only for PHP 7.2 and newer. Unfortunately, this change requires work on your part. Depending on the features you use, the work to update to the new version may be significant, especially if you work with GridFS a lot.

Migrating to 2.0

To help people migrate to 2.0, we are releasing MongoDB ODM 1.3, which deprecates all behaviour that will be dropped or changed in 2.0. Where possible, new functionality is also included so you can fix these deprecations to be compatible with 2.0. However, due to the driver change underneath, this is not always possible. Some deprecations in 1.3 can only be fixed by upgrading to 2.0.

All deprecations coming in 1.3 have been documented in the UPGRADE-1.3 document. The UPGRADE-2.0 document notes all removals from 1.3 to 2.0. This document also contains information about BC breaks due to signature changes in methods or classes, excluding cases where type hints were introduced. We recommend the usage of a static analyser like PHPStan or Psalm to find those BC breaks. Alternatively, the raw report from roave/backwards-compatibility-check is available as a gist for your viewing pleasure.

What’s new in 1.3?

The ResolveTargetDocumentListener event listener now not only resolves class names when looking for a targetDocument in the mapping, but also when loading ClassMetadata objects. This is a feature that has been around in ORM for a while but was never ported over to MongoDB ODM.

The corresponding release of the Symfony Bundle (version 3.6) brings fixture services, which have been in DoctrineFixturesBundle for quite some time now. Loading fixtures from files or folders is now deprecated and will be dropped in 4.0.

What’s new in 2.0?

For MongoDB ODM 2.0, the biggest feature is using the new driver. This makes it considerably easier to run MongoDB ODM on PHP 7, as you no longer need an adapter library to provide the legacy driver API. This also brings a small performance boost since we no longer need time-consuming type conversion from and to legacy types. The new features added to MongoDB ODM 1.3 are part of this release as well.

The corresponding release of the Symfony Bundle (version 4.0) contains no new features over the previous bundle version. It was updated to support MongoDB ODM 2.0 and the new configuration options required for it.

Further support for 1.x

Due to the large number of BC breaks in 2.0, we are committed to provide bug fixes and support for MongoDB ODM 1.3 for at least 6 months after the release of 2.0. After this time has passed, we will evaluate the usage of 1.3 and 2.0 and decide whether to extend the support lifetime for 1.x. MongoDB ODM 1.2 will not receive bug fixes after the release of 1.3, since all users will be able to update to 1.3 without issues.

MongoDB Bundle for Symfony

The MongoDB bundle for Symfony follows the same deprecation principle: version 3.6 will deprecate all behaviour that is dropped or changed in 4.0. 3.6 works with MongoDB ODM 1.x, while 4.0 will require MongoDB ODM 2.0. We recommend updating to the latest minor version before attempting an update to the new major release.

Future releases

Now that the 2.0 release cycle has commenced, the pace of new releases will hopefully increase. For 2.1 we are planning to catch up on new features of MongoDB, such as aggregation pipelines. Support for sessions and transactions is also planned, but not yet scheduled for a specific release. You can follow the development plan by checking out the Roadmap Project Board on GitHub. We will use this board to keep track of features for upcoming releases and make the roadmap more transparent.




Doctrine coordinator and MongoDB ODM maintainer. I break stuff so you don’t have to. Lead Engineer @mongodb — join me in making databases more fun to use.

Recommended from Medium


See more recommendations