Merge pull request #10737 from nicolas-grekas/lexer-deprec

Merge 2.14.x up into 2.15.x

.doctrine-project.json

@@ -12,21 +12,33 @@
             "upcoming": true
         },
         {
-            "name": "2.14",
-            "branchName": "2.14.x",
-            "slug": "2.14",
+            "name": "2.16",
+            "branchName": "2.16.x",
+            "slug": "2.16",
             "upcoming": true
         },
         {
-            "name": "2.13",
-            "branchName": "2.13.x",
-            "slug": "2.13",
+            "name": "2.15",
+            "branchName": "2.15.x",
+            "slug": "2.15",
             "current": true,
             "aliases": [
                 "current",
                 "stable"
             ]
         },
+        {
+            "name": "2.14",
+            "branchName": "2.14.x",
+            "slug": "2.14",
+            "maintained": false
+        },
+        {
+            "name": "2.13",
+            "branchName": "2.13.x",
+            "slug": "2.13",
+            "maintained": false
+        },
         {
             "name": "2.12",
             "branchName": "2.12.x",

.github/workflows/coding-standards.yml

@@ -24,4 +24,4 @@ on:
 
 jobs:
   coding-standards:
-    uses: "doctrine/.github/.github/workflows/coding-standards.yml@2.1.0"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@3.0.0"

.github/workflows/continuous-integration.yml

@@ -43,6 +43,8 @@ jobs:
           - "default"
         extension:
           - "pdo_sqlite"
+        proxy:
+          - "common"
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
@@ -53,6 +55,10 @@ jobs:
           - php-version: "8.2"
             dbal-version: "default"
             extension: "sqlite3"
+          - php-version: "8.1"
+            dbal-version: "default"
+            proxy: "lazy-ghost"
+            extension: "pdo_sqlite"
 
     steps:
       - name: "Checkout"
@@ -66,7 +72,7 @@ jobs:
           php-version: "${{ matrix.php-version }}"
           extensions: "apcu, pdo, ${{ matrix.extension }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
@@ -81,11 +87,13 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
       - name: "Run PHPUnit with Second Level Cache"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v3"
@@ -108,13 +116,18 @@ jobs:
           - "3@dev"
         postgres-version:
           - "15"
+        extension:
+          - pdo_pgsql
+          - pgsql
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
             postgres-version: "14"
+            extension: pdo_pgsql
           - php-version: "8.2"
             dbal-version: "default"
             postgres-version: "9.6"
+            extension: pdo_pgsql
 
     services:
       postgres:
@@ -138,8 +151,9 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
+          extensions: "pgsql pdo_pgsql"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
@@ -211,7 +225,7 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
           extensions: "${{ matrix.extension }}"
 
       - name: "Install dependencies with Composer"
@@ -276,7 +290,7 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
           extensions: "${{ matrix.extension }}"
 
       - name: "Require specific DBAL version"
@@ -327,7 +341,7 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"

.github/workflows/phpbench.yml

@@ -45,7 +45,7 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Cache dependencies installed with composer"
         uses: "actions/cache@v3"

.github/workflows/release-on-milestone-closed.yml

@@ -7,7 +7,7 @@ on:
 
 jobs:
   release:
-    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@2.1.0"
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@3.0.0"
     secrets:
       GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
       GIT_AUTHOR_NAME: ${{ secrets.GIT_AUTHOR_NAME }}

.github/workflows/static-analysis.yml

@@ -1,4 +1,3 @@
-
 name: "Static Analysis"
 
 on:
@@ -31,18 +30,14 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-version:
-          - "8.1"
         dbal-version:
           - "default"
         persistence-version:
           - "default"
         include:
-          - php-version: "8.1"
-            dbal-version: "2.13"
+          - dbal-version: "2.13"
             persistence-version: "default"
-          - php-version: "8.1"
-            dbal-version: "default"
+          - dbal-version: "default"
             persistence-version: "2.5"
 
     steps:
@@ -53,15 +48,14 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           coverage: "none"
-          php-version: "${{ matrix.php-version }}"
+          php-version: "8.2"
 
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Require specific persistence version"
-        run: "composer require doctrine/persistence ^${{ matrix.persistence-version }} --no-update"
-        if: "${{ matrix.persistence-version != 'default' }}"
+        run: "composer require doctrine/persistence ^$([ ${{ matrix.persistence-version }} = default ] && echo '3.1' || echo ${{ matrix.persistence-version }}) --no-update"
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"
@@ -86,9 +80,6 @@ jobs:
 
     strategy:
       fail-fast: false
-      matrix:
-        php-version:
-          - "8.1"
 
     steps:
       - name: "Checkout code"
@@ -98,7 +89,10 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           coverage: "none"
-          php-version: "${{ matrix.php-version }}"
+          php-version: "8.2"
+
+      - name: "Require specific persistence version"
+        run: "composer require doctrine/persistence ^3.1 --no-update"
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v2"

.gitignore

@@ -15,5 +15,6 @@ vendor/
 /tests/Doctrine/Performance/history.db
 /.phpcs-cache
 composer.lock
+.phpunit.cache
 .phpunit.result.cache
 /*.phpunit.xml

CONTRIBUTING.md

@@ -40,6 +40,11 @@ cd orm
 composer install
 ```
 
+You will also need to enable the PHP extension that provides the SQLite driver
+for PDO: `pdo_sqlite`. How to do so depends on your system, but checking that it
+is enabled can universally be done with `php -m`: that command should list the
+extension.
+
 To run the testsuite against another database, copy the ``phpunit.xml.dist``
 to for example ``mysql.phpunit.xml`` and edit the parameters. You can
 take a look at the ``ci/github/phpunit`` directory for some examples. Then run:

README.md

@@ -1,7 +1,7 @@
-| [3.0.x][3.0] | [2.14.x][2.14] | [2.13.x][2.13] |
+| [3.0.x][3.0] | [2.16.x][2.16] | [2.15.x][2.15] |
 |:----------------:|:----------------:|:----------:|
-| [![Build status][3.0 image]][3.0] | [![Build status][2.14 image]][2.14] | [![Build status][2.13 image]][2.13] |
-| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.14 coverage image]][2.14 coverage] | [![Coverage Status][2.13 coverage image]][2.13 coverage]  |
+| [![Build status][3.0 image]][3.0] | [![Build status][2.16 image]][2.16] | [![Build status][2.15 image]][2.15] |
+| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.16 coverage image]][2.16 coverage] | [![Coverage Status][2.15 coverage image]][2.15 coverage]  |
 
 [<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
 
@@ -22,11 +22,11 @@ without requiring unnecessary code duplication.
   [3.0]: https://github.com/doctrine/orm/tree/3.0.x
   [3.0 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.0.x/graph/badge.svg
   [3.0 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.0.x
-  [2.14 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.14.x
-  [2.14]: https://github.com/doctrine/orm/tree/2.14.x
-  [2.14 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.14.x/graph/badge.svg
-  [2.14 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.14.x
-  [2.13 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.13.x
-  [2.13]: https://github.com/doctrine/orm/tree/2.13.x
-  [2.13 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.13.x/graph/badge.svg
-  [2.13 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.13.x
+  [2.16 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.16.x
+  [2.16]: https://github.com/doctrine/orm/tree/2.16.x
+  [2.16 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.16.x/graph/badge.svg
+  [2.16 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.16.x
+  [2.15 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.15.x
+  [2.15]: https://github.com/doctrine/orm/tree/2.15.x
+  [2.15 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.15.x/graph/badge.svg
+  [2.15 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.15.x

UPGRADE.md

@@ -1,5 +1,114 @@
+# Upgrade to 2.15
+
+## Deprecated configuring `JoinColumn` on the inverse side of one-to-one associations
+
+For one-to-one associations, the side using the `mappedBy` attribute is the inverse side.
+The owning side is the entity with the table containing the foreign key. Using `JoinColumn`
+configuration on the _inverse_ side now triggers a deprecation notice and will be an error
+in 3.0.
+
+## Deprecated overriding fields or associations not declared in mapped superclasses
+
+As stated in the documentation, fields and associations may only be overridden when being inherited
+from mapped superclasses. Overriding them for parent entity classes now triggers a deprecation notice
+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 
+be declared by adding the appropriate configuration for the root entity.
+
+## Deprecated stubs for "concrete table inheritance"
+
+This third way of mapping class inheritance was never implemented. Code stubs are
+now deprecated and will be removed in 3.0.
+
+* `\Doctrine\ORM\Mapping\ClassMetadataInfo::INHERITANCE_TYPE_TABLE_PER_CLASS` constant
+* `\Doctrine\ORM\Mapping\ClassMetadataInfo::isInheritanceTypeTablePerClass()` method
+* Using `TABLE_PER_CLASS` as the value for the `InheritanceType` attribute or annotation
+  or in XML configuration files.
+
+# Upgrade to 2.14
+
+## Deprecated `Doctrine\ORM\Persisters\Exception\UnrecognizedField::byName($field)` method.
+
+Use `Doctrine\ORM\Persisters\Exception\UnrecognizedField::byFullyQualifiedName($className, $field)` instead.
+
+## Deprecated constants of `Doctrine\ORM\Internal\CommitOrderCalculator`
+
+The following public constants have been deprecated:
+
+* `CommitOrderCalculator::NOT_VISITED`
+* `CommitOrderCalculator::IN_PROGRESS`
+* `CommitOrderCalculator::VISITED`
+
+These constants were used for internal purposes. Relying on them is discouraged.
+
+## Deprecated `Doctrine\ORM\Query\AST\InExpression`
+
+The AST parser will create a `InListExpression` or a `InSubselectExpression` when
+encountering an `IN ()` DQL expression instead of a generic `InExpression`.
+
+As a consequence, `SqlWalker::walkInExpression()` has been deprecated in favor of
+`SqlWalker::walkInListExpression()` and `SqlWalker::walkInSubselectExpression()`.
+
+## Deprecated constructing a `CacheKey` without `$hash`
+
+The `Doctrine\ORM\Cache\CacheKey` class has an explicit constructor now with
+an optional parameter `$hash`. That parameter will become mandatory in 3.0.
+
+## Deprecated `AttributeDriver::$entityAnnotationClasses`
+
+If you need to change the behavior of `AttributeDriver::isTransient()`,
+override that method instead.
+
+## Deprecated incomplete schema updates
+
+Using `orm:schema-tool:update` without passing the `--complete` flag is
+deprecated. Use schema asset filtering if you need to preserve assets not
+managed by DBAL.
+
+Likewise, calling `SchemaTool::updateSchema()` or
+`SchemaTool::getUpdateSchemaSql()` with a second argument is deprecated.
+
+## Deprecated annotation mapping driver.
+
+Please switch to one of the other mapping drivers. Native attributes which PHP
+supports since version 8.0 are probably your best option.
+
+As a consequence, the following methods are deprecated:
+- `ORMSetup::createAnnotationMetadataConfiguration`
+- `ORMSetup::createDefaultAnnotationDriver`
+
+The marker interface `Doctrine\ORM\Mapping\Annotation` is deprecated as well.
+All annotation/attribute classes implement
+`Doctrine\ORM\Mapping\MappingAttribute` now.
+
+## Deprecated `Doctrine\ORM\Proxy\Proxy` interface.
+
+Use `Doctrine\Persistence\Proxy` instead to check whether proxies are initialized.
+
+## Deprecated `Doctrine\ORM\Event\LifecycleEventArgs` class.
+
+It will be removed in 3.0. Use one of the dedicated event classes instead:
+
+* `Doctrine\ORM\Event\PrePersistEventArgs`
+* `Doctrine\ORM\Event\PreUpdateEventArgs`
+* `Doctrine\ORM\Event\PreRemoveEventArgs`
+* `Doctrine\ORM\Event\PostPersistEventArgs`
+* `Doctrine\ORM\Event\PostUpdateEventArgs`
+* `Doctrine\ORM\Event\PostRemoveEventArgs`
+* `Doctrine\ORM\Event\PostLoadEventArgs`
+
 # Upgrade to 2.13
 
+## Deprecated `EntityManager::create()`
+
+The constructor of `EntityManager` is now public and should be used instead of the `create()` method.
+However, the constructor expects a `Connection` while `create()` accepted an array with connection parameters.
+You can pass that array to DBAL's `Doctrine\DBAL\DriverManager::getConnection()` method to bootstrap the
+connection.
+
 ## Deprecated `QueryBuilder` methods and constants.
 
 1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.
@@ -191,8 +300,8 @@ The following methods have been deprecated:
 
 - `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryMapping()`
 - `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryResultClassMapping()`
-- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativQueryResultSetMapping()`
-- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativQueryEntityResultMapping()`
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryResultSetMapping()`
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryEntityResultMapping()`
 
 ## Deprecated classes related to Doctrine 1 and reverse engineering
 
@@ -394,7 +503,7 @@ function foo(EntityManagerInterface $entityManager, callable $func) {
     if (method_exists($entityManager, 'wrapInTransaction')) {
         return $entityManager->wrapInTransaction($func);
     }
-    
+
     return $entityManager->transactional($func);
 }
 ```
@@ -460,7 +569,7 @@ implementation. To work around this:
 * As a quick workaround, you can lock the doctrine/cache dependency to work around this: `composer require doctrine/cache ^1.11`.
   Note that this is only recommended as a bandaid fix, as future versions of ORM will no longer work with doctrine/cache
   1.11.
-  
+
 ## Deprecated: doctrine/cache for metadata caching
 
 The `Doctrine\ORM\Configuration#setMetadataCacheImpl()` method is deprecated and should no longer be used. Please use
@@ -485,12 +594,12 @@ Note that `toIterable()` yields results of the query, unlike `iterate()` which y
 
 # Upgrade to 2.7
 
-## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods	
+## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods
 
 Method `Doctrine\ORM\AbstractQuery#useResultCache()` which could be used for both enabling and disabling the cache
-(depending on passed flag) was split into two.	
+(depending on passed flag) was split into two.
 
-## Minor BC BREAK: paginator output walkers aren't be called anymore on sub-queries for queries without max results  
+## Minor BC BREAK: paginator output walkers aren't be called anymore on sub-queries for queries without max results
 
 To optimize DB interaction, `Doctrine\ORM\Tools\Pagination\Paginator` no longer fetches identifiers to be able to
 perform the pagination with join collections when max results isn't set in the query.
@@ -509,7 +618,7 @@ In the last patch of the `v2.6.x` series, we fixed a bug that was not converting
 In order to not break BC we've introduced a way to enable the fixed behavior using a boolean constructor argument. This
 argument will be removed in 3.0 and the default behavior will be the fixed one.
 
-## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`	
+## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`
 
 Method `Doctrine\ORM\AbstractQuery#useResultCache()` is deprecated because it is split into `enableResultCache()`
 and `disableResultCache()`. It will be removed in 3.0.
@@ -539,7 +648,7 @@ These related classes have been deprecated:
 
  * `Doctrine\ORM\Proxy\ProxyFactory`
  * `Doctrine\ORM\Proxy\Autoloader` - we suggest using the composer autoloader instead
- 
+
 These methods have been deprecated:
 
  * `Doctrine\ORM\Configuration#getAutoGenerateProxyClasses()`
@@ -588,7 +697,7 @@ If your code relies on single entity flushing optimisations via
 
 Said API was affected by multiple data integrity bugs due to the fact
 that change tracking was being restricted upon a subset of the managed
-entities. The ORM cannot support committing subsets of the managed 
+entities. The ORM cannot support committing subsets of the managed
 entities while also guaranteeing data integrity, therefore this
 utility was removed.
 
@@ -689,8 +798,8 @@ either:
  - map those classes as `MappedSuperclass`
 
 ## Minor BC BREAK: ``EntityManagerInterface`` instead of ``EntityManager`` in type-hints
- 
-As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require 
+
+As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require
 an ``EntityManagerInterface`` instead.
 If you are extending any of the following classes, then you need to check following
 signatures:
@@ -783,7 +892,7 @@ the `Doctrine\ORM\Repository\DefaultRepositoryFactory`.
 When executing DQL queries with new object expressions, instead of returning DTOs numerically indexes, it will now respect user provided aliases. Consider the following query:
 
     SELECT new UserDTO(u.id,u.name) as user,new AddressDTO(a.street,a.postalCode) as address, a.id as addressId FROM User u INNER JOIN u.addresses a WITH a.isPrimary = true
-    
+
 Previously, your result would be similar to this:
 
     array(

ci/github/phpunit/pgsql.xml

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         convertDeprecationsToExceptions="true"
+>
+    <php>
+        <ini name="error_reporting" value="-1" />
+        <var name="db_driver" value="pgsql"/>
+        <var name="db_host" value="localhost" />
+        <var name="db_user" value="postgres" />
+        <var name="db_password" value="postgres" />
+        <var name="db_dbname" value="doctrine_tests" />
+
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../lib/Doctrine</directory>
+        </whitelist>
+    </filter>
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

composer.json

@@ -24,34 +24,35 @@
         "composer-runtime-api": "^2",
         "ext-ctype": "*",
         "doctrine/cache": "^1.12.1 || ^2.1.1",
-        "doctrine/collections": "^1.5",
+        "doctrine/collections": "^1.5 || ^2.1",
         "doctrine/common": "^3.0.3",
         "doctrine/dbal": "^2.13.1 || ^3.2",
         "doctrine/deprecations": "^0.5.3 || ^1",
-        "doctrine/event-manager": "^1.1",
+        "doctrine/event-manager": "^1.2 || ^2",
         "doctrine/inflector": "^1.4 || ^2.0",
-        "doctrine/instantiator": "^1.3",
-        "doctrine/lexer": "^1.2.3",
+        "doctrine/instantiator": "^1.3 || ^2",
+        "doctrine/lexer": "^2",
         "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^3.0 || ^4.0 || ^5.0 || ^6.0",
+        "symfony/console": "^4.2 || ^5.0 || ^6.0",
         "symfony/polyfill-php72": "^1.23",
         "symfony/polyfill-php80": "^1.16"
     },
     "require-dev": {
-        "doctrine/annotations": "^1.13",
-        "doctrine/coding-standard": "^9.0.2 || ^10.0",
+        "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.9.2",
-        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
+        "phpstan/phpstan": "~1.4.10 || 1.10.14",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6",
         "psr/log": "^1 || ^2 || ^3",
-        "squizlabs/php_codesniffer": "3.7.1",
+        "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"
+        "vimeo/psalm": "4.30.0 || 5.11.0"
     },
     "conflict": {
-        "doctrine/annotations": "<1.13 || >= 2.0"
+        "doctrine/annotations": "<1.13 || >= 3.0"
     },
     "suggest": {
         "ext-dom": "Provides support for XSD validation for XML mapping files",

docs/en/cookbook/accessing-private-properties-of-the-same-class-from-different-instance.rst

@@ -1,74 +0,0 @@
-Accessing private/protected properties/methods of the same class from different instance
-========================================================================================
-
-.. sectionauthor:: Michael Olsavsky (olsavmic)
-
-As explained in the :doc:`restrictions for entity classes in the manual <../reference/architecture>`,
-it is dangerous to access private/protected properties of different entity instance of the same class because of lazy loading.
-
-The proxy instance that's injected instead of the real entity may not be initialized yet
-and therefore not contain expected data which may result in unexpected behavior.
-That's a limitation of current proxy implementation - only public methods automatically initialize proxies.
-
-It is usually preferable to use a public interface to manipulate the object from outside the `$this`
-context but it may not be convenient in some cases. The following example shows how to do it safely.
-
-Safely accessing private properties from different instance of the same class
------------------------------------------------------------------------------
-
-To safely access private property of different instance of the same class, make sure to initialise
-the proxy before use manually as follows:
-
-.. code-block:: php
-
-    <?php
-
-    use Doctrine\Common\Proxy\Proxy;
-    use Doctrine\ORM\Mapping as ORM;
-
-    /**
-     * @ORM\Entity
-     */
-    class Entity
-    {
-        // ...
-
-        /**
-         * @ORM\ManyToOne(targetEntity="Entity")
-         * @ORM\JoinColumn(nullable=false)
-         */
-        private self $parent;
-
-        /**
-         * @ORM\Column(type="string", nullable=false)
-         */
-        private string $name;
-
-        // ...
-
-        public function doSomethingWithParent()
-        {
-            // Always initializing the proxy before use
-            if ($this->parent instanceof Proxy) {
-                $this->parent->__load();
-            }
-
-            // Accessing the `$this->parent->name` property without loading the proxy first
-            // may throw error in case the Proxy has not been initialized yet.
-            $this->parent->name;
-        }
-
-        public function doSomethingWithAnotherInstance(self $instance)
-        {
-            // Always initializing the proxy before use
-            if ($instance instanceof Proxy) {
-                $instance->__load();
-            }
-
-            // Accessing the `$instance->name` property without loading the proxy first
-            // may throw error in case the Proxy has not been initialized yet.
-            $instance->name;
-        }
-
-        // ...
-    }

docs/en/cookbook/advanced-field-value-conversion-using-custom-mapping-types.rst

@@ -196,7 +196,7 @@ Example usage
     <?php
 
     // Bootstrapping stuff...
-    // $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config);
+    // $em = new \Doctrine\ORM\EntityManager($connection, $config);
 
     // Setup custom mapping type
     use Doctrine\DBAL\Types\Type;

docs/en/cookbook/dql-user-defined-functions.rst

@@ -46,7 +46,7 @@ configuration:
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
 
-    $em = EntityManager::create($dbParams, $config);
+    $em = new EntityManager($connection, $config);
 
 The ``$name`` is the name the function will be referred to in the
 DQL query. ``$class`` is a string of a class-name which has to
@@ -247,5 +247,3 @@ vendor sql functions and extend the DQL languages scope.
 Code for this Extension to DQL and other Doctrine Extensions can be
 found
 `in the GitHub DoctrineExtensions repository <https://github.com/beberlei/DoctrineExtensions>`_.
-
-

docs/en/cookbook/implementing-wakeup-or-clone.rst

@@ -1,78 +0,0 @@
-Implementing Wakeup or Clone
-============================
-
-.. sectionauthor:: Roman Borschel (roman@code-factory.org)
-
-As explained in the :ref:`restrictions for entity classes in the manual
-<terminology_entities>`,
-it is usually not allowed for an entity to implement ``__wakeup``
-or ``__clone``, because Doctrine makes special use of them.
-However, it is quite easy to make use of these methods in a safe
-way by guarding the custom wakeup or clone code with an entity
-identity check, as demonstrated in the following sections.
-
-Safely implementing __wakeup
-----------------------------
-
-To safely implement ``__wakeup``, simply enclose your
-implementation code in an identity check as follows:
-
-.. code-block:: php
-
-    <?php
-    class MyEntity
-    {
-        private $id; // This is the identifier of the entity.
-        // ...
-    
-        public function __wakeup()
-        {
-            // If the entity has an identity, proceed as normal.
-            if ($this->id) {
-                // ... Your code here as normal ...
-            }
-            // otherwise do nothing, do NOT throw an exception!
-        }
-    
-        // ...
-    }
-
-Safely implementing __clone
----------------------------
-
-Safely implementing ``__clone`` is pretty much the same:
-
-.. code-block:: php
-
-    <?php
-    class MyEntity
-    {
-        private $id; // This is the identifier of the entity.
-        // ...
-    
-        public function __clone()
-        {
-            // If the entity has an identity, proceed as normal.
-            if ($this->id) {
-                // ... Your code here as normal ...
-            }
-            // otherwise do nothing, do NOT throw an exception!
-        }
-    
-        // ...
-    }
-
-Summary
--------
-
-As you have seen, it is quite easy to safely make use of
-``__wakeup`` and ``__clone`` in your entities without adding any
-really Doctrine-specific or Doctrine-dependant code.
-
-These implementations are possible and safe because when Doctrine
-invokes these methods, the entities never have an identity (yet).
-Furthermore, it is possibly a good idea to check for the identity
-in your code anyway, since it's rarely the case that you want to
-unserialize or clone an entity with no identity.
-
-

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

@@ -127,7 +127,8 @@ the targetEntity resolution will occur reliably:
     // Add the ResolveTargetEntityListener
     $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $rtel);
 
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
+    $connection = \Doctrine\DBAL\DriverManager::createConnection($connectionOptions, $config, $evm);
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);
 
 Final Thoughts
 --------------
@@ -136,5 +137,3 @@ With the ``ResolveTargetEntityListener``, we are able to decouple our
 bundles, keeping them usable by themselves, but still being able to
 define relationships between different objects. By using this method,
 I've found my bundles end up being easier to maintain independently.
-
-

docs/en/cookbook/sql-table-prefixes.rst

@@ -81,6 +81,4 @@ before the prefix has been set.
     $tablePrefix = new \DoctrineExtensions\TablePrefix('prefix_');
     $evm->addEventListener(\Doctrine\ORM\Events::loadClassMetadata, $tablePrefix);
     
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
-
-
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);

docs/en/cookbook/working-with-datetime.rst

@@ -21,7 +21,7 @@ these comparisons are always made **BY REFERENCE**. That means the following cha
     #[Entity]
     class Article
     {
-        #[Column(type='datetime')]
+        #[Column(type: 'datetime')]
         private DateTime $updated;
 
         public function setUpdated(): void

docs/en/index.rst

@@ -72,6 +72,7 @@ Advanced Topics
 * :doc:`Transactions and Concurrency <reference/transactions-and-concurrency>`
 * :doc:`Filters <reference/filters>`
 * :doc:`NamingStrategy <reference/namingstrategy>`
+* :doc:`TypedFieldMapper <reference/typedfieldmapper>`
 * :doc:`Improving Performance <reference/improving-performance>`
 * :doc:`Caching <reference/caching>`
 * :doc:`Partial Objects <reference/partial-objects>`
@@ -112,7 +113,6 @@ Cookbook
 * **Implementation**:
   :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
   :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
-  :doc:`Using Wakeup Or Clone <cookbook/implementing-wakeup-or-clone>` |
   :doc:`Working with DateTime <cookbook/working-with-datetime>` |
   :doc:`Validation <cookbook/validation-of-entities>` |
   :doc:`Entities in the Session <cookbook/entities-in-session>` |

docs/en/reference/advanced-configuration.rst

@@ -41,12 +41,12 @@ steps of configuration.
         $config->setAutoGenerateProxyClasses(false);
     }
 
-    $connectionOptions = array(
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
-        'path' => 'database.sqlite'
-    );
+        'path' => 'database.sqlite',
+    ], $config);
 
-    $em = EntityManager::create($connectionOptions, $config);
+    $em = new EntityManager($connection, $config);
 
 Doctrine and Caching
 --------------------
@@ -114,11 +114,13 @@ classes.
 There are currently 5 available implementations:
 
 
--  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
 -  ``Doctrine\ORM\Mapping\Driver\AttributeDriver``
 -  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
--  ``Doctrine\ORM\Mapping\Driver\YamlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\DriverChain``
+-  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver`` (deprecated and will
+  be removed in ``doctrine/orm`` 3.0)
+-  ``Doctrine\ORM\Mapping\Driver\YamlDriver`` (deprecated and will be
+   removed in ``doctrine/orm`` 3.0)
 
 Throughout the most part of this manual the AttributeDriver is
 used in the examples. For information on the usage of the
@@ -214,7 +216,7 @@ option that controls this behavior is:
 
 Possible values for ``$mode`` are:
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_NEVER``
 
 Never autogenerate a proxy. You will need to generate the proxies
 manually, for this use the Doctrine Console like so:
@@ -230,17 +232,17 @@ methods were added to the entity class that are not yet in the proxy class.
 In such a case, simply use the Doctrine Console to (re)generate the
 proxy classes.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_ALWAYS``
 
 Always generates a new proxy in every request and writes it to disk.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
 
 Generate 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.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_EVAL``
 
 Generate the proxy classes and evaluate them on the fly via eval(),
 avoiding writing the proxies to disk.
@@ -274,15 +276,13 @@ proxy sets an exclusive file lock which can cause serious
 performance bottlenecks in systems with regular concurrent
 requests.
 
-Connection Options
-------------------
+Connection
+----------
 
-The ``$connectionOptions`` passed as the first argument to
-``EntityManager::create()`` has to be either an array or an
-instance of ``Doctrine\DBAL\Connection``. If an array is passed it
-is directly passed along to the DBAL Factory
-``Doctrine\DBAL\DriverManager::getConnection()``. The DBAL
-configuration is explained in the
+The ``$connection`` passed as the first argument to he constructor of
+``EntityManager`` has to be an instance of ``Doctrine\DBAL\Connection``.
+You can use the factory ``Doctrine\DBAL\DriverManager::getConnection()``
+to create such a connection. The DBAL configuration is explained in the
 `DBAL section <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html>`_.
 
 Proxy Objects
@@ -325,8 +325,9 @@ identifier. You could simply do this:
     $cart->addItem($item);
 
 Here, we added an Item to a Cart without loading the Item from the
-database. If you invoke any method on the Item instance, it would
-fully initialize its state transparently from the database. Here
+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

docs/en/reference/annotations-reference.rst

@@ -1,6 +1,11 @@
 Annotations Reference
 =====================
 
+.. warning::
+    The annotation driver is deprecated and will be removed in version
+    3.0. It is strongly recommended to switch to one of the other
+    mapping drivers.
+
 .. note::
 
     To be able to use annotations, you will have to install an extra
@@ -124,7 +129,7 @@ Optional attributes:
 -  **nullable**: Determines if NULL values allowed for this column. If not specified, default value is false.
 
 -  **insertable**: Boolean value to determine if the column should be
-   included when inserting a new row into the underlying entities table. 
+   included when inserting a new row into the underlying entities table.
    If not specified, default value is true.
 
 -  **updatable**: Boolean value to determine if the column should be
@@ -1382,4 +1387,3 @@ Example:
      * @Version
      */
     protected $version;
-

docs/en/reference/architecture.rst

@@ -74,32 +74,13 @@ Entities
 An entity is a lightweight, persistent domain object. An entity can
 be any regular PHP class observing the following restrictions:
 
-
--  An entity class must not be final or contain final methods.
--  All persistent properties/field of any entity class should
-   always be private or protected, otherwise lazy-loading might not
-   work as expected. In case you serialize entities (for example Session)
-   properties should be protected (See Serialize section below).
--  An entity class must not implement ``__clone`` or
-   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
--  An entity class must not implement ``__wakeup`` or
-   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
-   You can also consider implementing
-   `Serializable <https://php.net/manual/en/class.serializable.php>`_,
-   but be aware that it is deprecated since PHP 8.1. We do not recommend its usage.
--  PHP 7.4 introduces :doc:`the new magic method <https://php.net/manual/en/language.oop5.magic.php#object.unserialize>`
-   ``__unserialize``, which changes the execution priority between
-   ``__wakeup`` and itself when used. This can cause unexpected behaviour in
-   an Entity.
+-  An entity class must not be final nor read-only but
+   it may contain final methods or read-only properties.
 -  Any two entity classes in a class hierarchy that inherit
    directly or indirectly from one another must not have a mapped
    property with the same name. That is, if B inherits from A then B
    must not have a mapped field with the same name as an already
    mapped field that is inherited from A.
--  An entity cannot make use of func_get_args() to implement variable parameters.
-   Generated proxies do not support this for performance reasons and your code might
-   actually fail to work when violating this restriction.
--  Entity cannot access private/protected properties/methods of another entity of the same class or :doc:`do so safely <../cookbook/accessing-private-properties-of-the-same-class-from-different-instance>`.
 
 Entities support inheritance, polymorphic associations, and
 polymorphic queries. Both abstract and concrete classes can be
@@ -113,6 +94,25 @@ classes, and non-entity classes may extend entity classes.
     never calls entity constructors, thus you are free to use them as
     you wish and even have it require arguments of any type.
 
+Mapped Superclasses
+~~~~~~~~~~~~~~~~~~~
+
+A mapped superclass is an abstract or concrete class that provides
+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>`.
+
+Transient Classes
+~~~~~~~~~~~~~~~~~
+
+The term "transient class" appears in some places in the mapping
+drivers as well as the code dealing with metadata handling.
+
+A transient class is a class that is neither an entity nor a mapped
+superclass. From the ORM's point of view, these classes can be
+completely ignored, and no class metadata is loaded for them at all.
 
 Entity states
 ~~~~~~~~~~~~~
@@ -159,17 +159,13 @@ Serializing entities
 
 Serializing entities can be problematic and is not really
 recommended, at least not as long as an entity instance still holds
-references to proxy objects or is still managed by an
-EntityManager. If you intend to serialize (and unserialize) entity
-instances that still hold references to proxy objects you may run
-into problems with private properties because of technical
-limitations. Proxy objects implement ``__sleep`` and it is not
-possible for ``__sleep`` to return names of private properties in
-parent classes. On the other hand it is not a solution for proxy
-objects to implement ``Serializable`` because Serializable does not
-work well with any potential cyclic object references (at least we
-did not find a way yet, if you did, please contact us). The
-``Serializable`` interface is also deprecated beginning with PHP 8.1.
+references to proxy objects or is still managed by an EntityManager.
+By default, serializing proxy objects does not initialize them. On
+unserialization, resulting objects are detached from the entity
+manager and cannot be initialiazed anymore. You can implement the
+``__serialize()`` method if you want to change that behavior, but
+then you need to ensure that you won't generate large serialized
+object graphs and take care of circular associations.
 
 The EntityManager
 ~~~~~~~~~~~~~~~~~

docs/en/reference/association-mapping.rst

@@ -1386,6 +1386,14 @@ Is essentially the same as following:
 
 .. configuration-block::
 
+    .. code-block:: attribute
+
+        <?php
+        /** One Product has One Shipment. */
+        #[OneToOne(targetEntity: Shipment::class)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id', nullable: false)]
+        private Shipment $shipment;
+
     .. code-block:: annotation
 
         <?php
@@ -1396,14 +1404,6 @@ Is essentially the same as following:
          */
         private Shipment $shipment;
 
-    .. code-block:: attribute
-
-        <?php
-        /** One Product has One Shipment. */
-        #[OneToOne(targetEntity: Shipment::class)]
-        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id', nullable: false)]
-        private Shipment $shipment;
-
     .. code-block:: xml
 
         <doctrine-mapping>

docs/en/reference/attributes-reference.rst

@@ -366,6 +366,9 @@ Optional parameters:
 
 -  **type**: By default this is string.
 -  **length**: By default this is 255.
+-  **columnDefinition**: By default this is null the definition according to the type will be used. This option allows to override it.
+-  **enumType**: By default this is `null`. Allows to map discriminatorColumn value to PHP enum
+-  **options**: See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
 .. _attrref_discriminatormap:
 
@@ -573,7 +576,7 @@ Example with partial indexes:
 
     #[Index(name: "search_idx", columns: ["category"],
         options: [
-            "where": "((category IS NOT NULL))"
+            "where" => "((category IS NOT NULL))"
         ]
     )]
     class ECommerceProduct
@@ -1102,7 +1105,8 @@ context.
 Required parameters:
 
 -  **name**: Name of the Index
--  **columns**: Array of columns.
+-  **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:
 

docs/en/reference/basic-mapping.rst

@@ -45,9 +45,10 @@ Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
 -  :doc:`Attributes <attributes-reference>`
--  :doc:`Docblock Annotations <annotations-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:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via attributes, though
@@ -288,6 +289,13 @@ These are the "automatic" mapping rules:
 As of version 2.11 Doctrine can also automatically map typed properties using a
 PHP 8.1 enum to set the right ``type`` and ``enumType``.
 
+.. versionadded:: 2.14
+
+Since version 2.14 you can specify custom typed field mapping between PHP type and DBAL type using ``Configuration``
+and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
+
+:doc:`Read more about TypedFieldMapper <typedfieldmapper>`.
+
 .. _reference-mapping-types:
 
 Doctrine Mapping Types
@@ -526,8 +534,6 @@ the above example with ``allocationSize=100`` Doctrine ORM would only
 need to access the sequence once to generate the identifiers for
 100 new entities.
 
-*The default allocationSize for a @SequenceGenerator is currently 10.*
-
 .. caution::
 
     The allocationSize is detected by SchemaTool and

docs/en/reference/batch-processing.rst

@@ -19,11 +19,13 @@ especially what the strategies presented here provide help with.
 .. note::
 
     Having an SQL logger enabled when processing batches can have a serious impact on performance and resource usage.
-    To avoid that you should disable it in the DBAL configuration:
+    To avoid that you should remove the corresponding middleware.
+    To remove all middlewares, you can use this line:
 .. code-block:: php
 
     <?php
-    $em->getConnection()->getConfiguration()->setSQLLogger(null);
+    $em->getConnection()->getConfiguration()->setMiddlewares([]); // DBAL 3
+    $em->getConnection()->getConfiguration()->setSQLLogger(null); // DBAL 2
 
 Bulk Inserts
 ------------
@@ -84,7 +86,7 @@ with the batching strategy that was already used for bulk inserts:
 
     <?php
     $batchSize = 20;
-    $i = 1;
+    $i = 0;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     foreach ($q->toIterable() as $user) {
         $user->increaseCredit();
@@ -143,7 +145,7 @@ The following example shows how to do this:
 
     <?php
     $batchSize = 20;
-    $i = 1;
+    $i = 0;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     foreach($q->toIterable() as $row) {
         $em->remove($row);

docs/en/reference/configuration.rst

@@ -41,22 +41,24 @@ access point to ORM functionality provided by Doctrine.
     // bootstrap.php
     require_once "vendor/autoload.php";
 
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
     use Doctrine\ORM\ORMSetup;
 
-    $paths = array("/path/to/entity-files");
+    $paths = ['/path/to/entity-files'];
     $isDevMode = false;
 
     // the connection configuration
-    $dbParams = array(
+    $dbParams = [
         'driver'   => 'pdo_mysql',
         'user'     => 'root',
         'password' => '',
         'dbname'   => 'foo',
-    );
+    ];
 
     $config = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
 
@@ -68,18 +70,20 @@ Or if you prefer XML:
 .. code-block:: php
 
     <?php
-    $paths = array("/path/to/xml-mappings");
+    $paths = ['/path/to/xml-mappings'];
     $config = ORMSetup::createXMLMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 Or if you prefer YAML:
 
 .. code-block:: php
 
     <?php
-    $paths = array("/path/to/yml-mappings");
+    $paths = ['/path/to/yml-mappings'];
     $config = ORMSetup::createYAMLMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     If you want to use yml mapping you should add yaml dependency to your `composer.json`:

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

@@ -180,10 +180,10 @@ not need to lazy load the association with another query.
 
     Doctrine allows you to walk all the associations between
     all the objects in your domain model. Objects that were not already
-    loaded from the database are replaced with lazy load proxy
-    instances. Non-loaded Collections are also replaced by lazy-load
+    loaded from the database are replaced with lazy-loading proxy
+    instances. Non-loaded Collections are also replaced by lazy-loading
     instances that fetch all the contained objects upon first access.
-    However relying on the lazy-load mechanism leads to many small
+    However relying on the lazy-loading mechanism leads to many small
     queries executed against the database, which can significantly
     affect the performance of your application. **Fetch Joins** are the
     solution to hydrate most or all of the entities that you need in a
@@ -319,11 +319,11 @@ With Nested Conditions in WHERE Clause:
 
     <?php
     $query = $em->createQuery('SELECT u FROM ForumUser u WHERE (u.username = :name OR u.username = :name2) AND u.id = :id');
-    $query->setParameters(array(
+    $query->setParameters([
         'name' => 'Bob',
         'name2' => 'Alice',
         'id' => 321,
-    ));
+    ]);
     $users = $query->getResult(); // array of ForumUser objects
 
 With COUNT DISTINCT:
@@ -794,7 +794,7 @@ You can register custom DQL functions in your ORM Configuration:
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
 
-    $em = EntityManager::create($dbParams, $config);
+    $em = new EntityManager($connection, $config);
 
 The functions have to return either a string, numeric or datetime
 value depending on the registered function type. As an example we
@@ -806,8 +806,8 @@ classes have to implement the base class :
     <?php
     namespace MyProject\Query\AST;
 
-    use \Doctrine\ORM\Query\AST\Functions\FunctionNode;
-    use \Doctrine\ORM\Query\Lexer;
+    use Doctrine\ORM\Query\AST\Functions\FunctionNode;
+    use Doctrine\ORM\Query\Lexer;
 
     class MysqlFloor extends FunctionNode
     {
@@ -1057,7 +1057,7 @@ the Query class. Here they are:
 
 Instead of using these methods, you can alternatively use the
 general-purpose method
-``Query#execute(array $params = array(), $hydrationMode = Query::HYDRATE_OBJECT)``.
+``Query#execute(array $params = [], $hydrationMode = Query::HYDRATE_OBJECT)``.
 Using this method you can directly supply the hydration mode as the
 second parameter via one of the Query constants. In fact, the
 methods mentioned earlier are just convenient shortcuts for the
@@ -1304,14 +1304,13 @@ creating a class which extends ``AbstractHydrator``:
     <?php
     namespace MyProject\Hydrators;
 
-    use Doctrine\DBAL\FetchMode;
     use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
 
     class CustomHydrator extends AbstractHydrator
     {
         protected function _hydrateAll()
         {
-            return $this->_stmt->fetchAll(FetchMode::FETCH_ASSOC);
+            return $this->_stmt->fetchAllAssociative();
         }
     }
 

docs/en/reference/events.rst

@@ -144,20 +144,20 @@ Events Overview
 | Event                                                           | Dispatched by         | Lifecycle | Passed                              |
 |                                                                 |                       | Callback  | Argument                            |
 +=================================================================+=======================+===========+=====================================+
-| :ref:`preRemove<reference-events-pre-remove>`                   | ``$em->remove()``     | Yes       | `LifecycleEventArgs`_               |
+| :ref:`preRemove<reference-events-pre-remove>`                   | ``$em->remove()``     | Yes       | `PreRemoveEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postRemove<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
+| :ref:`postRemove<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `PostRemoveEventArgs`_              |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`prePersist<reference-events-pre-persist>`                 | ``$em->persist()``    | Yes       | `LifecycleEventArgs`_               |
+| :ref:`prePersist<reference-events-pre-persist>`                 | ``$em->persist()``    | Yes       | `PrePersistEventArgs`_              |
 |                                                                 | on *initial* persist  |           |                                     |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
+| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()``      | Yes       | `PostPersistEventArgs`_             |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
 | :ref:`preUpdate<reference-events-pre-update>`                   | ``$em->flush()``      | Yes       | `PreUpdateEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postUpdate<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
+| :ref:`postUpdate<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `PostUpdateEventArgs`_              |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postLoad<reference-events-post-load>`                     | Loading from database | Yes       | `LifecycleEventArgs`_               |
+| :ref:`postLoad<reference-events-post-load>`                     | Loading from database | Yes       | `PostLoadEventArgs`_                |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
 | :ref:`loadClassMetadata<reference-events-load-class-metadata>`  | Loading of mapping    | No        | `LoadClassMetadataEventArgs`_       |
 |                                                                 | metadata              |           |                                     |
@@ -214,7 +214,7 @@ specific to a particular entity class's lifecycle.
 
         <?php
         use Doctrine\DBAL\Types\Types;
-        use Doctrine\ORM\Event\LifecycleEventArgs;
+        use Doctrine\ORM\Event\PrePersistEventArgs;
 
         #[Entity]
         #[HasLifecycleCallbacks]
@@ -226,7 +226,7 @@ specific to a particular entity class's lifecycle.
             public $value;
 
             #[PrePersist]
-            public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
+            public function doStuffOnPrePersist(PrePersistEventArgs $eventArgs)
             {
                 $this->createdAt = date('Y-m-d H:i:s');
             }
@@ -246,7 +246,7 @@ specific to a particular entity class's lifecycle.
     .. code-block:: annotation
 
         <?php
-        use Doctrine\Persistence\Event\LifecycleEventArgs;
+        use Doctrine\ORM\Event\PrePersistEventArgs;
 
         /**
          * @Entity
@@ -260,7 +260,7 @@ specific to a particular entity class's lifecycle.
             public $value;
 
             /** @PrePersist */
-            public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
+            public function doStuffOnPrePersist(PrePersistEventArgs $eventArgs)
             {
                 $this->createdAt = date('Y-m-d H:i:s');
             }
@@ -353,11 +353,11 @@ A lifecycle event listener looks like the following:
 .. code-block:: php
 
     <?php
-    use Doctrine\Persistence\Event\LifecycleEventArgs;
+    use Doctrine\ORM\Event\PreUpdateEventArgs;
 
     class MyEventListener
     {
-        public function preUpdate(LifecycleEventArgs $args)
+        public function preUpdate(PreUpdateEventArgs $args)
         {
             $entity = $args->getObject();
             $entityManager = $args->getObjectManager();
@@ -374,9 +374,9 @@ A lifecycle event subscriber may look like this:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\PostUpdateEventArgs;
     use Doctrine\ORM\Events;
     use Doctrine\EventSubscriber;
-    use Doctrine\Persistence\Event\LifecycleEventArgs;
 
     class MyEventSubscriber implements EventSubscriber
     {
@@ -387,7 +387,7 @@ A lifecycle event subscriber may look like this:
             );
         }
 
-        public function postUpdate(LifecycleEventArgs $args)
+        public function postUpdate(PostUpdateEventArgs $args)
         {
             $entity = $args->getObject();
             $entityManager = $args->getObjectManager();
@@ -416,7 +416,7 @@ EventManager that is passed to the EntityManager factory:
     $eventManager->addEventListener([Events::preUpdate], new MyEventListener());
     $eventManager->addEventSubscriber(new MyEventSubscriber());
 
-    $entityManager = EntityManager::create($dbOpts, $config, $eventManager);
+    $entityManager = new EntityManager($connection, $config, $eventManager);
 
 You can also retrieve the event manager instance after the
 EntityManager was created:
@@ -461,7 +461,7 @@ this association is marked as :ref:`cascade: persist<transitive-persistence>`. A
 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 ``LifecycleEventArgs`` instance
+In both cases you get passed a ``PrePersistEventArgs`` instance
 which has access to the entity and the entity manager.
 
 This event is only triggered on *initial* persist of an entity
@@ -830,69 +830,79 @@ you need to map the listener method using the event type mapping:
     .. code-block:: attribute
 
         <?php
-        use Doctrine\ORM\Event\PreUpdateEventArgs;
+        use Doctrine\ORM\Event\PostLoadEventArgs;
+        use Doctrine\ORM\Event\PostPersistEventArgs;
+        use Doctrine\ORM\Event\PostRemoveEventArgs;
+        use Doctrine\ORM\Event\PostUpdateEventArgs;
         use Doctrine\ORM\Event\PreFlushEventArgs;
-        use Doctrine\Persistence\Event\LifecycleEventArgs;
+        use Doctrine\ORM\Event\PrePersistEventArgs;
+        use Doctrine\ORM\Event\PreRemoveEventArgs;
+        use Doctrine\ORM\Event\PreUpdateEventArgs;
 
         class UserListener
         {
             #[PrePersist]
-            public function prePersistHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function prePersistHandler(User $user, PrePersistEventArgs $event): void { // ... }
 
             #[PostPersist]
-            public function postPersistHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postPersistHandler(User $user, PostPersistEventArgs $event): void { // ... }
 
             #[PreUpdate]
             public function preUpdateHandler(User $user, PreUpdateEventArgs $event): void { // ... }
 
             #[PostUpdate]
-            public function postUpdateHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postUpdateHandler(User $user, PostUpdateEventArgs $event): void { // ... }
 
             #[PostRemove]
-            public function postRemoveHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postRemoveHandler(User $user, PostRemoveEventArgs $event): void { // ... }
 
             #[PreRemove]
-            public function preRemoveHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function preRemoveHandler(User $user, PreRemoveEventArgs $event): void { // ... }
 
             #[PreFlush]
             public function preFlushHandler(User $user, PreFlushEventArgs $event): void { // ... }
 
             #[PostLoad]
-            public function postLoadHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postLoadHandler(User $user, PostLoadEventArgs $event): void { // ... }
         }
 
     .. code-block:: annotation
 
         <?php
-        use Doctrine\ORM\Event\PreUpdateEventArgs;
+        use Doctrine\ORM\Event\PostLoadEventArgs;
+        use Doctrine\ORM\Event\PostPersistEventArgs;
+        use Doctrine\ORM\Event\PostRemoveEventArgs;
+        use Doctrine\ORM\Event\PostUpdateEventArgs;
         use Doctrine\ORM\Event\PreFlushEventArgs;
-        use Doctrine\Persistence\Event\LifecycleEventArgs;
+        use Doctrine\ORM\Event\PrePersistEventArgs;
+        use Doctrine\ORM\Event\PreRemoveEventArgs;
+        use Doctrine\ORM\Event\PreUpdateEventArgs;
 
         class UserListener
         {
             /** @PrePersist */
-            public function prePersistHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function prePersistHandler(User $user, PrePersistEventArgs $event): void { // ... }
 
             /** @PostPersist */
-            public function postPersistHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postPersistHandler(User $user, PostPersistEventArgs $event): void { // ... }
 
             /** @PreUpdate */
             public function preUpdateHandler(User $user, PreUpdateEventArgs $event): void { // ... }
 
             /** @PostUpdate */
-            public function postUpdateHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postUpdateHandler(User $user, PostUpdateEventArgs $event): void { // ... }
 
             /** @PostRemove */
-            public function postRemoveHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postRemoveHandler(User $user, PostRemoveEventArgs $event): void { // ... }
 
             /** @PreRemove */
-            public function preRemoveHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function preRemoveHandler(User $user, PreRemoveEventArgs $event): void { // ... }
 
             /** @PreFlush */
             public function preFlushHandler(User $user, PreFlushEventArgs $event): void { // ... }
 
             /** @PostLoad */
-            public function postLoadHandler(User $user, LifecycleEventArgs $event): void { // ... }
+            public function postLoadHandler(User $user, PostLoadEventArgs $event): void { // ... }
         }
 
     .. code-block:: xml
@@ -1006,7 +1016,7 @@ Implementing your own resolver:
 
     // Configure the listener resolver only before instantiating the EntityManager
     $configurations->setEntityListenerResolver(new MyEntityListenerResolver);
-    EntityManager::create(.., $configurations, ..);
+    $entityManager = new EntityManager(.., $configurations, ..);
 
 .. _reference-events-load-class-metadata:
 
@@ -1106,8 +1116,13 @@ and the EntityManager.
         }
     }
 
-.. _LifecycleEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/LifecycleEventArgs.php
+.. _PrePersistEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PrePersistEventArgs.php
+.. _PreRemoveEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreRemoveEventArgs.php
 .. _PreUpdateEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php
+.. _PostPersistEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostPersistEventArgs.php
+.. _PostRemoveEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostRemoveEventArgs.php
+.. _PostUpdateEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostUpdateEventArgs.php
+.. _PostLoadEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostLoadEventArgs.php
 .. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreFlushEventArgs.php
 .. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostFlushEventArgs.php
 .. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnFlushEventArgs.php

docs/en/reference/faq.rst

@@ -38,7 +38,7 @@ upon insert:
 
         private string $algorithm = "sha1";
         /** @var self::STATUS_* */
-        private int $status = self:STATUS_DISABLED;
+        private int $status = self::STATUS_DISABLED;
     }
 
 .

docs/en/reference/filters.rst

@@ -28,10 +28,11 @@ table alias of the SQL table of the entity.
     In the case of joined or single table inheritance, you always get passed the ClassMetadata of the
     inheritance root. This is necessary to avoid edge cases that would break the SQL when applying the filters.
 
-Parameters for the query should be set on the filter object by
-``SQLFilter#setParameter()``. Only parameters set via this function can be used
-in filters.  The ``SQLFilter#getParameter()`` function takes care of the
-proper quoting of parameters.
+For the filter to correctly function, the following rules must be followed. Failure to do so will lead to unexpected results from the query cache.
+  1. Parameters for the query should be set on the filter object by ``SQLFilter#setParameter()`` before the filter is used by the ORM ( i.e. do not set parameters inside ``SQLFilter#addFilterConstraint()`` function ).
+  2. The filter must be deterministic. Don't change the values base on external inputs.
+
+The ``SQLFilter#getParameter()`` function takes care of the proper quoting of parameters.
 
 .. code-block:: php
 

docs/en/reference/improving-performance.rst

@@ -45,8 +45,7 @@ in scenarios where data is loaded for read-only purposes.
 Read-Only Entities
 ------------------
 
-You can mark entities as read only (See metadata mapping
-references for details).
+You can mark entities as read only. For details, see :ref:`attrref_entity`
 
 This means that the entity marked as read only is never considered for updates.
 During flush on the EntityManager these entities are skipped even if properties
@@ -55,8 +54,6 @@ changed.
 Read-Only allows to persist new entities of a kind and remove existing ones,
 they are just not considered for updates.
 
-See :ref:`annref_entity`
-
 You can also explicitly mark individual entities read only directly on the
 UnitOfWork via a call to ``markReadOnly()``:
 

docs/en/reference/inheritance-mapping.rst

@@ -1,6 +1,9 @@
 Inheritance Mapping
 ===================
 
+This chapter explains the available options for mapping class
+hierarchies.
+
 Mapped Superclasses
 -------------------
 
@@ -12,19 +15,52 @@ is common to multiple entity classes.
 
 Mapped superclasses, just as regular, non-mapped classes, can
 appear in the middle of an otherwise mapped inheritance hierarchy
-(through Single Table Inheritance or Class Table Inheritance).
+(through Single Table Inheritance or Class Table Inheritance). They
+are not query-able, and need not have an ``#[Id]`` property.
+
+No database table will be created for a mapped superclass itself,
+only for entity classes inheriting from it. That  implies that a
+mapped superclass cannot be the ``targetEntity`` in associations.
+
+In other words, a mapped superclass can use unidirectional One-To-One
+and Many-To-One associations where it is the owning side.
+Many-To-Many associations are only possible if the mapped
+superclass is only used in exactly one entity at the moment. For further
+support of inheritance, the single or joined table inheritance features
+have to be used.
 
 .. note::
 
-    A mapped superclass cannot be an entity, it is not query-able and
-    persistent relationships defined by a mapped superclass must be
-    unidirectional (with an owning side only). This means that One-To-Many
-    associations are not possible on a mapped superclass at all.
-    Furthermore Many-To-Many associations are only possible if the
-    mapped superclass is only used in exactly one entity at the moment.
-    For further support of inheritance, the single or
-    joined table inheritance features have to be used.
+    One-To-Many associations are not generally possible on a mapped
+    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>`
+    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
+    entity class at runtime, the mapped superclass *can* use One-To-Many associations
+    and be named as the ``targetEntity`` on the owning sides.
+
+.. 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
+    an entity nor a mapped superclass, but has properties with mapping configuration
+    on them that would also be used in the inheriting class.
+
+    This, however, is due to how the corresponding mapping
+    drivers work and what the PHP reflection API reports for inherited fields.
+
+    Such a configuration is explicitly not supported. To give just one example,
+    it will break for ``private`` properties.
+
+.. note::
+
+    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.
 
 Example:
 
@@ -77,21 +113,76 @@ like this (this is for SQLite):
 
 .. code-block:: sql
 
-    CREATE TABLE EntitySubClass (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, related1_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
+    CREATE TABLE Employee (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, toothbrush_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
 
 As you can see from this DDL snippet, there is only a single table
 for the entity subclass. All the mappings from the mapped
 superclass were inherited to the subclass as if they had been
 defined on that class directly.
 
+Entity Inheritance
+------------------
+
+As soon as one entity class inherits from another entity class, either
+directly, with a mapped superclass or other unmapped (also called
+"transient") classes in between, these entities form an inheritance
+hierarchy. The topmost entity class in this hierarchy is called the
+root entity, and the hierarchy includes all entities that are
+descendants of this root entity.
+
+On the root entity class, ``#[InheritanceType]``,
+``#[DiscriminatorColumn]`` and ``#[DiscriminatorMap]`` must be specified.
+
+``#[InheritanceType]`` specifies one of the two available inheritance
+mapping strategies that are explained in the following sections.
+
+``#[DiscriminatorColumn]`` designates the so-called discriminator column.
+This is an extra column in the table that keeps information about which
+type from the hierarchy applies for a particular database row.
+
+``#[DiscriminatorMap]`` declares the possible values for the discriminator
+column and maps them to class names in the hierarchy. This discriminator map
+has to declare all non-abstract entity classes that exist in that particular
+inheritance hierarchy. That includes the root as well as any intermediate
+entity classes, given they are not abstract.
+
+The names of the classes in the discriminator map do not need to be fully
+qualified if the classes are contained in the same namespace as the entity
+class on which the discriminator map is applied.
+
+If no discriminator map is provided, then the map is generated
+automatically. The automatically generated discriminator map contains the
+lowercase short name of each class as key.
+
+.. note::
+
+    Automatically generating the discriminator map is very expensive
+    computation-wise. The mapping driver has to provide all classes
+    for which mapping configuration exists, and those have to be
+    loaded and checked against  the current inheritance hierarchy
+    to see if they are part of it. The resulting map, however, can be kept
+    in the metadata cache.
+
+Performance impact on to-one associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a general performance consideration when using entity inheritance:
+If the target-entity of a many-to-one or one-to-one association is part of
+an inheritance hierarchy, it is preferable for performance reasons that it
+be a leaf entity (ie. have no subclasses).
+
+Otherwise, the ORM is currently unable to tell beforehand which entity class
+will have to be used, and so no appropriate proxy instance can be created.
+That means the referred-to entities will *always* be loaded eagerly, which
+might even propagate to relationships of these entities (in the case of
+self-referencing associations).
+
 Single Table Inheritance
 ------------------------
 
 `Single Table Inheritance <https://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
-is an inheritance mapping strategy where all classes of a hierarchy
-are mapped to a single database table. In order to distinguish
-which row represents which type in the hierarchy a so-called
-discriminator column is used.
+is an inheritance mapping strategy where all classes of a hierarchy are
+mapped to a single database table.
 
 Example:
 
@@ -156,27 +247,9 @@ Example:
         MyProject\Model\Employee:
           type: entity
 
-Things to note:
-
-
--  The ``#[InheritanceType]`` and ``#[DiscriminatorColumn]`` must be
-  specified on the topmost class that is part of the mapped entity
-  hierarchy.
--  The ``#[DiscriminatorMap]`` specifies which values of the
-   discriminator column identify a row as being of a certain type. In
-   the case above a value of "person" identifies a row as being of
-   type ``Person`` and "employee" identifies a row as being of type
-   ``Employee``.
--  All entity classes that is part of the mapped entity hierarchy
-   (including the topmost class) should be specified in the
-   ``#[DiscriminatorMap]``. In the case above Person class included.
--  The names of the classes in the discriminator map do not need to
-   be fully qualified if the classes are contained in the same
-   namespace as the entity class on which the discriminator map is
-   applied.
--  If no discriminator map is provided, then the map is generated
-   automatically. The automatically generated discriminator map
-   contains the lowercase short name of each class as key.
+In this example, the ``#[DiscriminatorMap]`` specifies that in the
+discriminator column, a value of "person" identifies a row as being of type
+``Person`` and employee" identifies a row as being of type ``Employee``.
 
 Design-time considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -192,17 +265,10 @@ Performance impact
 
 This strategy is very efficient for querying across all types in
 the hierarchy or for specific types. No table joins are required,
-only a WHERE clause listing the type identifiers. In particular,
+only a ``WHERE`` clause listing the type identifiers. In particular,
 relationships involving types that employ this mapping strategy are
 very performing.
 
-There is a general performance consideration with Single Table
-Inheritance: If the target-entity of a many-to-one or one-to-one
-association is an STI entity, it is preferable for performance reasons that it
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses).
-Otherwise Doctrine *CANNOT* create proxy instances
-of this entity and will *ALWAYS* load the entity eagerly.
-
 SQL Schema considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -210,7 +276,7 @@ For Single-Table-Inheritance to work in scenarios where you are
 using either a legacy database schema or a self-written database
 schema you have to make sure that all columns that are not in the
 root entity but in any of the different sub-entities has to allow
-null values. Columns that have NOT NULL constraints have to be on
+null values. Columns that have ``NOT NULL`` constraints have to be on
 the root entity of the single-table inheritance hierarchy.
 
 Class Table Inheritance
@@ -220,10 +286,11 @@ Class Table Inheritance
 is an inheritance mapping strategy where each class in a hierarchy
 is mapped to several tables: its own table and the tables of all
 parent classes. The table of a child class is linked to the table
-of a parent class through a foreign key constraint. Doctrine ORM
-implements this strategy through the use of a discriminator column
-in the topmost table of the hierarchy because this is the easiest
-way to achieve polymorphic queries with Class Table Inheritance.
+of a parent class through a foreign key constraint.
+
+The discriminator column is placed in the topmost table of the hierarchy,
+because this is the easiest way to achieve polymorphic queries with Class
+Table Inheritance.
 
 Example:
 
@@ -247,24 +314,9 @@ Example:
         // ...
     }
 
-Things to note:
-
-
--  The ``#[InheritanceType]``, ``#[DiscriminatorColumn]`` and
-  ``#[DiscriminatorMap]`` must be specified on the topmost class that is
-  part of the mapped entity hierarchy.
--  The ``#[DiscriminatorMap]`` specifies which values of the
-   discriminator column identify a row as being of which type. In the
-   case above a value of "person" identifies a row as being of type
-   ``Person`` and "employee" identifies a row as being of type
-   ``Employee``.
--  The names of the classes in the discriminator map do not need to
-   be fully qualified if the classes are contained in the same
-   namespace as the entity class on which the discriminator map is
-   applied.
--  If no discriminator map is provided, then the map is generated
-   automatically. The automatically generated discriminator map
-   contains the lowercase short name of each class as key.
+As before, the ``#[DiscriminatorMap]`` specifies that in the
+discriminator column, a value of "person" identifies a row as being of type
+``Person`` and "employee" identifies a row as being of type ``Employee``.
 
 .. note::
 
@@ -295,20 +347,13 @@ perform just about any query which can have a negative impact on
 performance, especially with large tables and/or large hierarchies.
 When partial objects are allowed, either globally or on the
 specific query, then querying for any type will not cause the
-tables of subtypes to be OUTER JOINed which can increase
+tables of subtypes to be ``OUTER JOIN``ed which can increase
 performance but the resulting partial objects will not fully load
 themselves on access of any subtype fields, so accessing fields of
 subtypes after such a query is not safe.
 
-There is a general performance consideration with Class Table
-Inheritance: If the target-entity of a many-to-one or one-to-one
-association is a CTI entity, it is preferable for performance reasons that it
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses).
-Otherwise Doctrine *CANNOT* create proxy instances
-of this entity and will *ALWAYS* load the entity eagerly.
-
-There is also another important performance consideration that it is *NOT POSSIBLE*
-to query for the base entity without any LEFT JOINs to the sub-types.
+There is also another important performance consideration that it is *not possible*
+to query for the base entity without any ``LEFT JOIN``s to the sub-types.
 
 SQL Schema considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -326,14 +371,16 @@ column and cascading on delete.
 Overrides
 ---------
 
-Used to override a mapping for an entity field or relationship.  Can only be
-applied to an entity that extends a mapped superclass or uses a trait to
-override a relationship or field mapping defined by the mapped superclass or
-trait.
+Overrides can only be applied to entities that extend a mapped superclass or
+use traits. They are used to override a mapping for an entity field or
+relationship defined in that mapped superclass or trait.
 
-It is not possible to override attributes or associations in entity to entity
-inheritance scenarios, because this can cause unforseen edge case behavior and
-increases complexity in ORM internal classes.
+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.
 
 
 Association Override
@@ -538,10 +585,11 @@ Example:
 
 Things to note:
 
--  The "association override" specifies the overrides base on the property name.
--  This feature is available for all kind of associations. (OneToOne, OneToMany, ManyToOne, ManyToMany)
--  The association type *CANNOT* be changed.
--  The override could redefine the joinTables or joinColumns depending on the association type.
+-  The "association override" specifies the overrides based on the property
+ name.
+-  This feature is available for all kind of associations (OneToOne, OneToMany, ManyToOne, ManyToMany).
+-  The association type *cannot* be changed.
+-  The override could redefine the ``joinTables`` or ``joinColumns`` depending on the association type.
 -  The override could redefine ``inversedBy`` to reference more than one extended entity.
 -  The override could redefine fetch to modify the fetch strategy of the extended entity.
 
@@ -714,8 +762,8 @@ Could be used by an entity that extends a mapped superclass to override a field
 
 Things to note:
 
--  The "attribute override" specifies the overrides base on the property name.
--  The column type *CANNOT* be changed. If the column type is not equal you get a ``MappingException``
+-  The "attribute override" specifies the overrides based on the property name.
+-  The column type *cannot* be changed. If the column type is not equal, you get a ``MappingException``.
 -  The override can redefine all the attributes except the type.
 
 Query the Type

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

@@ -130,10 +130,51 @@ included in the core of Doctrine ORM. However there are already two
 extensions out there that offer support for Nested Set with
 ORM:
 
-
 -  `Doctrine2 Hierarchical-Structural Behavior <https://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
 -  `Doctrine2 NestedSet <https://github.com/blt04/doctrine2-nestedset>`_
 
+Using Traits in Entity Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The use of traits in entity or mapped superclasses, at least when they
+include mapping configuration or mapped fields, is currently not
+endorsed by the Doctrine project. The reasons for this are as follows.
+
+Traits were added in PHP 5.4 more than 10 years ago, but at the same time
+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>`.
+Coverage of traits in test cases is practically nonexistent.
+
+Thus, you should at least be aware that when using traits in your entity and
+mapped superclasses, you will be in uncharted terrain.
+
+.. warning::
+
+    There be dragons.
+
+From a more technical point of view, traits basically work at the language level
+as if the code contained in them had been copied into the class where the trait
+is used, and even private fields are accessible by the using class. In addition to
+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
+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
+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.
+
+XML mapping configuration probably needs to completely re-configure or otherwise
+copy-and-paste configuration for fields used from traits.
+
 Known Issues
 ------------
 
@@ -177,27 +218,3 @@ MySQL with MyISAM tables
 Doctrine cannot provide atomic operations when calling ``EntityManager#flush()`` if one
 of the tables involved uses the storage engine MyISAM. You must use InnoDB or
 other storage engines that support transactions if you need integrity.
-
-Entities, Proxies and Reflection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using methods for Reflection on entities can be prone to error, when the entity
-is actually a proxy the following methods will not work correctly:
-
-- ``new ReflectionClass``
-- ``new ReflectionObject``
-- ``get_class()``
-- ``get_parent_class()``
-
-This is why ``Doctrine\Common\Util\ClassUtils`` class exists that has similar
-methods, which resolve the proxy problem beforehand.
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\Common\Util\ClassUtils;
-
-    $bookProxy = $entityManager->getReference('Acme\Book');
-
-    $reflection = ClassUtils::newReflectionClass($bookProxy);
-    $class = ClassUtils::getClass($bookProxy)¸

docs/en/reference/metadata-drivers.rst

@@ -13,11 +13,16 @@ metadata:
 
 
 -  **XML files** (XmlDriver)
--  **Class DocBlock Annotations** (AnnotationDriver)
 -  **Attributes** (AttributeDriver)
--  **YAML files** (YamlDriver)
 -  **PHP Code in files or static functions** (PhpDriver)
 
+There are also two deprecated ways to do this:
+
+-  **Class DocBlock Annotations** (AnnotationDriver)
+-  **YAML files** (YamlDriver)
+
+They will be removed in 3.0, make sure to avoid them.
+
 Something important to note about the above drivers is they are all
 an intermediate step to the same end result. The mapping
 information is populated to ``Doctrine\ORM\Mapping\ClassMetadata``
@@ -40,8 +45,9 @@ an entity.
 
 
 If you want to use one of the included core metadata drivers you need to
-configure it. If you pick the annotation driver, you will additionally
-need to install ``doctrine/annotations``. All the drivers are in the
+configure it. If you pick the annotation driver despite it being
+deprecated, you will additionally need to install
+``doctrine/annotations``. All the drivers are in the
 ``Doctrine\ORM\Mapping\Driver`` namespace:
 
 .. code-block:: php
@@ -117,22 +123,22 @@ the ``FileDriver`` implementation for you to extend from:
     class MyMetadataDriver extends FileDriver
     {
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
         protected $_fileExtension = '.dcm.ext';
-    
+
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
         public function loadMetadataForClass($className, ClassMetadata $metadata)
         {
             $data = $this->_loadMappingFile($file);
-    
+
             // populate ClassMetadata instance from $data
         }
-    
+
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
         protected function _loadMappingFile($file)
         {
@@ -198,5 +204,3 @@ iterate over them:
     foreach ($class->fieldMappings as $fieldMapping) {
         echo $fieldMapping['fieldName'] . "\n";
     }
-
-

docs/en/reference/php-mapping.rst

@@ -167,7 +167,7 @@ The API of the ClassMetadataBuilder has the following methods with a fluent inte
 -   ``addNamedQuery($name, $dqlQuery)``
 -   ``setJoinedTableInheritance()``
 -   ``setSingleTableInheritance()``
--   ``setDiscriminatorColumn($name, $type = 'string', $length = 255)``
+-   ``setDiscriminatorColumn($name, $type = 'string', $length = 255, $columnDefinition = null, $enumType = null, $options = [])``
 -   ``addDiscriminatorMapClass($name, $class)``
 -   ``setChangeTrackingPolicyDeferredExplicit()``
 -   ``setChangeTrackingPolicyNotify()``

docs/en/reference/transactions-and-concurrency.rst

@@ -114,8 +114,8 @@ functionally equivalent to the previously shown code looks as follows:
 The difference between ``Connection#transactional($func)`` and
 ``EntityManager#transactional($func)`` is that the latter
 abstraction flushes the ``EntityManager`` prior to transaction
-commit and rolls back the transaction when an
-exception occurs.
+commit and in case of an exception the ``EntityManager`` gets closed
+in addition to the transaction rollback.
 
 .. _transactions-and-concurrency_exception-handling:
 
@@ -412,7 +412,7 @@ Doctrine ORM currently supports two pessimistic lock modes:
    locks other concurrent requests that attempt to update or lock rows
    in write mode.
 
-You can use pessimistic locks in three different scenarios:
+You can use pessimistic locks in four different scenarios:
 
 
 1. Using
@@ -424,6 +424,10 @@ You can use pessimistic locks in three different scenarios:
    or
    ``EntityManager#lock($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
 3. Using
+   ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+   or
+   ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+4. Using
    ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
    or
    ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``

docs/en/reference/typedfieldmapper.rst

@@ -0,0 +1,179 @@
+Implementing a TypedFieldMapper
+===============================
+
+.. versionadded:: 2.14
+
+You can specify custom typed field mapping between PHP type and DBAL type using ``Doctrine\ORM\Configuration``
+and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
+
+.. code-block:: php
+
+    <?php
+    $configuration->setTypedFieldMapper(new CustomTypedFieldMapper());
+
+
+DefaultTypedFieldMapper
+-----------------------
+
+By default the ``Doctrine\ORM\Mapping\DefaultTypedFieldMapper`` is used, and you can pass an array of
+PHP type => DBAL type mappings into its constructor to override the default behavior or add new mappings.
+
+.. code-block:: php
+
+    <?php
+    use App\CustomIds\CustomIdObject;
+    use App\DBAL\Type\CustomIdObjectType;
+    use Doctrine\ORM\Mapping\DefaultTypedFieldMapper;
+
+    $configuration->setTypedFieldMapper(new DefaultTypedFieldMapper([
+        CustomIdObject::class => CustomIdObjectType::class,
+    ]));
+
+Then, an entity using the ``CustomIdObject`` typed field will be correctly assigned its DBAL type
+(``CustomIdObjectType``) without the need of explicit declaration.
+
+.. configuration-block::
+
+    .. code-block:: attribute
+
+        <?php
+        #[ORM\Entity]
+        #[ORM\Table(name: 'cms_users_typed_with_custom_typed_field')]
+        class UserTypedWithCustomTypedField
+        {
+            #[ORM\Column]
+            public CustomIdObject $customId;
+
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Table(name="cms_users_typed_with_custom_typed_field")
+         */
+        class UserTypedWithCustomTypedField
+        {
+            /** @Column */
+            public CustomIdObject $customId;
+
+            // ...
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="UserTypedWithCustomTypedField">
+            <field name="customId"/>
+            <!-- -->
+          </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        UserTypedWithCustomTypedField:
+          type: entity
+          fields:
+            customId: ~
+
+It is perfectly valid to override even the "automatic" mapping rules mentioned above:
+
+.. code-block:: php
+
+    <?php
+    use App\DBAL\Type\CustomIntType;
+    use Doctrine\ORM\Mapping\DefaultTypedFieldMapper;
+
+    $configuration->setTypedFieldMapper(new DefaultTypedFieldMapper([
+        'int' => CustomIntType::class,
+    ]));
+
+.. note::
+
+    If chained, once the first ``TypedFieldMapper`` assigns a type to a field, the ``DefaultTypedFieldMapper`` will
+    ignore its mapping and not override it anymore (if it is later in the chain). See below for chaining type mappers.
+
+
+TypedFieldMapper interface
+-------------------------
+The interface ``Doctrine\ORM\Mapping\TypedFieldMapper`` allows you to implement your own
+typed field mapping logic. It consists of just one function
+
+
+.. code-block:: php
+
+    <?php
+    /**
+     * Validates & completes the given field mapping based on typed property.
+     *
+     * @param array{fieldName: string, enumType?: string, type?: mixed}  $mapping The field mapping to validate & complete.
+     * @param \ReflectionProperty                                        $field
+     *
+     * @return array{fieldName: string, enumType?: string, type?: mixed} The updated mapping.
+     */
+    public function validateAndComplete(array $mapping, ReflectionProperty $field): array;
+
+
+ChainTypedFieldMapper
+---------------------
+
+The class ``Doctrine\ORM\Mapping\ChainTypedFieldMapper`` allows you to chain multiple ``TypedFieldMapper`` instances.
+When being evaluated, the ``TypedFieldMapper::validateAndComplete`` is called in the order in which
+the instances were supplied to the ``ChainTypedFieldMapper`` constructor.
+
+.. code-block:: php
+
+    <?php
+    use App\DBAL\Type\CustomIntType;
+    use Doctrine\ORM\Mapping\ChainTypedFieldMapper;
+    use Doctrine\ORM\Mapping\DefaultTypedFieldMapper;
+
+    $configuration->setTypedFieldMapper(
+        new ChainTypedFieldMapper(
+            new DefaultTypedFieldMapper(['int' => CustomIntType::class,]),
+            new CustomTypedFieldMapper()
+        )
+    );
+
+
+Implementing a TypedFieldMapper
+-------------------------------
+
+If you want to assign all ``BackedEnum`` fields to your custom ``BackedEnumDBALType`` or you want to use different
+DBAL types based on whether the entity field is nullable or not, you can achieve this by implementing your own
+typed field mapper.
+
+You need to create a class which implements ``Doctrine\ORM\Mapping\TypedFieldMapper``.
+
+.. code-block:: php
+
+    <?php
+    final class CustomEnumTypedFieldMapper implements TypedFieldMapper
+    {
+        /**
+         * {@inheritDoc}
+         */
+        public function validateAndComplete(array $mapping, ReflectionProperty $field): array
+        {
+            $type = $field->getType();
+
+            if (
+                ! isset($mapping['type'])
+                && ($type instanceof ReflectionNamedType)
+            ) {
+                if (! $type->isBuiltin() && enum_exists($type->getName())) {
+                    $mapping['type'] = BackedEnumDBALType::class;
+                }
+            }
+
+            return $mapping;
+        }
+    }
+
+.. note::
+
+    Note that this case checks whether the mapping is already assigned, and if yes, it skips it. This is up to your
+    implementation. You can make a "greedy" mapper which will always override the mapping with its own type, or one
+    that behaves like the ``DefaultTypedFieldMapper`` and does not modify the type once its set prior in the chain.

docs/en/reference/unitofwork.rst

@@ -38,7 +38,7 @@ will still end up with the same reference:
     {
         $objectA = $this->entityManager->getReference('EntityName', 1);
         // check for proxyinterface
-        $this->assertInstanceOf('Doctrine\ORM\Proxy\Proxy', $objectA);
+        $this->assertInstanceOf('Doctrine\Persistence\Proxy', $objectA);
 
         $objectB = $this->entityManager->find('EntityName', 1);
 

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

@@ -718,6 +718,7 @@ methods:
 
 * ``andX($arg1, $arg2, ...)``
 * ``orX($arg1, $arg2, ...)``
+* ``not($expression)``
 * ``eq($field, $value)``
 * ``gt($field, $value)``
 * ``lt($field, $value)``

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

@@ -162,28 +162,6 @@ your code. See the following code:
         echo "This will always be true!";
     }
 
-A slice of the generated proxy classes code looks like the
-following piece of code. A real proxy class override ALL public
-methods along the lines of the ``getName()`` method shown below:
-
-.. code-block:: php
-
-    <?php
-    class UserProxy extends User implements Proxy
-    {
-        private function _load(): void
-        {
-            // lazy loading code
-        }
-
-        public function getName(): string
-        {
-            $this->_load();
-            return parent::getName();
-        }
-        // .. other public methods of User
-    }
-
 .. warning::
 
     Traversing the object graph for parts that are lazy-loaded will
@@ -414,14 +392,6 @@ Example:
     // $entity now refers to the fully managed copy returned by the merge operation.
     // The EntityManager $em now manages the persistence of $entity as usual.
 
-.. note::
-
-    When you want to serialize/unserialize entities you
-    have to make all entity properties protected, never private. The
-    reason for this is, if you serialize a class that was a proxy
-    instance before, the private variables won't be serialized and a
-    PHP Notice is thrown.
-
 
 The semantics of the merge operation, applied to an entity X, are
 as follows:

docs/en/reference/yaml-mapping.rst

@@ -1,7 +1,7 @@
 YAML Mapping
 ============
 
-.. note::
+.. warning::
     The YAML driver is deprecated and will be removed in version 3.0.
     It is strongly recommended to switch to one of the other mappings.
 

docs/en/sidebar.rst

@@ -73,7 +73,6 @@
       cookbook/dql-user-defined-functions
       cookbook/implementing-arrayaccess-for-domain-objects
       cookbook/implementing-the-notify-changetracking-policy
-      cookbook/implementing-wakeup-or-clone
       cookbook/resolve-target-entity-listener
       cookbook/sql-table-prefixes
       cookbook/strategy-cookbook-introduction

docs/en/toc.rst

@@ -75,7 +75,6 @@ Cookbook
    cookbook/dql-user-defined-functions
    cookbook/implementing-arrayaccess-for-domain-objects
    cookbook/implementing-the-notify-changetracking-policy
-   cookbook/implementing-wakeup-or-clone
    cookbook/resolve-target-entity-listener
    cookbook/sql-table-prefixes
    cookbook/strategy-cookbook-introduction

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

@@ -32,9 +32,9 @@ and year of production as primary keys:
         class Car
         {
             public function __construct(
-                #[Id, Column(type: 'string')]
+                #[Id, Column]
                 private string $name,
-                #[Id, Column(type: 'integer')]
+                #[Id, Column]
                 private int $year,
             ) {
             }
@@ -82,27 +82,6 @@ and year of production as primary keys:
             }
         }
 
-    .. code-block:: annotation
-
-        <?php
-        /**
-         * @Entity
-         */
-        class User
-        {
-            /** @Id @Column(type="integer") @GeneratedValue */
-            private int|null $id = null;
-        }
-
-        /**
-         * @Entity
-         */
-        class Address
-        {
-            /** @Id @OneToOne(targetEntity="User") */
-            private User|null $user = null;
-        }
-
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
@@ -152,7 +131,7 @@ And for querying you can use arrays to both DQL and EntityRepositories:
 
     $dql = "SELECT c FROM VehicleCatalogue\Model\Car c WHERE c.id = ?1";
     $audi = $em->createQuery($dql)
-               ->setParameter(1, array("name" => "Audi A8", "year" => 2010))
+               ->setParameter(1, ["name" => "Audi A8", "year" => 2010])
                ->getSingleResult();
 
 You can also use this entity in associations. Doctrine will then generate two foreign keys one for ``name``
@@ -190,7 +169,52 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        namespace Application\Model;
+
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        #[Entity]
+        class Article
+        {
+            #[Id, Column, GeneratedValue]
+            private int|null $id = null;
+            #[Column]
+            private string $title;
+
+            /** @var ArrayCollection<string, ArticleAttribute> */
+            #[OneToMany(targetEntity: ArticleAttribute::class, mappedBy: 'article', cascade: ['ALL'], indexBy: 'attribute')]
+            private Collection $attributes;
+
+            public function addAttribute(string $name, ArticleAttribute $value): void
+            {
+                $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
+            }
+        }
+
+        #[Entity]
+        class ArticleAttribute
+        {
+            #[Id, ManyToOne(targetEntity: Article::class, inversedBy: 'attributes')]
+            private Article $article;
+
+            #[Id, Column]
+            private string $attribute;
+
+            #[Column]
+            private string $value;
+
+            public function __construct(string $name, string $value, Article $article)
+            {
+                $this->attribute = $name;
+                $this->value = $value;
+                $this->article = $article;
+            }
+        }
+
+    .. code-block:: annotation
 
         <?php
         namespace Application\Model;
@@ -241,51 +265,6 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
             }
         }
 
-    .. code-block:: attribute
-
-        <?php
-        namespace Application\Model;
-
-        use Doctrine\Common\Collections\ArrayCollection;
-
-        #[Entity]
-        class Article
-        {
-            #[Id, Column(type: 'integer'), GeneratedValue]
-            private int|null $id = null;
-            #[Column(type: 'string')]
-            private string $title;
-
-            /** @var ArrayCollection<string, ArticleAttribute> */
-            #[OneToMany(targetEntity: ArticleAttribute::class, mappedBy: 'article', cascade: ['ALL'], indexBy: 'attribute')]
-            private Collection $attributes;
-
-            public function addAttribute(string $name, ArticleAttribute $value): void
-            {
-                $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
-            }
-        }
-
-        #[Entity]
-        class ArticleAttribute
-        {
-            #[Id, ManyToOne(targetEntity: Article::class, inversedBy: 'attributes')]
-            private Article $article;
-
-            #[Id, Column(type: 'string')]
-            private string $attribute;
-
-            #[Column(type: 'string')]
-            private string $value;
-
-            public function __construct(string $name, string $value, Article $article)
-            {
-                $this->attribute = $name;
-                $this->value = $value;
-                $this->article = $article;
-            }
-        }
-
     .. code-block:: xml
 
         <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
@@ -338,7 +317,7 @@ One good example for this is a user-address relationship:
         #[Entity]
         class User
         {
-            #[Id, Column(type: 'integer'), GeneratedValue]
+            #[Id, Column, GeneratedValue]
             private int|null $id = null;
         }
 
@@ -386,18 +365,18 @@ of products purchased and maybe even the current price.
     #[Entity]
     class Order
     {
-        #[Id, Column(type: 'integer'), GeneratedValue]
+        #[Id, Column, GeneratedValue]
         private int|null $id = null;
 
         /** @var ArrayCollection<int, OrderItem> */
         #[OneToMany(targetEntity: OrderItem::class, mappedBy: 'order')]
         private Collection $items;
 
-        #[Column(type: 'boolean')]
+        #[Column]
         private bool $paid = false;
-        #[Column(type: 'boolean')]
+        #[Column]
         private bool $shipped = false;
-        #[Column(type: 'datetime')]
+        #[Column]
         private DateTime $created;
 
         public function __construct(
@@ -412,16 +391,16 @@ of products purchased and maybe even the current price.
     #[Entity]
     class Product
     {
-        #[Id, Column(type: 'integer'), GeneratedValue]
+        #[Id, Column, GeneratedValue]
         private int|null $id = null;
 
-        #[Column(type: 'string')]
+        #[Column]
         private string $name;
 
-        #[Column(type: 'decimal')]
-        private float $currentPrice;
+        #[Column]
+        private int $currentPrice;
 
-        public function getCurrentPrice(): float
+        public function getCurrentPrice(): int
         {
             return $this->currentPrice;
         }
@@ -436,11 +415,11 @@ of products purchased and maybe even the current price.
         #[Id, ManyToOne(targetEntity: Product::class)]
         private Product|null $product = null;
 
-        #[Column(type: 'integer')]
+        #[Column]
         private int $amount = 1;
 
-        #[Column(type: 'decimal')]
-        private float $offeredPrice;
+        #[Column]
+        private int $offeredPrice;
 
         public function __construct(Order $order, Product $product, int $amount = 1)
         {

docs/en/tutorials/getting-started-database.rst

@@ -22,5 +22,5 @@ In this workflow you would modify the database schema first and then
 regenerate the PHP code to use with this schema. You need a flexible
 code-generator for this task.
 
-We spinned off a subproject, Doctrine CodeGenerator, that will fill this gap and
+We spun off a subproject, Doctrine CodeGenerator, that will fill this gap and
 allow you to do *Database First* development.

docs/en/tutorials/getting-started.rst

@@ -43,14 +43,15 @@ What are Entities?
 
 Entities are PHP Objects that can be identified over many requests
 by a unique identifier or primary key. These classes don't need to extend any
-abstract base class or interface. An entity class must not be final
-or contain final methods. Additionally it must not implement
-**clone** nor **wakeup**, unless it :doc:`does so safely <../cookbook/implementing-wakeup-or-clone>`.
+abstract base class or interface.
 
 An entity contains persistable properties. A persistable property
 is an instance variable of the entity that is saved into and retrieved from the database
 by Doctrine's data mapping capabilities.
 
+An entity class must not be final nor read-only, although
+it can contain final methods or read-only properties.
+
 An Example Model: Bug Tracker
 -----------------------------
 
@@ -136,6 +137,7 @@ step:
 
     <?php
     // bootstrap.php
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
     use Doctrine\ORM\ORMSetup;
 
@@ -160,14 +162,14 @@ step:
     //    isDevMode: true,
     // );
 
-    // database configuration parameters
-    $conn = array(
+    // configuring the database connection
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
         'path' => __DIR__ . '/db.sqlite',
-    );
+    ], $config);
 
     // obtaining the entity manager
-    $entityManager = EntityManager::create($conn, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     The YAML driver is deprecated and will be removed in version 3.0.
@@ -320,7 +322,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
@@ -447,7 +449,7 @@ entity.
 
 .. note::
 
-    A `DTO <https://en.wikipedia.org/wiki/Data_transfer_object>` is an object
+    A `DTO <https://en.wikipedia.org/wiki/Data_transfer_object>`_ is an object
     that only carries data without any logic. Its only goal is to be transferred
     from one service to another.
     A ``DTO`` often represents data sent by a client and that has to be validated,
@@ -888,18 +890,6 @@ domain model to match the requirements:
     understand the changes that have happened to the collection that are
     noteworthy for persistence.
 
-.. warning::
-
-    Lazy load proxies always contain an instance of
-    Doctrine's EntityManager and all its dependencies. Therefore a
-    ``var_dump()`` will possibly dump a very large recursive structure
-    which is impossible to render and read. You have to use
-    ``Doctrine\Common\Util\Debug::dump()`` to restrict the dumping to a
-    human readable level. Additionally you should be aware that dumping
-    the EntityManager to a Browser may take several minutes, and the
-    ``Debug::dump()`` method just ignores any occurrences of it in Proxy
-    instances.
-
 Because we only work with collections for the references we must be
 careful to implement a bidirectional reference in the domain model.
 The concept of owning or inverse side of a relation is central to
@@ -1588,39 +1578,8 @@ The output of the engineer’s name is fetched from the database! What is happen
 
 Since we only retrieved the bug by primary key both the engineer and reporter
 are not immediately loaded from the database but are replaced by LazyLoading
-proxies. These proxies will load behind the scenes, when the first method
-is called on them.
-
-Sample code of this proxy generated code can be found in the specified Proxy
-Directory, it looks like:
-
-.. code-block:: php
-
-    <?php
-    namespace MyProject\Proxies;
-
-    /**
-     * THIS CLASS WAS GENERATED BY THE DOCTRINE ORM. DO NOT EDIT THIS FILE.
-     **/
-    class UserProxy extends \User implements \Doctrine\ORM\Proxy\Proxy
-    {
-        // .. lazy load code here
-
-        public function addReportedBug($bug)
-        {
-            $this->_load();
-            return parent::addReportedBug($bug);
-        }
-
-        public function assignedToBug($bug)
-        {
-            $this->_load();
-            return parent::assignedToBug($bug);
-        }
-    }
-
-See how upon each method call the proxy is lazily loaded from the
-database?
+proxies. These proxies will load behind the scenes, when attempting to access
+any of their un-initialized state.
 
 The call prints:
 

doctrine-mapping.xsd

@@ -302,7 +302,7 @@
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
-    <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
+    <xs:attribute name="type" type="orm:type" default="string" />
     <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
@@ -330,6 +330,7 @@
 
   <xs:complexType name="discriminator-column">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
@@ -337,6 +338,7 @@
     <xs:attribute name="field-name" type="xs:NMTOKEN" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="column-definition" type="xs:string" />
+    <xs:attribute name="enum-type" type="xs:string" />
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
@@ -413,7 +415,7 @@
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
-    <xs:attribute name="type" type="xs:NMTOKEN" />
+    <xs:attribute name="type" type="orm:type" />
     <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="association-key" type="xs:boolean" default="false" />
@@ -445,6 +447,13 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="type" id="type">
+    <xs:restriction base="xs:token">
+      <xs:pattern value="([a-zA-Z_u01-uff][a-zA-Z0-9_u01-uff]+)|(\c+)" id="type.class.pattern">
+      </xs:pattern>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="inverse-join-columns">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-column" type="orm:join-column" minOccurs="1" maxOccurs="unbounded" />
@@ -629,7 +638,7 @@
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
-    <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
+    <xs:attribute name="type" type="orm:type" default="string" />
     <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />

lib/Doctrine/ORM/AbstractQuery.php

@@ -1321,9 +1321,11 @@ abstract class AbstractQuery
     protected function getHydrationCacheId()
     {
         $parameters = [];
+        $types      = [];
 
         foreach ($this->getParameters() as $parameter) {
             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
+            $types[$parameter->getName()]      = $parameter->getType();
         }
 
         $sql = $this->getSQL();
@@ -1335,7 +1337,7 @@ abstract class AbstractQuery
         ksort($hints);
         assert($queryCacheProfile !== null);
 
-        return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
+        return $queryCacheProfile->generateCacheKeys($sql, $parameters, $types, $hints);
     }
 
     /**

lib/Doctrine/ORM/Cache/CacheFactory.php

@@ -14,6 +14,8 @@ use Doctrine\ORM\Persisters\Entity\EntityPersister;
 
 /**
  * Contract for building second level cache regions components.
+ *
+ * @psalm-import-type AssociationMapping from ClassMetadata
  */
 interface CacheFactory
 {
@@ -31,7 +33,7 @@ interface CacheFactory
     /**
      * Build a collection persister for the given relation mapping.
      *
-     * @param mixed[] $mapping The association mapping.
+     * @param AssociationMapping $mapping The association mapping.
      *
      * @return CachedCollectionPersister
      */

lib/Doctrine/ORM/Cache/CacheKey.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
+use Doctrine\Deprecations\Deprecation;
+
 /**
  * Defines entity / collection / query key to be stored in the cache region.
  * Allows multiple roles to be stored in the same cache region.
@@ -17,4 +19,18 @@ abstract class CacheKey
      * @var string
      */
     public $hash;
+
+    public function __construct(?string $hash = null)
+    {
+        if ($hash === null) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/10212',
+                'Calling %s() without providing a value for the $hash parameter is deprecated.',
+                __METHOD__
+            );
+        } else {
+            $this->hash = $hash;
+        }
+    }
 }

lib/Doctrine/ORM/Cache/CollectionCacheKey.php

@@ -52,6 +52,7 @@ class CollectionCacheKey extends CacheKey
         $this->ownerIdentifier = $ownerIdentifier;
         $this->entityClass     = (string) $entityClass;
         $this->association     = (string) $association;
-        $this->hash            = str_replace('\\', '.', strtolower($entityClass)) . '_' . implode(' ', $ownerIdentifier) . '__' . $association;
+
+        parent::__construct(str_replace('\\', '.', strtolower($entityClass)) . '_' . implode(' ', $ownerIdentifier) . '__' . $association);
     }
 }

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -48,7 +48,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getEntityCacheRegion($className)
     {
@@ -63,7 +63,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getCollectionCacheRegion($className, $association)
     {
@@ -78,7 +78,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function containsEntity($className, $identifier)
     {
@@ -93,7 +93,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictEntity($className, $identifier)
     {
@@ -108,7 +108,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictEntityRegion($className)
     {
@@ -123,7 +123,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictEntityRegions()
     {
@@ -141,7 +141,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function containsCollection($className, $association, $ownerIdentifier)
     {
@@ -156,7 +156,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictCollection($className, $association, $ownerIdentifier)
     {
@@ -171,7 +171,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictCollectionRegion($className, $association)
     {
@@ -186,7 +186,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictCollectionRegions()
     {
@@ -210,7 +210,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function containsQuery($regionName)
     {
@@ -218,7 +218,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictQueryRegion($regionName = null)
     {
@@ -234,7 +234,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictQueryRegions()
     {
@@ -246,7 +246,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getQueryCache($regionName = null)
     {

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -106,7 +106,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildCachedEntityPersister(EntityManagerInterface $em, EntityPersister $persister, ClassMetadata $metadata)
     {
@@ -134,10 +134,11 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildCachedCollectionPersister(EntityManagerInterface $em, CollectionPersister $persister, array $mapping)
     {
+        assert(isset($mapping['cache']));
         $usage  = $mapping['cache']['usage'];
         $region = $this->getRegion($mapping['cache']);
 
@@ -161,7 +162,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildQueryCache(EntityManagerInterface $em, $regionName = null)
     {
@@ -177,7 +178,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildCollectionHydrator(EntityManagerInterface $em, array $mapping)
     {
@@ -185,7 +186,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildEntityHydrator(EntityManagerInterface $em, ClassMetadata $metadata)
     {
@@ -193,7 +194,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getRegion(array $cache)
     {
@@ -224,7 +225,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getTimestampRegion()
     {
@@ -239,7 +240,7 @@ class DefaultCacheFactory implements CacheFactory
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createCache(EntityManagerInterface $entityManager)
     {

lib/Doctrine/ORM/Cache/DefaultCollectionHydrator.php

@@ -35,7 +35,7 @@ class DefaultCollectionHydrator implements CollectionHydrator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, $collection)
     {
@@ -49,7 +49,7 @@ class DefaultCollectionHydrator implements CollectionHydrator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, CollectionCacheEntry $entry, PersistentCollection $collection)
     {

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -47,7 +47,7 @@ class DefaultEntityHydrator implements EntityHydrator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function buildCacheEntry(ClassMetadata $metadata, EntityCacheKey $key, $entity)
     {
@@ -140,7 +140,7 @@ class DefaultEntityHydrator implements EntityHydrator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadCacheEntry(ClassMetadata $metadata, EntityCacheKey $key, EntityCacheEntry $entry, $entity = null)
     {

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -5,7 +5,6 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache;
 
 use Doctrine\Common\Collections\ArrayCollection;
-use Doctrine\Common\Proxy\Proxy;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Cache\Exception\FeatureNotImplemented;
 use Doctrine\ORM\Cache\Exception\NonCacheableEntity;
@@ -17,6 +16,7 @@ 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;
@@ -29,6 +29,8 @@ use function reset;
 
 /**
  * Default query cache implementation.
+ *
+ * @psalm-import-type AssociationMapping from ClassMetadata
  */
 class DefaultQueryCache implements QueryCache
 {
@@ -66,7 +68,7 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function get(QueryCacheKey $key, ResultSetMapping $rsm, array $hints = [])
     {
@@ -225,7 +227,7 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function put(QueryCacheKey $key, ResultSetMapping $rsm, $result, array $hints = [])
     {
@@ -326,8 +328,8 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * @param array<string,mixed> $assoc
-     * @param mixed               $assocValue
+     * @param AssociationMapping $assoc
+     * @param mixed              $assocValue
      *
      * @return mixed[]|null
      * @psalm-return array{targetEntity: class-string, type: mixed, list?: array[], identifier?: array}|null
@@ -448,7 +450,7 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function clear()
     {
@@ -456,7 +458,7 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getRegion()
     {

lib/Doctrine/ORM/Cache/EntityCacheKey.php

@@ -42,6 +42,7 @@ class EntityCacheKey extends CacheKey
 
         $this->identifier  = $identifier;
         $this->entityClass = $entityClass;
-        $this->hash        = str_replace('\\', '.', strtolower($entityClass) . '_' . implode(' ', $identifier));
+
+        parent::__construct(str_replace('\\', '.', strtolower($entityClass) . '_' . implode(' ', $identifier)));
     }
 }

lib/Doctrine/ORM/Cache/Logging/CacheLoggerChain.php

@@ -40,7 +40,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCacheHit($regionName, CollectionCacheKey $key)
     {
@@ -50,7 +50,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCacheMiss($regionName, CollectionCacheKey $key)
     {
@@ -60,7 +60,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCachePut($regionName, CollectionCacheKey $key)
     {
@@ -70,7 +70,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCacheHit($regionName, EntityCacheKey $key)
     {
@@ -80,7 +80,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCacheMiss($regionName, EntityCacheKey $key)
     {
@@ -90,7 +90,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCachePut($regionName, EntityCacheKey $key)
     {
@@ -100,7 +100,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCacheHit($regionName, QueryCacheKey $key)
     {
@@ -110,7 +110,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCacheMiss($regionName, QueryCacheKey $key)
     {
@@ -120,7 +120,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCachePut($regionName, QueryCacheKey $key)
     {

lib/Doctrine/ORM/Cache/Logging/StatisticsCacheLogger.php

@@ -25,7 +25,7 @@ class StatisticsCacheLogger implements CacheLogger
     private $cachePutCountMap = [];
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCacheMiss($regionName, CollectionCacheKey $key)
     {
@@ -34,7 +34,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCacheHit($regionName, CollectionCacheKey $key)
     {
@@ -43,7 +43,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function collectionCachePut($regionName, CollectionCacheKey $key)
     {
@@ -52,7 +52,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCacheMiss($regionName, EntityCacheKey $key)
     {
@@ -61,7 +61,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCacheHit($regionName, EntityCacheKey $key)
     {
@@ -70,7 +70,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function entityCachePut($regionName, EntityCacheKey $key)
     {
@@ -79,7 +79,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCacheHit($regionName, QueryCacheKey $key)
     {
@@ -88,7 +88,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCacheMiss($regionName, QueryCacheKey $key)
     {
@@ -97,7 +97,7 @@ class StatisticsCacheLogger implements CacheLogger
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function queryCachePut($regionName, QueryCacheKey $key)
     {

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

@@ -25,6 +25,7 @@ use function array_values;
 use function assert;
 use function count;
 
+/** @psalm-import-type AssociationMapping from ClassMetadata */
 abstract class AbstractCollectionPersister implements CachedCollectionPersister
 {
     /** @var UnitOfWork */
@@ -64,7 +65,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
      * @param CollectionPersister    $persister   The collection persister that will be cached.
      * @param Region                 $region      The collection region.
      * @param EntityManagerInterface $em          The entity manager.
-     * @param mixed[]                $association The association mapping.
+     * @param AssociationMapping     $association The association mapping.
      */
     public function __construct(CollectionPersister $persister, Region $region, EntityManagerInterface $em, array $association)
     {
@@ -85,7 +86,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getCacheRegion()
     {
@@ -93,7 +94,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getSourceEntityMetadata()
     {
@@ -101,7 +102,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getTargetEntityMetadata()
     {
@@ -109,7 +110,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadCollectionCache(PersistentCollection $collection, CollectionCacheKey $key)
     {
@@ -123,7 +124,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function storeCollectionCache(CollectionCacheKey $key, $elements)
     {
@@ -167,7 +168,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function contains(PersistentCollection $collection, $element)
     {
@@ -175,7 +176,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function containsKey(PersistentCollection $collection, $key)
     {
@@ -183,7 +184,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function count(PersistentCollection $collection)
     {
@@ -199,7 +200,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function get(PersistentCollection $collection, $index)
     {
@@ -207,7 +208,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function slice(PersistentCollection $collection, $offset, $length = null)
     {

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

@@ -12,7 +12,7 @@ use function spl_object_id;
 class NonStrictReadWriteCachedCollectionPersister extends AbstractCollectionPersister
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionComplete()
     {
@@ -32,7 +32,7 @@ class NonStrictReadWriteCachedCollectionPersister extends AbstractCollectionPers
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionRolledBack()
     {
@@ -40,7 +40,7 @@ class NonStrictReadWriteCachedCollectionPersister extends AbstractCollectionPers
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function delete(PersistentCollection $collection)
     {
@@ -53,7 +53,7 @@ class NonStrictReadWriteCachedCollectionPersister extends AbstractCollectionPers
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update(PersistentCollection $collection)
     {

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

@@ -11,7 +11,7 @@ use Doctrine\ORM\PersistentCollection;
 class ReadOnlyCachedCollectionPersister extends NonStrictReadWriteCachedCollectionPersister
 {
      /**
-      * {@inheritdoc}
+      * {@inheritDoc}
       */
     public function update(PersistentCollection $collection)
     {

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

@@ -7,21 +7,23 @@ namespace Doctrine\ORM\Cache\Persister\Collection;
 use Doctrine\ORM\Cache\CollectionCacheKey;
 use Doctrine\ORM\Cache\ConcurrentRegion;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Persisters\Collection\CollectionPersister;
 
 use function spl_object_id;
 
+/** @psalm-import-type AssociationMapping from ClassMetadata */
 class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
 {
-    /** @param mixed[] $association The association mapping. */
+    /** @param AssociationMapping $association The association mapping. */
     public function __construct(CollectionPersister $persister, ConcurrentRegion $region, EntityManagerInterface $em, array $association)
     {
         parent::__construct($persister, $region, $em, $association);
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionComplete()
     {
@@ -41,7 +43,7 @@ class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionRolledBack()
     {
@@ -61,7 +63,7 @@ class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function delete(PersistentCollection $collection)
     {
@@ -82,7 +84,7 @@ class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update(PersistentCollection $collection)
     {

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

@@ -98,7 +98,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function addInsert($entity)
     {
@@ -106,7 +106,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getInserts()
     {
@@ -114,7 +114,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getSelectSQL($criteria, $assoc = null, $lockMode = null, $limit = null, $offset = null, ?array $orderBy = null)
     {
@@ -130,7 +130,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getInsertSQL()
     {
@@ -138,7 +138,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getResultSetMapping()
     {
@@ -146,7 +146,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getSelectConditionStatementSQL($field, $value, $assoc = null, $comparison = null)
     {
@@ -154,7 +154,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function exists($entity, ?Criteria $extraConditions = null)
     {
@@ -170,7 +170,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getCacheRegion()
     {
@@ -184,7 +184,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function storeEntityCache($entity, EntityCacheKey $key)
     {
@@ -246,7 +246,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
      *
      * @param string            $query
      * @param string[]|Criteria $criteria
-     * @param string[]          $orderBy
+     * @param string[]|null     $orderBy
      * @param int|null          $limit
      * @param int|null          $offset
      *
@@ -262,7 +262,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function expandParameters($criteria)
     {
@@ -270,7 +270,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function expandCriteriaParameters(Criteria $criteria)
     {
@@ -278,7 +278,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getClassMetadata()
     {
@@ -286,7 +286,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getManyToManyCollection(array $assoc, $sourceEntity, $offset = null, $limit = null)
     {
@@ -294,7 +294,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getOneToManyCollection(array $assoc, $sourceEntity, $offset = null, $limit = null)
     {
@@ -302,7 +302,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getOwningTable($fieldName)
     {
@@ -310,7 +310,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function executeInserts()
     {
@@ -320,7 +320,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function load(array $criteria, $entity = null, $assoc = null, array $hints = [], $lockMode = null, $limit = null, ?array $orderBy = null)
     {
@@ -364,7 +364,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadAll(array $criteria = [], ?array $orderBy = null, $limit = null, $offset = null)
     {
@@ -400,7 +400,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadById(array $identifier, $entity = null)
     {
@@ -464,7 +464,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadCriteria(Criteria $criteria)
     {
@@ -503,7 +503,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadManyToManyCollection(array $assoc, $sourceEntity, PersistentCollection $collection)
     {
@@ -538,7 +538,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadOneToManyCollection(array $assoc, $sourceEntity, PersistentCollection $collection)
     {
@@ -573,7 +573,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function loadOneToOneEntity(array $assoc, $sourceEntity, array $identifier = [])
     {
@@ -581,7 +581,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function lock(array $criteria, $lockMode)
     {
@@ -589,7 +589,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function refresh(array $id, $entity, $lockMode = null)
     {

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

@@ -14,7 +14,7 @@ use function get_class;
 class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionComplete()
     {
@@ -48,7 +48,7 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionRolledBack()
     {
@@ -56,7 +56,7 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function delete($entity)
     {
@@ -73,7 +73,7 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update($entity)
     {

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

@@ -13,7 +13,7 @@ use Doctrine\ORM\Cache\Exception\CannotUpdateReadOnlyEntity;
 class ReadOnlyCachedEntityPersister extends NonStrictReadWriteCachedEntityPersister
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update($entity)
     {

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

@@ -21,7 +21,7 @@ class ReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionComplete()
     {
@@ -51,7 +51,7 @@ class ReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function afterTransactionRolledBack()
     {
@@ -71,7 +71,7 @@ class ReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function delete($entity)
     {
@@ -96,7 +96,7 @@ class ReadWriteCachedEntityPersister extends AbstractEntityPersister
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update($entity)
     {

lib/Doctrine/ORM/Cache/QueryCacheKey.php

@@ -41,9 +41,10 @@ class QueryCacheKey extends CacheKey
         int $cacheMode = Cache::MODE_NORMAL,
         ?TimestampCacheKey $timestampKey = null
     ) {
-        $this->hash         = $cacheId;
         $this->lifetime     = $lifetime;
         $this->cacheMode    = $cacheMode;
         $this->timestampKey = $timestampKey;
+
+        parent::__construct($cacheId);
     }
 }

lib/Doctrine/ORM/Cache/Region/DefaultRegion.php

@@ -91,7 +91,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getName()
     {
@@ -109,7 +109,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function contains(CacheKey $key)
     {
@@ -117,7 +117,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function get(CacheKey $key)
     {
@@ -132,7 +132,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getMultiple(CollectionCacheEntry $collection)
     {
@@ -164,7 +164,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @return bool
      */
@@ -182,7 +182,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @return bool
      */
@@ -192,7 +192,7 @@ class DefaultRegion implements Region
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @return bool
      */

lib/Doctrine/ORM/Cache/Region/FileLockRegion.php

@@ -116,7 +116,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getName()
     {
@@ -124,7 +124,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function contains(CacheKey $key)
     {
@@ -136,7 +136,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function get(CacheKey $key)
     {
@@ -148,7 +148,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getMultiple(CollectionCacheEntry $collection)
     {
@@ -160,7 +160,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function put(CacheKey $key, CacheEntry $entry, ?Lock $lock = null)
     {
@@ -172,7 +172,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evict(CacheKey $key)
     {
@@ -184,7 +184,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function evictAll()
     {
@@ -202,7 +202,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function lock(CacheKey $key)
     {
@@ -223,7 +223,7 @@ class FileLockRegion implements ConcurrentRegion
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function unlock(CacheKey $key, Lock $lock)
     {

lib/Doctrine/ORM/Cache/Region/UpdateTimestampCache.php

@@ -14,7 +14,7 @@ use Doctrine\ORM\Cache\TimestampRegion;
 class UpdateTimestampCache extends DefaultRegion implements TimestampRegion
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function update(CacheKey $key)
     {

lib/Doctrine/ORM/Cache/TimestampCacheKey.php

@@ -12,6 +12,6 @@ class TimestampCacheKey extends CacheKey
     /** @param string $space Result cache id */
     public function __construct($space)
     {
-        $this->hash = (string) $space;
+        parent::__construct((string) $space);
     }
 }

lib/Doctrine/ORM/Cache/TimestampQueryCacheValidator.php

@@ -17,7 +17,7 @@ class TimestampQueryCacheValidator implements QueryCacheValidator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isValid(QueryCacheKey $key, QueryCacheEntry $entry)
     {

lib/Doctrine/ORM/Configuration.php

@@ -4,8 +4,8 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM;
 
+use BadMethodCallException;
 use Doctrine\Common\Annotations\AnnotationReader;
-use Doctrine\Common\Annotations\AnnotationRegistry;
 use Doctrine\Common\Annotations\CachedReader;
 use Doctrine\Common\Annotations\SimpleAnnotationReader;
 use Doctrine\Common\Cache\ArrayCache;
@@ -13,7 +13,6 @@ 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\Common\Proxy\AbstractProxyFactory;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Cache\Exception\CacheException;
@@ -36,6 +35,7 @@ use Doctrine\ORM\Mapping\Driver\AnnotationDriver;
 use Doctrine\ORM\Mapping\EntityListenerResolver;
 use Doctrine\ORM\Mapping\NamingStrategy;
 use Doctrine\ORM\Mapping\QuoteStrategy;
+use Doctrine\ORM\Mapping\TypedFieldMapper;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Query\AST\Functions\FunctionNode;
 use Doctrine\ORM\Query\Filter\SQLFilter;
@@ -44,14 +44,17 @@ use Doctrine\ORM\Repository\DefaultRepositoryFactory;
 use Doctrine\ORM\Repository\RepositoryFactory;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Persistence\ObjectRepository;
+use Doctrine\Persistence\Reflection\RuntimeReflectionProperty;
 use LogicException;
 use Psr\Cache\CacheItemPoolInterface;
+use Symfony\Component\VarExporter\LazyGhostTrait;
 
 use function class_exists;
 use function is_a;
 use function method_exists;
 use function sprintf;
 use function strtolower;
+use function trait_exists;
 use function trim;
 
 /**
@@ -92,18 +95,18 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the strategy for automatically generating proxy classes.
      *
-     * @return int Possible values are constants of Doctrine\Common\Proxy\AbstractProxyFactory.
+     * @return int Possible values are constants of Doctrine\ORM\Proxy\ProxyFactory.
      * @psalm-return AutogenerateMode
      */
     public function getAutoGenerateProxyClasses()
     {
-        return $this->_attributes['autoGenerateProxyClasses'] ?? AbstractProxyFactory::AUTOGENERATE_ALWAYS;
+        return $this->_attributes['autoGenerateProxyClasses'] ?? ProxyFactory::AUTOGENERATE_ALWAYS;
     }
 
     /**
      * Sets the strategy for automatically generating proxy classes.
      *
-     * @param bool|int $autoGenerate Possible values are constants of Doctrine\Common\Proxy\AbstractProxyFactory.
+     * @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.
      *
@@ -172,16 +175,21 @@ class Configuration extends \Doctrine\DBAL\Configuration
         );
 
         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.'
-            ));
+            );
         }
 
-        AnnotationRegistry::registerFile(__DIR__ . '/Mapping/Driver/DoctrineAnnotations.php');
-
         if ($useSimpleAnnotationReader) {
+            if (! class_exists(SimpleAnnotationReader::class)) {
+                throw new BadMethodCallException(
+                    'SimpleAnnotationReader has been removed in doctrine/annotations 2.'
+                    . ' Downgrade to version 1 or set $useSimpleAnnotationReader to false.'
+                );
+            }
+
             // Register the ORM Annotations in the AnnotationRegistry
             $reader = new SimpleAnnotationReader();
             $reader->addNamespace('Doctrine\ORM\Mapping');
@@ -189,7 +197,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
             $reader = new AnnotationReader();
         }
 
-        if (class_exists(ArrayCache::class)) {
+        if (class_exists(ArrayCache::class) && class_exists(CachedReader::class)) {
             $reader = new CachedReader($reader, new ArrayCache());
         }
 
@@ -219,7 +227,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
                 $alias
             );
         } else {
-            NotSupported::createForPersistence3(sprintf(
+            throw NotSupported::createForPersistence3(sprintf(
                 'Using short namespace alias "%s" by calling %s',
                 $alias,
                 __METHOD__
@@ -572,7 +580,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
             throw QueryCacheUsesNonPersistentCache::fromDriver($queryCacheImpl);
         }
 
-        if ($this->getAutoGenerateProxyClasses() !== AbstractProxyFactory::AUTOGENERATE_NEVER) {
+        if ($this->getAutoGenerateProxyClasses() !== ProxyFactory::AUTOGENERATE_NEVER) {
             throw ProxyClassesAlwaysRegenerating::create();
         }
 
@@ -717,7 +725,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|callable|null
-     * @psalm-return class-string|callable|null $name
+     * @psalm-return class-string|callable|null
      */
     public function getCustomDatetimeFunction($name)
     {
@@ -746,6 +754,22 @@ class Configuration extends \Doctrine\DBAL\Configuration
         }
     }
 
+    /**
+     * Sets a TypedFieldMapper for php typed fields to DBAL types auto-completion.
+     */
+    public function setTypedFieldMapper(?TypedFieldMapper $typedFieldMapper): void
+    {
+        $this->_attributes['typedFieldMapper'] = $typedFieldMapper;
+    }
+
+    /**
+     * Gets a TypedFieldMapper for php typed fields to DBAL types auto-completion.
+     */
+    public function getTypedFieldMapper(): ?TypedFieldMapper
+    {
+        return $this->_attributes['typedFieldMapper'] ?? null;
+    }
+
     /**
      * Sets the custom hydrator modes in one pass.
      *
@@ -1073,4 +1097,28 @@ class Configuration extends \Doctrine\DBAL\Configuration
     {
         $this->_attributes['schemaIgnoreClasses'] = $schemaIgnoreClasses;
     }
+
+    public function isLazyGhostObjectEnabled(): bool
+    {
+        return $this->_attributes['isLazyGhostObjectEnabled'] ?? false;
+    }
+
+    public function setLazyGhostObjectEnabled(bool $flag): void
+    {
+        if ($flag && ! trait_exists(LazyGhostTrait::class)) {
+            throw new LogicException(
+                'Lazy ghost objects cannot be enabled because the "symfony/var-exporter" library'
+                . ' version 6.2 or higher is not installed. Please run "composer require symfony/var-exporter:^6.2".'
+            );
+        }
+
+        if ($flag && ! class_exists(RuntimeReflectionProperty::class)) {
+            throw new LogicException(
+                'Lazy ghost objects cannot be enabled because the "doctrine/persistence" library'
+                . ' version 3.1 or higher is not installed. Please run "composer update doctrine/persistence".'
+            );
+        }
+
+        $this->_attributes['isLazyGhostObjectEnabled'] = $flag;
+    }
 }

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -9,6 +9,8 @@ use Doctrine\ORM\EntityRepository;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\ObjectManagerDecorator;
 
+use function func_get_arg;
+use function func_num_args;
 use function get_debug_type;
 use function method_exists;
 use function sprintf;
@@ -29,7 +31,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getConnection()
     {
@@ -37,7 +39,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getExpressionBuilder()
     {
@@ -45,7 +47,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @psalm-param class-string<T> $className
      *
@@ -59,7 +61,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getClassMetadata($className)
     {
@@ -67,7 +69,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function beginTransaction()
     {
@@ -75,7 +77,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function transactional($func)
     {
@@ -83,7 +85,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function wrapInTransaction(callable $func)
     {
@@ -100,7 +102,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function commit()
     {
@@ -108,7 +110,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function rollback()
     {
@@ -116,7 +118,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createQuery($dql = '')
     {
@@ -124,7 +126,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createNamedQuery($name)
     {
@@ -132,7 +134,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createNativeQuery($sql, ResultSetMapping $rsm)
     {
@@ -140,7 +142,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createNamedNativeQuery($name)
     {
@@ -148,7 +150,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function createQueryBuilder()
     {
@@ -156,7 +158,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getReference($entityName, $id)
     {
@@ -164,7 +166,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getPartialReference($entityName, $identifier)
     {
@@ -172,7 +174,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function close()
     {
@@ -180,7 +182,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function copy($entity, $deep = false)
     {
@@ -188,7 +190,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function lock($entity, $lockMode, $lockVersion = null)
     {
@@ -196,7 +198,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function find($className, $id, $lockMode = null, $lockVersion = null)
     {
@@ -204,7 +206,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function flush($entity = null)
     {
@@ -212,7 +214,21 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
+     */
+    public function refresh($object)
+    {
+        $lockMode = null;
+
+        if (func_num_args() > 1) {
+            $lockMode = func_get_arg(1);
+        }
+
+        $this->wrapped->refresh($object, $lockMode);
+    }
+
+    /**
+     * {@inheritDoc}
      */
     public function getEventManager()
     {
@@ -220,7 +236,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getConfiguration()
     {
@@ -228,7 +244,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isOpen()
     {
@@ -236,7 +252,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getUnitOfWork()
     {
@@ -244,7 +260,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getHydrator($hydrationMode)
     {
@@ -252,7 +268,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function newHydrator($hydrationMode)
     {
@@ -260,7 +276,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getProxyFactory()
     {
@@ -268,7 +284,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getFilters()
     {
@@ -276,7 +292,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isFiltersStateClean()
     {
@@ -284,7 +300,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function hasFilters()
     {
@@ -292,7 +308,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getCache()
     {

lib/Doctrine/ORM/EntityManager.php

@@ -60,8 +60,8 @@ use function strpos;
  *     $paths = ['/path/to/entity/mapping/files'];
  *
  *     $config = ORMSetup::createAttributeMetadataConfiguration($paths);
- *     $dbParams = ['driver' => 'pdo_sqlite', 'memory' => true];
- *     $entityManager = EntityManager::create($dbParams, $config);
+ *     $connection = DriverManager::getConnection(['driver' => 'pdo_sqlite', 'memory' => true], $config);
+ *     $entityManager = new EntityManager($connection, $config);
  *
  * For more information see
  * {@link http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/configuration.html}
@@ -156,7 +156,7 @@ class EntityManager implements EntityManagerInterface
      * Creates a new EntityManager that operates on the given database connection
      * and uses the given Configuration and EventManager implementations.
      */
-    public function __construct(Connection $conn, Configuration $config)
+    public function __construct(Connection $conn, Configuration $config, ?EventManager $eventManager = null)
     {
         if (! $config->getMetadataDriverImpl()) {
             throw MissingMappingDriverImplementation::create();
@@ -164,7 +164,7 @@ class EntityManager implements EntityManagerInterface
 
         $this->conn         = $conn;
         $this->config       = $config;
-        $this->eventManager = $conn->getEventManager();
+        $this->eventManager = $eventManager ?? $conn->getEventManager();
 
         $metadataFactoryClassName = $config->getClassMetadataFactoryName();
 
@@ -693,14 +693,16 @@ class EntityManager implements EntityManagerInterface
      * Refreshes the persistent state of an entity from the database,
      * overriding any local changes that have not yet been persisted.
      *
-     * @param object $entity The entity to refresh.
+     * @param object $entity The entity to refresh
+     * @psalm-param LockMode::*|null $lockMode
      *
      * @return void
      *
      * @throws ORMInvalidArgumentException
      * @throws ORMException
+     * @throws TransactionRequiredException
      */
-    public function refresh($entity)
+    public function refresh($entity, ?int $lockMode = null)
     {
         if (! is_object($entity)) {
             throw ORMInvalidArgumentException::invalidObject('EntityManager#refresh()', $entity);
@@ -708,7 +710,7 @@ class EntityManager implements EntityManagerInterface
 
         $this->errorIfClosed();
 
-        $this->unitOfWork->refresh($entity);
+        $this->unitOfWork->refresh($entity, $lockMode);
     }
 
     /**
@@ -767,6 +769,8 @@ class EntityManager implements EntityManagerInterface
 
     /**
      * {@inheritDoc}
+     *
+     * @psalm-return never
      */
     public function copy($entity, $deep = false)
     {
@@ -810,7 +814,7 @@ class EntityManager implements EntityManagerInterface
                     $entityName
                 );
             } else {
-                NotSupported::createForPersistence3(sprintf(
+                throw NotSupported::createForPersistence3(sprintf(
                     'Using short namespace alias "%s" when calling %s',
                     $entityName,
                     __METHOD__
@@ -952,6 +956,8 @@ class EntityManager implements EntityManagerInterface
     /**
      * Factory method to create EntityManager instances.
      *
+     * @deprecated Use {@see DriverManager::getConnection()} to bootstrap the connection and call the constructor.
+     *
      * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
      * @param Configuration      $config       The Configuration instance to use.
      * @param EventManager|null  $eventManager The EventManager instance to use.
@@ -964,6 +970,15 @@ class EntityManager implements EntityManagerInterface
      */
     public static function create($connection, Configuration $config, ?EventManager $eventManager = null)
     {
+        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.',
+            __METHOD__,
+            DriverManager::class,
+            self::class
+        );
+
         $connection = static::createConnection($connection, $config, $eventManager);
 
         return new EntityManager($connection, $config);
@@ -972,6 +987,8 @@ class EntityManager implements EntityManagerInterface
     /**
      * Factory method to create Connection instances.
      *
+     * @deprecated Use {@see DriverManager::getConnection()} to bootstrap the connection.
+     *
      * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
      * @param Configuration      $config       The Configuration instance to use.
      * @param EventManager|null  $eventManager The EventManager instance to use.
@@ -984,6 +1001,14 @@ class EntityManager implements EntityManagerInterface
      */
     protected static function createConnection($connection, Configuration $config, ?EventManager $eventManager = null)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9961',
+            '%s() is deprecated, call %s::getConnection() instead.',
+            __METHOD__,
+            DriverManager::class
+        );
+
         if (is_array($connection)) {
             return DriverManager::getConnection($connection, $config, $eventManager ?: new EventManager());
         }

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -22,11 +22,12 @@ use Doctrine\Persistence\ObjectManager;
  *
  * @method Mapping\ClassMetadataFactory getMetadataFactory()
  * @method mixed wrapInTransaction(callable $func)
+ * @method void refresh(object $object, ?int $lockMode = null)
  */
 interface EntityManagerInterface extends ObjectManager
 {
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @psalm-param class-string<T> $className
      *

lib/Doctrine/ORM/EntityRepository.php

@@ -297,7 +297,7 @@ class EntityRepository implements ObjectRepository, Selectable
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function getClassName()
     {

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -12,6 +12,8 @@ use Doctrine\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
  * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions
  * of entities.
  *
+ * @deprecated This class will be removed in ORM 3.0. Use one of the dedicated classes instead.
+ *
  * @extends BaseLifecycleEventArgs<EntityManagerInterface>
  */
 class LifecycleEventArgs extends BaseLifecycleEventArgs

lib/Doctrine/ORM/Event/PostLoadEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PostLoadEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PostPersistEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PostPersistEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PostRemoveEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PostRemoveEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PostUpdateEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PostUpdateEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PrePersistEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PrePersistEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PreRemoveEventArgs.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Event;
+
+final class PreRemoveEventArgs extends LifecycleEventArgs
+{
+}

lib/Doctrine/ORM/Event/PreUpdateEventArgs.php

@@ -12,7 +12,7 @@ use function get_debug_type;
 use function sprintf;
 
 /**
- * Class that holds event arguments for a preInsert/preUpdate event.
+ * Class that holds event arguments for a preUpdate event.
  */
 class PreUpdateEventArgs extends LifecycleEventArgs
 {

lib/Doctrine/ORM/Events.php

@@ -73,7 +73,7 @@ final class Events
      * has been applied to it.
      *
      * Note that the postLoad event occurs for an entity before any associations have been
-     * initialized. Therefore it is not safe to access associations in a postLoad callback
+     * initialized. Therefore, it is not safe to access associations in a postLoad callback
      * or event handler.
      *
      * This is an entity lifecycle event.

lib/Doctrine/ORM/Id/AssignedGenerator.php

@@ -17,7 +17,7 @@ class AssignedGenerator extends AbstractIdGenerator
     /**
      * Returns the identifier assigned to the given entity.
      *
-     * {@inheritdoc}
+     * {@inheritDoc}
      *
      * @throws EntityMissingAssignedId
      */

lib/Doctrine/ORM/Id/IdentityGenerator.php

@@ -49,7 +49,7 @@ class IdentityGenerator extends AbstractIdGenerator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     public function isPostInsertGenerator()
     {

lib/Doctrine/ORM/Id/SequenceGenerator.php

@@ -21,20 +21,20 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
      *
      * @var int
      */
-    private $_allocationSize;
+    private $allocationSize;
 
     /**
      * The name of the sequence.
      *
      * @var string
      */
-    private $_sequenceName;
+    private $sequenceName;
 
     /** @var int */
-    private $_nextValue = 0;
+    private $nextValue = 0;
 
     /** @var int|null */
-    private $_maxValue = null;
+    private $maxValue = null;
 
     /**
      * Initializes a new sequence generator.
@@ -44,8 +44,8 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
      */
     public function __construct($sequenceName, $allocationSize)
     {
-        $this->_sequenceName   = $sequenceName;
-        $this->_allocationSize = $allocationSize;
+        $this->sequenceName   = $sequenceName;
+        $this->allocationSize = $allocationSize;
     }
 
     /**
@@ -53,20 +53,20 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
      */
     public function generateId(EntityManagerInterface $em, $entity)
     {
-        if ($this->_maxValue === null || $this->_nextValue === $this->_maxValue) {
+        if ($this->maxValue === null || $this->nextValue === $this->maxValue) {
             // Allocate new values
             $connection = $em->getConnection();
-            $sql        = $connection->getDatabasePlatform()->getSequenceNextValSQL($this->_sequenceName);
+            $sql        = $connection->getDatabasePlatform()->getSequenceNextValSQL($this->sequenceName);
 
             if ($connection instanceof PrimaryReadReplicaConnection) {
                 $connection->ensureConnectedToPrimary();
             }
 
-            $this->_nextValue = (int) $connection->fetchOne($sql);
-            $this->_maxValue  = $this->_nextValue + $this->_allocationSize;
+            $this->nextValue = (int) $connection->fetchOne($sql);
+            $this->maxValue  = $this->nextValue + $this->allocationSize;
         }
 
-        return $this->_nextValue++;
+        return $this->nextValue++;
     }
 
     /**
@@ -76,7 +76,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
      */
     public function getCurrentMaxValue()
     {
-        return $this->_maxValue;
+        return $this->maxValue;
     }
 
     /**
@@ -86,7 +86,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
      */
     public function getNextValue()
     {
-        return $this->_nextValue;
+        return $this->nextValue;
     }
 
     /**
@@ -103,8 +103,8 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
     public function __serialize(): array
     {
         return [
-            'allocationSize' => $this->_allocationSize,
-            'sequenceName' => $this->_sequenceName,
+            'allocationSize' => $this->allocationSize,
+            'sequenceName' => $this->sequenceName,
         ];
     }
 
@@ -123,7 +123,7 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
     /** @param array<string, mixed> $data */
     public function __unserialize(array $data): void
     {
-        $this->_sequenceName   = $data['sequenceName'];
-        $this->_allocationSize = $data['allocationSize'];
+        $this->sequenceName   = $data['sequenceName'];
+        $this->allocationSize = $data['allocationSize'];
     }
 }

lib/Doctrine/ORM/Id/TableGenerator.php

@@ -14,19 +14,19 @@ use Doctrine\ORM\EntityManagerInterface;
 class TableGenerator extends AbstractIdGenerator
 {
     /** @var string */
-    private $_tableName;
+    private $tableName;
 
     /** @var string */
-    private $_sequenceName;
+    private $sequenceName;
 
     /** @var int */
-    private $_allocationSize;
+    private $allocationSize;
 
     /** @var int|null */
-    private $_nextValue;
+    private $nextValue;
 
     /** @var int|null */
-    private $_maxValue;
+    private $maxValue;
 
     /**
      * @param string $tableName
@@ -35,9 +35,9 @@ class TableGenerator extends AbstractIdGenerator
      */
     public function __construct($tableName, $sequenceName = 'default', $allocationSize = 10)
     {
-        $this->_tableName      = $tableName;
-        $this->_sequenceName   = $sequenceName;
-        $this->_allocationSize = $allocationSize;
+        $this->tableName      = $tableName;
+        $this->sequenceName   = $sequenceName;
+        $this->allocationSize = $allocationSize;
     }
 
     /**
@@ -47,23 +47,23 @@ class TableGenerator extends AbstractIdGenerator
         EntityManagerInterface $em,
         $entity
     ) {
-        if ($this->_maxValue === null || $this->_nextValue === $this->_maxValue) {
+        if ($this->maxValue === null || $this->nextValue === $this->maxValue) {
             // Allocate new values
             $conn = $em->getConnection();
 
             if ($conn->getTransactionNestingLevel() === 0) {
                 // use select for update
-                $sql          = $conn->getDatabasePlatform()->getTableHiLoCurrentValSql($this->_tableName, $this->_sequenceName);
+                $sql          = $conn->getDatabasePlatform()->getTableHiLoCurrentValSql($this->tableName, $this->sequenceName);
                 $currentLevel = $conn->fetchOne($sql);
 
                 if ($currentLevel !== null) {
-                    $this->_nextValue = $currentLevel;
-                    $this->_maxValue  = $this->_nextValue + $this->_allocationSize;
+                    $this->nextValue = $currentLevel;
+                    $this->maxValue  = $this->nextValue + $this->allocationSize;
 
                     $updateSql = $conn->getDatabasePlatform()->getTableHiLoUpdateNextValSql(
-                        $this->_tableName,
-                        $this->_sequenceName,
-                        $this->_allocationSize
+                        $this->tableName,
+                        $this->sequenceName,
+                        $this->allocationSize
                     );
 
                     if ($conn->executeStatement($updateSql, [1 => $currentLevel, 2 => $currentLevel + 1]) !== 1) {
@@ -78,6 +78,6 @@ class TableGenerator extends AbstractIdGenerator
             }
         }
 
-        return $this->_nextValue++;
+        return $this->nextValue++;
     }
 }

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

@@ -0,0 +1,34 @@
+<?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

@@ -0,0 +1,38 @@
+<?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

@@ -0,0 +1,17 @@
+<?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

@@ -4,7 +4,10 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Internal;
 
-use stdClass;
+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;
 
@@ -17,33 +20,28 @@ use function array_reverse;
  */
 class CommitOrderCalculator
 {
-    public const NOT_VISITED = 0;
-    public const IN_PROGRESS = 1;
-    public const VISITED     = 2;
+    /** @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.
      *
-     * The node state definition contains the following properties:
-     *
-     * - <b>state</b> (integer)
-     * Whether the node is NOT_VISITED or IN_PROGRESS
-     *
-     * - <b>value</b> (object)
-     * Actual node value
-     *
-     * - <b>dependencyList</b> (array<string>)
-     * Map of node dependencies defined as hashes.
-     *
-     * @var array<stdClass>
+     * @var array<string, Vertex>
      */
     private $nodeList = [];
 
     /**
      * Volatile variable holding calculated nodes during sorting process.
      *
-     * @psalm-var list<object>
+     * @psalm-var list<ClassMetadata>
      */
     private $sortedNodeList = [];
 
@@ -62,21 +60,14 @@ class CommitOrderCalculator
     /**
      * Adds a new node (vertex) to the graph, assigning its hash and value.
      *
-     * @param string $hash
-     * @param object $node
+     * @param string        $hash
+     * @param ClassMetadata $node
      *
      * @return void
      */
     public function addNode($hash, $node)
     {
-        $vertex = new stdClass();
-
-        $vertex->hash           = $hash;
-        $vertex->state          = self::NOT_VISITED;
-        $vertex->value          = $node;
-        $vertex->dependencyList = [];
-
-        $this->nodeList[$hash] = $vertex;
+        $this->nodeList[$hash] = new Vertex($hash, $node);
     }
 
     /**
@@ -90,14 +81,8 @@ class CommitOrderCalculator
      */
     public function addDependency($fromHash, $toHash, $weight)
     {
-        $vertex = $this->nodeList[$fromHash];
-        $edge   = new stdClass();
-
-        $edge->from   = $fromHash;
-        $edge->to     = $toHash;
-        $edge->weight = $weight;
-
-        $vertex->dependencyList[$toHash] = $edge;
+        $this->nodeList[$fromHash]->dependencyList[$toHash]
+            = new Edge($fromHash, $toHash, $weight);
     }
 
     /**
@@ -106,12 +91,12 @@ class CommitOrderCalculator
      *
      * {@internal Highly performance-sensitive method.}
      *
-     * @psalm-return list<object>
+     * @psalm-return list<ClassMetadata>
      */
     public function sort()
     {
         foreach ($this->nodeList as $vertex) {
-            if ($vertex->state !== self::NOT_VISITED) {
+            if ($vertex->state !== VertexState::NOT_VISITED) {
                 continue;
             }
 
@@ -131,19 +116,19 @@ class CommitOrderCalculator
      *
      * {@internal Highly performance-sensitive method.}
      */
-    private function visit(stdClass $vertex): void
+    private function visit(Vertex $vertex): void
     {
-        $vertex->state = self::IN_PROGRESS;
+        $vertex->state = VertexState::IN_PROGRESS;
 
         foreach ($vertex->dependencyList as $edge) {
             $adjacentVertex = $this->nodeList[$edge->to];
 
             switch ($adjacentVertex->state) {
-                case self::VISITED:
+                case VertexState::VISITED:
                     // Do nothing, since node was already visited
                     break;
 
-                case self::IN_PROGRESS:
+                case VertexState::IN_PROGRESS:
                     if (
                         isset($adjacentVertex->dependencyList[$vertex->hash]) &&
                         $adjacentVertex->dependencyList[$vertex->hash]->weight < $edge->weight
@@ -153,25 +138,25 @@ class CommitOrderCalculator
                         foreach ($adjacentVertex->dependencyList as $adjacentEdge) {
                             $adjacentEdgeVertex = $this->nodeList[$adjacentEdge->to];
 
-                            if ($adjacentEdgeVertex->state === self::NOT_VISITED) {
+                            if ($adjacentEdgeVertex->state === VertexState::NOT_VISITED) {
                                 $this->visit($adjacentEdgeVertex);
                             }
                         }
 
-                        $adjacentVertex->state = self::VISITED;
+                        $adjacentVertex->state = VertexState::VISITED;
 
                         $this->sortedNodeList[] = $adjacentVertex->value;
                     }
 
                     break;
 
-                case self::NOT_VISITED:
+                case VertexState::NOT_VISITED:
                     $this->visit($adjacentVertex);
             }
         }
 
-        if ($vertex->state !== self::VISITED) {
-            $vertex->state = self::VISITED;
+        if ($vertex->state !== VertexState::VISITED) {
+            $vertex->state = VertexState::VISITED;
 
             $this->sortedNodeList[] = $vertex->value;
         }

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

@@ -617,6 +617,7 @@ abstract class AbstractHydrator
                     'fieldName'    => $fieldName,
                     'type'         => $type,
                     'dqlAlias'     => $dqlAlias,
+                    'enumType'     => $this->_rsm->enumMappings[$key] ?? null,
                 ];
         }
 
@@ -697,7 +698,7 @@ abstract class AbstractHydrator
      *
      * @return BackedEnum|array<BackedEnum>
      */
-    private function buildEnum($value, string $enumType)
+    final protected function buildEnum($value, string $enumType)
     {
         if (is_array($value)) {
             return array_map(static function ($value) use ($enumType): BackedEnum {

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

@@ -19,39 +19,39 @@ use function reset;
 class ArrayHydrator extends AbstractHydrator
 {
     /** @var array<string,bool> */
-    private $_rootAliases = [];
+    private $rootAliases = [];
 
     /** @var bool */
-    private $_isSimpleQuery = false;
+    private $isSimpleQuery = false;
 
     /** @var mixed[] */
-    private $_identifierMap = [];
+    private $identifierMap = [];
 
     /** @var mixed[] */
-    private $_resultPointers = [];
+    private $resultPointers = [];
 
     /** @var array<string,string> */
-    private $_idTemplate = [];
+    private $idTemplate = [];
 
     /** @var int */
-    private $_resultCounter = 0;
+    private $resultCounter = 0;
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function prepare()
     {
-        $this->_isSimpleQuery = count($this->resultSetMapping()->aliasMap) <= 1;
+        $this->isSimpleQuery = count($this->resultSetMapping()->aliasMap) <= 1;
 
         foreach ($this->resultSetMapping()->aliasMap as $dqlAlias => $className) {
-            $this->_identifierMap[$dqlAlias]  = [];
-            $this->_resultPointers[$dqlAlias] = [];
-            $this->_idTemplate[$dqlAlias]     = '';
+            $this->identifierMap[$dqlAlias]  = [];
+            $this->resultPointers[$dqlAlias] = [];
+            $this->idTemplate[$dqlAlias]     = '';
         }
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function hydrateAllData()
     {
@@ -65,12 +65,12 @@ class ArrayHydrator extends AbstractHydrator
     }
 
     /**
-     * {@inheritdoc}
+     * {@inheritDoc}
      */
     protected function hydrateRowData(array $row, array &$result)
     {
         // 1) Initialize
-        $id                 = $this->_idTemplate; // initialize the id-memory
+        $id                 = $this->idTemplate; // initialize the id-memory
         $nonemptyComponents = [];
         $rowData            = $this->gatherRowData($row, $id, $nonemptyComponents);
 
@@ -91,14 +91,14 @@ class ArrayHydrator extends AbstractHydrator
 
                 // Get a reference to the right element in the result tree.
                 // This element will get the associated element attached.
-                if ($this->resultSetMapping()->isMixed && isset($this->_rootAliases[$parent])) {
-                    $first = reset($this->_resultPointers);
+                if ($this->resultSetMapping()->isMixed && isset($this->rootAliases[$parent])) {
+                    $first = reset($this->resultPointers);
                     // TODO: Exception if $key === null ?
-                    $baseElement =& $this->_resultPointers[$parent][key($first)];
-                } elseif (isset($this->_resultPointers[$parent])) {
-                    $baseElement =& $this->_resultPointers[$parent];
+                    $baseElement =& $this->resultPointers[$parent][key($first)];
+                } elseif (isset($this->resultPointers[$parent])) {
+                    $baseElement =& $this->resultPointers[$parent];
                 } else {
-                    unset($this->_resultPointers[$dqlAlias]); // Ticket #1228
+                    unset($this->resultPointers[$dqlAlias]); // Ticket #1228
 
                     continue;
                 }
@@ -116,8 +116,8 @@ class ArrayHydrator extends AbstractHydrator
                     }
 
                     if (isset($nonemptyComponents[$dqlAlias])) {
-                        $indexExists  = isset($this->_identifierMap[$path][$id[$parent]][$id[$dqlAlias]]);
-                        $index        = $indexExists ? $this->_identifierMap[$path][$id[$parent]][$id[$dqlAlias]] : false;
+                        $indexExists  = isset($this->identifierMap[$path][$id[$parent]][$id[$dqlAlias]]);
+                        $index        = $indexExists ? $this->identifierMap[$path][$id[$parent]][$id[$dqlAlias]] : false;
                         $indexIsValid = $index !== false ? isset($baseElement[$relationAlias][$index]) : false;
 
                         if (! $indexExists || ! $indexIsValid) {
@@ -131,7 +131,7 @@ class ArrayHydrator extends AbstractHydrator
 
                             end($baseElement[$relationAlias]);
 
-                            $this->_identifierMap[$path][$id[$parent]][$id[$dqlAlias]] = key($baseElement[$relationAlias]);
+                            $this->identifierMap[$path][$id[$parent]][$id[$dqlAlias]] = key($baseElement[$relationAlias]);
                         }
                     }
                 } else {
@@ -155,8 +155,8 @@ class ArrayHydrator extends AbstractHydrator
             } else {
                 // It's a root result element
 
-                $this->_rootAliases[$dqlAlias] = true; // Mark as root
-                $entityKey                     = $this->resultSetMapping()->entityMappings[$dqlAlias] ?: 0;
+                $this->rootAliases[$dqlAlias] = true; // Mark as root
+                $entityKey                    = $this->resultSetMapping()->entityMappings[$dqlAlias] ?: 0;
 
                 // if this row has a NULL value for the root result id then make it a null result.
                 if (! isset($nonemptyComponents[$dqlAlias])) {
@@ -164,14 +164,14 @@ class ArrayHydrator extends AbstractHydrator
                         ? [$entityKey => null]
                         : null;
 
-                    $resultKey = $this->_resultCounter;
-                    ++$this->_resultCounter;
+                    $resultKey = $this->resultCounter;
+                    ++$this->resultCounter;
 
                     continue;
                 }
 
                 // Check for an existing element
-                if ($this->_isSimpleQuery || ! isset($this->_identifierMap[$dqlAlias][$id[$dqlAlias]])) {
+                if ($this->isSimpleQuery || ! isset($this->identifierMap[$dqlAlias][$id[$dqlAlias]])) {
                     $element = $this->resultSetMapping()->isMixed
                         ? [$entityKey => $data]
                         : $data;
@@ -180,15 +180,15 @@ class ArrayHydrator extends AbstractHydrator
                         $resultKey          = $row[$this->resultSetMapping()->indexByMap[$dqlAlias]];
                         $result[$resultKey] = $element;
                     } else {
-                        $resultKey = $this->_resultCounter;
+                        $resultKey = $this->resultCounter;
                         $result[]  = $element;
 
-                        ++$this->_resultCounter;
+                        ++$this->resultCounter;
                     }
 
-                    $this->_identifierMap[$dqlAlias][$id[$dqlAlias]] = $resultKey;
+                    $this->identifierMap[$dqlAlias][$id[$dqlAlias]] = $resultKey;
                 } else {
-                    $index     = $this->_identifierMap[$dqlAlias][$id[$dqlAlias]];
+                    $index     = $this->identifierMap[$dqlAlias][$id[$dqlAlias]];
                     $resultKey = $index;
                 }
 
@@ -197,7 +197,7 @@ class ArrayHydrator extends AbstractHydrator
         }
 
         if (! isset($resultKey)) {
-            $this->_resultCounter++;
+            $this->resultCounter++;
         }
 
         // Append scalar values to mixed result sets
@@ -206,7 +206,7 @@ class ArrayHydrator extends AbstractHydrator
                 // this only ever happens when no object is fetched (scalar result only)
                 $resultKey = isset($this->resultSetMapping()->indexByMap['scalars'])
                     ? $row[$this->resultSetMapping()->indexByMap['scalars']]
-                    : $this->_resultCounter - 1;
+                    : $this->resultCounter - 1;
             }
 
             foreach ($rowData['scalars'] as $name => $value) {
@@ -217,7 +217,7 @@ class ArrayHydrator extends AbstractHydrator
         // Append new object to mixed result sets
         if (isset($rowData['newObjects'])) {
             if (! isset($resultKey)) {
-                $resultKey = $this->_resultCounter - 1;
+                $resultKey = $this->resultCounter - 1;
             }
 
             $scalarCount = (isset($rowData['scalars']) ? count($rowData['scalars']) : 0);
@@ -253,19 +253,19 @@ class ArrayHydrator extends AbstractHydrator
         bool $oneToOne
     ): void {
         if ($coll === null) {
-            unset($this->_resultPointers[$dqlAlias]); // Ticket #1228
+            unset($this->resultPointers[$dqlAlias]); // Ticket #1228
 
             return;
         }
 
         if ($oneToOne) {
-            $this->_resultPointers[$dqlAlias] =& $coll;
+            $this->resultPointers[$dqlAlias] =& $coll;
 
             return;
         }
 
         if ($index !== false) {
-            $this->_resultPointers[$dqlAlias] =& $coll[$index];
+            $this->resultPointers[$dqlAlias] =& $coll[$index];
 
             return;
         }
@@ -275,6 +275,6 @@ class ArrayHydrator extends AbstractHydrator
         }
 
         end($coll);
-        $this->_resultPointers[$dqlAlias] =& $coll[key($coll)];
+        $this->resultPointers[$dqlAlias] =& $coll[key($coll)];
     }
 }

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

@@ -16,21 +16,21 @@ use ReturnTypeWillChange;
 class IterableResult implements Iterator
 {
     /** @var AbstractHydrator */
-    private $_hydrator;
+    private $hydrator;
 
     /** @var bool */
-    private $_rewinded = false;
+    private $rewinded = false;
 
     /** @var int */
-    private $_key = -1;
+    private $key = -1;
 
     /** @var mixed[]|null */
-    private $_current = null;
+    private $current = null;
 
     /** @param AbstractHydrator $hydrator */
     public function __construct($hydrator)
     {
-        $this->_hydrator = $hydrator;
+        $this->hydrator = $hydrator;
     }
 
     /**
@@ -41,12 +41,12 @@ class IterableResult implements Iterator
     #[ReturnTypeWillChange]
     public function rewind()
     {
-        if ($this->_rewinded === true) {
+        if ($this->rewinded === true) {
             throw new HydrationException('Can only iterate a Result once.');
         }
 
-        $this->_current  = $this->next();
-        $this->_rewinded = true;
+        $this->current  = $this->next();
+        $this->rewinded = true;
     }
 
     /**
@@ -57,30 +57,30 @@ class IterableResult implements Iterator
     #[ReturnTypeWillChange]
     public function next()
     {
-        $this->_current = $this->_hydrator->hydrateRow();
-        $this->_key++;
+        $this->current = $this->hydrator->hydrateRow();
+        $this->key++;
 
-        return $this->_current;
+        return $this->current;
     }
 
     /** @return mixed */
     #[ReturnTypeWillChange]
     public function current()
     {
-        return $this->_current;
+        return $this->current;
     }
 
     /** @return int */
     #[ReturnTypeWillChange]
     public function key()
     {
-        return $this->_key;
+        return $this->key;
     }
 
     /** @return bool */
     #[ReturnTypeWillChange]
     public function valid()
     {
-        return $this->_current !== false;
+        return $this->current !== false;
     }
 }