Released doctrine/migrations 3.0-alpha

Posted on April 10, 2020 by Asmir Mustafic

doctrine/migrations 3.0-alpha has been published on the 29th March 2020.

The upcoming 3.0 new major release is the result of almost 6 months of work and brings a completely refactored/rewritten internal structure and some interesting new features.

Why a new major release?

The doctrine/migrations v1.x codebase is 10 years old, and in the past years a lot of features have been added on top of its initial architecture.
doctrine/migrations 2.0 was released a bit more than a year ago. This major release did a bit of cleanup, but the general structure remained the same. In this schema you can see the dependencies between classes in the latest 2.3.x branch:

The red lines are circular dependencies (and we already know that in software development circular dependencies are not a good thing).

In doctrine/migrations 3.x, most of the internal classes have been re-written and dependency injection has been widely adopted.
In this schema you can see the dependencies between classes in the latest master branch (release v3.0):

As you can see the circular dependencies are gone. This has been possible thanks to extensive use of dependency injection and applying SOLID principles. To reduce future backward incompatibilities, many classes have been marked as final or as @internal while keeping the functionalities intact. Extensibility is still possible by using dependency injection and providing classes implementing dedicated interfaces.

These schemas have been generated using PhpDependencyAnalysis with this configuration.

New features and improvements

Beside the code quality improvements, there is a a long list of improvements (see below), but the main user-facing feature is the ability to collect migrations from multiple folders/namespaces and to specify dependencies between migrations.

Here a (probably not complete) list of improvements implemented in the upcoming 3.0 release:

  • ability to collect migrations from multiple folders/namespaces and to specify dependencies between migrations
  • doctrine/migrations will write to your database only when running migrations (previously the metadata table was created on the very first command run even if it was a read-only command)
  • Output verbosity can be controlled using the -v, -vv or -vvv command parameters
  • Use of dependency injection allows you to decorate/replace most services
  • Removed usage of console helpers to provide the connection or entity manager in favor of dependency injection
  • Introduced migrations:list command to list the available/executed migrations
  • Introduced migrations:sync-metadata-storage command to explicitly update the metadata schema in case a newer version introduces changes to the metadata table
  • Multiple migrations can be passed to the migrations:execute command
  • More organized output of the migrations:status command
  • Configurations and Dependency Factory are read-only during the migration process
  • The down() migration is optional now
  • Multi-namespace migrations
  • Custom migrations metadata storage
  • Added warning when using the migrations:diff if there are not executed migrations

Backward compatibility

In doctrine/migrations 3.0 a lot of things changed, but for end-users most of the things will look the same. Your migration files do not need any update.

You will have to change your configuration files, as the configuration format has changed. The official documentation contains more information about these changes. This documentation should be particularly helpful if you did also some custom integration with third party frameworks or libraries.

If you wrote custom event listeners, please take a look at them as the method signatures for event listeners have been updated.

Symfony Integration

If you are using DoctrineMigrationsBundle then things are even easier: the 2.3.0 release introduced some deprecation notices and if you have already solved them your configuration is already compatible. If you want you can have a look to the latest configuration format available on the official documentation. You can look more in detail to which changes are needed in the upgrading document.

What is next

In the upcoming weeks, we will be preparing the first beta release and starting the process to reach a stable release. To be able to deliver a good stable release it is important that you test the pre-release and share your feedback!

To try the alpha version, you can run:

composer require 'doctrine/migrations:^[email protected]'

If you are using Symfony:

composer require 'doctrine/doctrine-migrations-bundle:^[email protected]' 'doctrine/migrations:^[email protected]'

You can be also more brave trying the development versions by specifying @dev instead of @alpha when requiring the composer dependencies above.

You can also have a look at the release notes and the upgrading document.

Similarly you can also have a look at the release notes and the upgrading document for the Symfony bundle.

In the alpha release, breaking changes are still possible. In the beta, release breaking changes are possible but will happen only if we will find very unexpected behaviors. When the alpha and beta phase will be completed, a stable version will be made available.


This post was initially published on

Doctrine MongoDB ODM 1.3.0 and 2.0.0-RC2 released

Posted on September 30, 2019 by Andreas Braun

The Doctrine team is proud to announce that MongoDB ODM 1.3.0 and 2.0.0-RC2 have been released. These releases are the culmination of a long effort to migrate the ODM away from the legacy mongo extension to the new MongoDB driver (mongodb extension and PHP library). This results in a number of BC breaks for users, but will enable us to add many new features in future releases, among them support for multi-document transactions.

MongoDB ODM 1.3.0 is a compatibility release targeted for users of the legacy extension that want to migrate to MongoDB ODM 2.0. It helps identify BC breaks by throwing deprecation notices and offering a forward compatibility layer where possible. To efficiently find usages of deprecated code, you can use the PHPUnit bridge developed by Symfony (symfony/phpunit-bridge) which logs all deprecation notices encountered during a run of PHPUnit. You can read more about this component in the Symfony documentation.

MongoDB ODM 2.0.0RC-2 is the recommended package to use for those starting new projects with MongoDB ODM. It ensures that you use the modern API for ODM without having to worry about deprecations. While this is still a release candidate, it is planned to make this version the next stable MongoDB ODM release.

What’s new in MongoDB ODM 2.0?

Most importantly, this version no longer uses the legacy mongo extension. That extension is no longer maintained and does not support server versions beyond MongoDB 3.0. The new MongoDB driver ensures that MongoDB ODM can leverage features and improvements contained in newer MongoDB versions, such as support for multi-document transactions, retryable reads, retryable writes, change streams, and much more.

Changing the driver also means significant changes to some APIs. Most importantly, the GridFS API has been rewritten from scratch to conform with MongoDB’s GridFS spec for drivers. If you’ve used GridFS before, this will be a big change for you, but the new API is much simpler and cleaner to use. Check out the GridFS documentation to find out how to use the new API. Unfortunately, we cannot provide a forward compatibility layer for this, as re-implementing this API atop the legacy driver is not feasible.

Lazy reference support has been changed completely and no longer uses proxy objects from the deprecated doctrine/common library. Instead, it builds on ocramius/proxy-manager, which gives us access to more advanced features like partial proxy loading, which we will start leveraging in future releases.

In 2.0 we dropped support for the YAML mapping of documents. This step was necessary to both reduce the complexity of the code base and lower the burden of maintaining multiple mapping drivers. If you are currently using YAML mappings, we provide a console command to migrate YAML mappings to the XML format. We are currently working on an alternative that allows for a more flexible mapping configuration system, but this is not ready yet and will only be provided in a future 2.x release.

Migrating to MongoDB ODM 2.0

If you are using MongoDB ODM 1.x, the upgrade consists of multiple steps. First, ensure that you are fulfilling the necessary requisites for MongoDB ODM 2.0:

  • PHP version 7.2 or newer
  • ext-mongodb 1.5.0 or newer
  • mongodb/mongodb library 1.4.0 or newer
  • MongoDB 3.0 or newer

If you are already running PHP 7, you will most likely already be running ext-mongodb as the legacy extension is not available for PHP 7. If you are still running PHP 5.x, it is recommended that you migrate to PHP 7 before attempting to use a newer ODM version. You can do so by following the instructions on running ODM 1.x on PHP 7.

Once you fulfill all dependencies, the first step is updating to the latest 1.3 release of MongoDB ODM. If you are using Symfony, you also need to upgrade the ODM bundle to its latest 3.6 version. Once this is done, you can start fixing any deprecation notices that you find. This should be a familiar process for any existing Symfony users. We tried to provide compatibility layers where possible; unfortunately, we could not do so in all cases.

The next step is upgrading to ODM 2.0 directly. For many users, this step shouldn’t be a problem thanks to the compatibility layer in 1.x. There may be some necessary changes depending on the features you use (e.g. GridFS).

What’s next for MongoDB ODM

During the past few years, we focussed our limited development time almost exclusively on the driver migration, which came at the expense of supporting new features in MongoDB. We plan to add support for many of those features in future releases. You can get an overview of what’s planned by checking the roadmap. If you are looking for a specific feature, please let us know in the issue tracker.

While not exhaustive or guaranteed, these are some of the features we plan to implement in future releases:

  • Support for multi-document transactions (on-demand and implicit while flushing the Document Manager)
  • Support for new aggregation pipeline stages and operators
  • Support for the $expr query operator
  • Support for aggregation pipelines in update operations
  • Support for reading documents from views instead of collections
  • Atomic updates for collections using new array update operators

Support timeline

With these releases, we’re also introducing our new support timeline. Along with the two releases announced above, we are also releasing the end-of-life release for MongoDB ODM 1.2. We will not support MongoDB ODM 1.2 any more and encourage users to upgrade to 1.3. Since 1.3 has no additional requirements over 1.2, upgrading should be possible for all users of ODM 1.2.

MongoDB ODM 1.3 will be supported for at least 6 months after the first stable release of ODM 2.0. We will communicate this date when releasing ODM 2.0. After those 6 months, we will either drop support for ODM 1.3 or extend it for another 3 months, depending on the adoption rate of ODM 2.0. We are aware that the number and kind of BC breaks for 2.0 pose a significant challenge for many users, which is why we don’t want to force people to rush into this update.

During the support phase for MongoDB ODM 1.3, we will also continue to provide bug fixes to the MongoDB Abstraction Layer that is used by MongoDB ODM 1.x. This project will reach end-of-life at the same time as MongoDB ODM 1.3, and will no longer be supported beyond that. We encourage users that depend on this library to switch to using the MongoDB PHP Library, which is part of the official MongoDB driver for PHP.

Contributing to MongoDB ODM

We are currently looking for contributors. This doesn’t necessarily mean implementing new features or merging pull requests. Reporting or triaging issues, requesting features, and reporting bugs are all extremely important and helps us deliver better software!

Getting help

The documentation can be found on the website: To get support, contact us via the #mongodb-odm channel within the Doctrine Slack. If you believe you have found a bug, please file a bug report on GitHub.

Doctrine Webinars

Posted on May 30, 2019 by Jonathan H. Wage

As mentioned in the Monetizing Open Source blog post, Doctrine will be regularly organizing online webinars hosted with Zoom. You can join from anywhere in the world with a laptop and an internet connection. We will have topics presented by Doctrine core team members and members of the community.

To get things started we have a few webinars scheduled for the next few months:

Don't see something that you are interested in? Suggest an event topic you would like to see and we will see what we can do. We will be publishing new events in the coming weeks so check back soon!

Monetizing Open Source

Posted on May 21, 2019 by Jonathan H. Wage

In our quest to make Doctrine financially sustainable, we have created Doctrine Company, LLC under which the team can conduct business. We've had a strong 10 years of open source success but we believe that in order for Doctrine to be truly sustainable and to last another decade, we need to diversify and monetize the project. It is our goal to be able to generate enough money through the project to fund full or part time work on the project. Below you will find details of some of our monetization efforts.


Patreon is a platform that allows open source maintainers, artists, creators, etc. to create relationships with their users and offer them benefits for becoming a patron.

If you would like to make a donation to the project, Patreon is the place to do it. Depending on the tier, we offer a few different benefits:

  • A mention on Twitter.
  • Your name and website link on the Doctrine website.
  • Priority responses to Stack Overflow or GitHub issues/PRs.
  • Placement on a Partners page on the Doctrine website, with your logo, link, and a paragraph advertising your company's services.

Become a Patreon of Doctrine today!


Under the Doctrine Company, we are providing consulting and training services to companies that use PHP. The services we offer are not limited to Doctrine itself. Our team specializes in producing high quality PHP. Whether you are starting a new project or modernizing a legacy application, we can help your team level up their skills with tools like the following:

  • Doctrine DBAL - Connect to your favorite RDBMS using Doctrine's database abstraction library.
  • Doctrine Database Migrations - Safely manage your database schema and keep it up to date.
  • Doctrine ORM - Represent your domain model cleanly with plain old PHP objects and ensure the integrity of your data.
  • PHP_CodeSniffer - Keep aesthetic debates out of your code reviews by adopting a coding standard and enforcing it in your build process. We can help integrate Doctrine's own coding standard into your project or help codify your own.
  • Psalm / PHPStan - Statically analyze your codebase and find bugs that would otherwise only be found at runtime in production.

If you are interested, take a look at our Consulting page or contact us at [email protected] for more information.


We will host regular monthly webinars using Zoom. Each month we will have different topics presented to you by members of the Doctrine Core team or greater PHP community. We already have some great topics lined up for the next few months:


Tidelift is a managed open source subscription service backed by creators and maintainers. Development teams get better maintained open source. Maintainers get paid.

We have partnered with Tidelift as a maintainer to guarantee a high level of maintenance for their customers. In return, Tidelift pays Doctrine maintainers a percentage of what the customer pays. Tidelift is attempting to create a marketplace of open source maintainers and customers with the goal of providing higher levels of confidence for commercial entities when using open source. This can sometimes be one of the biggest challenges for using open source in the corporate world. Tidelift is taking a unique approach to solving this problem and we are excited to be a part of it!

Carbon Ads

One of the most valuable assets we have besides software is our website and the traffic we receive every month. You may have noticed some subtle ad placements on our website. These text-based ads are provided by Carbon Ads which is an ad network optimized for reaching designers and developers. We understand ads can be annoying and we hope that our users understand the trade-off we've made by choosing to place ads on our website.


Finally, we are partnering with commercial entities and other projects that use Doctrine to cross promote each other. Through our partner network we hope to introduce our users to vetted services and offerings from which they can benefit. Thanks to our Partners for supporting Doctrine.

Migrations 2.0 Stable Released

Posted on January 9, 2019 by Jonathan H. Wage

Today we are very excited to announce the stable release of Doctrine Migrations 2.0. Almost 10 years ago on Mar 23, 2010, the first commit of the 1.0 codebase was created. The history of the Doctrine Migrations project actually even goes back further to the days of Doctrine1 ORM but this was before the days of GitHub, Composer, etc and I think some of that history has been lost. It is amazing to look back over the last decade at how much the PHP eco-system has changed. It makes us appreciate all the great tools we have, even with all their flaws.

What is in 2.0?

The 2.0 release should be a relatively easy upgrade for most people. The primary goal of the 2.0 release was to modernize the codebase according to Doctrine Coding Standards, PHPStan and all of the other standardized Doctrine project infrastructure that has evolved over the last few years. This will ensure the project is alive and relevant for another decade.

In addition to upgrading the infrastructure of the project, it came with a few new nice features:

You can view the full changelog in the release on GitHub.

This release contains 36 resolved issues with 71 pull requests coming from 18 different contributors. Thanks to the following people for their help with this release:

Phasing out Doctrine Common & release of DBAL 2.8 and ORM 2.6.2

Posted on July 12, 2018 by Michael Moravec

Common 2.9 and phasing out the package

As another step in the ongoing effort to eliminate doctrine/common, there are now three new separate Doctrine packages:

This release introduces the following deprecations:

  • Doctrine\Common\Proxy component is deprecated, use ocramius/proxy-manager instead;
  • Doctrine\Common\Util\Debug is deprecated, use symfony/var-dumper instead;
  • Doctrine\Common\Lexer is deprecated, use Doctrine\Common\Lexer\AbstractLexer from doctrine/lexer or migrate to hoa/compiler instead;
  • Doctrine\Common\Util\Inflector is deprecated, use Doctrine\Common\Inflector\Inflector from doctrine/inflector instead;
  • Doctrine\Common\Util\ClassUtils is deprecated without replacement;
  • Doctrine\Common\Version is deprecated, refrain from checking Common version at runtime;
  • Doctrine\Common\CommonException is deprecated without replacement.

In addition to that, there will be no doctrine/common 3.0 and the package will be gradually phased out.

Version 2.x will be maintained at least until ORM 3.0 is released, ensuring compatibility with the latest PHP and providing bugfixes, but it will no longer ship any new features.

For complete release notes, visit GitHub.

DBAL 2.8.0

DBAL 2.8.0 is a minor release of Doctrine DBAL that aggregates over 30 fixes and improvements developed over the last 3 months.

The dependency on doctrine/common is removed. DBAL now depends on doctrine/cache and doctrine/event-manager instead.

For complete release notes, visit GitHub.

ORM 2.6.2

ORM 2.6.2 comes as a regular bugfix release.

It no longer uses the long ago deprecated Lexer and Inflector from doctrine/common.

For complete release notes, visit GitHub.

New Website

Posted on April 6, 2018 by Jonathan H. Wage

In 2007 Doctrine got its first official website at Before that, the website was an instance of Trac which also served as our documentation, issue tracker and project management tool.

The new website design was created by Phu Son Nguyen who worked at Yahoo! at the time. It was a huge step forward for the Doctrine Project and it gave us 10 solid years!

Fast-forward and today we are happy to be launching a new foundation for our website and documentation. In addition to the new look, here are some new features:

  • GitHub Edit links on all documentation pages to make it easy to contribute fixes when you come across something that could be improved.
  • Automated deploys with GitHub Pages. Simply create a pull request and it will be deployed to Merges to master automatically deploy to
  • Search powered by Algolia.
  • Mobile friendly.
  • Documentation supports multiple versions.
  • Documentation user experience improvements.

We hope that this helps improve the experience and make it easier to contribute. The code for the site is open source and can be found here. If you want to contribute to the documentation for a project, you can find the docs in a folder named /docs in the root of the project repository. Here is the ORM for example.

If you discover any issues, please report them on the GitHub Issue tracker for the project.

Doctrine ORM 2.6 and Next (3.0)

Posted on December 21, 2017 by Mike Simonson

We are happy to announce the immediate availability of Doctrine ORM 2.6.0.

ORM 2.6.0

This release contains almost 3 years of active development and it provides several improvements and fixes, including:

  • Better commit order calculation
  • More stable second level cache
  • Strict testing and quality control
  • PHP 7.1+ requirement



This release marks the feature freeze of the 2.x version.

If you need to improve please work on the develop branch that will become the 3.0 branch in the coming days. The changes are already too numerous to easily rebase a feature from the 2.x branch to the develop one.

Doctrine MongoDB ODM 1.2.0 and 1.1.7 Released

Posted on October 24, 2017 by Andreas Braun

We are happy to announce the immediate availability of Doctrine MongoDB ODM 1.2.0 and 1.1.7.

MongoDB ODM 1.1.7

Notable fixes may be found in the changelog. A full list of issues and pull requests included in this release may be found in the 1.1.7 milestone.

What is new in 1.2.0?

Doctrine MongoDB ODM 1.2.0 introduces the following new features:

  • The readOnly mapping option allows you to map immutable documents.
  • With slaveOkay being deprecated, you can now specify a readPreference for your documents. This readPreference will automatically be applied to all queries for those mapped documents.
  • With dbRef only offering limited support in aggregation pipeline queries, there's a new reference storage strategy called ref that stores references as objects (without "\$"-prefixed field names), allowing you to use it with discriminators and aggregation pipeline queries.
  • When mapping inverse references, you may now specify fields that will be primed when the reference is resolved. This saves you from writing a dedicated repository method for the sole purpose of priming references.
  • The odm:schema:validate command validates the document mapping to help you spot mistakes.
  • A new builder for aggregation pipeline queries, including support for marshalling results into read-only documents.
  • Query result documents that can be used to hydrate results from an aggregation pipeline query. These documents cannot be written back to the database.

Upgrading to 1.2.0

The new version requires PHP 5.6. Running on PHP 7+ requires the use of a polyfill for the legacy driver, e.g. mongo-php-adapter. When running on PHP 5.6, MongoDB ODM requires version 1.6.7 or newer of the legacy MongoDB driver.

Several features have been deprecated in this release and will be dropped in the 2.0 release. To see this, please view the UPGRADE document.


You can install the new version of MongoDB ODM by using Composer and the following composer.json contents:

    "require": {
        "doctrine/mongodb-odm": "^1.2.0"

Stability and upcoming releases

As of today, Doctrine MongoDB ODM 1.2.0 is the stable distribution. There is no release schedule for an upcoming version yet.

1.1.7 is the last release of the 1.1.x development line and will no longer receive bug fixes. Instead, we will focus on developing MongoDB ODM 2.0 with native support for the new MongoDB driver. This release will require at least PHP 7.1 and contain several BC breaking changes. To ease the migration process, we will release a 1.3.0 which will be backwards compatible to the 1.2.x line and only deprecate features to be removed in 2.0. The 1.x line of MongoDB ODM will not receive any new features.

PHP 7.1 requirement for Doctrine packages

Posted on July 25, 2017 by Andreas Braun

A few days ago, the Doctrine team released new versions of many packages, dropping support for PHP 5.6 and 7.0, as well as HHVM. The affected packages are:

  • doctrine/common 2.8.0
  • doctrine/dbal 2.6.0
  • doctrine/collections 1.5.0
  • doctrine/inflector 1.2.0
  • doctrine/cache 1.7.0
  • doctrine/instantiator 1.1.0
  • doctrine/annotations 1.5.0

Since many people are encountering issues with these updates, here are a few suggestions to ensure your code continues working as usual.

Composer version constraints

Chances are your version constraints in composer.json look something like this:

    "require": {
        "doctrine/orm": "^2.5"

The ^2.5 constraint resolves to: >= 2.5.0 && <= 2.999999.999999. This is intended: our projects all follow Semantic Versioning, so you can safely install a new minor version without having to fear BC breaks.

When determining what version to install, composer employs a SAT solver to make sure all dependencies are fulfilled. In our example above, the SAT solver finds a version newer than 2.5 that satisfies all requirements.

Making sure you get a compatible version

When you run composer update the next time, you'll automatically receive updates for the packages mentioned above, provided that you are running on PHP 7.1. If you are running an older PHP version, composer will not install a version that requires PHP 7.1, since its requirements are not fulfilled.

A common problem is people running a newer PHP version on their developer machines than on their production servers. In this case, running composer update on a developer machine (with PHP 7.1) might happily pull in an update that simply won't work when deployed on a production machine running PHP 5.6.

To make sure this doesn't happen to you, there are two choices:

  • run composer update on a machine with the same PHP version that you use in production
  • use the platform.config config setting in composer.json to override your local PHP version.

Why dropping PHP support in a minor version is not a BC break

One question we frequently hear is, "isn't dropping support for a PHP version a BC break"? In a nutshell, no. A BC break happens when there is an incompatible change that your package manager can't handle. For example, changing a method signature in a minor version is a no-go, since the composer version constraints mentioned above assume any minor upgrade can safely be used.

However, when we drop support for an older version of PHP, composer will not consider the new version if the PHP version requirement is no longer fulfilled. Thus, you won't end up with a fatal error due to a wrong method signature, you just won't get the new version.

View Blog Archive