Allow to skip property type validation (#11130)

Fix enum mapping validation

.doctrine-project.json

@@ -11,21 +11,29 @@
             "slug": "latest",
             "upcoming": true
         },
+        {
+            "name": "2.18",
+            "branchName": "2.18.x",
+            "slug": "2.18",
+            "upcoming": true
+        },
+        {
+            "name": "2.17",
+            "branchName": "2.17.x",
+            "slug": "2.17",
+            "current": true
+        },
         {
             "name": "2.16",
             "branchName": "2.16.x",
             "slug": "2.16",
-            "upcoming": true
+            "maintained": false
         },
         {
             "name": "2.15",
             "branchName": "2.15.x",
             "slug": "2.15",
-            "current": true,
-            "aliases": [
-                "current",
-                "stable"
-            ]
+            "maintained": false
         },
         {
             "name": "2.14",

.github/workflows/continuous-integration.yml

@@ -39,6 +39,7 @@ jobs:
           - "8.0"
           - "8.1"
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
         extension:
@@ -62,7 +63,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -111,6 +112,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -143,7 +145,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -183,6 +185,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -212,7 +215,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -252,6 +255,7 @@ jobs:
       matrix:
         php-version:
           - "8.2"
+          - "8.3"
         dbal-version:
           - "default"
           - "3@dev"
@@ -281,7 +285,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -333,7 +337,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -363,7 +367,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 

.github/workflows/documentation.yml

@@ -0,0 +1,48 @@
+name: "Documentation"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/documentation.yml
+      - docs/**
+
+jobs:
+  validate-with-guides:
+    name: "Validate documentation with phpDocumentor/guides"
+    runs-on: "ubuntu-22.04"
+
+    steps:
+      - name: "Checkout code"
+        uses: "actions/checkout@v4"
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.2"
+
+      - name: "Remove existing composer file"
+        run: "rm composer.json"
+
+      - name: "Require phpdocumentor/guides-cli"
+        run: "composer require --dev phpdocumentor/guides-cli --no-update"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v2"
+        with:
+          dependency-versions: "highest"
+
+      - name: "Add dummy title to the sidebar"
+        run: |
+          printf '%s\n%s\n\n%s\n' "Dummy title" "===========" "$(cat docs/en/sidebar.rst)" > docs/en/sidebar.rst
+
+      - name: "Run guides-cli"
+        run: "vendor/bin/guides -vvv --no-progress docs/en 2>&1 | grep -v 'Unknown directive' | ( ! grep WARNING )"

.github/workflows/phpbench.yml

@@ -36,7 +36,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 

.github/workflows/static-analysis.yml

@@ -42,7 +42,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
@@ -83,7 +83,7 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"

UPGRADE.md

@@ -1,3 +1,108 @@
+# Upgrade to 2.17
+
+## Deprecate annotations classes for named queries
+
+The following classes have been deprecated:
+
+* `Doctrine\ORM\Mapping\NamedNativeQueries`
+* `Doctrine\ORM\Mapping\NamedNativeQuery`
+* `Doctrine\ORM\Mapping\NamedQueries`
+* `Doctrine\ORM\Mapping\NamedQuery`
+
+## Deprecate `Doctrine\ORM\Query\Exec\AbstractSqlExecutor::_sqlStatements`
+
+Use `Doctrine\ORM\Query\Exec\AbstractSqlExecutor::sqlStatements` instead.
+
+## Undeprecate `Doctrine\ORM\Proxy\Autoloader`
+
+It will be a full-fledged class, no longer extending
+`Doctrine\Common\Proxy\Autoloader` in 3.0.x.
+
+## Deprecated: reliance on the non-optimal defaults that come with the `AUTO` identifier generation strategy
+
+When the `AUTO` identifier generation strategy was introduced, the best
+strategy at the time was selected for each database platform.
+A lot of time has passed since then, and with ORM 3.0.0 and DBAL 4.0.0, support
+for better strategies will be added.
+
+Because of that, it is now deprecated to rely on the historical defaults when
+they differ from what we will be recommended in the future.
+
+Instead, you should pick a strategy for each database platform you use, and it
+will be used when using `AUTO`. As of now, only PostgreSQL is affected by this.
+
+It is recommended that PostgreSQL users configure their existing and new
+applications to use `SEQUENCE` until `doctrine/dbal` 4.0.0 is released:
+
+```php
+use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
+use Doctrine\ORM\Configuration;
+
+assert($configuration instanceof Configuration);
+$configuration->setIdentityGenerationPreferences([
+    PostgreSQLPlatform::CLASS => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+]);
+```
+
+When DBAL 4 is released, `AUTO` will result in `IDENTITY`, and the above
+configuration should be removed to migrate to it.
+
+## Deprecate `EntityManagerInterface::getPartialReference()`
+
+This method does not have a replacement and will be removed in 3.0.
+
+## Deprecate not-enabling lazy-ghosts
+
+Not enabling lazy ghost objects is deprecated. In ORM 3.0, they will be always enabled.
+Ensure `Doctrine\ORM\Configuration::setLazyGhostObjectEnabled(true)` is called to enable them.
+
+# Upgrade to 2.16
+
+## Deprecated accepting duplicate IDs in the identity map
+
+For any given entity class and ID value, there should be only one object instance
+representing the entity.
+
+In https://github.com/doctrine/orm/pull/10785, a check was added that will guard this
+in the identity map. The most probable cause for violations of this rule are collisions
+of application-provided IDs.
+
+In ORM 2.16.0, the check was added by throwing an exception. In ORM 2.16.1, this will be
+changed to a deprecation notice. ORM 3.0 will make it an exception again. Use
+`\Doctrine\ORM\Configuration::setRejectIdCollisionInIdentityMap()` if you want to opt-in
+to the new mode.
+
+## Potential changes to the order in which `INSERT`s are executed
+
+In https://github.com/doctrine/orm/pull/10547, the commit order computation was improved
+to fix a series of bugs where a correct (working) commit order was previously not found.
+Also, the new computation may get away with fewer queries being executed: By inserting
+referred-to entities first and using their ID values for foreign key fields in subsequent
+`INSERT` statements, additional `UPDATE` statements that were previously necessary can be
+avoided.
+
+When using database-provided, auto-incrementing IDs, this may lead to IDs being assigned
+to entities in a different order than it was previously the case.
+
+## Deprecated returning post insert IDs from `EntityPersister::executeInserts()`
+
+Persisters implementing `\Doctrine\ORM\Persisters\Entity\EntityPersister` should no longer
+return an array of post insert IDs from their `::executeInserts()` method. Make the
+persister call `Doctrine\ORM\UnitOfWork::assignPostInsertId()` instead.
+
+## Changing the way how reflection-based mapping drivers report fields, deprecated the "old" mode
+
+In ORM 3.0, a change will be made regarding how the `AttributeDriver` reports field mappings.
+This change is necessary to be able to detect (and reject) some invalid mapping configurations.
+
+To avoid surprises during 2.x upgrades, the new mode is opt-in. It can be activated on the
+`AttributeDriver` and `AnnotationDriver` by setting the `$reportFieldsWhereDeclared`
+constructor parameter to `true`. It will cause `MappingException`s to be thrown when invalid
+configurations are detected.
+
+Not enabling the new mode will cause a deprecation notice to be raised. In ORM 3.0,
+only the new mode will be available.
+
 # Upgrade to 2.15
 
 ## Deprecated configuring `JoinColumn` on the inverse side of one-to-one associations
@@ -15,7 +120,7 @@ and will be an error in 3.0.
 
 ## Deprecated undeclared entity inheritance
 
-As soon as an entity class inherits from another entity class, inheritance has to 
+As soon as an entity class inherits from another entity class, inheritance has to
 be declared by adding the appropriate configuration for the root entity.
 
 ## Deprecated stubs for "concrete table inheritance"

composer.json

@@ -34,7 +34,7 @@
         "doctrine/lexer": "^2",
         "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^4.2 || ^5.0 || ^6.0",
+        "symfony/console": "^4.2 || ^5.0 || ^6.0 || ^7.0",
         "symfony/polyfill-php72": "^1.23",
         "symfony/polyfill-php80": "^1.16"
     },
@@ -42,14 +42,14 @@
         "doctrine/annotations": "^1.13 || ^2",
         "doctrine/coding-standard": "^9.0.2 || ^12.0",
         "phpbench/phpbench": "^0.16.10 || ^1.0",
-        "phpstan/phpstan": "~1.4.10 || 1.10.14",
+        "phpstan/phpstan": "~1.4.10 || 1.10.35",
         "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6",
         "psr/log": "^1 || ^2 || ^3",
         "squizlabs/php_codesniffer": "3.7.2",
-        "symfony/cache": "^4.4 || ^5.4 || ^6.0",
-        "symfony/var-exporter": "^4.4 || ^5.4 || ^6.2",
-        "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
-        "vimeo/psalm": "4.30.0 || 5.11.0"
+        "symfony/cache": "^4.4 || ^5.4 || ^6.4 || ^7.0",
+        "symfony/var-exporter": "^4.4 || ^5.4 || ^6.2 || ^7.0",
+        "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0 || ^7.0",
+        "vimeo/psalm": "4.30.0 || 5.16.0"
     },
     "conflict": {
         "doctrine/annotations": "<1.13 || >= 3.0"

docs/en/cookbook/aggregate-fields.rst

@@ -211,7 +211,7 @@ Now look at the following test-code for our entities:
     {
         public function testAddEntry()
         {
-            $account = new Account("123456", $maxCredit = 200);
+            $account = new Account("123456", maxCredit: 200);
             $this->assertEquals(0, $account->getBalance());
     
             $account->addEntry(500);
@@ -223,7 +223,7 @@ Now look at the following test-code for our entities:
     
         public function testExceedMaxLimit()
         {
-            $account = new Account("123456", $maxCredit = 200);
+            $account = new Account("123456", maxCredit: 200);
     
             $this->expectException(Exception::class);
             $account->addEntry(-1000);

docs/en/cookbook/implementing-the-notify-changetracking-policy.rst

@@ -13,7 +13,7 @@ for all our domain objects.
 .. note::
 
     The notify change tracking policy is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
 
 Implementing NotifyPropertyChanged
 ----------------------------------

docs/en/cookbook/resolve-target-entity-listener.rst

@@ -127,7 +127,7 @@ the targetEntity resolution will occur reliably:
     // Add the ResolveTargetEntityListener
     $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $rtel);
 
-    $connection = \Doctrine\DBAL\DriverManager::createConnection($connectionOptions, $config, $evm);
+    $connection = \Doctrine\DBAL\DriverManager::getConnection($connectionOptions, $config, $evm);
     $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);
 
 Final Thoughts

docs/en/cookbook/validation-of-entities.rst

@@ -58,6 +58,10 @@ First Attributes:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Mapping\Entity;
+    use Doctrine\ORM\Mapping\HasLifecycleCallbacks;
+    use Doctrine\ORM\Mapping\PrePersist;
+    use Doctrine\ORM\Mapping\PreUpdate;
 
     #[Entity]
     #[HasLifecycleCallbacks]

docs/en/index.rst

@@ -18,8 +18,8 @@ Doctrine ORM don't panic. You can get help from different sources:
 -  Report a bug on `GitHub <https://github.com/doctrine/orm/issues>`_.
 -  On `StackOverflow <https://stackoverflow.com/questions/tagged/doctrine-orm>`_
 
-If you need more structure over the different topics you can browse the :doc:`table
-of contents <toc>`.
+If you need more structure over the different topics you can browse the table
+of contents.
 
 Getting Started
 ---------------
@@ -34,32 +34,32 @@ Mapping Objects onto a Database
 -------------------------------
 
 * **Mapping**:
-  :doc:`Objects <reference/basic-mapping>` |
-  :doc:`Associations <reference/association-mapping>` |
+  :doc:`Objects <reference/basic-mapping>` \|
+  :doc:`Associations <reference/association-mapping>` \|
   :doc:`Inheritance <reference/inheritance-mapping>`
 
 * **Drivers**:
-  :doc:`Docblock Annotations <reference/annotations-reference>` |
-  :doc:`Attributes <reference/attributes-reference>` |
-  :doc:`XML <reference/xml-mapping>` |
-  :doc:`YAML <reference/yaml-mapping>` |
+  :doc:`Docblock Annotations <reference/annotations-reference>` \|
+  :doc:`Attributes <reference/attributes-reference>` \|
+  :doc:`XML <reference/xml-mapping>` \|
+  :doc:`YAML <reference/yaml-mapping>` \|
   :doc:`PHP <reference/php-mapping>`
 
 Working with Objects
 --------------------
 
 * **Basic Reference**:
-  :doc:`Entities <reference/working-with-objects>` |
-  :doc:`Associations <reference/working-with-associations>` |
+  :doc:`Entities <reference/working-with-objects>` \|
+  :doc:`Associations <reference/working-with-associations>` \|
   :doc:`Events <reference/events>`
 
 * **Query Reference**:
-  :doc:`DQL <reference/dql-doctrine-query-language>` |
-  :doc:`QueryBuilder <reference/query-builder>` |
+  :doc:`DQL <reference/dql-doctrine-query-language>` \|
+  :doc:`QueryBuilder <reference/query-builder>` \|
   :doc:`Native SQL <reference/native-sql>`
 
 * **Internals**:
-  :doc:`Internals explained <reference/unitofwork>` |
+  :doc:`Internals explained <reference/unitofwork>` \|
   :doc:`Associations <reference/unitofwork-associations>`
 
 Advanced Topics
@@ -102,20 +102,20 @@ Cookbook
 --------
 
 * **Patterns**:
-  :doc:`Aggregate Fields <cookbook/aggregate-fields>` |
-  :doc:`Decorator Pattern <cookbook/decorator-pattern>` |
+  :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
 * **DQL Extension Points**:
-  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
+  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` \|
   :doc:`DQL User-Defined-Functions <cookbook/dql-user-defined-functions>`
 
 * **Implementation**:
-  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
-  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
-  :doc:`Working with DateTime <cookbook/working-with-datetime>` |
-  :doc:`Validation <cookbook/validation-of-entities>` |
-  :doc:`Entities in the Session <cookbook/entities-in-session>` |
+  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` \|
+  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` \|
+  :doc:`Working with DateTime <cookbook/working-with-datetime>` \|
+  :doc:`Validation <cookbook/validation-of-entities>` \|
+  :doc:`Entities in the Session <cookbook/entities-in-session>` \|
   :doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
 
 * **Hidden Gems**
@@ -124,5 +124,3 @@ Cookbook
 * **Custom Datatypes**
   :doc:`MySQL Enums <cookbook/mysql-enums>`
   :doc:`Advanced Field Value Conversion <cookbook/advanced-field-value-conversion-using-custom-mapping-types>`
-
-.. include:: toc.rst

docs/en/reference/advanced-configuration.rst

@@ -29,7 +29,7 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
     $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
@@ -134,7 +134,7 @@ The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
     <?php
     use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
 
 The path information to the entities is required for the attribute
@@ -311,10 +311,12 @@ Reference Proxies
 
 The method ``EntityManager#getReference($entityName, $identifier)``
 lets you obtain a reference to an entity for which the identifier
-is known, without loading that entity from the database. This is
-useful, for example, as a performance enhancement, when you want to
-establish an association to an entity for which you have the
-identifier. You could simply do this:
+is known, without necessarily loading that entity from the database.
+This is useful, for example, as a performance enhancement, when you
+want to establish an association to an entity for which you have the
+identifier.
+
+Consider the following example:
 
 .. code-block:: php
 
@@ -324,15 +326,33 @@ identifier. You could simply do this:
     $item = $em->getReference('MyProject\Model\Item', $itemId);
     $cart->addItem($item);
 
-Here, we added an Item to a Cart without loading the Item from the
-database. If you access any state that isn't yet available in the
-Item instance, the proxying mechanism would fully initialize the
-object's state transparently from the database. Here
-$item is actually an instance of the proxy class that was generated
-for the Item class but your code does not need to care. In fact it
-**should not care**. Proxy objects should be transparent to your
+Whether the object being returned from ``EntityManager#getReference()``
+is a proxy or a direct instance of the entity class may depend on different
+factors, including whether the entity has already been loaded into memory
+or entity inheritance being used. But your code does not need to care
+and in fact it **should not care**. Proxy objects should be transparent to your
 code.
 
+When using the ``EntityManager#getReference()`` method, you need to be aware
+of a few peculiarities.
+
+At the best case, the ORM can avoid querying the database at all. But, that
+also means that this method will not throw an exception when an invalid value
+for the ``$identifier`` parameter is passed. ``$identifier`` values are
+not checked and there is no guarantee that the requested entity instance even
+exists – the method will still return a proxy object.
+
+Its only when the proxy has to be fully initialized or associations cannot
+be written to the database that invalid ``$identifier`` values may lead to
+exceptions.
+
+The ``EntityManager#getReference()`` is mostly useful when you only
+need a reference to some entity to make an association, like in the example
+above. In that case, it can save you from loading data from the database
+that you don't need. But remember – as soon as you read any property values
+besides those making up the ID, a database request will be made to initialize
+all fields.
+
 Association proxies
 ~~~~~~~~~~~~~~~~~~~
 
@@ -388,7 +408,7 @@ means that you have to register a special autoloader for these classes:
 .. code-block:: php
 
     <?php
-    use Doctrine\Common\Proxy\Autoloader;
+    use Doctrine\ORM\Proxy\Autoloader;
 
     $proxyDir = "/path/to/proxies";
     $proxyNamespace = "MyProxies";

docs/en/reference/annotations-reference.rst

@@ -545,12 +545,12 @@ has meaning in the SchemaTool schema generation context.
 Required attributes:
 
 
--  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will
@@ -1316,12 +1316,12 @@ context.
 Required attributes:
 
 
--  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will

docs/en/reference/architecture.rst

@@ -24,28 +24,34 @@ performance it is also recommended that you use APC with PHP.
 Doctrine ORM Packages
 -------------------
 
-Doctrine ORM is divided into three main packages.
+Doctrine ORM is divided into four main packages.
 
--  Common
--  DBAL (includes Common)
--  ORM (includes DBAL+Common)
+-  `Collections <https://www.doctrine-project.org/projects/doctrine-collections/en/stable/index.html>`_
+-  `Event Manager <https://www.doctrine-project.org/projects/doctrine-event-manager/en/stable/index.html>`_
+-  `Persistence <https://www.doctrine-project.org/projects/doctrine-persistence/en/stable/index.html>`_
+-  `DBAL <https://www.doctrine-project.org/projects/doctrine-dbal/en/stable/index.html>`_
+-  ORM (depends on DBAL+Persistence+Collections)
 
 This manual mainly covers the ORM package, sometimes touching parts
-of the underlying DBAL and Common packages. The Doctrine code base
+of the underlying DBAL and Persistence packages. The Doctrine code base
 is split in to these packages for a few reasons and they are to...
 
 
 -  ...make things more maintainable and decoupled
--  ...allow you to use the code in Doctrine Common without the ORM
-   or DBAL
+-  ...allow you to use the code in Doctrine Persistence and Collections
+  without the ORM or DBAL
 -  ...allow you to use the DBAL without the ORM
 
-The Common Package
-~~~~~~~~~~~~~~~~~~
+Collection, Event Manager and Persistence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Common package contains highly reusable components that have no
-dependencies beyond the package itself (and PHP, of course). The
-root namespace of the Common package is ``Doctrine\Common``.
+The Collection, Event Manager and Persistence packages contain highly
+reusable components that have no dependencies beyond the packages
+themselves (and PHP, of course). The root namespace of the Persistence
+package is ``Doctrine\Persistence``. The root namespace of the
+Collection package is ``Doctrine\Common\Collections``, for historical
+reasons. The root namespace of the Event Manager package is just
+``Doctrine\Common``, also for historical reasons.
 
 The DBAL Package
 ~~~~~~~~~~~~~~~~
@@ -102,7 +108,7 @@ persistent entity state and mapping information for its subclasses,
 but which is not itself an entity.
 
 Mapped superclasses are explained in greater detail in the chapter
-on :doc:`inheritance mapping <reference/inheritance-mapping>`.
+on :doc:`inheritance mapping </reference/inheritance-mapping>`.
 
 Transient Classes
 ~~~~~~~~~~~~~~~~~
@@ -199,5 +205,3 @@ typical implementation of the
 to keep track of all the things that need to be done the next time
 ``flush`` is invoked. You usually do not directly interact with a
 ``UnitOfWork`` but with the ``EntityManager`` instead.
-
-

docs/en/reference/association-mapping.rst

@@ -881,6 +881,15 @@ Generated MySQL Schema:
     replaced by one-to-many/many-to-one associations between the 3
     participating classes.
 
+.. note::
+
+    For many-to-many associations, the ORM takes care of managing rows
+    in the join table connecting both sides. Due to the way it deals
+    with entity removals, database-level constraints may not work the
+    way one might intuitively assume. Thus, be sure not to miss the section
+    on :ref:`join table management <remove_object_many_to_many_join_tables>`.
+
+
 Many-To-Many, Bidirectional
 ---------------------------
 
@@ -1019,6 +1028,15 @@ one is bidirectional.
 The MySQL schema is exactly the same as for the Many-To-Many
 uni-directional case above.
 
+.. note::
+
+    For many-to-many associations, the ORM takes care of managing rows
+    in the join table connecting both sides. Due to the way it deals
+    with entity removals, database-level constraints may not work the
+    way one might intuitively assume. Thus, be sure not to miss the section
+    on :ref:`join table management <remove_object_many_to_many_join_tables>`.
+
+
 Owning and Inverse Side on a ManyToMany Association
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/reference/attributes-reference.rst

@@ -540,13 +540,13 @@ has meaning in the ``SchemaTool`` schema generation context.
 
 Required parameters:
 
--  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields, columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields, columns** is required.
 
 
 Optional parameters:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will
@@ -1104,12 +1104,12 @@ context.
 
 Required parameters:
 
--  **name**: Name of the Index
 -  **fields**: Array of fields (the names of the properties, used in the entity class).
 -  **columns**: Array of columns (the names of the columns, used in the schema).
 
 Optional parameters:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will

docs/en/reference/basic-mapping.rst

@@ -47,8 +47,7 @@ mapping metadata:
 -  :doc:`Attributes <attributes-reference>`
 -  :doc:`XML <xml-mapping>`
 -  :doc:`PHP code <php-mapping>`
--  :doc:`Docblock Annotations <annotations-reference>` (deprecated and
-  will be removed in ``doctrine/orm`` 3.0)
+-  :doc:`Docblock Annotations <annotations-reference>` (deprecated and will be removed in ``doctrine/orm`` 3.0)
 -  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via attributes, though
@@ -423,9 +422,11 @@ the field that serves as the identifier with the ``#[Id]`` attribute.
             # fields here
 
 In most cases using the automatic generator strategy (``#[GeneratedValue]``) is
-what you want. It defaults to the identifier generation mechanism your current
-database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL
-and Oracle and so on.
+what you want, but for backwards-compatibility reasons it might not. It
+defaults to the identifier generation mechanism your current database
+vendor preferred at the time that strategy was introduced:
+``AUTO_INCREMENT`` with MySQL, sequences with PostgreSQL and Oracle and
+so on.
 
 .. _identifier-generation-strategies:
 
@@ -442,17 +443,18 @@ Here is the list of possible generation strategies:
 
 -  ``AUTO`` (default): Tells Doctrine to pick the strategy that is
    preferred by the used database platform. The preferred strategies
-   are IDENTITY for MySQL, SQLite, MsSQL and SQL Anywhere and SEQUENCE
-   for Oracle and PostgreSQL. This strategy provides full portability.
--  ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
-   generation. This strategy does currently not provide full
-   portability. Sequences are supported by Oracle, PostgreSql and
-   SQL Anywhere.
+   are ``IDENTITY`` for MySQL, SQLite, MsSQL and SQL Anywhere and, for
+   historical reasons, ``SEQUENCE`` for Oracle and PostgreSQL. This
+   strategy provides full portability.
 -  ``IDENTITY``: Tells Doctrine to use special identity columns in
    the database that generate a value on insertion of a row. This
    strategy does currently not provide full portability and is
    supported by the following platforms: MySQL/SQLite/SQL Anywhere
-   (AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
+   (``AUTO_INCREMENT``), MSSQL (``IDENTITY``) and PostgreSQL (``SERIAL``).
+-  ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
+   generation. This strategy does currently not provide full
+   portability. Sequences are supported by Oracle, PostgreSql and
+   SQL Anywhere.
 -  ``UUID`` (deprecated): Tells Doctrine to use the built-in Universally
    Unique Identifier generator. This strategy provides full portability.
 -  ``NONE``: Tells Doctrine that the identifiers are assigned (and
@@ -460,7 +462,7 @@ Here is the list of possible generation strategies:
    a new entity is passed to ``EntityManager#persist``. NONE is the
    same as leaving off the ``#[GeneratedValue]`` entirely.
 -  ``CUSTOM``: With this option, you can use the ``#[CustomIdGenerator]`` attribute.
-   It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
+   It will allow you to pass a :ref:`class of your own to generate the identifiers.<annref_customidgenerator>`
 
 Sequence Generator
 ^^^^^^^^^^^^^^^^^^

docs/en/reference/change-tracking-policies.rst

@@ -63,7 +63,7 @@ Notify
 .. note::
 
     The notify change tracking policy is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
 
 This policy is based on the assumption that the entities notify
 interested listeners of changes to their properties. For that

docs/en/reference/configuration.rst

@@ -104,7 +104,7 @@ Inside the ``ORMSetup`` methods several assumptions are made:
     In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
     has to be installed as a dependency.
 
-If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration </reference/advanced-configuration>` section.
 
 .. note::
 

docs/en/reference/dql-doctrine-query-language.rst

@@ -464,6 +464,11 @@ hierarchies:
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF Doctrine\Tests\Models\Company\CompanyEmployee');
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF ?1');
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u NOT INSTANCE OF ?1');
+    $query->setParameter(0, $em->getClassMetadata(CompanyEmployee::class));
+
+.. note::
+    To use a class as parameter, you have to bind its class metadata:
+    ``$query->setParameter(0, $em->getClassMetadata(CompanyEmployee::class);``.
 
 Get all users visible on a given website that have chosen certain gender:
 
@@ -1336,8 +1341,8 @@ There are situations when a query you want to execute returns a
 very large result-set that needs to be processed. All the
 previously described hydration modes completely load a result-set
 into memory which might not be feasible with large result sets. See
-the `Batch Processing <batch-processing.html>`_ section on details how
-to iterate large result sets.
+the :doc:`Batch Processing </reference/batch-processing>` section on
+details how to iterate large result sets.
 
 Functions
 ~~~~~~~~~
@@ -1381,7 +1386,7 @@ Result Cache API:
     $query->setResultCacheDriver(new ApcCache());
 
     $query->useResultCache(true)
-          ->setResultCacheLifeTime($seconds = 3600);
+          ->setResultCacheLifeTime(3600);
 
     $result = $query->getResult(); // cache miss
 
@@ -1392,7 +1397,7 @@ Result Cache API:
     $result = $query->getResult(); // saved in given result cache id.
 
     // or call useResultCache() with all parameters:
-    $query->useResultCache(true, $seconds = 3600, 'my_query_result');
+    $query->useResultCache(true, 3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
@@ -1425,7 +1430,7 @@ userland:
    reloading this data. Partially loaded objects have to be passed to
    ``EntityManager::refresh()`` if they are to be reloaded fully from
    the database. This query hint is deprecated and will be removed
-   in the future (`Details <https://github.com/doctrine/orm/issues/8471>`_)
+   in the future (\ `Details <https://github.com/doctrine/orm/issues/8471>`_)
 -  ``Query::HINT_REFRESH`` - This query is used internally by
    ``EntityManager::refresh()`` and can be used in userland as well.
    If you specify this hint and a query returns the data for an entity
@@ -1457,7 +1462,7 @@ several methods to interact with it:
 
 -  ``Query::setQueryCacheDriver($driver)`` - Allows to set a Cache
    instance
--  ``Query::setQueryCacheLifeTime($seconds = 3600)`` - Set lifetime
+-  ``Query::setQueryCacheLifeTime($seconds)`` - Set lifetime
    of the query caching.
 -  ``Query::expireQueryCache($bool)`` - Enforce the expiring of the
    query cache if set to true.

docs/en/reference/events.rst

@@ -215,6 +215,10 @@ specific to a particular entity class's lifecycle.
         <?php
         use Doctrine\DBAL\Types\Types;
         use Doctrine\ORM\Event\PrePersistEventArgs;
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\HasLifecycleCallbacks;
+        use Doctrine\ORM\Mapping\PrePersist;
+        use Doctrine\ORM\Mapping\PreUpdate;
 
         #[Entity]
         #[HasLifecycleCallbacks]
@@ -281,10 +285,10 @@ specific to a particular entity class's lifecycle.
 
         <?xml version="1.0" encoding="UTF-8"?>
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
             <entity name="User">
                 <!-- ... -->
                 <lifecycle-callbacks>
@@ -453,13 +457,12 @@ prePersist
 
 There are two ways for the ``prePersist`` event to be triggered:
 
-- One is obviously when you call ``EntityManager::persist()``. The
-event is also called for all :ref:`cascaded associations<transitive-persistence>`.
-- The other is inside the
-``flush()`` method when changes to associations are computed and
-this association is marked as :ref:`cascade: persist<transitive-persistence>`. Any new entity found
-during this operation is also persisted and ``prePersist`` called
-on it. This is called :ref:`persistence by reachability<persistence-by-reachability>`.
+- One is when you call ``EntityManager::persist()``. The
+  event is also called for all :ref:`cascaded associations<transitive-persistence>`.
+- The other is inside the ``flush()`` method when changes to associations are computed and
+  this association is marked as :ref:`cascade: persist<transitive-persistence>`. Any new entity found
+  during this operation is also persisted and ``prePersist`` called
+  on it. This is called :ref:`persistence by reachability<persistence-by-reachability>`.
 
 In both cases you get passed a ``PrePersistEventArgs`` instance
 which has access to the entity and the entity manager.
@@ -705,13 +708,21 @@ not directly mapped by Doctrine.
 -  The ``postUpdate`` event occurs after the database
    update operations to entity data. It is not called for a DQL
    ``UPDATE`` statement.
--  The ``postPersist`` event occurs for an entity after
-   the entity has been made persistent. It will be invoked after the
-   database insert operations. Generated primary key values are
-   available in the postPersist event.
+-  The ``postPersist`` event occurs for an entity after the entity has
+   been made persistent. It will be invoked after all database insert
+   operations for new entities have been performed. Generated primary
+   key values will be available for all entities at the time this
+   event is triggered.
 -  The ``postRemove`` event occurs for an entity after the
-   entity has been deleted. It will be invoked after the database
-   delete operations. It is not called for a DQL ``DELETE`` statement.
+   entity has been deleted. It will be invoked after all database
+   delete operations for entity rows have been executed. This event is
+   not called for a DQL ``DELETE`` statement.
+
+.. note::
+
+    At the time ``postPersist`` is called, there may still be collection and/or
+    "extra" updates pending. The database may not yet be completely in
+    sync with the entity states in memory, not even for the new entities.
 
 .. warning::
 
@@ -720,6 +731,19 @@ not directly mapped by Doctrine.
     cascade remove relations. In this case, you should load yourself the proxy in
     the associated ``pre*`` event.
 
+.. warning::
+
+    Making changes to entities and calling ``EntityManager::flush()`` from within
+    ``post*`` event handlers is strongly discouraged, and might be deprecated and
+    eventually prevented in the future.
+
+    The reason is that it causes re-entrance into ``UnitOfWork::commit()`` while a commit
+    is currently being processed. The ``UnitOfWork`` was never designed to support this,
+    and its behavior in this situation is not covered by any tests.
+
+    This may lead to entity or collection updates being missed, applied only in parts and
+    changes being lost at the end of the commit phase.
+
 .. _reference-events-post-load:
 
 postLoad

docs/en/reference/faq.rst

@@ -13,11 +13,10 @@ Database Schema
 How do I set the charset and collation for MySQL tables?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can't set these values with attributes, annotations or inside yml or
-xml mapping files. To make a database work with the default charset and
-collation you should configure MySQL to use it as default charset, or
-create the database with charset and collation details. This way they
-get inherited to all newly created database tables and columns.
+In your mapping configuration, the column definition (for example, the
+``#[Column]`` attribute) has an ``options`` parameter where you can specify
+the ``charset`` and ``collation``. The default values are ``utf8`` and
+``utf8_unicode_ci``, respectively.
 
 Entity Classes
 --------------

docs/en/reference/filters.rst

@@ -93,3 +93,34 @@ object.
     want to refresh or reload an object after having modified a filter or the
     FilterCollection, then you should clear the EntityManager and re-fetch your
     entities, having the new rules for filtering applied.
+
+
+Suspending/Restoring Filters
+----------------------------
+When a filter is disabled, the instance is fully deleted and all the filter
+parameters previously set are lost. Then, if you enable it again, a new filter
+is created without the previous filter parameters. If you want to keep a filter
+(in order to use it later) but temporary disable it, you'll need to use the
+``FilterCollection#suspend($name)`` and ``FilterCollection#restore($name)``
+methods instead.
+
+.. code-block:: php
+
+    <?php
+    $filter = $em->getFilters()->enable("locale");
+    $filter->setParameter('locale', 'en');
+
+    // Temporary suspend the filter
+    $filter = $em->getFilters()->suspend("locale");
+
+    // Do things
+
+    // Then restore it, the locale parameter will still be set
+    $filter = $em->getFilters()->restore("locale");
+
+.. warning::
+    If you enable a previously disabled filter, doctrine will create a new
+    one without keeping any of the previously parameter set with
+    ``SQLFilter#setParameter()`` or ``SQLFilter#getParameterList()``. If you
+    want to restore the previously disabled filter instead, you must use the
+    ``FilterCollection#restore($name)`` method.

docs/en/reference/improving-performance.rst

@@ -91,7 +91,7 @@ Apply Best Practices
 A lot of the points mentioned in the Best Practices chapter will
 also positively affect the performance of Doctrine.
 
-See :doc:`Best Practices <reference/best-practices>`
+See :doc:`Best Practices </reference/best-practices>`
 
 Change Tracking policies
 ------------------------

docs/en/reference/inheritance-mapping.rst

@@ -35,7 +35,7 @@ have to be used.
     superclass, since they require the "many" side to hold the foreign
     key.
 
-    It is, however, possible to use the :doc:`ResolveTargetEntityListener <cookbook/resolve-target-entity-listener>`
+    It is, however, possible to use the :doc:`ResolveTargetEntityListener </cookbook/resolve-target-entity-listener>`
     to replace references to a mapped superclass with an entity class at runtime.
     As long as there is only one entity subclass inheriting from the mapped
     superclass and all references to the mapped superclass are resolved to that
@@ -45,7 +45,7 @@ have to be used.
 .. warning::
 
     At least when using attributes or annotations to specify your mapping,
-    it _seems_ as if you could inherit from a base class that is neither
+    it *seems* as if you could inherit from a base class that is neither
     an entity nor a mapped superclass, but has properties with mapping configuration
     on them that would also be used in the inheriting class.
 
@@ -60,7 +60,7 @@ have to be used.
     You may be tempted to use traits to mix mapped fields or relationships
     into your entity classes to circumvent some of the limitations of
     mapped superclasses. Before doing that, please read the section on traits
-    in the :doc:`Limitations and Known Issues <reference/limitations-and-known-issues>` chapter.
+    in the :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
 
 Example:
 
@@ -380,7 +380,7 @@ It is not supported to use overrides in entity inheritance scenarios.
 .. note::
 
     When using traits, make sure not to miss the warnings given in the
-    :doc:`Limitations and Known Issues<reference/limitations-and-known-issues>` chapter.
+    :doc:`Limitations and Known Issues</reference/limitations-and-known-issues>` chapter.
 
 
 Association Override

docs/en/reference/installation.rst

@@ -1,4 +1,4 @@
 Installation
 ============
 
-The installation chapter has moved to :doc:`Installation and Configuration <reference/configuration>`_.
+The installation chapter has moved to :doc:`Installation and Configuration </reference/configuration>`.

docs/en/reference/limitations-and-known-issues.rst

@@ -145,7 +145,7 @@ more than two years after the initial Doctrine 2 release and the time where
 core components were designed.
 
 In fact, this documentation mentions traits only in the context of
-:doc:`overriding field association mappings in subclasses <tutorials/override-field-association-mappings-in-subclasses>`.
+:doc:`overriding field association mappings in subclasses </tutorials/override-field-association-mappings-in-subclasses>`.
 Coverage of traits in test cases is practically nonexistent.
 
 Thus, you should at least be aware that when using traits in your entity and
@@ -162,12 +162,12 @@ that, some precedence and conflict resolution rules apply.
 
 When it comes to loading mapping configuration, the annotation and attribute drivers
 rely on PHP reflection to inspect class properties including their docblocks.
-As long as the results are consistent with what a solution _without_ traits would
+As long as the results are consistent with what a solution *without* traits would
 have produced, this is probably fine.
 
 However, to mention known limitations, it is currently not possible to use "class"
 level `annotations <https://github.com/doctrine/orm/pull/1517>`_ or
-`attributes <https://github.com/doctrine/orm/issues/8868>` on traits, and attempts to
+`attributes <https://github.com/doctrine/orm/issues/8868>`_ on traits, and attempts to
 improve parser support for traits as `here <https://github.com/doctrine/annotations/pull/102>`_
 or `there <https://github.com/doctrine/annotations/pull/63>`_ have been abandoned
 due to complexity.

docs/en/reference/native-sql.rst

@@ -250,6 +250,40 @@ The first parameter is the name of the column in the SQL result set
 and the second parameter is the result alias under which the value
 of the column will be placed in the transformed Doctrine result.
 
+Special case: DTOs
+...................
+
+You can also use ``ResultSetMapping`` to map the results of a native SQL
+query to a DTO (Data Transfer Object). This is done by adding scalar
+results for each argument of the DTO's constructor, then filling the
+``newObjectMappings`` property of the ``ResultSetMapping`` with
+information about where to map each scalar result:
+
+.. code-block:: php
+
+   <?php
+
+    $rsm = new ResultSetMapping();
+    $rsm->addScalarResult('name', 1, 'string');
+    $rsm->addScalarResult('email', 2, 'string');
+    $rsm->addScalarResult('city', 3, 'string');
+    $rsm->newObjectMappings['name']  = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0, // a result can contain many DTOs, this is the index of the DTO to map to
+        'argIndex'  => 0, // each scalar result can be mapped to a different argument of the DTO constructor
+    ];
+    $rsm->newObjectMappings['email'] = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0,
+        'argIndex'  => 1,
+    ];
+    $rsm->newObjectMappings['city']  = [
+        'className' => CmsUserDTO::class,
+        'objIndex'  => 0,
+        'argIndex'  => 2,
+    ];
+
+
 Meta results
 ~~~~~~~~~~~~
 

docs/en/reference/partial-objects.rst

@@ -6,7 +6,7 @@ Partial Objects
 
     Creating Partial Objects through DQL is deprecated and
     will be removed in the future, use data transfer object
-    support in DQL instead. (`Details
+    support in DQL instead. (\ `Details
     <https://github.com/doctrine/orm/issues/8471>`_)
 
 A partial object is an object whose state is not fully initialized

docs/en/reference/query-builder.rst

@@ -253,7 +253,7 @@ Calling ``setParameter()`` automatically infers which type you are setting as
 value. This works for integers, arrays of strings/integers, DateTime instances
 and for managed entities. If you want to set a type explicitly you can call
 the third argument to ``setParameter()`` explicitly. It accepts either a DBAL
-Doctrine\DBAL\ParameterType::* or a DBAL Type name for conversion.
+``Doctrine\DBAL\ParameterType::*`` or a DBAL Type name for conversion.
 
 .. note::
 
@@ -578,8 +578,6 @@ of DQL. It takes 3 parameters: ``$dqlPartName``, ``$dqlPart`` and
    not (no effect on the ``where`` and ``having`` DQL query parts,
    which always override all previously defined items)
 
--
-
 .. code-block:: php
 
     <?php

docs/en/reference/second-level-cache.rst

@@ -322,7 +322,10 @@ level cache region.
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="Country">
             <cache usage="READ_ONLY" region="my_entity_region" />
             <id name="id" type="integer" column="id">
@@ -427,7 +430,10 @@ It caches the primary keys of association and cache each element will be cached
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="State">
 
             <cache usage="NONSTRICT_READ_WRITE" />

docs/en/reference/unitofwork.rst

@@ -37,8 +37,8 @@ will still end up with the same reference:
     public function testIdentityMapReference(): void
     {
         $objectA = $this->entityManager->getReference('EntityName', 1);
-        // check for proxyinterface
-        $this->assertInstanceOf('Doctrine\Persistence\Proxy', $objectA);
+        // check entity is not initialized
+        $this->assertTrue($this->entityManager->isUninitializedObject($objectA));
 
         $objectB = $this->entityManager->find('EntityName', 1);
 
@@ -137,7 +137,7 @@ optimize the performance of the Flush Operation:
 .. note::
 
     Flush only a single entity with ``$entityManager->flush($entity)`` is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8459>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8459>`_)
 
 Query Internals
 ---------------

docs/en/reference/working-with-objects.rst

@@ -192,6 +192,11 @@ be properly synchronized with the database when
     database in the most efficient way and a single, short transaction,
     taking care of maintaining referential integrity.
 
+.. note::
+
+    Do not make any assumptions in your code about the number of queries
+    it takes to flush changes, about the ordering of ``INSERT``, ``UPDATE``
+    and ``DELETE`` queries or the order in which entities will be processed.
 
 Example:
 
@@ -286,17 +291,53 @@ as follows:
 After an entity has been removed, its in-memory state is the same as
 before the removal, except for generated identifiers.
 
-Removing an entity will also automatically delete any existing
-records in many-to-many join tables that link this entity. The
-action taken depends on the value of the ``@joinColumn`` mapping
-attribute "onDelete". Either Doctrine issues a dedicated ``DELETE``
-statement for records of each join table or it depends on the
-foreign key semantics of onDelete="CASCADE".
+During the ``EntityManager#flush()`` operation, the removed entity
+will also be removed from all collections in entities currently
+loaded into memory.
+
+.. _remove_object_many_to_many_join_tables:
+
+Join-table management when removing from many-to-many collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Regarding existing rows in many-to-many join tables that refer to
+an entity being removed, the following applies.
+
+When the entity being removed does not declare the many-to-many association
+itself (that is, the many-to-many association is unidirectional and
+the entity is on the inverse side), the ORM has no reasonable way to
+detect associations targeting the entity's class. Thus, no ORM-level handling
+of join-table rows is attempted and database-level constraints apply.
+In case of database-level ``ON DELETE RESTRICT`` constraints, the
+``EntityManager#flush()`` operation may abort and a ``ConstraintViolationException``
+may be thrown. No in-memory collections will be modified in this case.
+With ``ON DELETE CASCADE``, the RDBMS will take care of removing rows
+from join tables.
+
+When the entity being removed is part of bi-directional many-to-many
+association, either as the owning or inverse side, the ORM will
+delete rows from join tables before removing the entity itself. That means
+database-level ``ON DELETE RESTRICT`` constraints on join tables are not
+effective, since the join table rows are removed first. Removal of join table
+rows happens through specialized methods in entity and collection persister
+classes and take one query per entity and join table. In case the association
+uses a ``@JoinColumn`` configuration with ``onDelete="CASCADE"``, instead
+of using a dedicated ``DELETE`` query the database-level operation will be
+relied upon.
+
+.. note::
+
+    In case you rely on database-level ``ON DELETE RESTRICT`` constraints,
+    be aware that by making many-to-many associations bidirectional the
+    assumed protection may be lost.
+
+
+Performance of different deletion strategies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Deleting an object with all its associated objects can be achieved
 in multiple ways with very different performance impacts.
 
-
 1. If an association is marked as ``CASCADE=REMOVE`` Doctrine ORM
    will fetch this association. If its a Single association it will
    pass this entity to
@@ -741,6 +782,23 @@ and these associations are mapped as EAGER, they will automatically
 be loaded together with the entity being queried and is thus
 immediately available to your application.
 
+Eager Loading can also be configured at runtime through
+``AbstractQuery::setFetchMode`` in DQL or Native Queries.
+
+Eager loading for many-to-one and one-to-one associations is using either a
+LEFT JOIN or a second query for fetching the related entity eagerly.
+
+Eager loading for many-to-one associations uses a second query to load
+the collections for several entities at the same time.
+
+When many-to-many, one-to-one or one-to-many associations are eagerly loaded,
+then the global batch size configuration is used to avoid IN(?) queries with
+too many arguments. The default batch size is 100 and can be changed with
+``Configuration::setEagerFetchBatchSize()``.
+
+For eagerly loaded Many-To-Many associations one query has to be made for each
+collection.
+
 By Lazy Loading
 ~~~~~~~~~~~~~~~
 

docs/en/reference/xml-mapping.rst

@@ -16,9 +16,9 @@ setup for the latest code in trunk.
 
 .. code-block:: xml
 
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         ...
@@ -102,9 +102,9 @@ of several common elements:
 
     // Doctrine.Tests.ORM.Mapping.User.dcm.xml
     <?xml version="1.0" encoding="UTF-8"?>
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         <entity name="Doctrine\Tests\ORM\Mapping\User" table="cms_users">
@@ -769,9 +769,9 @@ entity relationship. You can define this in XML with the "association-key" attri
 
 .. code-block:: xml
 
-    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
           xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
          <entity name="Application\Model\ArticleAttribute">

docs/en/toc.rst

@@ -1,86 +0,0 @@
-Welcome to Doctrine 2 ORM's documentation!
-==========================================
-
-Tutorials
----------
-
-.. toctree::
-   :maxdepth: 1
-
-   tutorials/getting-started
-   tutorials/getting-started-database
-   tutorials/getting-started-models
-   tutorials/working-with-indexed-associations
-   tutorials/extra-lazy-associations
-   tutorials/composite-primary-keys
-   tutorials/ordered-associations
-   tutorials/override-field-association-mappings-in-subclasses
-   tutorials/pagination.rst
-   tutorials/embeddables.rst
-
-Reference Guide
----------------
-
-.. toctree::
-   :maxdepth: 1
-   :numbered:
-
-   reference/architecture
-   reference/configuration.rst
-   reference/faq
-   reference/basic-mapping
-   reference/association-mapping
-   reference/inheritance-mapping
-   reference/working-with-objects
-   reference/working-with-associations
-   reference/events
-   reference/unitofwork
-   reference/unitofwork-associations
-   reference/transactions-and-concurrency
-   reference/batch-processing
-   reference/dql-doctrine-query-language
-   reference/query-builder
-   reference/native-sql
-   reference/change-tracking-policies
-   reference/partial-objects
-   reference/annotations-reference
-   reference/attributes-reference
-   reference/xml-mapping
-   reference/yaml-mapping
-   reference/php-mapping
-   reference/caching
-   reference/improving-performance
-   reference/tools
-   reference/metadata-drivers
-   reference/best-practices
-   reference/limitations-and-known-issues
-   tutorials/pagination
-   reference/filters
-   reference/namingstrategy
-   reference/advanced-configuration
-   reference/second-level-cache
-   reference/security
-   
-
-Cookbook
---------
-
-.. toctree::
-   :maxdepth: 1
-
-   cookbook/aggregate-fields
-   cookbook/custom-mapping-types
-   cookbook/decorator-pattern
-   cookbook/dql-custom-walkers
-   cookbook/dql-user-defined-functions
-   cookbook/implementing-arrayaccess-for-domain-objects
-   cookbook/implementing-the-notify-changetracking-policy
-   cookbook/resolve-target-entity-listener
-   cookbook/sql-table-prefixes
-   cookbook/strategy-cookbook-introduction
-   cookbook/validation-of-entities
-   cookbook/working-with-datetime
-   cookbook/mysql-enums
-   cookbook/advanced-field-value-conversion-using-custom-mapping-types
-   cookbook/entities-in-session
-

docs/en/tutorials/composite-primary-keys.rst

@@ -85,9 +85,9 @@ and year of production as primary keys:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="VehicleCatalogue\Model\Car">
@@ -267,9 +267,9 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="Application\Model\ArticleAttribute">

docs/en/tutorials/extra-lazy-associations.rst

@@ -85,9 +85,9 @@ switch to extra lazy as shown in these examples:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\CMS\CmsGroup">

docs/en/tutorials/getting-started.rst

@@ -18,7 +18,7 @@ before. There are some prerequisites for the tutorial that have to be
 installed:
 
 - PHP (latest stable version)
-- Composer Package Manager (`Install Composer
+- Composer Package Manager (\ `Install Composer
   <https://getcomposer.org/doc/00-intro.md>`_)
 
 The code of this tutorial is `available on Github <https://github.com/doctrine/doctrine2-orm-tutorial>`_.
@@ -102,8 +102,7 @@ Install Doctrine using the Composer Dependency Management tool, by calling:
 This will install the packages Doctrine Common, Doctrine DBAL, Doctrine ORM,
 into the ``vendor`` directory.
 
-Add the following directories:
-::
+Add the following directories::
 
     doctrine2-tutorial
     |-- config
@@ -322,7 +321,7 @@ data in your storage, and later in your application when the data is loaded agai
 .. note::
 
     This method, although very common, is inappropriate for Domain Driven
-    Design (`DDD <https://en.wikipedia.org/wiki/Domain-driven_design>`_)
+    Design (\ `DDD <https://en.wikipedia.org/wiki/Domain-driven_design>`_)
     where methods should represent real business operations and not simple
     property change, And business invariants should be maintained both in the
     application state (entities in this case) and in the database, with no
@@ -558,10 +557,10 @@ methods, but you only need to choose one.
     .. code-block:: xml
 
         <!-- config/xml/Product.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Product" table="products">
                   <id name="id" type="integer">
@@ -736,7 +735,7 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
         #[ORM\Id]
         #[ORM\Column(type: 'integer')]
         #[ORM\GeneratedValue]
-        private int $id;
+        private int|null $id;
 
         #[ORM\Column(type: 'string')]
         private string $description;
@@ -1139,10 +1138,10 @@ the ``Product`` before:
     .. code-block:: xml
 
         <!-- config/xml/Bug.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Bug" table="bugs">
                 <id name="id" type="integer">
@@ -1200,21 +1199,21 @@ which translates the YYYY-mm-dd HH:mm:ss database format
 into a PHP DateTime instance and back.
 
 After the field definitions, the two qualified references to the
-user entity are defined. They are created by the ``many-to-one``
-tag. The class name of the related entity has to be specified with
-the ``target-entity`` attribute, which is enough information for
-the database mapper to access the foreign-table. Since
+user entity are defined. They are created by the ``ManyToOne``
+attribute. The class name of the related entity has to be specified with
+the ``targetEntity`` parameter, which is enough information for
+the database mapper to access the foreign table. Since
 ``reporter`` and ``engineer`` are on the owning side of a
-bi-directional relation, we also have to specify the ``inversed-by``
-attribute. They have to point to the field names on the inverse
-side of the relationship. We will see in the next example that the ``inversed-by``
-attribute has a counterpart ``mapped-by`` which makes that
+bi-directional relation, we also have to specify the ``inversedBy``
+parameter. They have to point to the field names on the inverse
+side of the relationship. We will see in the next example that the ``inversedBy``
+parameter has a counterpart ``mappedBy`` which makes that
 the inverse side.
 
 The last definition is for the ``Bug#products`` collection. It
 holds all products where the specific bug occurs. Again
-you have to define the ``target-entity`` and ``field`` attributes
-on the ``many-to-many`` tag.
+you have to define the ``targetEntity`` and ``field`` parameters
+on the ``ManyToMany`` attribute.
 
 Finally, we'll add metadata mappings for the ``User`` entity.
 
@@ -1294,10 +1293,10 @@ Finally, we'll add metadata mappings for the ``User`` entity.
     .. code-block:: xml
 
         <!-- config/xml/User.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="User" table="users">
                  <id name="id" type="integer">
@@ -1337,15 +1336,14 @@ Finally, we'll add metadata mappings for the ``User`` entity.
               targetEntity: Bug
               mappedBy: engineer
 
-Here are some new things to mention about the ``one-to-many`` tags.
+Here are some new things to mention about the ``OneToMany`` attribute.
 Remember that we discussed about the inverse and owning side. Now
 both reportedBugs and assignedBugs are inverse relations, which
 means the join details have already been defined on the owning
 side. Therefore we only have to specify the property on the Bug
 class that holds the owning sides.
 
-Update your database schema by running:
-::
+Update your database schema by running::
 
     $ php bin/doctrine orm:schema-tool:update --force
 
@@ -1819,9 +1817,9 @@ we have to adjust the metadata slightly.
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Bug" table="bugs" repository-class="BugRepository">

docs/en/tutorials/pagination.rst

@@ -15,7 +15,7 @@ has a very simple API and implements the SPL interfaces ``Countable`` and
                            ->setFirstResult(0)
                            ->setMaxResults(100);
 
-    $paginator = new Paginator($query, $fetchJoinCollection = true);
+    $paginator = new Paginator($query, fetchJoinCollection: true);
 
     $c = count($paginator);
     foreach ($paginator as $post) {
@@ -36,10 +36,25 @@ correct result:
 
 This behavior is only necessary if you actually fetch join a to-many
 collection. You can disable this behavior by setting the
-``$fetchJoinCollection`` flag to ``false``; in that case only 2 instead of the 3 queries
+``fetchJoinCollection`` argument to ``false``; in that case only 2 instead of the 3 queries
 described are executed. We hope to automate the detection for this in
 the future.
 
 .. note::
 
-    ``$fetchJoinCollection`` flag set to ``true`` might affect results if you use aggregations in your query.
+    ``fetchJoinCollection`` argument set to ``true`` might affect results if you use aggregations in your query.
+
+By using the ``Paginator::HINT_ENABLE_DISTINCT`` you can instruct doctrine that the query to be executed
+will not produce "duplicate" rows (only to-one relations are joined), thus the SQL limit will work as expected.
+In this way the `DISTINCT` keyword will be omitted and can bring important performance improvements.
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\Pagination\Paginator;
+
+    $dql = "SELECT u, p FROM User u JOIN u.mainPicture p";
+    $query = $entityManager->createQuery($dql)
+                           ->setHint(Paginator::HINT_ENABLE_DISTINCT, false)
+                           ->setFirstResult(0)
+                           ->setMaxResults(100);

docs/en/tutorials/working-with-indexed-associations.rst

@@ -161,9 +161,9 @@ The code and mappings for the Market entity looks like this:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\StockExchange\Market">
@@ -278,9 +278,9 @@ here are the code and mappings for it:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\StockExchange\Stock">

lib/Doctrine/ORM/AbstractQuery.php

@@ -10,7 +10,6 @@ use Doctrine\Common\Cache\Psr6\CacheAdapter;
 use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
 use Doctrine\DBAL\Result;
 use Doctrine\Deprecations\Deprecation;
@@ -20,6 +19,7 @@ use Doctrine\ORM\Cache\QueryCacheKey;
 use Doctrine\ORM\Cache\TimestampCacheKey;
 use Doctrine\ORM\Internal\Hydration\IterableResult;
 use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\Query\Parameter;
 use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Query\ResultSetMapping;
@@ -430,7 +430,7 @@ abstract class AbstractQuery
         }
 
         try {
-            $class = ClassUtils::getClass($value);
+            $class = DefaultProxyClassNameResolver::getClass($value);
             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
 
             if ($value === null) {
@@ -1010,7 +1010,7 @@ abstract class AbstractQuery
      *
      * Alias for getSingleResult(HYDRATE_SINGLE_SCALAR).
      *
-     * @return mixed The scalar result.
+     * @return bool|float|int|string|null The scalar result.
      *
      * @throws NoResultException        If the query returned no result.
      * @throws NonUniqueResultException If the query result is not unique.

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -4,12 +4,12 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Cache\Persister\CachedPersister;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\ORMInvalidArgumentException;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\UnitOfWork;
 
 use function is_array;
@@ -293,7 +293,7 @@ class DefaultCache implements Cache
     private function toIdentifierArray(ClassMetadata $metadata, $identifier): array
     {
         if (is_object($identifier)) {
-            $class = ClassUtils::getClass($identifier);
+            $class = DefaultProxyClassNameResolver::getClass($identifier);
             if ($this->em->getMetadataFactory()->hasMetadataFor($class)) {
                 $identifier = $this->uow->getSingleIdentifierValue($identifier);
 

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -4,9 +4,9 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Mapping\ClassMetadata;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
 use Doctrine\ORM\Utility\IdentifierFlattener;
@@ -112,7 +112,7 @@ class DefaultEntityHydrator implements EntityHydrator
             }
 
             if (! isset($assoc['id'])) {
-                $targetClass = ClassUtils::getClass($data[$name]);
+                $targetClass = DefaultProxyClassNameResolver::getClass($data[$name]);
                 $targetId    = $this->uow->getEntityIdentifier($data[$name]);
                 $data[$name] = new AssociationCacheEntry($targetClass, $targetId);
 

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -16,7 +16,6 @@ use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\UnitOfWork;
-use Doctrine\Persistence\Proxy;
 
 use function array_map;
 use function array_shift;
@@ -345,7 +344,7 @@ class DefaultQueryCache implements QueryCache
             $assocIdentifier = $this->uow->getEntityIdentifier($assocValue);
             $entityKey       = new EntityCacheKey($assocMetadata->rootEntityName, $assocIdentifier);
 
-            if (! $assocValue instanceof Proxy && ($key->cacheMode & Cache::MODE_REFRESH) || ! $assocRegion->contains($entityKey)) {
+            if (! $this->uow->isUninitializedObject($assocValue) && ($key->cacheMode & Cache::MODE_REFRESH) || ! $assocRegion->contains($entityKey)) {
                 // Entity put fail
                 if (! $assocPersister->storeEntityCache($assocValue, $entityKey)) {
                     return null;

lib/Doctrine/ORM/Cache/Persister/Collection/AbstractCollectionPersister.php

@@ -6,7 +6,6 @@ namespace Doctrine\ORM\Cache\Persister\Collection;
 
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\Criteria;
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CollectionCacheKey;
 use Doctrine\ORM\Cache\CollectionHydrator;
@@ -19,6 +18,7 @@ use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Persisters\Collection\CollectionPersister;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\UnitOfWork;
 
 use function array_values;
@@ -148,7 +148,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
             }
 
             $class     = $this->targetEntity;
-            $className = ClassUtils::getClass($elements[$index]);
+            $className = DefaultProxyClassNameResolver::getClass($elements[$index]);
 
             if ($className !== $this->targetEntity->name) {
                 $class = $this->metadataFactory->getMetadataFor($className);

lib/Doctrine/ORM/Cache/Persister/Collection/ReadOnlyCachedCollectionPersister.php

@@ -4,9 +4,9 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Persister\Collection;
 
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\ORM\Cache\Exception\CannotUpdateReadOnlyCollection;
 use Doctrine\ORM\PersistentCollection;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 
 class ReadOnlyCachedCollectionPersister extends NonStrictReadWriteCachedCollectionPersister
 {
@@ -17,7 +17,7 @@ class ReadOnlyCachedCollectionPersister extends NonStrictReadWriteCachedCollecti
     {
         if ($collection->isDirty() && $collection->getSnapshot()) {
             throw CannotUpdateReadOnlyCollection::fromEntityAndField(
-                ClassUtils::getClass($collection->getOwner()),
+                DefaultProxyClassNameResolver::getClass($collection->getOwner()),
                 $this->association['fieldName']
             );
         }

lib/Doctrine/ORM/Cache/Persister/Entity/AbstractEntityPersister.php

@@ -5,7 +5,6 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache\Persister\Entity;
 
 use Doctrine\Common\Collections\Criteria;
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Cache\CollectionCacheKey;
 use Doctrine\ORM\Cache\EntityCacheKey;
@@ -21,8 +20,10 @@ use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Persisters\Entity\EntityPersister;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\UnitOfWork;
 
+use function array_merge;
 use function assert;
 use function serialize;
 use function sha1;
@@ -189,7 +190,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     public function storeEntityCache($entity, EntityCacheKey $key)
     {
         $class     = $this->class;
-        $className = ClassUtils::getClass($entity);
+        $className = DefaultProxyClassNameResolver::getClass($entity);
 
         if ($className !== $this->class->name) {
             $class = $this->metadataFactory->getMetadataFor($className);
@@ -314,7 +315,13 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
      */
     public function executeInserts()
     {
-        $this->queuedCache['insert'] = $this->persister->getInserts();
+        // The commit order/foreign key relationships may make it necessary that multiple calls to executeInsert()
+        // are performed, so collect all the new entities.
+        $newInserts = $this->persister->getInserts();
+
+        if ($newInserts) {
+            $this->queuedCache['insert'] = array_merge($this->queuedCache['insert'] ?? [], $newInserts);
+        }
 
         return $this->persister->executeInserts();
     }
@@ -431,7 +438,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
         }
 
         $class     = $this->class;
-        $className = ClassUtils::getClass($entity);
+        $className = DefaultProxyClassNameResolver::getClass($entity);
 
         if ($className !== $this->class->name) {
             $class = $this->metadataFactory->getMetadataFor($className);

lib/Doctrine/ORM/Cache/Persister/Entity/ReadOnlyCachedEntityPersister.php

@@ -4,8 +4,8 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Persister\Entity;
 
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\ORM\Cache\Exception\CannotUpdateReadOnlyEntity;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 
 /**
  * Specific read-only region entity persister
@@ -17,6 +17,6 @@ class ReadOnlyCachedEntityPersister extends NonStrictReadWriteCachedEntityPersis
      */
     public function update($entity)
     {
-        throw CannotUpdateReadOnlyEntity::fromEntity(ClassUtils::getClass($entity));
+        throw CannotUpdateReadOnlyEntity::fromEntity(DefaultProxyClassNameResolver::getClass($entity));
     }
 }

lib/Doctrine/ORM/Configuration.php

@@ -13,6 +13,7 @@ use Doctrine\Common\Cache\Cache as CacheDriver;
 use Doctrine\Common\Cache\Psr6\CacheAdapter;
 use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\Persistence\PersistentObject;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Cache\Exception\CacheException;
@@ -27,6 +28,7 @@ use Doctrine\ORM\Exception\NotSupported;
 use Doctrine\ORM\Exception\ProxyClassesAlwaysRegenerating;
 use Doctrine\ORM\Exception\UnknownEntityNamespace;
 use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
+use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\Mapping\DefaultEntityListenerResolver;
 use Doctrine\ORM\Mapping\DefaultNamingStrategy;
@@ -62,14 +64,27 @@ use function trim;
  * It combines all configuration options from DBAL & ORM.
  *
  * Internal note: When adding a new configuration option just write a getter/setter pair.
- *
- * @psalm-import-type AutogenerateMode from ProxyFactory
  */
 class Configuration extends \Doctrine\DBAL\Configuration
 {
     /** @var mixed[] */
     protected $_attributes = [];
 
+    /** @psalm-var array<class-string<AbstractPlatform>, ClassMetadata::GENERATOR_TYPE_*> */
+    private $identityGenerationPreferences = [];
+
+    /** @psalm-param array<class-string<AbstractPlatform>, ClassMetadata::GENERATOR_TYPE_*> $value */
+    public function setIdentityGenerationPreferences(array $value): void
+    {
+        $this->identityGenerationPreferences = $value;
+    }
+
+    /** @psalm-return array<class-string<AbstractPlatform>, ClassMetadata::GENERATOR_TYPE_*> $value */
+    public function getIdentityGenerationPreferences(): array
+    {
+        return $this->identityGenerationPreferences;
+    }
+
     /**
      * Sets the directory where Doctrine generates any necessary proxy class files.
      *
@@ -95,8 +110,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the strategy for automatically generating proxy classes.
      *
-     * @return int Possible values are constants of Doctrine\ORM\Proxy\ProxyFactory.
-     * @psalm-return AutogenerateMode
+     * @return ProxyFactory::AUTOGENERATE_*
      */
     public function getAutoGenerateProxyClasses()
     {
@@ -106,9 +120,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Sets the strategy for automatically generating proxy classes.
      *
-     * @param bool|int $autoGenerate Possible values are constants of Doctrine\ORM\Proxy\ProxyFactory.
-     * @psalm-param bool|AutogenerateMode $autoGenerate
-     * True is converted to AUTOGENERATE_ALWAYS, false to AUTOGENERATE_NEVER.
+     * @param bool|ProxyFactory::AUTOGENERATE_* $autoGenerate True is converted to AUTOGENERATE_ALWAYS, false to AUTOGENERATE_NEVER.
      *
      * @return void
      */
@@ -164,7 +176,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @return AnnotationDriver
      */
-    public function newDefaultAnnotationDriver($paths = [], $useSimpleAnnotationReader = true)
+    public function newDefaultAnnotationDriver($paths = [], $useSimpleAnnotationReader = true, bool $reportFieldsWhereDeclared = false)
     {
         Deprecation::trigger(
             'doctrine/orm',
@@ -203,15 +215,16 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
         return new AnnotationDriver(
             $reader,
-            (array) $paths
+            (array) $paths,
+            $reportFieldsWhereDeclared
         );
     }
 
     /**
-     * @deprecated No replacement planned.
-     *
      * Adds a namespace under a certain alias.
      *
+     * @deprecated No replacement planned.
+     *
      * @param string $alias
      * @param string $namespace
      *
@@ -1121,4 +1134,24 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
         $this->_attributes['isLazyGhostObjectEnabled'] = $flag;
     }
+
+    public function setRejectIdCollisionInIdentityMap(bool $flag): void
+    {
+        $this->_attributes['rejectIdCollisionInIdentityMap'] = $flag;
+    }
+
+    public function isRejectIdCollisionInIdentityMapEnabled(): bool
+    {
+        return $this->_attributes['rejectIdCollisionInIdentityMap'] ?? false;
+    }
+
+    public function setEagerFetchBatchSize(int $batchSize = 100): void
+    {
+        $this->_attributes['fetchModeSubselectBatchSize'] = $batchSize;
+    }
+
+    public function getEagerFetchBatchSize(): int
+    {
+        return $this->_attributes['fetchModeSubselectBatchSize'] ?? 100;
+    }
 }

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Decorator;
 
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\EntityRepository;
 use Doctrine\ORM\Query\ResultSetMapping;
@@ -170,6 +171,13 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
      */
     public function getPartialReference($entityName, $identifier)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/10987',
+            'Method %s is deprecated and will be removed in 3.0.',
+            __METHOD__
+        );
+
         return $this->wrapped->getPartialReference($entityName, $identifier);
     }
 

lib/Doctrine/ORM/EntityManager.php

@@ -9,7 +9,6 @@ use BadMethodCallException;
 use Doctrine\Common\Cache\Psr6\CacheAdapter;
 use Doctrine\Common\EventManager;
 use Doctrine\Common\Persistence\PersistentObject;
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\LockMode;
@@ -24,6 +23,7 @@ use Doctrine\ORM\Exception\ORMException;
 use Doctrine\ORM\Exception\UnrecognizedIdentifierFields;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Query\Expr;
 use Doctrine\ORM\Query\FilterCollection;
@@ -444,7 +444,7 @@ class EntityManager implements EntityManagerInterface
 
         foreach ($id as $i => $value) {
             if (is_object($value)) {
-                $className = ClassUtils::getClass($value);
+                $className = DefaultProxyClassNameResolver::getClass($value);
                 if ($this->metadataFactory->hasMetadataFor($className)) {
                     $id[$i] = $this->unitOfWork->getSingleIdentifierValue($value);
 
@@ -571,6 +571,12 @@ class EntityManager implements EntityManagerInterface
      */
     public function getPartialReference($entityName, $identifier)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/10987',
+            'Method %s is deprecated and will be removed in 3.0.',
+            __METHOD__
+        );
         $class = $this->metadataFactory->getMetadataFor(ltrim($entityName, '\\'));
 
         $entity = $this->unitOfWork->tryGetById($identifier, $class->rootEntityName);
@@ -953,6 +959,14 @@ class EntityManager implements EntityManagerInterface
         $this->unitOfWork->initializeObject($obj);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function isUninitializedObject($obj): bool
+    {
+        return $this->unitOfWork->isUninitializedObject($obj);
+    }
+
     /**
      * Factory method to create EntityManager instances.
      *
@@ -973,7 +987,7 @@ class EntityManager implements EntityManagerInterface
         Deprecation::trigger(
             'doctrine/orm',
             'https://github.com/doctrine/orm/pull/9961',
-            '%s() is deprecated. To boostrap a DBAL connection, call %s::getConnection() instead. Use the constructor to create an instance of %s.',
+            '%s() is deprecated. To bootstrap a DBAL connection, call %s::getConnection() instead. Use the constructor to create an instance of %s.',
             __METHOD__,
             DriverManager::class,
             self::class

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -200,6 +200,8 @@ interface EntityManagerInterface extends ObjectManager
      * never be visible to the application (especially not event listeners) as it will
      * never be loaded in the first place.
      *
+     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
+     *
      * @param string $entityName The name of the entity type.
      * @param mixed  $identifier The entity identifier.
      * @psalm-param class-string<T> $entityName

lib/Doctrine/ORM/Exception/EntityIdentityCollisionException.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Exception;
+
+use function get_class;
+use function sprintf;
+
+final class EntityIdentityCollisionException extends ORMException
+{
+    /**
+     * @param object $existingEntity
+     * @param object $newEntity
+     */
+    public static function create($existingEntity, $newEntity, string $idHash): self
+    {
+        return new self(
+            sprintf(
+                <<<'EXCEPTION'
+While adding an entity of class %s with an ID hash of "%s" to the identity map,
+another object of class %s was already present for the same ID. This exception
+is a safeguard against an internal inconsistency - IDs should uniquely map to
+entity object instances. This problem may occur if:
+
+- you use application-provided IDs and reuse ID values;
+- database-provided IDs are reassigned after truncating the database without
+clearing the EntityManager;
+- you might have been using EntityManager#getReference() to create a reference
+for a nonexistent ID that was subsequently (by the RDBMS) assigned to another
+entity.
+
+Otherwise, it might be an ORM-internal inconsistency, please report it.
+EXCEPTION
+                ,
+                get_class($newEntity),
+                $idHash,
+                get_class($existingEntity)
+            )
+        );
+    }
+}

lib/Doctrine/ORM/Internal/CommitOrder/Edge.php

@@ -1,34 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Internal\CommitOrder;
-
-/** @internal */
-final class Edge
-{
-    /**
-     * @var string
-     * @readonly
-     */
-    public $from;
-
-    /**
-     * @var string
-     * @readonly
-     */
-    public $to;
-
-    /**
-     * @var int
-     * @readonly
-     */
-    public $weight;
-
-    public function __construct(string $from, string $to, int $weight)
-    {
-        $this->from   = $from;
-        $this->to     = $to;
-        $this->weight = $weight;
-    }
-}

lib/Doctrine/ORM/Internal/CommitOrder/Vertex.php

@@ -1,38 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Internal\CommitOrder;
-
-use Doctrine\ORM\Mapping\ClassMetadata;
-
-/** @internal */
-final class Vertex
-{
-    /**
-     * @var string
-     * @readonly
-     */
-    public $hash;
-
-    /**
-     * @var int
-     * @psalm-var VertexState::*
-     */
-    public $state = VertexState::NOT_VISITED;
-
-    /**
-     * @var ClassMetadata
-     * @readonly
-     */
-    public $value;
-
-    /** @var array<string, Edge> */
-    public $dependencyList = [];
-
-    public function __construct(string $hash, ClassMetadata $value)
-    {
-        $this->hash  = $hash;
-        $this->value = $value;
-    }
-}

lib/Doctrine/ORM/Internal/CommitOrder/VertexState.php

@@ -1,17 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Internal\CommitOrder;
-
-/** @internal */
-final class VertexState
-{
-    public const NOT_VISITED = 0;
-    public const IN_PROGRESS = 1;
-    public const VISITED     = 2;
-
-    private function __construct()
-    {
-    }
-}

lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

@@ -1,164 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Internal;
-
-use Doctrine\ORM\Internal\CommitOrder\Edge;
-use Doctrine\ORM\Internal\CommitOrder\Vertex;
-use Doctrine\ORM\Internal\CommitOrder\VertexState;
-use Doctrine\ORM\Mapping\ClassMetadata;
-
-use function array_reverse;
-
-/**
- * CommitOrderCalculator implements topological sorting, which is an ordering
- * algorithm for directed graphs (DG) and/or directed acyclic graphs (DAG) by
- * using a depth-first searching (DFS) to traverse the graph built in memory.
- * This algorithm have a linear running time based on nodes (V) and dependency
- * between the nodes (E), resulting in a computational complexity of O(V + E).
- */
-class CommitOrderCalculator
-{
-    /** @deprecated */
-    public const NOT_VISITED = VertexState::NOT_VISITED;
-
-    /** @deprecated */
-    public const IN_PROGRESS = VertexState::IN_PROGRESS;
-
-    /** @deprecated */
-    public const VISITED = VertexState::VISITED;
-
-    /**
-     * Matrix of nodes (aka. vertex).
-     *
-     * Keys are provided hashes and values are the node definition objects.
-     *
-     * @var array<string, Vertex>
-     */
-    private $nodeList = [];
-
-    /**
-     * Volatile variable holding calculated nodes during sorting process.
-     *
-     * @psalm-var list<ClassMetadata>
-     */
-    private $sortedNodeList = [];
-
-    /**
-     * Checks for node (vertex) existence in graph.
-     *
-     * @param string $hash
-     *
-     * @return bool
-     */
-    public function hasNode($hash)
-    {
-        return isset($this->nodeList[$hash]);
-    }
-
-    /**
-     * Adds a new node (vertex) to the graph, assigning its hash and value.
-     *
-     * @param string        $hash
-     * @param ClassMetadata $node
-     *
-     * @return void
-     */
-    public function addNode($hash, $node)
-    {
-        $this->nodeList[$hash] = new Vertex($hash, $node);
-    }
-
-    /**
-     * Adds a new dependency (edge) to the graph using their hashes.
-     *
-     * @param string $fromHash
-     * @param string $toHash
-     * @param int    $weight
-     *
-     * @return void
-     */
-    public function addDependency($fromHash, $toHash, $weight)
-    {
-        $this->nodeList[$fromHash]->dependencyList[$toHash]
-            = new Edge($fromHash, $toHash, $weight);
-    }
-
-    /**
-     * Return a valid order list of all current nodes.
-     * The desired topological sorting is the reverse post order of these searches.
-     *
-     * {@internal Highly performance-sensitive method.}
-     *
-     * @psalm-return list<ClassMetadata>
-     */
-    public function sort()
-    {
-        foreach ($this->nodeList as $vertex) {
-            if ($vertex->state !== VertexState::NOT_VISITED) {
-                continue;
-            }
-
-            $this->visit($vertex);
-        }
-
-        $sortedList = $this->sortedNodeList;
-
-        $this->nodeList       = [];
-        $this->sortedNodeList = [];
-
-        return array_reverse($sortedList);
-    }
-
-    /**
-     * Visit a given node definition for reordering.
-     *
-     * {@internal Highly performance-sensitive method.}
-     */
-    private function visit(Vertex $vertex): void
-    {
-        $vertex->state = VertexState::IN_PROGRESS;
-
-        foreach ($vertex->dependencyList as $edge) {
-            $adjacentVertex = $this->nodeList[$edge->to];
-
-            switch ($adjacentVertex->state) {
-                case VertexState::VISITED:
-                    // Do nothing, since node was already visited
-                    break;
-
-                case VertexState::IN_PROGRESS:
-                    if (
-                        isset($adjacentVertex->dependencyList[$vertex->hash]) &&
-                        $adjacentVertex->dependencyList[$vertex->hash]->weight < $edge->weight
-                    ) {
-                        // If we have some non-visited dependencies in the in-progress dependency, we
-                        // need to visit them before adding the node.
-                        foreach ($adjacentVertex->dependencyList as $adjacentEdge) {
-                            $adjacentEdgeVertex = $this->nodeList[$adjacentEdge->to];
-
-                            if ($adjacentEdgeVertex->state === VertexState::NOT_VISITED) {
-                                $this->visit($adjacentEdgeVertex);
-                            }
-                        }
-
-                        $adjacentVertex->state = VertexState::VISITED;
-
-                        $this->sortedNodeList[] = $adjacentVertex->value;
-                    }
-
-                    break;
-
-                case VertexState::NOT_VISITED:
-                    $this->visit($adjacentVertex);
-            }
-        }
-
-        if ($vertex->state !== VertexState::VISITED) {
-            $vertex->state = VertexState::VISITED;
-
-            $this->sortedNodeList[] = $vertex->value;
-        }
-    }
-}

lib/Doctrine/ORM/Internal/Hydration/ObjectHydrator.php

@@ -10,7 +10,6 @@ use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
-use Doctrine\Persistence\Proxy;
 
 use function array_fill_keys;
 use function array_keys;
@@ -313,7 +312,6 @@ class ObjectHydrator extends AbstractHydrator
      * that belongs to a particular component/class. Afterwards, all these chunks
      * are processed, one after the other. For each chunk of class data only one of the
      * following code paths is executed:
-     *
      * Path A: The data chunk belongs to a joined/associated object and the association
      *         is collection-valued.
      * Path B: The data chunk belongs to a joined/associated object and the association
@@ -440,7 +438,7 @@ class ObjectHydrator extends AbstractHydrator
                     // PATH B: Single-valued association
                     $reflFieldValue = $reflField->getValue($parentObject);
 
-                    if (! $reflFieldValue || isset($this->_hints[Query::HINT_REFRESH]) || ($reflFieldValue instanceof Proxy && ! $reflFieldValue->__isInitialized())) {
+                    if (! $reflFieldValue || isset($this->_hints[Query::HINT_REFRESH]) || $this->_uow->isUninitializedObject($reflFieldValue)) {
                         // we only need to take action if this value is null,
                         // we refresh the entity or its an uninitialized proxy.
                         if (isset($nonemptyComponents[$dqlAlias])) {
@@ -458,9 +456,6 @@ class ObjectHydrator extends AbstractHydrator
                                         $targetClass->reflFields[$inverseAssoc['fieldName']]->setValue($element, $parentObject);
                                         $this->_uow->setOriginalEntityProperty(spl_object_id($element), $inverseAssoc['fieldName'], $parentObject);
                                     }
-                                } elseif ($parentClass === $targetClass && $relation['mappedBy']) {
-                                    // Special case: bi-directional self-referencing one-one on the same class
-                                    $targetClass->reflFields[$relationField]->setValue($element, $parentObject);
                                 }
                             } else {
                                 // For sure bidirectional, as there is no inverse side in unidirectional mappings

lib/Doctrine/ORM/Internal/SQLResultCasing.php

@@ -9,7 +9,9 @@ use Doctrine\DBAL\Platforms\DB2Platform;
 use Doctrine\DBAL\Platforms\OraclePlatform;
 use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
 
+use function get_class;
 use function method_exists;
+use function strpos;
 use function strtolower;
 use function strtoupper;
 
@@ -26,7 +28,7 @@ trait SQLResultCasing
             return strtolower($column);
         }
 
-        if (method_exists(AbstractPlatform::class, 'getSQLResultCasing')) {
+        if (strpos(get_class($platform), 'Doctrine\\DBAL\\Platforms\\') !== 0 && method_exists(AbstractPlatform::class, 'getSQLResultCasing')) {
             return $platform->getSQLResultCasing($column);
         }
 

lib/Doctrine/ORM/Internal/TopologicalSort.php

@@ -0,0 +1,165 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Internal;
+
+use Doctrine\ORM\Internal\TopologicalSort\CycleDetectedException;
+
+use function array_keys;
+use function array_reverse;
+use function array_unshift;
+use function spl_object_id;
+
+/**
+ * TopologicalSort implements topological sorting, which is an ordering
+ * algorithm for directed graphs (DG) using a depth-first searching (DFS)
+ * to traverse the graph built in memory.
+ * This algorithm has a linear running time based on nodes (V) and edges
+ * between the nodes (E), resulting in a computational complexity of O(V + E).
+ *
+ * @internal
+ */
+final class TopologicalSort
+{
+    private const NOT_VISITED = 1;
+    private const IN_PROGRESS = 2;
+    private const VISITED     = 3;
+
+    /**
+     * Array of all nodes, indexed by object ids.
+     *
+     * @var array<int, object>
+     */
+    private $nodes = [];
+
+    /**
+     * DFS state for the different nodes, indexed by node object id and using one of
+     * this class' constants as value.
+     *
+     * @var array<int, self::*>
+     */
+    private $states = [];
+
+    /**
+     * Edges between the nodes. The first-level key is the object id of the outgoing
+     * node; the second array maps the destination node by object id as key. The final
+     * boolean value indicates whether the edge is optional or not.
+     *
+     * @var array<int, array<int, bool>>
+     */
+    private $edges = [];
+
+    /**
+     * Builds up the result during the DFS.
+     *
+     * @var list<object>
+     */
+    private $sortResult = [];
+
+    /** @param object $node */
+    public function addNode($node): void
+    {
+        $id                = spl_object_id($node);
+        $this->nodes[$id]  = $node;
+        $this->states[$id] = self::NOT_VISITED;
+        $this->edges[$id]  = [];
+    }
+
+    /** @param object $node */
+    public function hasNode($node): bool
+    {
+        return isset($this->nodes[spl_object_id($node)]);
+    }
+
+    /**
+     * Adds a new edge between two nodes to the graph
+     *
+     * @param object $from
+     * @param object $to
+     * @param bool   $optional This indicates whether the edge may be ignored during the topological sort if it is necessary to break cycles.
+     */
+    public function addEdge($from, $to, bool $optional): void
+    {
+        $fromId = spl_object_id($from);
+        $toId   = spl_object_id($to);
+
+        if (isset($this->edges[$fromId][$toId]) && $this->edges[$fromId][$toId] === false) {
+            return; // we already know about this dependency, and it is not optional
+        }
+
+        $this->edges[$fromId][$toId] = $optional;
+    }
+
+    /**
+     * Returns a topological sort of all nodes. When we have an edge A->B between two nodes
+     * A and B, then A will be listed before B in the result.
+     *
+     * @return list<object>
+     */
+    public function sort(): array
+    {
+        /*
+         * When possible, keep objects in the result in the same order in which they were added as nodes.
+         * Since nodes are unshifted into $this->>sortResult (see the visit() method), that means we
+         * need to work them in array_reverse order here.
+         */
+        foreach (array_reverse(array_keys($this->nodes)) as $oid) {
+            if ($this->states[$oid] === self::NOT_VISITED) {
+                $this->visit($oid);
+            }
+        }
+
+        return $this->sortResult;
+    }
+
+    private function visit(int $oid): void
+    {
+        if ($this->states[$oid] === self::IN_PROGRESS) {
+            // This node is already on the current DFS stack. We've found a cycle!
+            throw new CycleDetectedException($this->nodes[$oid]);
+        }
+
+        if ($this->states[$oid] === self::VISITED) {
+            // We've reached a node that we've already seen, including all
+            // other nodes that are reachable from here. We're done here, return.
+            return;
+        }
+
+        $this->states[$oid] = self::IN_PROGRESS;
+
+        // Continue the DFS downwards the edge list
+        foreach ($this->edges[$oid] as $adjacentId => $optional) {
+            try {
+                $this->visit($adjacentId);
+            } catch (CycleDetectedException $exception) {
+                if ($exception->isCycleCollected()) {
+                    // There is a complete cycle downstream of the current node. We cannot
+                    // do anything about that anymore.
+                    throw $exception;
+                }
+
+                if ($optional) {
+                    // The current edge is part of a cycle, but it is optional and the closest
+                    // such edge while backtracking. Break the cycle here by skipping the edge
+                    // and continuing with the next one.
+                    continue;
+                }
+
+                // We have found a cycle and cannot break it at $edge. Best we can do
+                // is to retreat from the current vertex, hoping that somewhere up the
+                // stack this can be salvaged.
+                $this->states[$oid] = self::NOT_VISITED;
+                $exception->addToCycle($this->nodes[$oid]);
+
+                throw $exception;
+            }
+        }
+
+        // We have traversed all edges and visited all other nodes reachable from here.
+        // So we're done with this vertex as well.
+
+        $this->states[$oid] = self::VISITED;
+        array_unshift($this->sortResult, $this->nodes[$oid]);
+    }
+}

lib/Doctrine/ORM/Internal/TopologicalSort/CycleDetectedException.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Internal\TopologicalSort;
+
+use RuntimeException;
+
+use function array_unshift;
+
+class CycleDetectedException extends RuntimeException
+{
+    /** @var list<object> */
+    private $cycle;
+
+    /** @var object */
+    private $startNode;
+
+    /**
+     * Do we have the complete cycle collected?
+     *
+     * @var bool
+     */
+    private $cycleCollected = false;
+
+    /** @param object $startNode */
+    public function __construct($startNode)
+    {
+        parent::__construct('A cycle has been detected, so a topological sort is not possible. The getCycle() method provides the list of nodes that form the cycle.');
+
+        $this->startNode = $startNode;
+        $this->cycle     = [$startNode];
+    }
+
+    /** @return list<object> */
+    public function getCycle(): array
+    {
+        return $this->cycle;
+    }
+
+    /** @param object $node */
+    public function addToCycle($node): void
+    {
+        array_unshift($this->cycle, $node);
+
+        if ($node === $this->startNode) {
+            $this->cycleCollected = true;
+        }
+    }
+
+    public function isCycleCollected(): bool
+    {
+        return $this->cycleCollected;
+    }
+}

lib/Doctrine/ORM/Mapping/ClassMetadataFactory.php

@@ -7,6 +7,9 @@ namespace Doctrine\ORM\Mapping;
 use Doctrine\Common\EventManager;
 use Doctrine\DBAL\Platforms;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Platforms\MySQLPlatform;
+use Doctrine\DBAL\Platforms\SqlitePlatform;
+use Doctrine\DBAL\Platforms\SQLServerPlatform;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Event\LoadClassMetadataEventArgs;
@@ -21,6 +24,7 @@ use Doctrine\ORM\Id\UuidGenerator;
 use Doctrine\ORM\Mapping\Exception\CannotGenerateIds;
 use Doctrine\ORM\Mapping\Exception\InvalidCustomGenerator;
 use Doctrine\ORM\Mapping\Exception\UnknownGeneratorType;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\Persistence\Mapping\AbstractClassMetadataFactory;
 use Doctrine\Persistence\Mapping\ClassMetadata as ClassMetadataInterface;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
@@ -35,6 +39,7 @@ use function end;
 use function explode;
 use function get_class;
 use function in_array;
+use function is_a;
 use function is_subclass_of;
 use function str_contains;
 use function strlen;
@@ -68,9 +73,17 @@ class ClassMetadataFactory extends AbstractClassMetadataFactory
     /** @var mixed[] */
     private $embeddablesActiveNesting = [];
 
+    private const NON_IDENTITY_DEFAULT_STRATEGY = [
+        'Doctrine\DBAL\Platforms\PostgreSqlPlatform' => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+        Platforms\OraclePlatform::class => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+        Platforms\PostgreSQLPlatform::class => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+    ];
+
     /** @return void */
     public function setEntityManager(EntityManagerInterface $em)
     {
+        parent::setProxyClassNameResolver(new DefaultProxyClassNameResolver());
+
         $this->em = $em;
     }
 
@@ -110,7 +123,7 @@ class ClassMetadataFactory extends AbstractClassMetadataFactory
         if ($parent) {
             $class->setInheritanceType($parent->inheritanceType);
             $class->setDiscriminatorColumn($parent->discriminatorColumn);
-            $class->setIdGeneratorType($parent->generatorType);
+            $this->inheritIdGeneratorMapping($class, $parent);
             $this->addInheritedFields($class, $parent);
             $this->addInheritedRelations($class, $parent);
             $this->addInheritedEmbeddedClasses($class, $parent);
@@ -138,12 +151,8 @@ class ClassMetadataFactory extends AbstractClassMetadataFactory
             throw MappingException::reflectionFailure($class->getName(), $e);
         }
 
-        // If this class has a parent the id generator strategy is inherited.
-        // However this is only true if the hierarchy of parents contains the root entity,
-        // if it consists of mapped superclasses these don't necessarily include the id field.
-        if ($parent && $rootEntityFound) {
-            $this->inheritIdGeneratorMapping($class, $parent);
-        } else {
+        // Complete id generator mapping when the generator was declared/added in this class
+        if ($class->identifier && (! $parent || ! $parent->identifier)) {
             $this->completeIdGeneratorMapping($class);
         }
 
@@ -621,15 +630,17 @@ class ClassMetadataFactory extends AbstractClassMetadataFactory
             case ClassMetadata::GENERATOR_TYPE_IDENTITY:
                 $sequenceName = null;
                 $fieldName    = $class->identifier ? $class->getSingleIdentifierFieldName() : null;
+                $platform     = $this->getTargetPlatform();
 
                 // Platforms that do not have native IDENTITY support need a sequence to emulate this behaviour.
-                if ($this->getTargetPlatform()->usesSequenceEmulatedIdentityColumns()) {
+                /** @psalm-suppress UndefinedClass, InvalidClass */
+                if (! $platform instanceof MySQLPlatform && ! $platform instanceof SqlitePlatform && ! $platform instanceof SQLServerPlatform && $platform->usesSequenceEmulatedIdentityColumns()) {
                     Deprecation::trigger(
                         'doctrine/orm',
                         'https://github.com/doctrine/orm/issues/8850',
                         <<<'DEPRECATION'
 Context: Loading metadata for class %s
-Problem: Using the IDENTITY generator strategy with platform "%s" is deprecated and will not be possible in Doctrine ORM 3.0.
+Problem: Using identity columns emulated with a sequence is deprecated and will not be possible in Doctrine ORM 3.0.
 Solution: Use the SEQUENCE generator strategy instead.
 DEPRECATION
                             ,
@@ -724,14 +735,40 @@ DEPRECATION
         }
     }
 
-    /** @psalm-return ClassMetadata::GENERATOR_TYPE_SEQUENCE|ClassMetadata::GENERATOR_TYPE_IDENTITY */
+    /** @psalm-return ClassMetadata::GENERATOR_TYPE_* */
     private function determineIdGeneratorStrategy(AbstractPlatform $platform): int
     {
-        if (
-            $platform instanceof Platforms\OraclePlatform
-            || $platform instanceof Platforms\PostgreSQLPlatform
-        ) {
-            return ClassMetadata::GENERATOR_TYPE_SEQUENCE;
+        assert($this->em !== null);
+        foreach ($this->em->getConfiguration()->getIdentityGenerationPreferences() as $platformFamily => $strategy) {
+            if (is_a($platform, $platformFamily)) {
+                return $strategy;
+            }
+        }
+
+        foreach (self::NON_IDENTITY_DEFAULT_STRATEGY as $platformFamily => $strategy) {
+            if (is_a($platform, $platformFamily)) {
+                if ($platform instanceof Platforms\PostgreSQLPlatform || is_a($platform, 'Doctrine\DBAL\Platforms\PostgreSqlPlatform')) {
+                    Deprecation::trigger(
+                        'doctrine/orm',
+                        'https://github.com/doctrine/orm/issues/8893',
+                        <<<'DEPRECATION'
+Relying on non-optimal defaults for ID generation is deprecated, and IDENTITY
+results in SERIAL, which is not recommended.
+Instead, configure identifier generation strategies explicitly through
+configuration.
+We currently recommend "SEQUENCE" for "%s", so you should use
+$configuration->setIdentityGenerationPreferences([
+    "%s" => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+]);
+DEPRECATION
+                        ,
+                        $platformFamily,
+                        $platformFamily
+                    );
+                }
+
+                return $strategy;
+            }
         }
 
         if ($platform->supportsIdentityColumns()) {

lib/Doctrine/ORM/Mapping/ClassMetadataInfo.php

@@ -1176,7 +1176,7 @@ class ClassMetadataInfo implements ClassMetadata
         $this->namespace = $reflService->getClassNamespace($this->name);
 
         if ($this->reflClass) {
-            $this->name = $this->rootEntityName = $this->reflClass->getName();
+            $this->name = $this->rootEntityName = $this->reflClass->name;
         }
 
         $this->table['name'] = $this->namingStrategy->classToTableName($this->name);
@@ -2764,6 +2764,10 @@ class ClassMetadataInfo implements ClassMetadata
         $this->fieldMappings[$fieldMapping['fieldName']] = $fieldMapping;
         $this->columnNames[$fieldMapping['fieldName']]   = $fieldMapping['columnName'];
         $this->fieldNames[$fieldMapping['columnName']]   = $fieldMapping['fieldName'];
+
+        if (isset($fieldMapping['generated'])) {
+            $this->requiresFetchAfterChange = true;
+        }
     }
 
     /**
@@ -3862,7 +3866,7 @@ class ClassMetadataInfo implements ClassMetadata
     {
         $reflectionProperty = $reflService->getAccessibleProperty($class, $field);
         if ($reflectionProperty !== null && PHP_VERSION_ID >= 80100 && $reflectionProperty->isReadOnly()) {
-            $declaringClass = $reflectionProperty->getDeclaringClass()->name;
+            $declaringClass = $reflectionProperty->class;
             if ($declaringClass !== $class) {
                 $reflectionProperty = $reflService->getAccessibleProperty($declaringClass, $field);
             }

lib/Doctrine/ORM/Mapping/Driver/AnnotationDriver.php

@@ -30,10 +30,13 @@ use function is_numeric;
 
 /**
  * The AnnotationDriver reads the mapping metadata from docblock annotations.
+ *
+ * @deprecated This class will be removed in 3.0 without replacement.
  */
 class AnnotationDriver extends CompatibilityAnnotationDriver
 {
     use ColocatedMappingDriver;
+    use ReflectionBasedDriver;
 
     /**
      * The annotation reader.
@@ -60,7 +63,7 @@ class AnnotationDriver extends CompatibilityAnnotationDriver
      * @param Reader               $reader The AnnotationReader to use
      * @param string|string[]|null $paths  One or multiple paths where mapping classes can be found.
      */
-    public function __construct($reader, $paths = null)
+    public function __construct($reader, $paths = null, bool $reportFieldsWhereDeclared = false)
     {
         Deprecation::trigger(
             'doctrine/orm',
@@ -70,6 +73,17 @@ class AnnotationDriver extends CompatibilityAnnotationDriver
         $this->reader = $reader;
 
         $this->addPaths((array) $paths);
+
+        if (! $reportFieldsWhereDeclared) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/10455',
+                'In ORM 3.0, the AttributeDriver will report fields for the classes where they are declared. This may uncover invalid mapping configurations. To opt into the new mode also with the AnnotationDriver today, set the "reportFieldsWhereDeclared" constructor parameter to true.',
+                self::class
+            );
+        }
+
+        $this->reportFieldsWhereDeclared = $reportFieldsWhereDeclared;
     }
 
     /**
@@ -348,20 +362,12 @@ class AnnotationDriver extends CompatibilityAnnotationDriver
 
         // Evaluate annotations on properties/fields
         foreach ($class->getProperties() as $property) {
-            if (
-                $metadata->isMappedSuperclass && ! $property->isPrivate()
-                ||
-                $metadata->isInheritedField($property->name)
-                ||
-                $metadata->isInheritedAssociation($property->name)
-                ||
-                $metadata->isInheritedEmbeddedClass($property->name)
-            ) {
+            if ($this->isRepeatedPropertyDeclaration($property, $metadata)) {
                 continue;
             }
 
             $mapping              = [];
-            $mapping['fieldName'] = $property->getName();
+            $mapping['fieldName'] = $property->name;
 
             // Evaluate @Cache annotation
             $cacheAnnot = $this->reader->getPropertyAnnotation($property, Mapping\Cache::class);
@@ -394,7 +400,7 @@ class AnnotationDriver extends CompatibilityAnnotationDriver
             // @Column, @OneToOne, @OneToMany, @ManyToOne, @ManyToMany
             $columnAnnot = $this->reader->getPropertyAnnotation($property, Mapping\Column::class);
             if ($columnAnnot) {
-                $mapping = $this->columnToArray($property->getName(), $columnAnnot);
+                $mapping = $this->columnToArray($property->name, $columnAnnot);
 
                 $idAnnot = $this->reader->getPropertyAnnotation($property, Mapping\Id::class);
                 if ($idAnnot) {

lib/Doctrine/ORM/Mapping/Driver/AttributeDriver.php

@@ -23,13 +23,13 @@ use function class_exists;
 use function constant;
 use function defined;
 use function get_class;
-use function sprintf;
 
 use const PHP_VERSION_ID;
 
 class AttributeDriver extends CompatibilityAnnotationDriver
 {
     use ColocatedMappingDriver;
+    use ReflectionBasedDriver;
 
     private const ENTITY_ATTRIBUTE_CLASSES = [
         Mapping\Entity::class => 1,
@@ -53,13 +53,13 @@ class AttributeDriver extends CompatibilityAnnotationDriver
     protected $reader;
 
     /** @param array<string> $paths */
-    public function __construct(array $paths)
+    public function __construct(array $paths, bool $reportFieldsWhereDeclared = false)
     {
         if (PHP_VERSION_ID < 80000) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'The attribute metadata driver cannot be enabled on PHP 7. Please upgrade to PHP 8 or choose a different'
                 . ' metadata driver.'
-            ));
+            );
         }
 
         $this->reader = new AttributeReader();
@@ -73,6 +73,17 @@ class AttributeDriver extends CompatibilityAnnotationDriver
                 self::class
             );
         }
+
+        if (! $reportFieldsWhereDeclared) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/10455',
+                'In ORM 3.0, the AttributeDriver will report fields for the classes where they are declared. This may uncover invalid mapping configurations. To opt into the new mode today, set the "reportFieldsWhereDeclared" constructor parameter to true.',
+                self::class
+            );
+        }
+
+        $this->reportFieldsWhereDeclared = $reportFieldsWhereDeclared;
     }
 
     /**
@@ -298,20 +309,13 @@ class AttributeDriver extends CompatibilityAnnotationDriver
 
         foreach ($reflectionClass->getProperties() as $property) {
             assert($property instanceof ReflectionProperty);
-            if (
-                $metadata->isMappedSuperclass && ! $property->isPrivate()
-                ||
-                $metadata->isInheritedField($property->name)
-                ||
-                $metadata->isInheritedAssociation($property->name)
-                ||
-                $metadata->isInheritedEmbeddedClass($property->name)
-            ) {
+
+            if ($this->isRepeatedPropertyDeclaration($property, $metadata)) {
                 continue;
             }
 
             $mapping              = [];
-            $mapping['fieldName'] = $property->getName();
+            $mapping['fieldName'] = $property->name;
 
             // Evaluate #[Cache] attribute
             $cacheAttribute = $this->reader->getPropertyAttribute($property, Mapping\Cache::class);
@@ -346,7 +350,7 @@ class AttributeDriver extends CompatibilityAnnotationDriver
             $embeddedAttribute   = $this->reader->getPropertyAttribute($property, Mapping\Embedded::class);
 
             if ($columnAttribute !== null) {
-                $mapping = $this->columnToArray($property->getName(), $columnAttribute);
+                $mapping = $this->columnToArray($property->name, $columnAttribute);
 
                 if ($this->reader->getPropertyAttribute($property, Mapping\Id::class)) {
                     $mapping['id'] = true;

lib/Doctrine/ORM/Mapping/Driver/AttributeReader.php

@@ -69,8 +69,7 @@ final class AttributeReader
             ));
         }
 
-        return $this->getPropertyAttributes($property)[$attributeName]
-            ?? ($this->isRepeatable($attributeName) ? new RepeatableAttributeCollection() : null);
+        return $this->getPropertyAttributes($property)[$attributeName] ?? null;
     }
 
     /**

lib/Doctrine/ORM/Mapping/Driver/DatabaseDriver.php

@@ -196,7 +196,7 @@ class DatabaseDriver implements MappingDriver
             Deprecation::trigger(
                 'doctrine/orm',
                 'https://github.com/doctrine/orm/pull/249',
-                'Passing an instance of %s to %s is deprecated, please pass a ClassMetadata instance instead.',
+                'Passing an instance of %s to %s is deprecated, please pass a %s instance instead.',
                 get_class($metadata),
                 __METHOD__,
                 ClassMetadata::class

lib/Doctrine/ORM/Mapping/Driver/ReflectionBasedDriver.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Mapping\Driver;
+
+use Doctrine\ORM\Mapping\ClassMetadata;
+use ReflectionProperty;
+
+/** @internal */
+trait ReflectionBasedDriver
+{
+    /** @var bool */
+    private $reportFieldsWhereDeclared = false;
+
+    /**
+     * Helps to deal with the case that reflection may report properties inherited from parent classes.
+     * When we know about the fields already (inheritance has been anticipated in ClassMetadataFactory),
+     * the driver must skip them.
+     *
+     * The declaring classes may mismatch when there are private properties: The same property name may be
+     * reported multiple times, but since it is private, it is in fact multiple (different) properties in
+     * different classes. In that case, report the property as an individual field. (ClassMetadataFactory will
+     * probably fail in that case, though.)
+     */
+    private function isRepeatedPropertyDeclaration(ReflectionProperty $property, ClassMetadata $metadata): bool
+    {
+        if (! $this->reportFieldsWhereDeclared) {
+            return $metadata->isMappedSuperclass && ! $property->isPrivate()
+                || $metadata->isInheritedField($property->name)
+                || $metadata->isInheritedAssociation($property->name)
+                || $metadata->isInheritedEmbeddedClass($property->name);
+        }
+
+        $declaringClass = $property->class;
+
+        if (
+            isset($metadata->fieldMappings[$property->name]['declared'])
+            && $metadata->fieldMappings[$property->name]['declared'] === $declaringClass
+        ) {
+            return true;
+        }
+
+        if (
+            isset($metadata->associationMappings[$property->name]['declared'])
+            && $metadata->associationMappings[$property->name]['declared'] === $declaringClass
+        ) {
+            return true;
+        }
+
+        return isset($metadata->embeddedClasses[$property->name]['declared'])
+            && $metadata->embeddedClasses[$property->name]['declared'] === $declaringClass;
+    }
+}

lib/Doctrine/ORM/Mapping/Driver/XmlDriver.php

@@ -50,27 +50,25 @@ class XmlDriver extends FileDriver
     public function __construct($locator, $fileExtension = self::DEFAULT_FILE_EXTENSION, bool $isXsdValidationEnabled = false)
     {
         if (! extension_loaded('simplexml')) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'The XML metadata driver cannot be enabled because the SimpleXML PHP extension is missing.'
                 . ' Please configure PHP with SimpleXML or choose a different metadata driver.'
-            ));
+            );
         }
 
         if (! $isXsdValidationEnabled) {
             Deprecation::trigger(
                 'doctrine/orm',
                 'https://github.com/doctrine/orm/pull/6728',
-                sprintf(
-                    'Using XML mapping driver with XSD validation disabled is deprecated'
-                    . ' and will not be supported in Doctrine ORM 3.0.'
-                )
+                'Using XML mapping driver with XSD validation disabled is deprecated'
+                . ' and will not be supported in Doctrine ORM 3.0.'
             );
         }
 
         if ($isXsdValidationEnabled && ! extension_loaded('dom')) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'XSD validation cannot be enabled because the DOM extension is missing.'
-            ));
+            );
         }
 
         $this->isXsdValidationEnabled = $isXsdValidationEnabled;
@@ -130,7 +128,7 @@ class XmlDriver extends FileDriver
 
         // Evaluate named queries
         if (isset($xmlRoot->{'named-queries'})) {
-            foreach ($xmlRoot->{'named-queries'}->{'named-query'} as $namedQueryElement) {
+            foreach ($xmlRoot->{'named-queries'}->{'named-query'} ?? [] as $namedQueryElement) {
                 $metadata->addNamedQuery(
                     [
                         'name'  => (string) $namedQueryElement['name'],
@@ -142,7 +140,7 @@ class XmlDriver extends FileDriver
 
         // Evaluate native named queries
         if (isset($xmlRoot->{'named-native-queries'})) {
-            foreach ($xmlRoot->{'named-native-queries'}->{'named-native-query'} as $nativeQueryElement) {
+            foreach ($xmlRoot->{'named-native-queries'}->{'named-native-query'} ?? [] as $nativeQueryElement) {
                 $metadata->addNamedNativeQuery(
                     [
                         'name'              => isset($nativeQueryElement['name']) ? (string) $nativeQueryElement['name'] : null,
@@ -156,7 +154,7 @@ class XmlDriver extends FileDriver
 
         // Evaluate sql result set mapping
         if (isset($xmlRoot->{'sql-result-set-mappings'})) {
-            foreach ($xmlRoot->{'sql-result-set-mappings'}->{'sql-result-set-mapping'} as $rsmElement) {
+            foreach ($xmlRoot->{'sql-result-set-mappings'}->{'sql-result-set-mapping'} ?? [] as $rsmElement) {
                 $entities = [];
                 $columns  = [];
                 foreach ($rsmElement as $entityElement) {
@@ -242,7 +240,7 @@ class XmlDriver extends FileDriver
         // Evaluate <indexes...>
         if (isset($xmlRoot->indexes)) {
             $metadata->table['indexes'] = [];
-            foreach ($xmlRoot->indexes->index as $indexXml) {
+            foreach ($xmlRoot->indexes->index ?? [] as $indexXml) {
                 $index = [];
 
                 if (isset($indexXml['columns']) && ! empty($indexXml['columns'])) {
@@ -285,7 +283,7 @@ class XmlDriver extends FileDriver
         // Evaluate <unique-constraints..>
         if (isset($xmlRoot->{'unique-constraints'})) {
             $metadata->table['uniqueConstraints'] = [];
-            foreach ($xmlRoot->{'unique-constraints'}->{'unique-constraint'} as $uniqueXml) {
+            foreach ($xmlRoot->{'unique-constraints'}->{'unique-constraint'} ?? [] as $uniqueXml) {
                 $unique = [];
 
                 if (isset($uniqueXml['columns']) && ! empty($uniqueXml['columns'])) {
@@ -372,36 +370,14 @@ class XmlDriver extends FileDriver
 
         // Evaluate <id ...> mappings
         $associationIds = [];
-        foreach ($xmlRoot->id as $idElement) {
+        foreach ($xmlRoot->id ?? [] as $idElement) {
             if (isset($idElement['association-key']) && $this->evaluateBoolean($idElement['association-key'])) {
                 $associationIds[(string) $idElement['name']] = true;
                 continue;
             }
 
-            $mapping = [
-                'id' => true,
-                'fieldName' => (string) $idElement['name'],
-            ];
-
-            if (isset($idElement['type'])) {
-                $mapping['type'] = (string) $idElement['type'];
-            }
-
-            if (isset($idElement['length'])) {
-                $mapping['length'] = (int) $idElement['length'];
-            }
-
-            if (isset($idElement['column'])) {
-                $mapping['columnName'] = (string) $idElement['column'];
-            }
-
-            if (isset($idElement['column-definition'])) {
-                $mapping['columnDefinition'] = (string) $idElement['column-definition'];
-            }
-
-            if (isset($idElement->options)) {
-                $mapping['options'] = $this->parseOptions($idElement->options->children());
-            }
+            $mapping       = $this->columnToArray($idElement);
+            $mapping['id'] = true;
 
             $metadata->mapField($mapping);
 
@@ -463,7 +439,7 @@ class XmlDriver extends FileDriver
                     if (isset($oneToOneElement->{'join-column'})) {
                         $joinColumns[] = $this->joinColumnToArray($oneToOneElement->{'join-column'});
                     } elseif (isset($oneToOneElement->{'join-columns'})) {
-                        foreach ($oneToOneElement->{'join-columns'}->{'join-column'} as $joinColumnElement) {
+                        foreach ($oneToOneElement->{'join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                             $joinColumns[] = $this->joinColumnToArray($joinColumnElement);
                         }
                     }
@@ -514,7 +490,7 @@ class XmlDriver extends FileDriver
 
                 if (isset($oneToManyElement->{'order-by'})) {
                     $orderBy = [];
-                    foreach ($oneToManyElement->{'order-by'}->{'order-by-field'} as $orderByField) {
+                    foreach ($oneToManyElement->{'order-by'}->{'order-by-field'} ?? [] as $orderByField) {
                         $orderBy[(string) $orderByField['name']] = isset($orderByField['direction'])
                             ? (string) $orderByField['direction']
                             : Criteria::ASC;
@@ -566,7 +542,7 @@ class XmlDriver extends FileDriver
                 if (isset($manyToOneElement->{'join-column'})) {
                     $joinColumns[] = $this->joinColumnToArray($manyToOneElement->{'join-column'});
                 } elseif (isset($manyToOneElement->{'join-columns'})) {
-                    foreach ($manyToOneElement->{'join-columns'}->{'join-column'} as $joinColumnElement) {
+                    foreach ($manyToOneElement->{'join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                         $joinColumns[] = $this->joinColumnToArray($joinColumnElement);
                     }
                 }
@@ -625,11 +601,11 @@ class XmlDriver extends FileDriver
                         $joinTable['options'] = $this->parseOptions($joinTableElement->options->children());
                     }
 
-                    foreach ($joinTableElement->{'join-columns'}->{'join-column'} as $joinColumnElement) {
+                    foreach ($joinTableElement->{'join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                         $joinTable['joinColumns'][] = $this->joinColumnToArray($joinColumnElement);
                     }
 
-                    foreach ($joinTableElement->{'inverse-join-columns'}->{'join-column'} as $joinColumnElement) {
+                    foreach ($joinTableElement->{'inverse-join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                         $joinTable['inverseJoinColumns'][] = $this->joinColumnToArray($joinColumnElement);
                     }
 
@@ -642,7 +618,7 @@ class XmlDriver extends FileDriver
 
                 if (isset($manyToManyElement->{'order-by'})) {
                     $orderBy = [];
-                    foreach ($manyToManyElement->{'order-by'}->{'order-by-field'} as $orderByField) {
+                    foreach ($manyToManyElement->{'order-by'}->{'order-by-field'} ?? [] as $orderByField) {
                         $orderBy[(string) $orderByField['name']] = isset($orderByField['direction'])
                             ? (string) $orderByField['direction']
                             : Criteria::ASC;
@@ -668,9 +644,9 @@ class XmlDriver extends FileDriver
 
         // Evaluate association-overrides
         if (isset($xmlRoot->{'attribute-overrides'})) {
-            foreach ($xmlRoot->{'attribute-overrides'}->{'attribute-override'} as $overrideElement) {
+            foreach ($xmlRoot->{'attribute-overrides'}->{'attribute-override'} ?? [] as $overrideElement) {
                 $fieldName = (string) $overrideElement['name'];
-                foreach ($overrideElement->field as $field) {
+                foreach ($overrideElement->field ?? [] as $field) {
                     $mapping              = $this->columnToArray($field);
                     $mapping['fieldName'] = $fieldName;
                     $metadata->setAttributeOverride($fieldName, $mapping);
@@ -680,14 +656,14 @@ class XmlDriver extends FileDriver
 
         // Evaluate association-overrides
         if (isset($xmlRoot->{'association-overrides'})) {
-            foreach ($xmlRoot->{'association-overrides'}->{'association-override'} as $overrideElement) {
+            foreach ($xmlRoot->{'association-overrides'}->{'association-override'} ?? [] as $overrideElement) {
                 $fieldName = (string) $overrideElement['name'];
                 $override  = [];
 
                 // Check for join-columns
                 if (isset($overrideElement->{'join-columns'})) {
                     $joinColumns = [];
-                    foreach ($overrideElement->{'join-columns'}->{'join-column'} as $joinColumnElement) {
+                    foreach ($overrideElement->{'join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                         $joinColumns[] = $this->joinColumnToArray($joinColumnElement);
                     }
 
@@ -709,13 +685,13 @@ class XmlDriver extends FileDriver
                     }
 
                     if (isset($joinTableElement->{'join-columns'})) {
-                        foreach ($joinTableElement->{'join-columns'}->{'join-column'} as $joinColumnElement) {
+                        foreach ($joinTableElement->{'join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                             $joinTable['joinColumns'][] = $this->joinColumnToArray($joinColumnElement);
                         }
                     }
 
                     if (isset($joinTableElement->{'inverse-join-columns'})) {
-                        foreach ($joinTableElement->{'inverse-join-columns'}->{'join-column'} as $joinColumnElement) {
+                        foreach ($joinTableElement->{'inverse-join-columns'}->{'join-column'} ?? [] as $joinColumnElement) {
                             $joinTable['inverseJoinColumns'][] = $this->joinColumnToArray($joinColumnElement);
                         }
                     }
@@ -739,14 +715,14 @@ class XmlDriver extends FileDriver
 
         // Evaluate <lifecycle-callbacks...>
         if (isset($xmlRoot->{'lifecycle-callbacks'})) {
-            foreach ($xmlRoot->{'lifecycle-callbacks'}->{'lifecycle-callback'} as $lifecycleCallback) {
+            foreach ($xmlRoot->{'lifecycle-callbacks'}->{'lifecycle-callback'} ?? [] as $lifecycleCallback) {
                 $metadata->addLifecycleCallback((string) $lifecycleCallback['method'], constant('Doctrine\ORM\Events::' . (string) $lifecycleCallback['type']));
             }
         }
 
         // Evaluate entity listener
         if (isset($xmlRoot->{'entity-listeners'})) {
-            foreach ($xmlRoot->{'entity-listeners'}->{'entity-listener'} as $listenerElement) {
+            foreach ($xmlRoot->{'entity-listeners'}->{'entity-listener'} ?? [] as $listenerElement) {
                 $className = (string) $listenerElement['class'];
                 // Evaluate the listener using naming convention.
                 if ($listenerElement->count() === 0) {
@@ -768,16 +744,14 @@ class XmlDriver extends FileDriver
     /**
      * Parses (nested) option elements.
      *
-     * @param SimpleXMLElement $options The XML element.
-     *
      * @return mixed[] The options array.
      * @psalm-return array<int|string, array<int|string, mixed|string>|bool|string>
      */
-    private function parseOptions(SimpleXMLElement $options): array
+    private function parseOptions(?SimpleXMLElement $options): array
     {
         $array = [];
 
-        foreach ($options as $option) {
+        foreach ($options ?? [] as $option) {
             if ($option->count()) {
                 $value = $this->parseOptions($option->children());
             } else {
@@ -840,7 +814,7 @@ class XmlDriver extends FileDriver
         }
 
         if (isset($joinColumnElement['options'])) {
-            $joinColumn['options'] = $this->parseOptions($joinColumnElement['options']->children());
+            $joinColumn['options'] = $this->parseOptions($joinColumnElement['options'] ? $joinColumnElement['options']->children() : null);
         }
 
         return $joinColumn;
@@ -968,7 +942,10 @@ class XmlDriver extends FileDriver
     private function getCascadeMappings(SimpleXMLElement $cascadeElement): array
     {
         $cascades = [];
-        foreach ($cascadeElement->children() as $action) {
+        $children = $cascadeElement->children();
+        assert($children !== null);
+
+        foreach ($children as $action) {
             // According to the JPA specifications, XML uses "cascade-persist"
             // instead of "persist". Here, both variations
             // are supported because YAML, Annotation and Attribute use "persist"
@@ -993,19 +970,19 @@ class XmlDriver extends FileDriver
 
         if (isset($xmlElement->entity)) {
             foreach ($xmlElement->entity as $entityElement) {
-                /** @psalm-var class-string */
+                /** @psalm-var class-string $entityName */
                 $entityName          = (string) $entityElement['name'];
                 $result[$entityName] = $entityElement;
             }
         } elseif (isset($xmlElement->{'mapped-superclass'})) {
             foreach ($xmlElement->{'mapped-superclass'} as $mappedSuperClass) {
-                /** @psalm-var class-string */
+                /** @psalm-var class-string $className */
                 $className          = (string) $mappedSuperClass['name'];
                 $result[$className] = $mappedSuperClass;
             }
         } elseif (isset($xmlElement->embeddable)) {
             foreach ($xmlElement->embeddable as $embeddableElement) {
-                /** @psalm-var class-string */
+                /** @psalm-var class-string $embeddableName */
                 $embeddableName          = (string) $embeddableElement['name'];
                 $result[$embeddableName] = $embeddableElement;
             }

lib/Doctrine/ORM/Mapping/Driver/YamlDriver.php

@@ -48,11 +48,11 @@ class YamlDriver extends FileDriver
         );
 
         if (! class_exists(Yaml::class)) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'The YAML metadata driver cannot be enabled because the "symfony/yaml" library'
                 . ' is not installed. Please run "composer require symfony/yaml" or choose a different'
                 . ' metadata driver.'
-            ));
+            );
         }
 
         parent::__construct($locator, $fileExtension);

lib/Doctrine/ORM/Mapping/NamedNativeQueries.php

@@ -8,6 +8,8 @@ namespace Doctrine\ORM\Mapping;
  * Is used to specify an array of native SQL named queries.
  * The NamedNativeQueries annotation can be applied to an entity or mapped superclass.
  *
+ * @deprecated Named queries won't be supported in ORM 3.
+ *
  * @Annotation
  * @Target("CLASS")
  */

lib/Doctrine/ORM/Mapping/NamedNativeQuery.php

@@ -8,6 +8,8 @@ namespace Doctrine\ORM\Mapping;
  * Is used to specify a native SQL named query.
  * The NamedNativeQuery annotation can be applied to an entity or mapped superclass.
  *
+ * @deprecated Named queries won't be supported in ORM 3.
+ *
  * @Annotation
  * @Target("ANNOTATION")
  */

lib/Doctrine/ORM/Mapping/NamedQueries.php

@@ -5,6 +5,8 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Mapping;
 
 /**
+ * @deprecated Named queries won't be supported in ORM 3.
+ *
  * @Annotation
  * @Target("CLASS")
  */

lib/Doctrine/ORM/Mapping/NamedQuery.php

@@ -5,6 +5,8 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Mapping;
 
 /**
+ * @deprecated Named queries won't be supported in ORM 3.
+ *
  * @Annotation
  * @Target("ANNOTATION")
  */

lib/Doctrine/ORM/Mapping/Reflection/ReflectionPropertiesGetter.php

@@ -73,7 +73,7 @@ final class ReflectionPropertiesGetter
 
             $parentClass = $currentClass->getParentClass();
             if ($parentClass) {
-                $parentClassName = $parentClass->getName();
+                $parentClassName = $parentClass->name;
             }
         }
 
@@ -111,14 +111,14 @@ final class ReflectionPropertiesGetter
     private function getAccessibleProperty(ReflectionProperty $property): ?ReflectionProperty
     {
         return $this->reflectionService->getAccessibleProperty(
-            $property->getDeclaringClass()->getName(),
-            $property->getName()
+            $property->class,
+            $property->name
         );
     }
 
     private function getLogicalName(ReflectionProperty $property): string
     {
-        $propertyName = $property->getName();
+        $propertyName = $property->name;
 
         if ($property->isPublic()) {
             return $propertyName;
@@ -128,6 +128,6 @@ final class ReflectionPropertiesGetter
             return "\0*\0" . $propertyName;
         }
 
-        return "\0" . $property->getDeclaringClass()->getName() . "\0" . $propertyName;
+        return "\0" . $property->class . "\0" . $propertyName;
     }
 }

lib/Doctrine/ORM/Mapping/ReflectionEmbeddedProperty.php

@@ -38,7 +38,7 @@ class ReflectionEmbeddedProperty extends ReflectionProperty
         $this->childProperty  = $childProperty;
         $this->embeddedClass  = (string) $embeddedClass;
 
-        parent::__construct($childProperty->getDeclaringClass()->getName(), $childProperty->getName());
+        parent::__construct($childProperty->class, $childProperty->name);
     }
 
     /**

lib/Doctrine/ORM/Mapping/ReflectionEnumProperty.php

@@ -28,8 +28,8 @@ class ReflectionEnumProperty extends ReflectionProperty
         $this->enumType                   = $enumType;
 
         parent::__construct(
-            $originalReflectionProperty->getDeclaringClass()->getName(),
-            $originalReflectionProperty->getName()
+            $originalReflectionProperty->class,
+            $originalReflectionProperty->name
         );
     }
 
@@ -98,7 +98,7 @@ class ReflectionEnumProperty extends ReflectionProperty
         } catch (ValueError $e) {
             throw MappingException::invalidEnumValue(
                 get_class($object),
-                $this->originalReflectionProperty->getName(),
+                $this->originalReflectionProperty->name,
                 (string) $value,
                 $enumType,
                 $e

lib/Doctrine/ORM/Mapping/UnderscoreNamingStrategy.php

@@ -30,7 +30,10 @@ class UnderscoreNamingStrategy implements NamingStrategy
     /** @var int */
     private $case;
 
-    /** @var string */
+    /**
+     * @var string
+     * @psalm-var non-empty-string
+     */
     private $pattern;
 
     /**

lib/Doctrine/ORM/NativeQuery.php

@@ -11,8 +11,10 @@ use function ksort;
 
 /**
  * Represents a native SQL query.
+ *
+ * @final
  */
-final class NativeQuery extends AbstractQuery
+class NativeQuery extends AbstractQuery
 {
     /** @var string */
     private $sql;

lib/Doctrine/ORM/ORMInvalidArgumentException.php

@@ -15,6 +15,7 @@ use function func_num_args;
 use function get_debug_type;
 use function gettype;
 use function implode;
+use function is_scalar;
 use function method_exists;
 use function reset;
 use function spl_object_id;
@@ -261,6 +262,32 @@ EXCEPTION
         return new self(sprintf('Entity name must be a string, %s given', get_debug_type($entityName)));
     }
 
+    /** @param mixed $value */
+    public static function invalidAutoGenerateMode($value): self
+    {
+        return new self(sprintf('Invalid auto generate mode "%s" given.', is_scalar($value) ? (string) $value : get_debug_type($value)));
+    }
+
+    public static function missingPrimaryKeyValue(string $className, string $idField): self
+    {
+        return new self(sprintf('Missing value for primary key %s on %s', $idField, $className));
+    }
+
+    public static function proxyDirectoryRequired(): self
+    {
+        return new self('You must configure a proxy directory. See docs for details');
+    }
+
+    public static function proxyNamespaceRequired(): self
+    {
+        return new self('You must configure a proxy namespace');
+    }
+
+    public static function proxyDirectoryNotWritable(string $proxyDirectory): self
+    {
+        return new self(sprintf('Your proxy directory "%s" must be writable', $proxyDirectory));
+    }
+
     /**
      * Helper method to show an object as string.
      *

lib/Doctrine/ORM/ORMSetup.php

@@ -24,7 +24,6 @@ use function apcu_enabled;
 use function class_exists;
 use function extension_loaded;
 use function md5;
-use function sprintf;
 use function sys_get_temp_dir;
 
 final class ORMSetup
@@ -63,7 +62,8 @@ final class ORMSetup
      */
     public static function createDefaultAnnotationDriver(
         array $paths = [],
-        ?CacheItemPoolInterface $cache = null
+        ?CacheItemPoolInterface $cache = null,
+        bool $reportFieldsWhereDeclared = false
     ): AnnotationDriver {
         Deprecation::trigger(
             'doctrine/orm',
@@ -72,11 +72,11 @@ final class ORMSetup
             __METHOD__
         );
         if (! class_exists(AnnotationReader::class)) {
-            throw new LogicException(sprintf(
+            throw new LogicException(
                 'The annotation metadata driver cannot be enabled because the "doctrine/annotations" library'
                 . ' is not installed. Please run "composer require doctrine/annotations" or choose a different'
                 . ' metadata driver.'
-            ));
+            );
         }
 
         $reader = new AnnotationReader();
@@ -89,7 +89,7 @@ final class ORMSetup
             $reader = new PsrCachedReader($reader, $cache);
         }
 
-        return new AnnotationDriver($reader, $paths);
+        return new AnnotationDriver($reader, $paths, $reportFieldsWhereDeclared);
     }
 
     /**
@@ -101,10 +101,11 @@ final class ORMSetup
         array $paths,
         bool $isDevMode = false,
         ?string $proxyDir = null,
-        ?CacheItemPoolInterface $cache = null
+        ?CacheItemPoolInterface $cache = null,
+        bool $reportFieldsWhereDeclared = false
     ): Configuration {
         $config = self::createConfiguration($isDevMode, $proxyDir, $cache);
-        $config->setMetadataDriverImpl(new AttributeDriver($paths));
+        $config->setMetadataDriverImpl(new AttributeDriver($paths, $reportFieldsWhereDeclared));
 
         return $config;
     }

lib/Doctrine/ORM/Persisters/Collection/OneToManyPersister.php

@@ -16,6 +16,7 @@ use function array_reverse;
 use function array_values;
 use function assert;
 use function implode;
+use function is_int;
 use function is_string;
 
 /**
@@ -174,16 +175,22 @@ class OneToManyPersister extends AbstractCollectionPersister
         $targetClass = $this->em->getClassMetadata($mapping['targetEntity']);
         $columns     = [];
         $parameters  = [];
+        $types       = [];
 
         foreach ($targetClass->associationMappings[$mapping['mappedBy']]['joinColumns'] as $joinColumn) {
             $columns[]    = $this->quoteStrategy->getJoinColumnName($joinColumn, $targetClass, $this->platform);
             $parameters[] = $identifier[$sourceClass->getFieldForColumn($joinColumn['referencedColumnName'])];
+            $types[]      = PersisterHelper::getTypeOfColumn($joinColumn['referencedColumnName'], $sourceClass, $this->em);
         }
 
         $statement = 'DELETE FROM ' . $this->quoteStrategy->getTableName($targetClass, $this->platform)
             . ' WHERE ' . implode(' = ? AND ', $columns) . ' = ?';
 
-        return $this->conn->executeStatement($statement, $parameters);
+        $numAffected = $this->conn->executeStatement($statement, $parameters, $types);
+
+        assert(is_int($numAffected));
+
+        return $numAffected;
     }
 
     /**
@@ -247,6 +254,8 @@ class OneToManyPersister extends AbstractCollectionPersister
 
         $this->conn->executeStatement($statement);
 
+        assert(is_int($numDeleted));
+
         return $numDeleted;
     }
 }

lib/Doctrine/ORM/Persisters/Entity/BasicEntityPersister.php

@@ -7,7 +7,6 @@ namespace Doctrine\ORM\Persisters\Entity;
 use BackedEnum;
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Collections\Expr\Comparison;
-use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\LockMode;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
@@ -26,6 +25,7 @@ use Doctrine\ORM\Persisters\Exception\InvalidOrientation;
 use Doctrine\ORM\Persisters\Exception\UnrecognizedField;
 use Doctrine\ORM\Persisters\SqlExpressionVisitor;
 use Doctrine\ORM\Persisters\SqlValueVisitor;
+use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Repository\Exception\InvalidFindByCall;
@@ -183,7 +183,7 @@ class BasicEntityPersister implements EntityPersister
      *
      * @var IdentifierFlattener
      */
-    private $identifierFlattener;
+    protected $identifierFlattener;
 
     /** @var CachedPersisterContext */
     protected $currentPersisterContext;
@@ -256,27 +256,23 @@ class BasicEntityPersister implements EntityPersister
     public function executeInserts()
     {
         if (! $this->queuedInserts) {
-            return [];
+            return;
         }
 
-        $postInsertIds  = [];
+        $uow            = $this->em->getUnitOfWork();
         $idGenerator    = $this->class->idGenerator;
         $isPostInsertId = $idGenerator->isPostInsertGenerator();
 
         $stmt      = $this->conn->prepare($this->getInsertSQL());
         $tableName = $this->class->getTableName();
 
-        foreach ($this->queuedInserts as $entity) {
+        foreach ($this->queuedInserts as $key => $entity) {
             $insertData = $this->prepareInsertData($entity);
 
             if (isset($insertData[$tableName])) {
                 $paramIndex = 1;
 
                 foreach ($insertData[$tableName] as $column => $value) {
-                    if ($value instanceof BackedEnum) {
-                        $value = $value->value;
-                    }
-
                     $stmt->bindValue($paramIndex++, $value, $this->columnTypes[$column]);
                 }
             }
@@ -284,12 +280,10 @@ class BasicEntityPersister implements EntityPersister
             $stmt->executeStatement();
 
             if ($isPostInsertId) {
-                $generatedId     = $idGenerator->generateId($this->em, $entity);
-                $id              = [$this->class->identifier[0] => $generatedId];
-                $postInsertIds[] = [
-                    'generatedId' => $generatedId,
-                    'entity' => $entity,
-                ];
+                $generatedId = $idGenerator->generateId($this->em, $entity);
+                $id          = [$this->class->identifier[0] => $generatedId];
+
+                $uow->assignPostInsertId($entity, $generatedId);
             } else {
                 $id = $this->class->getIdentifierValues($entity);
             }
@@ -297,11 +291,16 @@ class BasicEntityPersister implements EntityPersister
             if ($this->class->requiresFetchAfterChange) {
                 $this->assignDefaultVersionAndUpsertableValues($entity, $id);
             }
+
+            // Unset this queued insert, so that the prepareUpdateData() method knows right away
+            // (for the next entity already) that the current entity has been written to the database
+            // and no extra updates need to be scheduled to refer to it.
+            //
+            // In \Doctrine\ORM\UnitOfWork::executeInserts(), the UoW already removed entities
+            // from its own list (\Doctrine\ORM\UnitOfWork::$entityInsertions) right after they
+            // were given to our addInsert() method.
+            unset($this->queuedInserts[$key]);
         }
-
-        $this->queuedInserts = [];
-
-        return $postInsertIds;
     }
 
     /**
@@ -380,7 +379,7 @@ class BasicEntityPersister implements EntityPersister
      * @return int[]|null[]|string[]
      * @psalm-return list<int|string|null>
      */
-    private function extractIdentifierTypes(array $id, ClassMetadata $versionedClass): array
+    final protected function extractIdentifierTypes(array $id, ClassMetadata $versionedClass): array
     {
         $types = [];
 
@@ -542,7 +541,7 @@ class BasicEntityPersister implements EntityPersister
     protected function deleteJoinTableRecords(array $identifier, array $types): void
     {
         foreach ($this->class->associationMappings as $mapping) {
-            if ($mapping['type'] !== ClassMetadata::MANY_TO_MANY) {
+            if ($mapping['type'] !== ClassMetadata::MANY_TO_MANY || isset($mapping['isOnDeleteCascade'])) {
                 continue;
             }
 
@@ -578,10 +577,6 @@ class BasicEntityPersister implements EntityPersister
                 $otherKeys[] = $this->quoteStrategy->getJoinColumnName($joinColumn, $class, $this->platform);
             }
 
-            if (isset($mapping['isOnDeleteCascade'])) {
-                continue;
-            }
-
             $joinTableName = $this->quoteStrategy->getJoinTableName($association, $this->class, $this->platform);
 
             $this->conn->delete($joinTableName, array_combine($keys, $identifier), $types);
@@ -683,10 +678,30 @@ class BasicEntityPersister implements EntityPersister
             if ($newVal !== null) {
                 $oid = spl_object_id($newVal);
 
-                if (isset($this->queuedInserts[$oid]) || $uow->isScheduledForInsert($newVal)) {
-                    // The associated entity $newVal is not yet persisted, so we must
-                    // set $newVal = null, in order to insert a null value and schedule an
-                    // extra update on the UnitOfWork.
+                // If the associated entity $newVal is not yet persisted and/or does not yet have
+                // an ID assigned, we must set $newVal = null. This will insert a null value and
+                // schedule an extra update on the UnitOfWork.
+                //
+                // This gives us extra time to a) possibly obtain a database-generated identifier
+                // value for $newVal, and b) insert $newVal into the database before the foreign
+                // key reference is being made.
+                //
+                // When looking at $this->queuedInserts and $uow->isScheduledForInsert, be aware
+                // of the implementation details that our own executeInserts() method will remove
+                // entities from the former as soon as the insert statement has been executed and
+                // a post-insert ID has been assigned (if necessary), and that the UnitOfWork has
+                // already removed entities from its own list at the time they were passed to our
+                // addInsert() method.
+                //
+                // Then, there is one extra exception we can make: An entity that references back to itself
+                // _and_ uses an application-provided ID (the "NONE" generator strategy) also does not
+                // need the extra update, although it is still in the list of insertions itself.
+                // This looks like a minor optimization at first, but is the capstone for being able to
+                // use non-NULLable, self-referencing associations in applications that provide IDs (like UUIDs).
+                if (
+                    (isset($this->queuedInserts[$oid]) || $uow->isScheduledForInsert($newVal))
+                    && ! ($newVal === $entity && $this->class->isIdentifierNatural())
+                ) {
                     $uow->scheduleExtraUpdate($entity, [$field => [null, $newVal]]);
 
                     $newVal = null;
@@ -1249,7 +1264,7 @@ class BasicEntityPersister implements EntityPersister
             }
 
             $isAssocToOneInverseSide = $assoc['type'] & ClassMetadata::TO_ONE && ! $assoc['isOwningSide'];
-            $isAssocFromOneEager     = $assoc['type'] !== ClassMetadata::MANY_TO_MANY && $assoc['fetch'] === ClassMetadata::FETCH_EAGER;
+            $isAssocFromOneEager     = $assoc['type'] & ClassMetadata::TO_ONE && $assoc['fetch'] === ClassMetadata::FETCH_EAGER;
 
             if (! ($isAssocFromOneEager || $isAssocToOneInverseSide)) {
                 continue;
@@ -2013,7 +2028,7 @@ class BasicEntityPersister implements EntityPersister
             return [$value->value];
         }
 
-        $valueClass = ClassUtils::getClass($value);
+        $valueClass = DefaultProxyClassNameResolver::getClass($value);
 
         if ($this->em->getMetadataFactory()->isTransient($valueClass)) {
             return [$value];

lib/Doctrine/ORM/Persisters/Entity/EntityPersister.php

@@ -109,17 +109,15 @@ interface EntityPersister
     public function addInsert($entity);
 
     /**
-     * Executes all queued entity insertions and returns any generated post-insert
-     * identifiers that were created as a result of the insertions.
+     * Executes all queued entity insertions.
      *
      * If no inserts are queued, invoking this method is a NOOP.
      *
-     * @psalm-return list<array{
+     * @psalm-return void|list<array{
      *                   generatedId: int,
      *                   entity: object
-     *               }> An array of any generated post-insert IDs. This will be
-     *                  an empty array if the entity class does not use the
-     *                  IDENTITY generation strategy.
+     *               }> Returning an array of generated post-insert IDs is deprecated, implementations
+     *                  should call UnitOfWork::assignPostInsertId() and return void.
      */
     public function executeInserts();
 

lib/Doctrine/ORM/Persisters/Entity/JoinedSubclassPersister.php

@@ -11,8 +11,11 @@ use Doctrine\DBAL\Types\Types;
 use Doctrine\ORM\Internal\SQLResultCasing;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Utility\PersisterHelper;
+use LengthException;
 
 use function array_combine;
+use function array_keys;
+use function array_values;
 use function implode;
 
 /**
@@ -109,10 +112,10 @@ class JoinedSubclassPersister extends AbstractEntityInheritancePersister
     public function executeInserts()
     {
         if (! $this->queuedInserts) {
-            return [];
+            return;
         }
 
-        $postInsertIds  = [];
+        $uow            = $this->em->getUnitOfWork();
         $idGenerator    = $this->class->idGenerator;
         $isPostInsertId = $idGenerator->isPostInsertGenerator();
         $rootClass      = $this->class->name !== $this->class->rootEntityName
@@ -157,20 +160,14 @@ class JoinedSubclassPersister extends AbstractEntityInheritancePersister
             $rootTableStmt->executeStatement();
 
             if ($isPostInsertId) {
-                $generatedId     = $idGenerator->generateId($this->em, $entity);
-                $id              = [$this->class->identifier[0] => $generatedId];
-                $postInsertIds[] = [
-                    'generatedId' => $generatedId,
-                    'entity' => $entity,
-                ];
+                $generatedId = $idGenerator->generateId($this->em, $entity);
+                $id          = [$this->class->identifier[0] => $generatedId];
+
+                $uow->assignPostInsertId($entity, $generatedId);
             } else {
                 $id = $this->em->getUnitOfWork()->getEntityIdentifier($entity);
             }
 
-            if ($this->class->requiresFetchAfterChange) {
-                $this->assignDefaultVersionAndUpsertableValues($entity, $id);
-            }
-
             // Execute inserts on subtables.
             // The order doesn't matter because all child tables link to the root table via FK.
             foreach ($subTableStmts as $tableName => $stmt) {
@@ -191,11 +188,13 @@ class JoinedSubclassPersister extends AbstractEntityInheritancePersister
 
                 $stmt->executeStatement();
             }
+
+            if ($this->class->requiresFetchAfterChange) {
+                $this->assignDefaultVersionAndUpsertableValues($entity, $id);
+            }
         }
 
         $this->queuedInserts = [];
-
-        return $postInsertIds;
     }
 
     /**
@@ -514,6 +513,7 @@ class JoinedSubclassPersister extends AbstractEntityInheritancePersister
                     || isset($this->class->associationMappings[$name]['inherited'])
                     || ($this->class->isVersioned && $this->class->versionField === $name)
                     || isset($this->class->embeddedClasses[$name])
+                    || isset($this->class->fieldMappings[$name]['notInsertable'])
             ) {
                 continue;
             }
@@ -556,6 +556,60 @@ class JoinedSubclassPersister extends AbstractEntityInheritancePersister
         }
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    protected function fetchVersionAndNotUpsertableValues($versionedClass, array $id)
+    {
+        $columnNames = [];
+        foreach ($this->class->fieldMappings as $key => $column) {
+            $class = null;
+            if ($this->class->isVersioned && $key === $versionedClass->versionField) {
+                $class = $versionedClass;
+            } elseif (isset($column['generated'])) {
+                $class = isset($column['inherited'])
+                    ? $this->em->getClassMetadata($column['inherited'])
+                    : $this->class;
+            } else {
+                continue;
+            }
+
+            $columnNames[$key] = $this->getSelectColumnSQL($key, $class);
+        }
+
+        $tableName      = $this->quoteStrategy->getTableName($versionedClass, $this->platform);
+        $baseTableAlias = $this->getSQLTableAlias($this->class->name);
+        $joinSql        = $this->getJoinSql($baseTableAlias);
+        $identifier     = $this->quoteStrategy->getIdentifierColumnNames($versionedClass, $this->platform);
+        foreach ($identifier as $i => $idValue) {
+            $identifier[$i] = $baseTableAlias . '.' . $idValue;
+        }
+
+        $sql = 'SELECT ' . implode(', ', $columnNames)
+            . ' FROM ' . $tableName . ' ' . $baseTableAlias
+            . $joinSql
+            . ' WHERE ' . implode(' = ? AND ', $identifier) . ' = ?';
+
+        $flatId = $this->identifierFlattener->flattenIdentifier($versionedClass, $id);
+        $values = $this->conn->fetchNumeric(
+            $sql,
+            array_values($flatId),
+            $this->extractIdentifierTypes($id, $versionedClass)
+        );
+
+        if ($values === false) {
+            throw new LengthException('Unexpected empty result for database query.');
+        }
+
+        $values = array_combine(array_keys($columnNames), $values);
+
+        if (! $values) {
+            throw new LengthException('Unexpected number of database columns.');
+        }
+
+        return $values;
+    }
+
     private function getJoinSql(string $baseTableAlias): string
     {
         $joinSql          = '';

lib/Doctrine/ORM/Proxy/Autoloader.php

@@ -6,7 +6,6 @@ namespace Doctrine\ORM\Proxy;
 
 use Doctrine\Common\Proxy\Autoloader as BaseAutoloader;
 
-/** @deprecated use \Doctrine\Common\Proxy\Autoloader instead */
 class Autoloader extends BaseAutoloader
 {
 }

lib/Doctrine/ORM/Proxy/DefaultProxyClassNameResolver.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Proxy;
+
+use Doctrine\Persistence\Mapping\ProxyClassNameResolver;
+use Doctrine\Persistence\Proxy;
+
+use function get_class;
+use function strrpos;
+use function substr;
+
+/**
+ * Class-related functionality for objects that might or not be proxy objects
+ * at the moment.
+ */
+final class DefaultProxyClassNameResolver implements ProxyClassNameResolver
+{
+    public function resolveClassName(string $className): string
+    {
+        $pos = strrpos($className, '\\' . Proxy::MARKER . '\\');
+
+        if ($pos === false) {
+            return $className;
+        }
+
+        return substr($className, $pos + Proxy::MARKER_LENGTH + 2);
+    }
+
+    /**
+     * @param object $object
+     *
+     * @return class-string
+     */
+    public static function getClass($object): string
+    {
+        return (new self())->resolveClassName(get_class($object));
+    }
+}

lib/Doctrine/ORM/Proxy/InternalProxy.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Proxy;
+
+use Doctrine\Persistence\Proxy;
+
+/**
+ * @internal
+ *
+ * @template T of object
+ * @template-extends Proxy<T>
+ *
+ * @method void __setInitialized(bool $initialized)
+ */
+interface InternalProxy extends Proxy
+{
+}

lib/Doctrine/ORM/Proxy/Proxy.php

@@ -10,7 +10,11 @@ use Doctrine\Common\Proxy\Proxy as BaseProxy;
  * Interface for proxy classes.
  *
  * @deprecated 2.14. Use \Doctrine\Persistence\Proxy instead
+ *
+ * @template T of object
+ * @template-extends BaseProxy<T>
+ * @template-extends InternalProxy<T>
  */
-interface Proxy extends BaseProxy
+interface Proxy extends BaseProxy, InternalProxy
 {
 }

lib/Doctrine/ORM/Proxy/ProxyFactory.php

@@ -9,9 +9,10 @@ use Doctrine\Common\Proxy\AbstractProxyFactory;
 use Doctrine\Common\Proxy\Proxy as CommonProxy;
 use Doctrine\Common\Proxy\ProxyDefinition;
 use Doctrine\Common\Proxy\ProxyGenerator;
-use Doctrine\Common\Util\ClassUtils;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\EntityNotFoundException;
+use Doctrine\ORM\ORMInvalidArgumentException;
 use Doctrine\ORM\Persisters\Entity\EntityPersister;
 use Doctrine\ORM\Proxy\Proxy as LegacyProxy;
 use Doctrine\ORM\UnitOfWork;
@@ -20,21 +21,82 @@ use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\Proxy;
 use ReflectionProperty;
 use Symfony\Component\VarExporter\ProxyHelper;
-use Symfony\Component\VarExporter\VarExporter;
+use Throwable;
 
+use function array_combine;
 use function array_flip;
+use function array_intersect_key;
+use function bin2hex;
+use function chmod;
+use function class_exists;
+use function dirname;
+use function file_exists;
+use function file_put_contents;
+use function filemtime;
+use function is_bool;
+use function is_dir;
+use function is_int;
+use function is_writable;
+use function ltrim;
+use function mkdir;
+use function preg_match_all;
+use function random_bytes;
+use function rename;
+use function rtrim;
 use function str_replace;
 use function strpos;
+use function strrpos;
+use function strtr;
 use function substr;
-use function uksort;
+use function ucfirst;
+
+use const DIRECTORY_SEPARATOR;
+use const PHP_VERSION_ID;
 
 /**
  * This factory is used to create proxy objects for entities at runtime.
- *
- * @psalm-type AutogenerateMode = ProxyFactory::AUTOGENERATE_NEVER|ProxyFactory::AUTOGENERATE_ALWAYS|ProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS|ProxyFactory::AUTOGENERATE_EVAL|ProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS_OR_CHANGED
  */
 class ProxyFactory extends AbstractProxyFactory
 {
+    /**
+     * Never autogenerate a proxy and rely that it was generated by some
+     * process before deployment.
+     */
+    public const AUTOGENERATE_NEVER = 0;
+
+    /**
+     * Always generates a new proxy in every request.
+     *
+     * This is only sane during development.
+     */
+    public const AUTOGENERATE_ALWAYS = 1;
+
+    /**
+     * Autogenerate the proxy class when the proxy file does not exist.
+     *
+     * This strategy causes a file_exists() call whenever any proxy is used the
+     * first time in a request.
+     */
+    public const AUTOGENERATE_FILE_NOT_EXISTS = 2;
+
+    /**
+     * Generate the proxy classes using eval().
+     *
+     * This strategy is only sane for development, and even then it gives me
+     * the creeps a little.
+     */
+    public const AUTOGENERATE_EVAL = 3;
+
+    /**
+     * Autogenerate the proxy class when the proxy file does not exist or
+     * when the proxied file changed.
+     *
+     * This strategy causes a file_exists() call whenever any proxy is used the
+     * first time in a request. When the proxied file is changed, the proxy will
+     * be updated.
+     */
+    public const AUTOGENERATE_FILE_NOT_EXISTS_OR_CHANGED = 4;
+
     private const PROXY_CLASS_TEMPLATE = <<<'EOPHP'
 <?php
 
@@ -47,32 +109,11 @@ class <proxyShortClassName> extends \<className> implements \<baseProxyInterface
 {
     <useLazyGhostTrait>
 
-    /**
-     * @internal
-     */
-    public bool $__isCloning = false;
-
-    public function __construct(?\Closure $initializer = null)
-    {
-        self::createLazyGhost($initializer, <skippedProperties>, $this);
-    }
-
     public function __isInitialized(): bool
     {
         return isset($this->lazyObjectState) && $this->isLazyObjectInitialized();
     }
 
-    public function __clone()
-    {
-        $this->__isCloning = true;
-
-        try {
-            $this->__doClone();
-        } finally {
-            $this->__isCloning = false;
-        }
-    }
-
     public function __serialize(): array
     {
         <serializeImpl>
@@ -87,9 +128,15 @@ EOPHP;
     /** @var UnitOfWork The UnitOfWork this factory uses to retrieve persisters */
     private $uow;
 
+    /** @var string */
+    private $proxyDir;
+
     /** @var string */
     private $proxyNs;
 
+    /** @var self::AUTOGENERATE_* */
+    private $autoGenerate;
+
     /**
      * The IdentifierFlattener used for manipulating identifiers
      *
@@ -97,39 +144,118 @@ EOPHP;
      */
     private $identifierFlattener;
 
+    /** @var array<class-string, Closure> */
+    private $proxyFactories = [];
+
+    /** @var bool */
+    private $isLazyGhostObjectEnabled = true;
+
     /**
      * Initializes a new instance of the <tt>ProxyFactory</tt> class that is
      * connected to the given <tt>EntityManager</tt>.
      *
-     * @param EntityManagerInterface $em           The EntityManager the new factory works for.
-     * @param string                 $proxyDir     The directory to use for the proxy classes. It must exist.
-     * @param string                 $proxyNs      The namespace to use for the proxy classes.
-     * @param bool|int               $autoGenerate The strategy for automatically generating proxy classes. Possible
-     *                                             values are constants of {@see ProxyFactory::AUTOGENERATE_*}.
-     * @psalm-param bool|AutogenerateMode $autoGenerate
+     * @param EntityManagerInterface    $em           The EntityManager the new factory works for.
+     * @param string                    $proxyDir     The directory to use for the proxy classes. It must exist.
+     * @param string                    $proxyNs      The namespace to use for the proxy classes.
+     * @param bool|self::AUTOGENERATE_* $autoGenerate The strategy for automatically generating proxy classes.
      */
     public function __construct(EntityManagerInterface $em, $proxyDir, $proxyNs, $autoGenerate = self::AUTOGENERATE_NEVER)
     {
-        $proxyGenerator = new ProxyGenerator($proxyDir, $proxyNs);
+        if (! $em->getConfiguration()->isLazyGhostObjectEnabled()) {
+            if (PHP_VERSION_ID >= 80100) {
+                Deprecation::trigger(
+                    'doctrine/orm',
+                    'https://github.com/doctrine/orm/pull/10837/',
+                    'Not enabling lazy ghost objects is deprecated and will not be supported in Doctrine ORM 3.0. Ensure Doctrine\ORM\Configuration::setLazyGhostObjectEnabled(true) is called to enable them.'
+                );
+            }
 
-        if ($em->getConfiguration()->isLazyGhostObjectEnabled()) {
-            $proxyGenerator->setPlaceholder('baseProxyInterface', Proxy::class);
-            $proxyGenerator->setPlaceholder('useLazyGhostTrait', Closure::fromCallable([$this, 'generateUseLazyGhostTrait']));
-            $proxyGenerator->setPlaceholder('skippedProperties', Closure::fromCallable([$this, 'generateSkippedProperties']));
-            $proxyGenerator->setPlaceholder('serializeImpl', Closure::fromCallable([$this, 'generateSerializeImpl']));
-            $proxyGenerator->setProxyClassTemplate(self::PROXY_CLASS_TEMPLATE);
-        } else {
+            $this->isLazyGhostObjectEnabled = false;
+
+            $proxyGenerator = new ProxyGenerator($proxyDir, $proxyNs);
             $proxyGenerator->setPlaceholder('baseProxyInterface', LegacyProxy::class);
+
+            parent::__construct($proxyGenerator, $em->getMetadataFactory(), $autoGenerate);
         }
 
-        parent::__construct($proxyGenerator, $em->getMetadataFactory(), $autoGenerate);
+        if (! $proxyDir) {
+            throw ORMInvalidArgumentException::proxyDirectoryRequired();
+        }
+
+        if (! $proxyNs) {
+            throw ORMInvalidArgumentException::proxyNamespaceRequired();
+        }
+
+        if (is_int($autoGenerate) ? $autoGenerate < 0 || $autoGenerate > 4 : ! is_bool($autoGenerate)) {
+            throw ORMInvalidArgumentException::invalidAutoGenerateMode($autoGenerate);
+        }
 
         $this->em                  = $em;
         $this->uow                 = $em->getUnitOfWork();
+        $this->proxyDir            = $proxyDir;
         $this->proxyNs             = $proxyNs;
+        $this->autoGenerate        = (int) $autoGenerate;
         $this->identifierFlattener = new IdentifierFlattener($this->uow, $em->getMetadataFactory());
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function getProxy($className, array $identifier)
+    {
+        if (! $this->isLazyGhostObjectEnabled) {
+            return parent::getProxy($className, $identifier);
+        }
+
+        $proxyFactory = $this->proxyFactories[$className] ?? $this->getProxyFactory($className);
+
+        return $proxyFactory($identifier);
+    }
+
+    /**
+     * Generates proxy classes for all given classes.
+     *
+     * @param ClassMetadata[] $classes  The classes (ClassMetadata instances) for which to generate proxies.
+     * @param string|null     $proxyDir The target directory of the proxy classes. If not specified, the
+     *                                  directory configured on the Configuration of the EntityManager used
+     *                                  by this factory is used.
+     *
+     * @return int Number of generated proxies.
+     */
+    public function generateProxyClasses(array $classes, $proxyDir = null)
+    {
+        if (! $this->isLazyGhostObjectEnabled) {
+            return parent::generateProxyClasses($classes, $proxyDir);
+        }
+
+        $generated = 0;
+
+        foreach ($classes as $class) {
+            if ($this->skipClass($class)) {
+                continue;
+            }
+
+            $proxyFileName  = $this->getProxyFileName($class->getName(), $proxyDir ?: $this->proxyDir);
+            $proxyClassName = self::generateProxyClassName($class->getName(), $this->proxyNs);
+
+            $this->generateProxyClass($class, $proxyFileName, $proxyClassName);
+
+            ++$generated;
+        }
+
+        return $generated;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @deprecated ProxyFactory::resetUninitializedProxy() is deprecated and will be removed in version 3.0 of doctrine/orm.
+     */
+    public function resetUninitializedProxy(CommonProxy $proxy)
+    {
+        return parent::resetUninitializedProxy($proxy);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -142,23 +268,19 @@ EOPHP;
 
     /**
      * {@inheritDoc}
+     *
+     * @deprecated ProxyFactory::createProxyDefinition() is deprecated and will be removed in version 3.0 of doctrine/orm.
      */
     protected function createProxyDefinition($className)
     {
         $classMetadata   = $this->em->getClassMetadata($className);
         $entityPersister = $this->uow->getEntityPersister($className);
 
-        if ($this->em->getConfiguration()->isLazyGhostObjectEnabled()) {
-            $initializer = $this->createLazyInitializer($classMetadata, $entityPersister);
-            $cloner      = static function (): void {
-            };
-        } else {
-            $initializer = $this->createInitializer($classMetadata, $entityPersister);
-            $cloner      = $this->createCloner($classMetadata, $entityPersister);
-        }
+        $initializer = $this->createInitializer($classMetadata, $entityPersister);
+        $cloner      = $this->createCloner($classMetadata, $entityPersister);
 
         return new ProxyDefinition(
-            ClassUtils::generateProxyClassName($className, $this->proxyNs),
+            self::generateProxyClassName($className, $this->proxyNs),
             $classMetadata->getIdentifierFieldNames(),
             $classMetadata->getReflectionProperties(),
             $initializer,
@@ -169,6 +291,8 @@ EOPHP;
     /**
      * Creates a closure capable of initializing a proxy
      *
+     * @deprecated ProxyFactory::createInitializer() is deprecated and will be removed in version 3.0 of doctrine/orm.
+     *
      * @psalm-return Closure(CommonProxy):void
      *
      * @throws EntityNotFoundException
@@ -204,7 +328,17 @@ EOPHP;
 
             $identifier = $classMetadata->getIdentifierValues($proxy);
 
-            if ($entityPersister->loadById($identifier, $proxy) === null) {
+            try {
+                $entity = $entityPersister->loadById($identifier, $proxy);
+            } catch (Throwable $exception) {
+                $proxy->__setInitializer($initializer);
+                $proxy->__setCloner($cloner);
+                $proxy->__setInitialized(false);
+
+                throw $exception;
+            }
+
+            if ($entity === null) {
                 $proxy->__setInitializer($initializer);
                 $proxy->__setCloner($cloner);
                 $proxy->__setInitialized(false);
@@ -220,24 +354,24 @@ EOPHP;
     /**
      * Creates a closure capable of initializing a proxy
      *
-     * @return Closure(Proxy):void
+     * @return Closure(InternalProxy, InternalProxy):void
      *
      * @throws EntityNotFoundException
      */
-    private function createLazyInitializer(ClassMetadata $classMetadata, EntityPersister $entityPersister): Closure
+    private function createLazyInitializer(ClassMetadata $classMetadata, EntityPersister $entityPersister, IdentifierFlattener $identifierFlattener): Closure
     {
-        return function (Proxy $proxy) use ($entityPersister, $classMetadata): void {
-            $identifier = $classMetadata->getIdentifierValues($proxy);
-            $entity     = $entityPersister->loadById($identifier, $proxy->__isCloning ? null : $proxy);
+        return static function (InternalProxy $proxy, InternalProxy $original) use ($entityPersister, $classMetadata, $identifierFlattener): void {
+            $identifier = $classMetadata->getIdentifierValues($original);
+            $entity     = $entityPersister->loadById($identifier, $original);
 
             if ($entity === null) {
                 throw EntityNotFoundException::fromClassNameAndIdentifier(
                     $classMetadata->getName(),
-                    $this->identifierFlattener->flattenIdentifier($classMetadata, $identifier)
+                    $identifierFlattener->flattenIdentifier($classMetadata, $identifier)
                 );
             }
 
-            if (! $proxy->__isCloning) {
+            if ($proxy === $original) {
                 return;
             }
 
@@ -248,7 +382,6 @@ EOPHP;
                     continue;
                 }
 
-                $property->setAccessible(true);
                 $property->setValue($proxy, $property->getValue($entity));
             }
         };
@@ -257,6 +390,8 @@ EOPHP;
     /**
      * Creates a closure capable of finalizing state a cloned proxy
      *
+     * @deprecated ProxyFactory::createCloner() is deprecated and will be removed in version 3.0 of doctrine/orm.
+     *
      * @psalm-return Closure(CommonProxy):void
      *
      * @throws EntityNotFoundException
@@ -293,6 +428,144 @@ EOPHP;
         };
     }
 
+    private function getProxyFileName(string $className, string $baseDirectory): string
+    {
+        $baseDirectory = $baseDirectory ?: $this->proxyDir;
+
+        return rtrim($baseDirectory, DIRECTORY_SEPARATOR) . DIRECTORY_SEPARATOR . InternalProxy::MARKER
+            . str_replace('\\', '', $className) . '.php';
+    }
+
+    private function getProxyFactory(string $className): Closure
+    {
+        $skippedProperties = [];
+        $class             = $this->em->getClassMetadata($className);
+        $identifiers       = array_flip($class->getIdentifierFieldNames());
+        $filter            = ReflectionProperty::IS_PUBLIC | ReflectionProperty::IS_PROTECTED | ReflectionProperty::IS_PRIVATE;
+        $reflector         = $class->getReflectionClass();
+
+        while ($reflector) {
+            foreach ($reflector->getProperties($filter) as $property) {
+                $name = $property->name;
+
+                if ($property->isStatic() || (($class->hasField($name) || $class->hasAssociation($name)) && ! isset($identifiers[$name]))) {
+                    continue;
+                }
+
+                $prefix = $property->isPrivate() ? "\0" . $property->class . "\0" : ($property->isProtected() ? "\0*\0" : '');
+
+                $skippedProperties[$prefix . $name] = true;
+            }
+
+            $filter    = ReflectionProperty::IS_PRIVATE;
+            $reflector = $reflector->getParentClass();
+        }
+
+        $className        = $class->getName(); // aliases and case sensitivity
+        $entityPersister  = $this->uow->getEntityPersister($className);
+        $initializer      = $this->createLazyInitializer($class, $entityPersister, $this->identifierFlattener);
+        $proxyClassName   = $this->loadProxyClass($class);
+        $identifierFields = array_intersect_key($class->getReflectionProperties(), $identifiers);
+
+        $proxyFactory = Closure::bind(static function (array $identifier) use ($initializer, $skippedProperties, $identifierFields, $className): InternalProxy {
+            $proxy = self::createLazyGhost(static function (InternalProxy $object) use ($initializer, &$proxy): void {
+                $initializer($object, $proxy);
+            }, $skippedProperties);
+
+            foreach ($identifierFields as $idField => $reflector) {
+                if (! isset($identifier[$idField])) {
+                    throw ORMInvalidArgumentException::missingPrimaryKeyValue($className, $idField);
+                }
+
+                $reflector->setValue($proxy, $identifier[$idField]);
+            }
+
+            return $proxy;
+        }, null, $proxyClassName);
+
+        return $this->proxyFactories[$className] = $proxyFactory;
+    }
+
+    private function loadProxyClass(ClassMetadata $class): string
+    {
+        $proxyClassName = self::generateProxyClassName($class->getName(), $this->proxyNs);
+
+        if (class_exists($proxyClassName, false)) {
+            return $proxyClassName;
+        }
+
+        if ($this->autoGenerate === self::AUTOGENERATE_EVAL) {
+            $this->generateProxyClass($class, null, $proxyClassName);
+
+            return $proxyClassName;
+        }
+
+        $fileName = $this->getProxyFileName($class->getName(), $this->proxyDir);
+
+        switch ($this->autoGenerate) {
+            case self::AUTOGENERATE_FILE_NOT_EXISTS_OR_CHANGED:
+                if (file_exists($fileName) && filemtime($fileName) >= filemtime($class->getReflectionClass()->getFileName())) {
+                    break;
+                }
+                // no break
+            case self::AUTOGENERATE_FILE_NOT_EXISTS:
+                if (file_exists($fileName)) {
+                    break;
+                }
+                // no break
+            case self::AUTOGENERATE_ALWAYS:
+                $this->generateProxyClass($class, $fileName, $proxyClassName);
+                break;
+        }
+
+        require $fileName;
+
+        return $proxyClassName;
+    }
+
+    private function generateProxyClass(ClassMetadata $class, ?string $fileName, string $proxyClassName): void
+    {
+        $i            = strrpos($proxyClassName, '\\');
+        $placeholders = [
+            '<className>' => $class->getName(),
+            '<namespace>' => substr($proxyClassName, 0, $i),
+            '<proxyShortClassName>' => substr($proxyClassName, 1 + $i),
+            '<baseProxyInterface>' => InternalProxy::class,
+        ];
+
+        preg_match_all('(<([a-zA-Z]+)>)', self::PROXY_CLASS_TEMPLATE, $placeholderMatches);
+
+        foreach (array_combine($placeholderMatches[0], $placeholderMatches[1]) as $placeholder => $name) {
+            $placeholders[$placeholder] ?? $placeholders[$placeholder] = $this->{'generate' . ucfirst($name)}($class);
+        }
+
+        $proxyCode = strtr(self::PROXY_CLASS_TEMPLATE, $placeholders);
+
+        if (! $fileName) {
+            if (! class_exists($proxyClassName)) {
+                eval(substr($proxyCode, 5));
+            }
+
+            return;
+        }
+
+        $parentDirectory = dirname($fileName);
+
+        if (! is_dir($parentDirectory) && ! @mkdir($parentDirectory, 0775, true)) {
+            throw ORMInvalidArgumentException::proxyDirectoryNotWritable($this->proxyDir);
+        }
+
+        if (! is_writable($parentDirectory)) {
+            throw ORMInvalidArgumentException::proxyDirectoryNotWritable($this->proxyDir);
+        }
+
+        $tmpFileName = $fileName . '.' . bin2hex(random_bytes(12));
+
+        file_put_contents($tmpFileName, $proxyCode);
+        @chmod($tmpFileName, 0664);
+        rename($tmpFileName, $fileName);
+    }
+
     private function generateUseLazyGhostTrait(ClassMetadata $class): string
     {
         $code = ProxyHelper::generateLazyGhost($class->getReflectionClass());
@@ -304,52 +577,18 @@ EOPHP;
             isLazyObjectInitialized as private;
             createLazyGhost as private;
             resetLazyObject as private;
-            __clone as private __doClone;
         }'), $code);
 
         return $code;
     }
 
-    private function generateSkippedProperties(ClassMetadata $class): string
-    {
-        $skippedProperties = ['__isCloning' => true];
-        $identifiers       = array_flip($class->getIdentifierFieldNames());
-        $filter            = ReflectionProperty::IS_PUBLIC | ReflectionProperty::IS_PROTECTED | ReflectionProperty::IS_PRIVATE;
-        $reflector         = $class->getReflectionClass();
-
-        while ($reflector) {
-            foreach ($reflector->getProperties($filter) as $property) {
-                $name = $property->getName();
-
-                if ($property->isStatic() || (($class->hasField($name) || $class->hasAssociation($name)) && ! isset($identifiers[$name]))) {
-                    continue;
-                }
-
-                $prefix = $property->isPrivate() ? "\0" . $property->getDeclaringClass()->getName() . "\0" : ($property->isProtected() ? "\0*\0" : '');
-
-                $skippedProperties[$prefix . $name] = true;
-            }
-
-            $filter    = ReflectionProperty::IS_PRIVATE;
-            $reflector = $reflector->getParentClass();
-        }
-
-        uksort($skippedProperties, 'strnatcmp');
-
-        $code = VarExporter::export($skippedProperties);
-        $code = str_replace(VarExporter::export($class->getName()), 'parent::class', $code);
-        $code = str_replace("\n", "\n        ", $code);
-
-        return $code;
-    }
-
     private function generateSerializeImpl(ClassMetadata $class): string
     {
         $reflector  = $class->getReflectionClass();
         $properties = $reflector->hasMethod('__serialize') ? 'parent::__serialize()' : '(array) $this';
 
         $code = '$properties = ' . $properties . ';
-        unset($properties["\0" . self::class . "\0lazyObjectState"], $properties[\'__isCloning\']);
+        unset($properties["\0" . self::class . "\0lazyObjectState"]);
 
         ';
 
@@ -360,7 +599,7 @@ EOPHP;
         return $code . '$data = [];
 
         foreach (parent::__sleep() as $name) {
-            $value = $properties[$k = $name] ?? $properties[$k = "\0*\0$name"] ?? $properties[$k = "\0' . $reflector->getName() . '\0$name"] ?? $k = null;
+            $value = $properties[$k = $name] ?? $properties[$k = "\0*\0$name"] ?? $properties[$k = "\0' . $reflector->name . '\0$name"] ?? $k = null;
 
             if (null === $k) {
                 trigger_error(sprintf(\'serialize(): "%s" returned as member variable from __sleep() but does not exist\', $name), \E_USER_NOTICE);
@@ -371,4 +610,9 @@ EOPHP;
 
         return $data;';
     }
+
+    private static function generateProxyClassName(string $className, string $proxyNamespace): string
+    {
+        return rtrim($proxyNamespace, '\\') . '\\' . Proxy::MARKER . '\\' . ltrim($className, '\\');
+    }
 }

lib/Doctrine/ORM/Query.php

@@ -44,8 +44,10 @@ use function stripos;
 
 /**
  * A Query object represents a DQL query.
+ *
+ * @final
  */
-final class Query extends AbstractQuery
+class Query extends AbstractQuery
 {
     /**
      * A query object is in CLEAN state when it has NO unparsed/unprocessed DQL parts.

lib/Doctrine/ORM/Query/AST/ConditionalFactor.php

@@ -9,7 +9,7 @@ namespace Doctrine\ORM\Query\AST;
  *
  * @link    www.doctrine-project.org
  */
-class ConditionalFactor extends Node
+class ConditionalFactor extends Node implements Phase2OptimizableConditional
 {
     /** @var bool */
     public $not = false;

lib/Doctrine/ORM/Query/AST/ConditionalPrimary.php

@@ -9,12 +9,12 @@ namespace Doctrine\ORM\Query\AST;
  *
  * @link    www.doctrine-project.org
  */
-class ConditionalPrimary extends Node
+class ConditionalPrimary extends Node implements Phase2OptimizableConditional
 {
     /** @var Node|null */
     public $simpleConditionalExpression;
 
-    /** @var ConditionalExpression|null */
+    /** @var ConditionalExpression|Phase2OptimizableConditional|null */
     public $conditionalExpression;
 
     /** @return bool */

lib/Doctrine/ORM/Query/AST/ConditionalTerm.php

@@ -9,7 +9,7 @@ namespace Doctrine\ORM\Query\AST;
  *
  * @link    www.doctrine-project.org
  */
-class ConditionalTerm extends Node
+class ConditionalTerm extends Node implements Phase2OptimizableConditional
 {
     /** @var mixed[] */
     public $conditionalFactors = [];

lib/Doctrine/ORM/Query/AST/HavingClause.php

@@ -6,10 +6,10 @@ namespace Doctrine\ORM\Query\AST;
 
 class HavingClause extends Node
 {
-    /** @var ConditionalExpression */
+    /** @var ConditionalExpression|Phase2OptimizableConditional */
     public $conditionalExpression;
 
-    /** @param ConditionalExpression $conditionalExpression */
+    /** @param ConditionalExpression|Phase2OptimizableConditional $conditionalExpression */
     public function __construct($conditionalExpression)
     {
         $this->conditionalExpression = $conditionalExpression;

lib/Doctrine/ORM/Query/AST/Join.php

@@ -25,7 +25,7 @@ class Join extends Node
     /** @var Node|null */
     public $joinAssociationDeclaration = null;
 
-    /** @var ConditionalExpression|null */
+    /** @var ConditionalExpression|Phase2OptimizableConditional|null */
     public $conditionalExpression = null;
 
     /**

lib/Doctrine/ORM/Query/AST/Phase2OptimizableConditional.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Query\AST;
+
+/**
+ * Marks types that can be used in place of a ConditionalExpression as a phase
+ * 2 optimization.
+ *
+ * @internal
+ *
+ * @psalm-inheritors ConditionalPrimary|ConditionalFactor|ConditionalTerm
+ */
+interface Phase2OptimizableConditional
+{
+}

lib/Doctrine/ORM/Query/AST/WhenClause.php

@@ -11,15 +11,15 @@ namespace Doctrine\ORM\Query\AST;
  */
 class WhenClause extends Node
 {
-    /** @var ConditionalExpression */
+    /** @var ConditionalExpression|Phase2OptimizableConditional */
     public $caseConditionExpression;
 
     /** @var mixed */
     public $thenScalarExpression = null;
 
     /**
-     * @param ConditionalExpression $caseConditionExpression
-     * @param mixed                 $thenScalarExpression
+     * @param ConditionalExpression|Phase2OptimizableConditional $caseConditionExpression
+     * @param mixed                                              $thenScalarExpression
      */
     public function __construct($caseConditionExpression, $thenScalarExpression)
     {

lib/Doctrine/ORM/Query/AST/WhereClause.php

@@ -11,10 +11,10 @@ namespace Doctrine\ORM\Query\AST;
  */
 class WhereClause extends Node
 {
-    /** @var ConditionalExpression|ConditionalTerm */
+    /** @var ConditionalExpression|Phase2OptimizableConditional */
     public $conditionalExpression;
 
-    /** @param ConditionalExpression $conditionalExpression */
+    /** @param ConditionalExpression|Phase2OptimizableConditional $conditionalExpression */
     public function __construct($conditionalExpression)
     {
         $this->conditionalExpression = $conditionalExpression;