What is blocking you from upgrading from ORM 2 to ORM 3?

[beberlei]

Hi!

we plan to phase out most maintenance of ORM 2 over the next year.

To help users we are trying to find out what is blocking everyone to upgrade to ORM 3 for now?
And if you have upgrade to ORM 3 already, what did you struggle with the most?

A few high level points that we changed since we first released and announced ORM 3.0:

• Partial objects are going to stay in ORM for good and are even going to get better. Related [GH-8471] undeprecate partials completly #11647 Deprecate Partial Objects #8471
• We think we fixed AbstractQuery::toIterable and scalar results [GH-9219] Add support for toIterable over mixed or scalar results. #12187 - so that AbstractQuery::toIterable is now a full replacement for AbstractQuery::iterate.
• You can run ORM 3 with DBAL 3, you are not required to upgrade to DBAL 4 to make the change, this is a future topic.

Let us know in the comments and we will occasionally distill all the comments and information here on top and linking to potential issues, and changes.

You can also write me to [email protected] with the subject "Doctrine ORM 3.0 Upgrade" if you want to remain anonymous or add more details that you don't want to post here.

Thank you for helping us help you make the migration to ORM 3 easier for everyone!

[GromNaN]

Migration from Yaml to Attributes

Shared on X.

Project with 200 entities still using legacy yaml notation. Tried custom Rector rules for conversion to attributes but that did not go to well. I have hope though that the codex model will be capable of the conversion in the coming weeks.

[greg0ire]

There seems to be a command for this using case on 2.x: https://www.doctrine-project.org/projects/doctrine-orm/en/2.20/reference/tools.html#convert-mapping-information

So to migrate from YAML to XML:

php bin/doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xml

[beberlei]

This command might not be 100% for all YAML out there, but we are willing to make changes to the code to make more stuff work.

[MantraMedia]

I do remember that I tried it a few years back and it would run into problems with some relations. I will see if I can recreate the issues with the latest version.

[gnutix]

Is that the Rector you used ? https://getrector.com/rule-detail/yaml-to-attribute-doctrine-mapping-rector

As with any automated refactoring tool, it will probably get 90% of the job done, and you can report issues to Rector to improve the missing 10%.

[Pierstoval]

On a personal level, the main issues I had to fix when migrating to ORM 3 were the following:

• Single-entity flush was removed (which is good)
• The merge() method too (good point too)
• The mix between Annotation and Attributes was kind of a problem: in certain systems (like external libraries), I entirely switched to XML mapping to make it cross-compatible
• As usual: external libs not compatible with ORM 3, or using deprecated/removed code

Overall, it wasn't "that hard", but it highly depends on the project.

Friendly pinging @webmozart, @theofidry , I recall you had some difficulties on certain internal libs that you use, especially regarding the persistence of ID-objects?

[CMH-Benny]

@beberlei I saw that and tried it once, we have a multi em setup and when I tried it, I only saw an error message:
Message: "Warning: Attempt to read property "name" on null"

I tried: bin/console doctrine:mapping:convert --em=foobar xml src/SomeBundlePath/Resources/config/doctrine
I set output path to the same location of the yaml files. As I didn't have much time to dig into it I can't really tell what the problem is.
Not even really sure if it correctly detects the yaml files, as I only give output format and output folder, but no input. and --from-database isn't an option, as it can't cover all cases.

Can't even tell if the symfony wrapper works as expected, but direct doctrine cli also doesn't work without some cli-config.php it complains:

[Warning] The use of this script is discouraged. See https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#doctrine-console for instructions on bootstrapping the console runner.

You are missing a "cli-config.php" or "config/cli-config.php" file in your
project, which is required to get the Doctrine Console working. You can use the
following sample as a template:

<?php
use Doctrine\ORM\Tools\Console\ConsoleRunner;

// replace with file to your own project bootstrap
require_once 'bootstrap.php';

// replace with mechanism to retrieve EntityManager in your app
$entityManager = GetEntityManager();

return ConsoleRunner::createHelperSet($entityManager);

and as we don't have a boostrap.php (only for tests) in our project, I was kinda lost when I quickly looked into it.

[greg0ire]

Do you get more details when you try the -vvv flag of bin/console?

[CMH-Benny]

I do:

 Warning: Attempt to read property "name" on null

Exception trace:
  at /var/www/html/vendor/doctrine/orm/src/Mapping/ClassMetadataInfo.php:3807
 Doctrine\ORM\Mapping\ClassMetadataInfo->inlineEmbeddable() at /var/www/html/vendor/doctrine/orm/src/Mapping/ClassMetadataFactory.php:197
 Doctrine\ORM\Mapping\ClassMetadataFactory->doLoadMetadata() at /var/www/html/vendor/doctrine/persistence/src/Persistence/Mapping/AbstractClassMetadataFactory.php:343
 Doctrine\Persistence\Mapping\AbstractClassMetadataFactory->loadMetadata() at /var/www/html/vendor/doctrine/persistence/src/Persistence/Mapping/AbstractClassMetadataFactory.php:225
 Doctrine\Persistence\Mapping\AbstractClassMetadataFactory->getMetadataFor() at /var/www/html/vendor/doctrine/persistence/src/Persistence/Mapping/AbstractClassMetadataFactory.php:96
 Doctrine\Persistence\Mapping\AbstractClassMetadataFactory->getAllMetadata() at /var/www/html/vendor/doctrine/orm/src/Tools/Console/Command/ConvertMappingCommand.php:116
 Doctrine\ORM\Tools\Console\Command\ConvertMappingCommand->doExecute() at /var/www/html/vendor/doctrine/orm/src/Tools/Console/CommandCompatibility.php:32
 Doctrine\ORM\Tools\Console\Command\ConvertMappingCommand->execute() at /var/www/html/vendor/symfony/console/Command/Command.php:326
 Symfony\Component\Console\Command\Command->run() at /var/www/html/vendor/symfony/console/Application.php:1096
 Symfony\Component\Console\Application->doRunCommand() at /var/www/html/vendor/symfony/framework-bundle/Console/Application.php:126
 Symfony\Bundle\FrameworkBundle\Console\Application->doRunCommand() at /var/www/html/vendor/symfony/console/Application.php:324
 Symfony\Component\Console\Application->doRun() at /var/www/html/vendor/symfony/framework-bundle/Console/Application.php:80
 Symfony\Bundle\FrameworkBundle\Console\Application->doRun() at /var/www/html/vendor/symfony/console/Application.php:175
 Symfony\Component\Console\Application->run() at /var/www/html/vendor/symfony/runtime/Runner/Symfony/ConsoleApplicationRunner.php:49
 Symfony\Component\Runtime\Runner\Symfony\ConsoleApplicationRunner->run() at /var/www/html/vendor/autoload_runtime.php:29
 require_once() at /var/www/html/bin/console:11

Seems to fail because of an embeddable. 6/8 contains embeddables in the yaml mapping files in this folder for this entity manager

[mpdude]

Can’t you migrate from annotations to attributes as a preparatory step?

[greg0ire]

@mpdude I think they're exclusively using YML files

[beberlei]

Private mention of PostgreSQL Identifier Migration from SERIAL to autoincrement being complicated: https://www.doctrine-project.org/projects/doctrine-dbal/en/4.0/how-to/postgresql-identity-migration.html

Others mention that they fixed this by moving to SEQUENCE strategy, which only requires:

1. a small database migration of the kind ALTER TABLE table_name ALTER id DROP DEFAULT to get rid of the default NEXTVAL(sequence_name)
2. Checking that you don't test for the id field as a means of entity being persistet already, as EntityManager::persist now immediately sets the id.

Diff for changing to SEQUENCE, that produces a migration to remove the default. Benefit of this migration strategy: it allows rolling out the code without the migration and will work, and then you can do the migration in a second deployment:

diff --git a/src/Entity/Example.php b/src/Entity/Example.php
index 28be8df378..3b7d61bda6 100644
--- a/src/Entity/Example.php
+++ b/src/Entity/Example.php
@@ -38,7 +38,7 @@ class Example
 
     #[ORM\Id]
     #[ORM\Column(type: 'integer')]
-    #[ORM\GeneratedValue(strategy: 'AUTO')]
+    #[ORM\GeneratedValue(strategy: 'SEQUENCE')]
     private int $id;

[tjveldhuizen]

Currently, our main issue is the fact that this column type does not seem to work anymore. However, I haven't had the opportunity to dig into the issue, to find out which component is the exact source. So it might be possible to update the ORM package, since the error seems to be due to the version of the DBAL package (but I didn't check compatibility).

    #[ORM\Column(
        name: 'tbk_source',
        type: 'string',
        enumType: SourceEnum::class,
        columnDefinition: "ENUM('source_a', 'source_b', 'source_c', 'source_d') NOT NULL"
    )]
    protected SourceEnum $source= SourceEnum::SOURCE_A;

In InvalidColumnDeclaration.php line 16:
  Column "tbk_source" has invalid type

In ColumnLengthRequired.php line 22:
  Doctrine\DBAL\Platforms\MySQLPlatform requires the length of a VARCHAR column to be specified

[derrabus]

It should still work if you upgrade only the ORM and keep the DBAL at 3 though.

[beberlei]

@tjveldhuizen I looked into that and DBAL 4 changed this to throw this exception, you should upgarde ORM 3 with DBAL 3 for now, that is already a big step forward.

However even then, what confuses me is that string types automatically get length=255 for VARCHAR types in the SchemaTool:

orm/src/Tools/SchemaTool.php

Line 467 in 85c13ed

if (strtolower($columnType) === 'string' && $options['length'] === null) {

- i am a bit confused if that is not happening in your case. Can you xdebug or var_dump the $options in that file on your code to see how an enum declaration there works?

Additionally, DBAL 4.2 has an enum type as well that you could migrate to: https://www.doctrine-project.org/2024/10/14/doctrine-core-team-meetup-2024.html#support-for-enum-database-types

[greg0ire]

@Nek- is blocked of upgrading because of this return type:

orm/src/EntityRepository.php

Line 200 in 4f3a5c5

public function matching(Criteria $criteria): AbstractLazyCollection&Selectable

It causes an issue with prophecy: phpspec/prophecy#535

[stof]

Good news for you. I just released version 1.23.0 of phpspec/prophecy which fixes this issue: https://github.com/phpspec/prophecy/releases/tag/v1.23.0

[derrabus]

Thanks a lot @stof!

@torchello I've flagged your workaround as resolved in order to discourage people from copying it. Now that Prophecy has fixed the issue, the way forward should be to upgrade Prophecy.

[torchello]

Great news! Thanks all!

[theofidry]

For Doctrine ORM 3 only, the biggest single issue was the change of the flush behaviour (that it is no longer possible to flush single entities). To migrate with more confidence, that required us to implement a "guarded flush", which registers a listener just before the flush call to check that nothing unexpected (within reason – checking the exact expectation can be tricky for relationships) is flushed. The source code changes themselves were fine, getting the infra necessary to introduce those changes with confidence a lot less so. Maybe some of this infra could be ported to Doctrine ORM, not sure. The final result is pretty neat, but that required quite a few hacks to work around some of Doctrine internal caches.

Doing so also highlighted an issue which is that value objects cannot be compared by equality. We had to introduce a listener to replace the references compared to not trigger unnecessary computation changes. I think you captured this in #5542.

[umulmrum]

For us it's also the change to flush and clear. We also hesitate to work on this consistently because an alternative was announced (#8459) that never came (no blame intended, just stating the fact). So either the alternative or a statement that there won't be one would be great, and would speed up our migration.

[kimhemsoe]

We solved the removal of the array type by adding our own type. Afterwards migrated to json field and duplicated the data in both until we were ready to remove the old array field.

…

On Wed, 8 Oct 2025 at 00:37, Théo FIDRY ***@***.***> wrote: For Doctrine ORM 3 only, the biggest single issue was the change of the flush behaviour (that it is no longer possible to flush single entities). To migrate with more confidence, that required us to implement a "guarded flush", which registers a listener just before the flush call to check that nothing unexpected (within reason – checking the exact expectation can be tricky for relationships) is flushed. The source code changes themselves were fine, getting the infra necessary to introduce those changes with confidence *a lot* less so. Maybe some of this infra could be ported to Doctrine ORM, not sure. The final result is pretty neat, but that required quite a few hacks to work around some of Doctrine internal caches. Doing so also highlighted an issue which is that value objects cannot be compared by equality. We had to introduce a listener to replace the references compared to not trigger unnecessary computation changes. I think you captured this in #5542 <#5542>. — Reply to this email directly, view it on GitHub <#12193 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAEK3U2NA6AK4ILTMQGIO333WQ6B5AVCNFSM6AAAAACIQQENFKVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTINRSGAYTKNI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[Fedik]

I use XML mapping from beginning and the migration to v3 (with dbal 3 and then to dbal 4) was relatively easy.
Only complex thing was to write own ClassGenerator and adopt XMLExporter from v2 that was removed from ORM core.

[stof]

Why needing XMLExporter and ClassGenerator ?

[Fedik]

ClassGenerator

I found it is more easy and faster to write mapping in XML and then generate the class based on it.
Especially when need add/update many fields. Saves a looooot of time. Compared to writing class by hand.
Greatly reduces human factor ;)

XMLExporter

I have an UI for the mapping and form creation. Then the backed create the mapping programaticaly and then export to XML and generate or update the class.

[rixafy]

I'm using ORM3, but I suspect this could be a blockers for some people, because now I'm constantly deleting additional lines from migration, since there are no longer comments in custom fields, it's harder to distinguish them for ORM if you want your own custom types that are already used by doctrine (for instance custom TinyInt type, it's already mapped to boolean and for some readon it has to have exactly same SQL definition).

doctrine/migrations#1435, doctrine/dbal#6743
-> this doctrine/dbal#6569 would solve it at least for TINYINT, but it was not merged due to inactivity of the author of the PR, basically there would be no (1) number in new TINYINT columns and default mysql/mariadb (3) would apply, but this has no effect on column size, it's just metadata attribute that some systems may use for displaying first 3 characters.

Also this is an annoying thing, when you use trait for ID, even at the start of entity class, the ID will be somewhere at random position surrounded by other columns, so when adding new tables there is some manual work of re-arranging the ID at the start of the table in migrations, this bug was introduced probably by DBAL 4.0 but I haven't had the time to debug it more deeply.
doctrine/migrations#1518

[MatthiasKuehneEllerhold]

Currently we cant upgrade because of this:

doctrine/doctrine-orm-module 6.3.0       requires  doctrine/orm (^2.13.0)                                           

It seems like there is a forgotton issue for the upgrade here: doctrine/DoctrineORMModule#752

[cjavad]

One of the major features we rely on is clearEntityChangeSet like doctrine-extensions (doctrine-extensions/DoctrineExtensions#2708 (comment)) we upgraded by using reflection to clear entityChangeSets. The goal is to be able to "unset" changes from getting flushed. Entity change set changes are only additive using the public api's without this, which is a bit of a bummer.

[cjavad]

Exactly, so delegating the persistence of one or more fields into another query, and ignoring them in the flush.

[mpdude]

Does that inc field need to be a mapped field in the first place?

[cjavad]

We need the value fetched with the entity to read if that is what you are asking? Yeah i would say so, obviously any number of workarounds could be used but we have data we want to perform atomic operations on, and this is our current approach w/ doctrine. Unless you mean we can do something like generated/read only so it excludes it from update? That could work as well if that was possible.

[stof]

See https://www.doctrine-project.org/projects/doctrine-orm/en/3.5/cookbook/generated-columns.html#generated-columns for generated columns.

[cjavad]

Yeah this could work quite nicely, but won't doctrine complain about updating generated columns in a DQL query? The changetracking we get from the uow is also very handy, and the entity can be updated from basically any context and it "just works". We are satisified with our workaround for now, and marking columns read-only w/ doctrine seems to be the way forward in particular if we implemented this functionality today. But the pattern we have is still very "nice"

class Entity {
     #[Increment]
     #[Column]
     public int seenCounter = 0;
}

$e = Entity();
$e->otherField = ...;
$e->seenCounter++; // Works just like this and is tracked in the same transaction as flush is.

On a sidenote there is a bug with generated never atm though: #11559