Address DBAL 3.4 deprecations (#9969)

* 2.12.x:
  Fix build (#9964)
  fix: class normalisation test (#9966)

.doctrine-project.json

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

.gitattributes

@@ -1,7 +1,8 @@
+/.github export-ignore
+/ci export-ignore
+/docs export-ignore
 /tests export-ignore
 /tools export-ignore
-/docs export-ignore
-/.github export-ignore
 .doctrine-project.json export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore

.github/workflows/continuous-integration.yml

@@ -30,7 +30,9 @@ jobs:
           - php-version: "8.0"
             dbal-version: "2.13"
           - php-version: "8.1"
-            dbal-version: "3.2@dev"
+            dbal-version: "3@dev"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
 
     steps:
       - name: "Checkout"
@@ -42,7 +44,7 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: "pdo, pdo_sqlite"
+          extensions: "apcu, pdo, pdo_sqlite"
           coverage: "pcov"
           ini-values: "zend.assertions=1"
 
@@ -52,6 +54,8 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --coverage-clover=coverage-no-cache.xml"
@@ -78,16 +82,19 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
         dbal-version:
           - "default"
         postgres-version:
           - "9.6"
-          - "13"
+          - "14"
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
-            postgres-version: "13"
+            postgres-version: "14"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            postgres-version: "14"
 
     services:
       postgres:
@@ -120,6 +127,8 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
@@ -139,19 +148,27 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
         dbal-version:
           - "default"
         mariadb-version:
-          - "10.5"
+          - "10.6"
         extension:
           - "mysqli"
           - "pdo_mysql"
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
-            mariadb-version: "10.5"
+            mariadb-version: "10.6"
             extension: "pdo_mysql"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            mariadb-version: "10.6"
+            extension: "pdo_mysql"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            mariadb-version: "10.6"
+            extension: "mysqli"
 
     services:
       mariadb:
@@ -186,6 +203,8 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
@@ -205,7 +224,7 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
         dbal-version:
           - "default"
         mysql-version:
@@ -219,6 +238,14 @@ jobs:
             dbal-version: "2.13"
             mysql-version: "8.0"
             extension: "pdo_mysql"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            mysql-version: "8.0"
+            extension: "mysqli"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            mysql-version: "8.0"
+            extension: "pdo_mysql"
 
     services:
       mysql:
@@ -252,6 +279,8 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"

.github/workflows/static-analysis.yml

@@ -21,7 +21,15 @@ jobs:
           - "8.1"
         dbal-version:
           - "default"
-          - "2.13"
+        persistence-version:
+          - "default"
+        include:
+          - php-version: "8.1"
+            dbal-version: "2.13"
+            persistence-version: "default"
+          - php-version: "8.1"
+            dbal-version: "default"
+            persistence-version: "2.5"
 
     steps:
       - name: "Checkout code"
@@ -37,6 +45,10 @@ jobs:
         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' }}"
+
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
         with:
@@ -44,12 +56,16 @@ jobs:
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse"
-        if: "${{ matrix.dbal-version == 'default' }}"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version == 'default'}}"
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse -c phpstan-dbal2.neon"
         if: "${{ matrix.dbal-version == '2.13' }}"
 
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -c phpstan-persistence2.neon"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version != 'default'}}"
+
   static-analysis-psalm:
     name: "Static Analysis with Psalm"
     runs-on: "ubuntu-20.04"

.gitignore

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

CONTRIBUTING.md

@@ -37,8 +37,7 @@ will have to run a composer installation in the project:
 ```sh
 git clone git@github.com:doctrine/orm.git
 cd orm
-curl -sS https://getcomposer.org/installer | php --
-./composer.phar install
+composer install
 ```
 
 To run the testsuite against another database, copy the ``phpunit.xml.dist``

README.md

@@ -1,9 +1,11 @@
-| [3.0.x][3.0] | [2.11.x][2.11] | [2.10.x][2.10] |
+| [3.0.x][3.0] | [2.13.x][2.13] | [2.12.x][2.12] |
 |:----------------:|:----------------:|:----------:|
-| [![Build status][3.0 image]][3.0] | [![Build status][2.11 image]][2.11] | [![Build status][2.10 image]][2.10] |
-| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.11 coverage image]][2.11 coverage] | [![Coverage Status][2.10 coverage image]][2.10 coverage]  |
+| [![Build status][3.0 image]][3.0] | [![Build status][2.13 image]][2.13] | [![Build status][2.12 image]][2.12] |
+| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.13 coverage image]][2.13 coverage] | [![Coverage Status][2.12 coverage image]][2.12 coverage]  |
 
-Doctrine 2 is an object-relational mapper (ORM) for PHP 7.1+ that provides transparent persistence
+[<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
+
+Doctrine ORM is an object-relational mapper for PHP 7.1+ that provides transparent persistence
 for PHP objects. It sits on top of a powerful database abstraction layer (DBAL). One of its key features
 is the option to write database queries in a proprietary object oriented SQL dialect called Doctrine Query Language (DQL),
 inspired by Hibernate's HQL. This provides developers with a powerful alternative to SQL that maintains flexibility
@@ -13,18 +15,18 @@ without requiring unnecessary code duplication.
 ## More resources:
 
 * [Website](http://www.doctrine-project.org)
-* [Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/index.html)
+* [Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/stable/index.html)
 
 
   [3.0 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0.x
   [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.10 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.10.x
-  [2.10]: https://github.com/doctrine/orm/tree/2.10.x
-  [2.10 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.10.x/graph/badge.svg
-  [2.10 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.10.x
-  [2.11 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.11.x
-  [2.11]: https://github.com/doctrine/orm/tree/2.11.x
-  [2.11 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.11.x/graph/badge.svg
-  [2.11 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.11.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.12 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.12.x
+  [2.12]: https://github.com/doctrine/orm/tree/2.12.x
+  [2.12 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.12.x/graph/badge.svg
+  [2.12 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.12.x

SECURITY.md

@@ -10,8 +10,8 @@ we cannot protect you from SQL injection.
 Please read the documentation chapter on Security in Doctrine DBAL and ORM to
 understand the assumptions we make.
 
-- [DBAL Security Page](https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/security.html)
-- [ORM Security Page](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/reference/security.html)
+- [DBAL Security Page](https://www.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/security.html)
+- [ORM Security Page](https://www.doctrine-project.org/projects/doctrine-orm/en/stable/reference/security.html)
 
 If you find a Security bug in Doctrine, please report it on Jira and change the
 Security Level to "Security Issues". It will be visible to Doctrine Core

UPGRADE.md

@@ -1,3 +1,374 @@
+# Upgrade to 2.13
+
+## Deprecated `QueryBuilder` methods and constants.
+
+1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.
+2. Relying on the type of the query being built by using `QueryBuilder::getType()` has been deprecated.
+   If necessary, track the type of the query being built outside of the builder.
+
+The following `QueryBuilder` constants related to the above methods have been deprecated:
+
+1. `SELECT`,
+2. `DELETE`,
+3. `UPDATE`,
+4. `STATE_DIRTY`,
+5. `STATE_CLEAN`.
+
+## Deprecated omitting only the alias argument for `QueryBuilder::update` and `QueryBuilder::delete`
+
+When building an UPDATE or DELETE query and when passing a class/type to the function, the alias argument must not be omitted.
+
+### Before
+
+```php
+$qb = $em->createQueryBuilder()
+    ->delete('User u')
+    ->where('u.id = :user_id')
+    ->setParameter('user_id', 1);
+```
+
+### After
+
+```php
+$qb = $em->createQueryBuilder()
+    ->delete('User', 'u')
+    ->where('u.id = :user_id')
+    ->setParameter('user_id', 1);
+```
+
+## Deprecated using the `IDENTITY` identifier strategy on platform that do not support identity columns
+
+If identity columns are emulated with sequences on the platform you are using,
+you should switch to the `SEQUENCE` strategy.
+
+## Deprecated passing `null` to `Doctrine\ORM\Query::setFirstResult()`
+
+`$query->setFirstResult(null);` is equivalent to `$query->setFirstResult(0)`.
+
+## Deprecated calling setters without arguments
+
+The following methods will require an argument in 3.0. Pass `null` instead of
+omitting the argument.
+
+* `Doctrine\ORM\Event\OnClassMetadataNotFoundEventArgs::setFoundMetadata()`
+* `Doctrine\ORM\AbstractQuery::setHydrationCacheProfile()`
+* `Doctrine\ORM\AbstractQuery::setResultCache()`
+* `Doctrine\ORM\AbstractQuery::setResultCacheProfile()`
+
+## Deprecated passing invalid fetch modes to `AbstractQuery::setFetchMode()`
+
+Calling `AbstractQuery::setFetchMode()` with anything else than
+`Doctrine\ORM\Mapping::FETCH_EAGER` results in
+`Doctrine\ORM\Mapping::FETCH_LAZY` being used. Relying on that behavior is
+deprecated and will result in an exception in 3.0.
+
+## Deprecated `getEntityManager()` in `Doctrine\ORM\Event\OnClearEventArgs` and `Doctrine\ORM\Event\*FlushEventArgs`
+
+This method has been deprecated in:
+
+* `Doctrine\ORM\Event\OnClearEventArgs`
+* `Doctrine\ORM\Event\OnFlushEventArgs`
+* `Doctrine\ORM\Event\PostFlushEventArgs`
+* `Doctrine\ORM\Event\PreFlushEventArgs`
+
+It will be removed in 3.0. Use `getObjectManager()` instead.
+
+## Deprecated `Doctrine\ORM\Event\LifecycleEventArgs` class
+
+It will be removed in 3.0. Use `Doctrine\Persistence\Event\LifecycleEventArgs` instead.
+
+## Prepare split of output walkers and tree walkers
+
+In 3.0, `SqlWalker` and its child classes won't implement the `TreeWalker`
+interface anymore. Relying on that inheritance is deprecated.
+
+The following methods of the `TreeWalker` interface have been deprecated:
+
+* `setQueryComponent()`
+* `walkSelectClause()`
+* `walkFromClause()`
+* `walkFunction()`
+* `walkOrderByClause()`
+* `walkOrderByItem()`
+* `walkHavingClause()`
+* `walkJoin()`
+* `walkSelectExpression()`
+* `walkQuantifiedExpression()`
+* `walkSubselect()`
+* `walkSubselectFromClause()`
+* `walkSimpleSelectClause()`
+* `walkSimpleSelectExpression()`
+* `walkAggregateExpression()`
+* `walkGroupByClause()`
+* `walkGroupByItem()`
+* `walkDeleteClause()`
+* `walkUpdateClause()`
+* `walkUpdateItem()`
+* `walkWhereClause()`
+* `walkConditionalExpression()`
+* `walkConditionalTerm()`
+* `walkConditionalFactor()`
+* `walkConditionalPrimary()`
+* `walkExistsExpression()`
+* `walkCollectionMemberExpression()`
+* `walkEmptyCollectionComparisonExpression()`
+* `walkNullComparisonExpression()`
+* `walkInExpression()`
+* `walkInstanceOfExpression()`
+* `walkLiteral()`
+* `walkBetweenExpression()`
+* `walkLikeExpression()`
+* `walkStateFieldPathExpression()`
+* `walkComparisonExpression()`
+* `walkInputParameter()`
+* `walkArithmeticExpression()`
+* `walkArithmeticTerm()`
+* `walkStringPrimary()`
+* `walkArithmeticFactor()`
+* `walkSimpleArithmeticExpression()`
+* `walkPathExpression()`
+* `walkResultVariable()`
+* `getExecutor()`
+
+The following changes have been made to the abstract `TreeWalkerAdapter` class:
+
+* All implementations of now-deprecated `TreeWalker` methods have been
+  deprecated as well.
+* The method `setQueryComponent()` will become protected in 3.0. Calling it
+  publicly is deprecated.
+* The method `_getQueryComponents()` is deprecated, call `getQueryComponents()`
+  instead.
+
+On the `TreeWalkerChain` class, all implementations of now-deprecated
+`TreeWalker` methods have been deprecated as well.  However, `SqlWalker` is
+unaffected by those deprecations and will continue to implement all of those
+methods.
+
+## Deprecated passing `null` to `Doctrine\ORM\Query::setDQL()`
+
+Doing `$query->setDQL(null);` achieves nothing.
+
+## Deprecated omitting second argument to `NamingStrategy::joinColumnName`
+
+When implementing `NamingStrategy`, it is deprecated to implement
+`joinColumnName()` with only one argument.
+
+### Before
+
+```php
+<?php
+class MyStrategy implements NamingStrategy
+{
+    /**
+     * @param string $propertyName A property name.
+     */
+    public function joinColumnName($propertyName): string
+    {
+        // …
+    }
+}
+```
+
+### After
+
+For backward-compatibility reasons, the parameter has to be optional, but can
+be documented as guaranteed to be a `class-string`.
+
+```php
+<?php
+class MyStrategy implements NamingStrategy
+{
+    /**
+     * @param string       $propertyName A property name.
+     * @param class-string $className
+     */
+    public function joinColumnName($propertyName, $className = null): string
+    {
+        // …
+    }
+}
+```
+
+## Deprecated methods related to named queries
+
+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()`
+
+## Deprecated classes related to Doctrine 1 and reverse engineering
+
+The following classes have been deprecated:
+
+- `Doctrine\ORM\Tools\ConvertDoctrine1Schema`
+- `Doctrine\ORM\Tools\DisconnectedClassMetadataFactory`
+
+## Deprecate `ClassMetadataInfo` usage
+
+It is deprecated to pass `Doctrine\ORM\Mapping\ClassMetadataInfo` instances
+that are not also instances of `Doctrine\ORM\ClassMetadata` to the following
+methods:
+
+- `Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder::__construct()`
+- `Doctrine\ORM\Mapping\Driver\DatabaseDriver::loadMetadataForClass()`
+- `Doctrine\ORM\Tools\SchemaValidator::validateClass()`
+
+# Upgrade to 2.12
+
+## Deprecated the `doctrine` binary.
+
+The documentation explains how the console tools can be bootstrapped for
+standalone usage.
+
+The method `ConsoleRunner::printCliConfigTemplate()` is deprecated because it
+was only useful in the context of the `doctrine` binary.
+
+## Deprecate omitting `$class` argument to `ORMInvalidArgumentException::invalidIdentifierBindingEntity()`
+
+To make it easier to identify understand the cause for that exception, it is
+deprecated to omit the class name when calling
+`ORMInvalidArgumentException::invalidIdentifierBindingEntity()`.
+
+## Deprecate `Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper`
+
+Using a console helper to provide the ORM's console commands with one or
+multiple entity managers had been deprecated with 2.9 already. This leaves
+The `EntityManagerHelper` class with no purpose which is why it is now
+deprecated too. Applications that still rely on the `em` console helper, can
+easily recreate that class in their own codebase.
+
+## Deprecate custom repository classes that don't extend `EntityRepository`
+
+Although undocumented, it is currently possible to configure a custom repository
+class that implements `ObjectRepository` but does not extend the
+`EntityRepository` base class.
+
+This is now deprecated. Please extend `EntityRepository` instead.
+
+## Deprecated more APIs related to entity namespace aliases
+
+```diff
+-$config = $entityManager->getConfiguration();
+-$config->addEntityNamespace('CMS', 'My\App\Cms');
++use My\App\Cms\CmsUser;
+
+-$entityManager->getRepository('CMS:CmsUser');
++$entityManager->getRepository(CmsUser::class);
+```
+
+## Deprecate `AttributeDriver::getReader()` and `AnnotationDriver::getReader()`
+
+That method was inherited from the abstract `AnnotationDriver` class of
+`doctrine/persistence`, and does not seem to serve any purpose.
+
+## Un-deprecate `Doctrine\ORM\Proxy\Proxy`
+
+Because no forward-compatible new proxy solution had been implemented yet, the
+current proxy mechanism is not considered deprecated anymore for the time
+being. This applies to the following interfaces/classes:
+
+* `Doctrine\ORM\Proxy\Proxy`
+* `Doctrine\ORM\Proxy\ProxyFactory`
+
+These methods have been un-deprecated:
+
+* `Doctrine\ORM\Configuration::getAutoGenerateProxyClasses()`
+* `Doctrine\ORM\Configuration::getProxyDir()`
+* `Doctrine\ORM\Configuration::getProxyNamespace()`
+
+Note that the `Doctrine\ORM\Proxy\Autoloader` remains deprecated and will be removed in 3.0.
+
+## Deprecate helper methods from `AbstractCollectionPersister`
+
+The following protected methods of
+`Doctrine\ORM\Cache\Persister\Collection\AbstractCollectionPersister`
+are not in use anymore and will be removed.
+
+* `evictCollectionCache()`
+* `evictElementCache()`
+
+## Deprecate `Doctrine\ORM\Query\TreeWalkerChainIterator`
+
+This class won't have a replacement.
+
+## Deprecate `OnClearEventArgs::getEntityClass()` and `OnClearEventArgs::clearsAllEntities()`
+
+These methods will be removed in 3.0 along with the ability to partially clear
+the entity manager.
+
+## Deprecate `Doctrine\ORM\Configuration::newDefaultAnnotationDriver`
+
+This functionality has been moved to the new `ORMSetup` class. Call
+`Doctrine\ORM\ORMSetup::createDefaultAnnotationDriver()` to create
+a new annotation driver.
+
+## Deprecate `Doctrine\ORM\Tools\Setup`
+
+In our effort to migrate from Doctrine Cache to PSR-6, the `Setup` class which
+accepted a Doctrine Cache instance in each method has been deprecated.
+
+The replacement is `Doctrine\ORM\ORMSetup` which accepts a PSR-6
+cache instead.
+
+## Deprecate `Doctrine\ORM\Cache\MultiGetRegion`
+
+The interface will be merged with `Doctrine\ORM\Cache\Region` in 3.0.
+
+# Upgrade to 2.11
+
+## Rename `AbstractIdGenerator::generate()` to `generateId()`
+
+Implementations of `AbstractIdGenerator` have to override the method
+`generateId()` without calling the parent implementation. Not doing so is
+deprecated. Calling `generate()` on any `AbstractIdGenerator` implementation
+is deprecated.
+
+## PSR-6-based second level cache
+
+The second level cache has been reworked to consume a PSR-6 cache. Using a
+Doctrine Cache instance is deprecated.
+
+* `DefaultCacheFactory`: The constructor expects a PSR-6 cache item pool as
+  second argument now.
+* `DefaultMultiGetRegion`: This class is deprecated in favor of `DefaultRegion`.
+* `DefaultRegion`:
+  * The constructor expects a PSR-6 cache item pool as second argument now.
+  * The protected `$cache` property is deprecated.
+  * The properties `$name` and `$lifetime` as well as the constant
+   `REGION_KEY_SEPARATOR` and the method `getCacheEntryKey()` are flagged as
+   `@internal` now. They all will become `private` in 3.0.
+  * The method `getCache()` is deprecated without replacement.
+
+## Deprecated: `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
+You can convert mappings with the `orm:convert-mapping` command or more simply
+in this case, `include` the metadata file from the `loadMetadata` static method
+used by the `StaticPHPDriver`.
+
+## Deprecated: `Setup::registerAutoloadDirectory()`
+
+Use Composer's autoloader instead.
+
+## Deprecated: `AbstractHydrator::hydrateRow()`
+
+Following the deprecation of the method `AbstractHydrator::iterate()`, the
+method `hydrateRow()` has been deprecated as well.
+
+## Deprecate cache settings inspection
+
+Doctrine does not provide its own cache implementation anymore and relies on
+the PSR-6 standard instead. As a consequence, we cannot determine anymore
+whether a given cache adapter is suitable for a production environment.
+Because of that, functionality that aims to do so has been deprecated:
+
+* `Configuration::ensureProductionSettings()`
+* the `orm:ensure-production-settings` console command
+
 # Upgrade to 2.10
 
 ## BC Break: `UnitOfWork` now relies on SPL object IDs, not hashes
@@ -182,8 +553,7 @@ These methods have been deprecated:
 ## Deprecated `Doctrine\ORM\Version`
 
 The `Doctrine\ORM\Version` class is now deprecated and will be removed in Doctrine ORM 3.0:
-please refrain from checking the ORM version at runtime or use
-[ocramius/package-versions](https://github.com/Ocramius/PackageVersions/).
+please refrain from checking the ORM version at runtime or use Composer's [runtime API](https://getcomposer.org/doc/07-runtime.md#knowing-whether-package-x-is-installed-in-version-y).
 
 ## Deprecated `EntityManager#merge()` method
 
@@ -237,8 +607,8 @@ If you would still like to perform batching operations over small `UnitOfWork`
 instances, it is suggested to follow these paths instead:
 
  * eagerly use `EntityManager#clear()` in conjunction with a specific second level
-   cache configuration (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html)
- * use an explicit change tracking policy (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/change-tracking-policies.html)
+   cache configuration (see http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/second-level-cache.html)
+ * use an explicit change tracking policy (see http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/change-tracking-policies.html)
 
 ## Deprecated `YAML` mapping drivers.
 

bin/doctrine-pear.php

@@ -1,5 +1,15 @@
 <?php
 
+fwrite(
+    STDERR,
+    '[Warning] The use of this script is discouraged. See'
+    . ' https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#doctrine-console'
+    . ' for instructions on bootstrapping the console runner.'
+    . PHP_EOL
+);
+
+echo PHP_EOL . PHP_EOL;
+
 require_once 'Doctrine/Common/ClassLoader.php';
 
 $classLoader = new \Doctrine\Common\ClassLoader('Doctrine');

bin/doctrine.php

@@ -3,6 +3,16 @@
 use Symfony\Component\Console\Helper\HelperSet;
 use Doctrine\ORM\Tools\Console\ConsoleRunner;
 
+fwrite(
+    STDERR,
+    '[Warning] The use of this script is discouraged. See'
+    . ' https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#doctrine-console'
+    . ' for instructions on bootstrapping the console runner.'
+    . PHP_EOL
+);
+
+echo PHP_EOL . PHP_EOL;
+
 $autoloadFiles = [
     __DIR__ . '/../vendor/autoload.php',
     __DIR__ . '/../../../autoload.php'

ci/github/phpunit/mysqli.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         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="mysqli"/>
         <var name="db_host" value="127.0.0.1" />
         <var name="db_port" value="3306"/>

ci/github/phpunit/pdo_mysql.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         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="pdo_mysql"/>
         <var name="db_host" value="127.0.0.1" />
         <var name="db_port" value="3306"/>

ci/github/phpunit/pdo_pgsql.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         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="pdo_pgsql"/>
         <var name="db_host" value="localhost" />
         <var name="db_user" value="postgres" />

ci/github/phpunit/sqlite.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
          beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
+         convertDeprecationsToExceptions="true"
 >
     <php>
+        <ini name="error_reporting" value="-1" />
         <!-- use an in-memory sqlite database -->
         <var name="db_driver" value="pdo_sqlite"/>
         <var name="db_memory" value="true"/>

composer.json

@@ -20,40 +20,41 @@
         "sort-packages": true
     },
     "require": {
-        "php": "^7.1 ||^8.0",
+        "php": "^7.1 || ^8.0",
+        "composer-runtime-api": "^2",
         "ext-ctype": "*",
-        "ext-pdo": "*",
-        "composer/package-versions-deprecated": "^1.8",
         "doctrine/cache": "^1.12.1 || ^2.1.1",
         "doctrine/collections": "^1.5",
         "doctrine/common": "^3.0.3",
-        "doctrine/dbal": "^2.13.1 || ^3.1.1",
-        "doctrine/deprecations": "^0.5.3",
+        "doctrine/dbal": "^2.13.1 || ^3.2",
+        "doctrine/deprecations": "^0.5.3 || ^1",
         "doctrine/event-manager": "^1.1",
         "doctrine/inflector": "^1.4 || ^2.0",
         "doctrine/instantiator": "^1.3",
-        "doctrine/lexer": "^1.0",
-        "doctrine/persistence": "^2.2",
+        "doctrine/lexer": "^1.2.3",
+        "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
         "symfony/console": "^3.0 || ^4.0 || ^5.0 || ^6.0",
         "symfony/polyfill-php72": "^1.23",
-        "symfony/polyfill-php80": "^1.15"
+        "symfony/polyfill-php80": "^1.16"
     },
     "require-dev": {
         "doctrine/annotations": "^1.13",
         "doctrine/coding-standard": "^9.0",
         "phpbench/phpbench": "^0.16.10 || ^1.0",
-        "phpstan/phpstan": "1.3.3",
-        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.4",
-        "squizlabs/php_codesniffer": "3.6.2",
+        "phpstan/phpstan": "~1.4.10 || 1.8.2",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.5",
+        "psr/log": "^1 || ^2 || ^3",
+        "squizlabs/php_codesniffer": "3.7.1",
         "symfony/cache": "^4.4 || ^5.4 || ^6.0",
         "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
-        "vimeo/psalm": "4.18.1"
+        "vimeo/psalm": "4.26.0"
     },
     "conflict": {
         "doctrine/annotations": "<1.13 || >= 2.0"
     },
     "suggest": {
+        "ext-dom": "Provides support for XSD validation for XML mapping files",
         "symfony/cache": "Provides cache support for Setup Tool with doctrine/cache 2.0",
         "symfony/yaml": "If you want to use YAML Metadata Mapping Driver"
     },

docs/en/conf.py

@@ -1,201 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Doctrine 2 ORM documentation build configuration file, created by
-# sphinx-quickstart on Fri Dec  3 18:10:24 2010.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-import sys, os, datetime
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.append(os.path.abspath('_exts'))
-
-# -- General configuration -----------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['configurationblock']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8'
-
-# The master toctree document.
-master_doc = 'index'
-
-# General information about the project.
-project = u'Doctrine 2 ORM'
-copyright = u'2010-%y, Doctrine Project Team'.format(datetime.date.today)
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '2'
-# The full version, including alpha/beta/rc tags.
-release = '2'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-language = 'en'
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-show_authors = True
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-
-# -- Options for HTML output ---------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'doctrine'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_theme']
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_use_modindex = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'Doctrine2ORMdoc'
-
-
-# -- Options for LaTeX output --------------------------------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-  ('index', 'Doctrine2ORM.tex', u'Doctrine 2 ORM Documentation',
-   u'Doctrine Project Team', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True
-
-primary_domain = "dcorm"
-
-def linkcode_resolve(domain, info):
-    if domain == 'dcorm':
-        return 'http://'
-    return None

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

@@ -0,0 +1,74 @@
+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/dql-user-defined-functions.rst

@@ -131,8 +131,8 @@ generation of a DateDiff FunctionNode somewhere in the AST of the
 dql statement.
 
 The ``ArithmeticPrimary`` method call is the most common
-denominator of valid EBNF tokens taken from the
-`DQL EBNF grammar <https://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#ebnf>`_
+denominator of valid EBNF tokens taken from the :ref:`DQL EBNF grammar
+<dql_ebnf_grammar>`
 that matches our requirements for valid input into the DateDiff Dql
 function. Picking the right tokens for your methods is a tricky
 business, but the EBNF grammar is pretty helpful finding it, as is

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

@@ -3,8 +3,8 @@ Implementing Wakeup or Clone
 
 .. sectionauthor:: Roman Borschel (roman@code-factory.org)
 
-As explained in the
-`restrictions for entity classes in the manual <https://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/architecture.html#entities>`_,
+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

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

@@ -47,7 +47,7 @@ appropriate autoloaders.
             }
 
             foreach ($classMetadata->getAssociationMappings() as $fieldName => $mapping) {
-                if ($mapping['type'] == \Doctrine\ORM\Mapping\ClassMetadataInfo::MANY_TO_MANY && $mapping['isOwningSide']) {
+                if ($mapping['type'] == \Doctrine\ORM\Mapping\ClassMetadata::MANY_TO_MANY && $mapping['isOwningSide']) {
                     $mappedTableName = $mapping['joinTable']['name'];
                     $classMetadata->associationMappings[$fieldName]['joinTable']['name'] = $this->prefix . $mappedTableName;
                 }

docs/en/cookbook/strategy-cookbook-introduction.rst

@@ -87,12 +87,12 @@ Such an interface could look like this:
          * @return \Zend_View_Helper_Interface
          */
         public function setView(\Zend_View_Interface $view);
-   
+
         /**
          * @return \Zend_View_Interface
          */
         public function getView();
-   
+
         /**
          * Renders this strategy. This method will be called when the user
          * displays the site.
@@ -100,7 +100,7 @@ Such an interface could look like this:
          * @return string
          */
         public function renderFrontend();
-   
+
         /**
          * Renders the backend of this block. This method will be called when
          * a user tries to reconfigure this block instance.
@@ -118,21 +118,21 @@ Such an interface could look like this:
          * @return array
          */
         public function getRequiredPanelTypes();
-   
+
         /**
          * Determines whether a Block is able to use a given type or not
          * @param string $typeName The typename
          * @return boolean
          */
         public function canUsePanelType($typeName);
-   
+
         public function setBlockEntity(AbstractBlock $block);
 
         public function getBlockEntity();
     }
-   
+
 As you can see, we have a method "setBlockEntity" which ties a potential strategy to an object of type AbstractBlock. This type will simply define the basic behaviour of our blocks and could potentially look something like this:
-   
+
 .. code-block:: php
 
     <?php
@@ -177,7 +177,7 @@ As you can see, we have a method "setBlockEntity" which ties a potential strateg
         public function getStrategyClassName() {
             return $this->strategyClassName;
         }
-    
+
         /**
          * Returns the instantiated strategy
          *
@@ -186,7 +186,7 @@ As you can see, we have a method "setBlockEntity" which ties a potential strateg
         public function getStrategyInstance() {
             return $this->strategyInstance;
         }
-    
+
         /**
          * Sets the strategy this block / panel should work as. Make sure that you've used
          * this method before persisting the block!
@@ -213,28 +213,29 @@ This might look like this:
 .. code-block:: php
 
     <?php
-    use \Doctrine\ORM,
-        \Doctrine\Common;
-    
+    use Doctrine\Common\EventSubscriber;
+    use Doctrine\ORM\Events;
+    use Doctrine\Persistence\Event\LifecycleEventArgs;
+
     /**
      * The BlockStrategyEventListener will initialize a strategy after the
      * block itself was loaded.
      */
-    class BlockStrategyEventListener implements Common\EventSubscriber {
-    
+    class BlockStrategyEventListener implements EventSubscriber {
+
         protected $view;
-    
+
         public function __construct(\Zend_View_Interface $view) {
             $this->view = $view;
         }
-    
+
         public function getSubscribedEvents() {
-           return array(ORM\Events::postLoad);
+           return array(Events::postLoad);
         }
-    
-        public function postLoad(ORM\Event\LifecycleEventArgs $args) {
-            $blockItem = $args->getEntity();
-    
+
+        public function postLoad(LifecycleEventArgs $args) {
+            $blockItem = $args->getObject();
+
             // Both blocks and panels are instances of Block\AbstractBlock
             if ($blockItem instanceof Block\AbstractBlock) {
                 $strategy  = $blockItem->getStrategyClassName();

docs/en/reference/advanced-configuration.rst

@@ -12,6 +12,7 @@ steps of configuration.
 
     use Doctrine\ORM\Configuration;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
     use Symfony\Component\Cache\Adapter\ArrayAdapter;
     use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
 
@@ -27,7 +28,7 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    $driverImpl = ORMSetup::createDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
     $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
@@ -129,7 +130,9 @@ the ``Doctrine\ORM\Configuration``:
 .. code-block:: php
 
     <?php
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    use Doctrine\ORM\ORMSetup;
+
+    $driverImpl = ORMSetup::createDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
     $config->setMetadataDriverImpl($driverImpl);
 
 The path information to the entities is required for the annotation
@@ -195,10 +198,7 @@ SQL Logger (***Optional***)
 
 Gets or sets the logger to use for logging all SQL statements
 executed by Doctrine. The logger class must implement the
-``Doctrine\DBAL\Logging\SQLLogger`` interface. A simple default
-implementation that logs to the standard output using ``echo`` and
-``var_dump`` can be found at
-``Doctrine\DBAL\Logging\EchoSQLLogger``.
+deprecated ``Doctrine\DBAL\Logging\SQLLogger`` interface.
 
 Auto-generating Proxy Classes (***OPTIONAL***)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -440,22 +440,22 @@ That will be available for all entities without a custom repository class.
 The default value is ``Doctrine\ORM\EntityRepository``.
 Any repository class must be a subclass of EntityRepository otherwise you got an ORMException
 
-Setting up the Console
-----------------------
+Ignoring entities (***OPTIONAL***)
+-----------------------------------
 
-Doctrine uses the Symfony Console component for generating the command
-line interface. You can take a look at the ``vendor/bin/doctrine.php``
-script and the ``Doctrine\ORM\Tools\Console\ConsoleRunner`` command
-for inspiration how to setup the cli.
-
-In general the required code looks like this:
+Specifies the Entity FQCNs to ignore.
+SchemaTool will then skip these (e.g. when comparing schemas).
 
 .. code-block:: php
 
     <?php
-    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
-    $cli->setCatchExceptions(true);
-    $cli->setHelperSet($helperSet);
-    Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
-    $cli->run();
+    $config->setSchemaIgnoreClasses([$fqcn]);
+    $config->getSchemaIgnoreClasses();
 
+
+Setting up the Console
+----------------------
+
+Doctrine uses the Symfony Console component for generating the command
+line interface. You can take a look at the
+:doc:`tools chapter <../reference/tools>` for inspiration how to setup the cli.

docs/en/reference/annotations-reference.rst

@@ -123,6 +123,18 @@ 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. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -193,6 +205,13 @@ Examples:
      */
     protected $loginCount;
 
+    /**
+     * Generated column
+     * @Column(type="string", name="user_fullname", insertable=false, updatable=false)
+     * MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+     */
+    protected $fullname;
+
 .. _annref_column_result:
 
 @ColumnResult

docs/en/reference/architecture.rst

@@ -66,6 +66,8 @@ The root namespace of the ORM package is ``Doctrine\ORM``.
 Terminology
 -----------
 
+.. _terminology_entities:
+
 Entities
 ~~~~~~~~
 
@@ -82,9 +84,13 @@ be any regular PHP class observing the following restrictions:
    :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>`.
-   Also consider implementing
-   `Serializable <https://php.net/manual/en/class.serializable.php>`_
-   instead.
+   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.
 -  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
@@ -93,6 +99,7 @@ be any regular PHP class observing the following restrictions:
 -  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
@@ -161,7 +168,8 @@ 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).
+did not find a way yet, if you did, please contact us). The
+``Serializable`` interface is also deprecated beginning with PHP 8.1.
 
 The EntityManager
 ~~~~~~~~~~~~~~~~~

docs/en/reference/attributes-reference.rst

@@ -10,6 +10,8 @@ annotation metadata supported since the first version 2.0.
 Index
 -----
 
+-  :ref:`#[AssociationOverride] <attrref_associationoverride]`
+-  :ref:`#[AttributeOverride] <attrref_attributeoverride]`
 -  :ref:`#[Column] <attrref_column>`
 -  :ref:`#[Cache] <attrref_cache>`
 -  :ref:`#[ChangeTrackingPolicy <attrref_changetrackingpolicy>`
@@ -49,6 +51,93 @@ Index
 Reference
 ---------
 
+.. _attrref_associationoverride:
+
+#[AssociationOverride]
+~~~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+assocation mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AssociationOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+
+Optional parameters:
+
+-  **joinColumns**: A list of nested ``#[JoinColumn]`` declarations.
+-  **joinTable**: A nested ``#[JoinTable]`` declaration in case of a many-to-many overwrite.
+-  **inversedBy**: The name of the inversedBy field on the target entity side.
+-  **fetch**: The fetch strategy, one of: EAGER, LAZY, EXTRA_LAZY.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AssociationOverride;
+    use Doctrine\ORM\Mapping\AssociationOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[AssociationOverrides([
+        new AssociationOverride(
+            name: "groups",
+            joinTable: new JoinTable(
+                name: "ddc964_users_admingroups",
+            ),
+            joinColumns: [new JoinColumn(name: "adminuser_id")],
+            inverseJoinColumns: [new JoinColumn(name: "admingroup_id")]
+        ),
+        new AssociationOverride(
+            name: "address",
+            joinColumns: [new JoinColumn(name: "adminaddress_id", referencedColumnName: "id")]
+        )
+    ])]
+    class DDC964Admin extends DDC964User
+    {
+    }
+
+.. _attrref_attributeoverride:
+
+#[AttributeOverride]
+~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+field mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AttributeOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+-  **column**: A nested ``#[Column]`` attribute with the overwritten field settings.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AttributeOverride;
+    use Doctrine\ORM\Mapping\AttributeOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[Entity]
+    #[AttributeOverrides([
+        new AttributeOverride(
+            name: "id",
+            column: new Column(name: "guest_id", type: "integer", length: 140)
+        ),
+        new AttributeOverride(
+            name: "name",
+            column: new Column(name: "guest_name", nullable: false, unique: true, length: 240)
+        )]
+    )]
+    class DDC964Guest extends DDC964User
+    {
+    }
+
 .. _attrref_column:
 
 #[Column]
@@ -89,6 +178,18 @@ Optional parameters:
 -  **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. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -106,6 +207,8 @@ Optional parameters:
    -  ``comment``: The comment of the column in the schema (might not
       be supported by all vendors).
 
+   -  ``charset``: The charset of the column (only supported by Mysql, PostgreSQL, Sqlite and SQLServer).
+
    -  ``collation``: The collation of the column (only supported by Mysql, PostgreSQL, Sqlite and SQLServer).
 
    -  ``check``: Adds a check constraint type to the column (might not
@@ -159,6 +262,15 @@ Examples:
     )]
     protected $loginCount;
 
+    // MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+    #[Column(
+        type: "string",
+        name: "user_fullname",
+        insertable: false,
+        updatable: false
+    )]
+    protected $fullname;
+
 .. _attrref_cache:
 
 #[Cache]
@@ -460,7 +572,7 @@ Example with partial indexes:
     <?php
     use Doctrine\ORM\Mapping\Index;
 
-    #[Index(name: "search_idx", columns: {"category"},
+    #[Index(name: "search_idx", columns: ["category"],
         options: [
             "where": "((category IS NOT NULL))"
         ]
@@ -518,7 +630,7 @@ Examples:
     #[Entity]
     #[InheritanceType("SINGLE_TABLE")]
     #[DiscriminatorColumn(name: "discr", type: "string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -527,7 +639,7 @@ Examples:
     #[Entity]
     #[InheritanceType("JOINED")]
     #[DiscriminatorColumn(name: "discr", type: "string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -546,7 +658,8 @@ are missing they will be computed considering the field's name and the current
 
 The ``#[InverseJoinColumn]`` is the same as ``#[JoinColumn]`` and is used in the context
 of a ``#[ManyToMany]`` attribute declaration to specifiy the details of the join table's
-column information used for the join to the inverse entity.
+column information used for the join to the inverse entity. This is only required
+on PHP 8.0, where nested attributes are not yet supported.
 
 Optional parameters:
 
@@ -570,6 +683,8 @@ Optional parameters:
    "columnDefinition" attribute on :ref:`#[Column] <attrref_column>` also sets
    the related ``#[JoinColumn]``'s columnDefinition. This is necessary to
    make foreign keys work.
+-  **options**:
+   See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
 Example:
 
@@ -596,7 +711,7 @@ details of the database join table. If you do not specify
 using the affected table and the column names.
 
 A notable difference to the annotation metadata support, ``#[JoinColumn]``
-and ``#[InverseJoinColumn]`` are specified at the property level and are not
+and ``#[InverseJoinColumn]`` can be specified at the property level and are not
 nested within the ``#[JoinTable]`` attribute.
 
 Required attribute:

docs/en/reference/basic-mapping.rst

@@ -14,17 +14,11 @@ After working through this guide you should know:
 Mapping of associations will be covered in the next chapter on
 :doc:`Association Mapping <association-mapping>`.
 
-Guide Assumptions
------------------
-
-You should have already :doc:`installed and configure <configuration>`
-Doctrine.
-
 Creating Classes for the Database
 ---------------------------------
 
 Every PHP object that you want to save in the database using Doctrine
-is called an "Entity". The term "Entity" describes objects
+is called an *Entity*. The term "Entity" describes objects
 that have an identity over many independent requests. This identity is
 usually achieved by assigning a unique identifier to an entity.
 In this tutorial the following ``Message`` PHP class will serve as the
@@ -50,11 +44,11 @@ that describes your entity.
 Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
--  :doc:`Docblock Annotations <annotations-reference>`
 -  :doc:`Attributes <attributes-reference>`
+-  :doc:`Docblock Annotations <annotations-reference>`
 -  :doc:`XML <xml-mapping>`
--  :doc:`YAML <yaml-mapping>`
 -  :doc:`PHP code <php-mapping>`
+-  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via docblock annotations, though
 many examples also show the equivalent configuration in YAML and XML.
@@ -62,8 +56,8 @@ many examples also show the equivalent configuration in YAML and XML.
 .. note::
 
     All metadata drivers perform equally. Once the metadata of a class has been
-    read from the source (annotations, xml or yaml) it is stored in an instance
-    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
+    read from the source (attributes, annotations, XML, etc.) it is stored in an instance
+    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class which are
     stored in the metadata cache.  If you're not using a metadata cache (not
     recommended!) then the XML driver is the fastest.
 
@@ -71,9 +65,22 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+
+        #[Entity]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+
         /** @Entity */
         class Message
         {
@@ -100,9 +107,25 @@ You can change this by configuring information about the table:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
+        #[Entity]
+        #[Table(name: 'message')]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
         /**
          * @Entity
          * @Table(name="message")
@@ -132,19 +155,38 @@ Now the class ``Message`` will be saved and fetched from the table ``message``.
 Property Mapping
 ----------------
 
-The next step after marking a PHP class as an entity is mapping its properties
-to columns in a table.
+The next step is mapping its properties to columns in the table.
 
-To configure a property use the ``@Column`` docblock annotation. The ``type``
+To configure a property use the ``Column`` docblock annotation. The ``type``
 attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>`
 to use for the field. If the type is not specified, ``string`` is used as the
 default.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Column;
+        use Doctrine\DBAL\Types\Types;
+
+        #[Entity]
+        class Message
+        {
+            #[Column(type: Types::INTEGER)]
+            private $id;
+            #[Column(length: 140)]
+            private $text;
+            #[Column(name: 'posted_at', type: Types::DATETIME)]
+            private $postedAt;
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Column;
+
         /** @Entity */
         class Message
         {
@@ -180,36 +222,34 @@ default.
               column: posted_at
 
 When we don't explicitly specify a column name via the ``name`` option, Doctrine
-assumes the field name is also the column name. This means that:
+assumes the field name is also the column name. So in this example:
 
 * the ``id`` property will map to the column ``id`` using the type ``integer``;
 * the ``text`` property will map to the column ``text`` with the default mapping type ``string``;
 * the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type.
 
-The Column annotation has some more attributes. Here is a complete
-list:
+Here is a complete list of ``Column``s attributes (all optional):
 
-- ``type``: (optional, defaults to 'string') The mapping type to
-  use for the column.
-- ``name``: (optional, defaults to field name) The name of the
-  column in the database.
-- ``length``: (optional, default 255) The length of the column in
-  the database. (Applies only if a string-valued column is used).
-- ``unique``: (optional, default FALSE) Whether the column is a
-  unique key.
-- ``nullable``: (optional, default FALSE) Whether the database
-  column is nullable.
-- ``precision``: (optional, default 0) The precision for a decimal
-  (exact numeric) column (applies only for decimal column),
+- ``type`` (default: 'string'): The mapping type to use for the column.
+- ``name`` (default: name of property): The name of the column in the database.
+- ``length`` (default: 255): The length of the column in the database.
+  Applies only if a string-valued column is used.
+- ``unique`` (default: ``false``): Whether the column is a unique key.
+- ``nullable`` (default: ``false``): Whether the column is nullable.
+- ``insertable`` (default: ``true``): Whether the column should be inserted.
+- ``updatable`` (default: ``true``): Whether the column should be updated.
+- ``enumType`` (requires PHP 8.1 and ``doctrine/orm`` 2.11): The PHP enum class name to convert the database value into.
+- ``precision`` (default: 0): The precision for a decimal (exact numeric) column
+  (applies only for decimal column),
   which is the maximum number of digits that are stored for the values.
-- ``scale``: (optional, default 0) The scale for a decimal (exact
+- ``scale`` (default: 0): The scale for a decimal (exact
   numeric) column (applies only for decimal column), which represents
   the number of digits to the right of the decimal point and must
-  not be greater than *precision*.
-- ``columnDefinition``: (optional) Allows to define a custom
+  not be greater than ``precision``.
+- ``columnDefinition``: Allows to define a custom
   DDL snippet that is used to create the column. Warning: This normally
-  confuses the SchemaTool to always detect the column as changed.
-- ``options``: (optional) Key-value pairs of options that get passed
+  confuses the :doc:`SchemaTool <tools>` to always detect the column as changed.
+- ``options``: Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
 .. _reference-php-mapping-types:
@@ -217,21 +257,35 @@ list:
 PHP Types Mapping
 _________________
 
-Since version 2.9 Doctrine can determine usable defaults from property types
-on entity classes. When property type is nullable this has no effect on
-``nullable`` Column attribute at the moment for backwards compatibility
-reasons.
+.. versionadded:: 2.9
 
-Additionally, Doctrine will map PHP types to ``type`` attribute as follows:
+The column types can be inferred automatically from PHP's property types.
+However, when the property type is nullable this has no effect on the ``nullable`` Column attribute.
 
-- ``DateInterval``: ``dateinterval``
-- ``DateTime``: ``datetime``
-- ``DateTimeImmutable``: ``datetime_immutable``
-- ``array``: ``json``
-- ``bool``: ``boolean``
-- ``float``: ``float``
-- ``int``: ``integer``
-- ``string`` or any other type: ``string``
+These are the "automatic" mapping rules:
+
++-----------------------+-------------------------------+
+| PHP property type     | Doctrine column type          |
++=======================+===============================+
+| ``DateInterval``      | ``Types::DATEINTERVAL``       |
++-----------------------+-------------------------------+
+| ``DateTime``          | ``Types::DATETIME_MUTABLE``   |
++-----------------------+-------------------------------+
+| ``DateTimeImmutable`` | ``Types::DATETIME_IMMUTABLE`` |
++-----------------------+-------------------------------+
+| ``array``             | ``Types::JSON``               |
++-----------------------+-------------------------------+
+| ``bool``              | ``Types::BOOLEAN``            |
++-----------------------+-------------------------------+
+| ``float``             | ``Types::FLOAT``              |
++-----------------------+-------------------------------+
+| ``int``               | ``Types::INTEGER``            |
++-----------------------+-------------------------------+
+| Any other type        | ``Types::STRING``             |
++-----------------------+-------------------------------+
+
+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``.
 
 .. _reference-mapping-types:
 

docs/en/reference/configuration.rst

@@ -41,8 +41,8 @@ access point to ORM functionality provided by Doctrine.
     // bootstrap.php
     require_once "vendor/autoload.php";
 
-    use Doctrine\ORM\Tools\Setup;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
 
     $paths = array("/path/to/entity-files");
     $isDevMode = false;
@@ -55,16 +55,21 @@ access point to ORM functionality provided by Doctrine.
         'dbname'   => 'foo',
     );
 
-    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
+    $config = ORMSetup::createAnnotationMetadataConfiguration($paths, $isDevMode);
     $entityManager = EntityManager::create($dbParams, $config);
 
+.. note::
+
+    The ``ORMSetup`` class has been introduced with ORM 2.12. It's predecessor ``Setup`` is deprecated and will
+    be removed in version 3.0.
+
 Or if you prefer XML:
 
 .. code-block:: php
 
     <?php
     $paths = array("/path/to/xml-mappings");
-    $config = Setup::createXMLMetadataConfiguration($paths, $isDevMode);
+    $config = ORMSetup::createXMLMetadataConfiguration($paths, $isDevMode);
     $entityManager = EntityManager::create($dbParams, $config);
 
 Or if you prefer YAML:
@@ -73,7 +78,7 @@ Or if you prefer YAML:
 
     <?php
     $paths = array("/path/to/yml-mappings");
-    $config = Setup::createYAMLMetadataConfiguration($paths, $isDevMode);
+    $config = ORMSetup::createYAMLMetadataConfiguration($paths, $isDevMode);
     $entityManager = EntityManager::create($dbParams, $config);
 
 .. note::
@@ -83,44 +88,29 @@ Or if you prefer YAML:
     
         "symfony/yaml": "*"
 
-Inside the ``Setup`` methods several assumptions are made:
+Inside the ``ORMSetup`` methods several assumptions are made:
 
--  If ``$isDevMode`` is true caching is done in memory with the ``ArrayCache``. Proxy objects are recreated on every request.
--  If ``$isDevMode`` is false, check for Caches in the order APC, Xcache, Memcache (127.0.0.1:11211), Redis (127.0.0.1:6379) unless `$cache` is passed as fourth argument.
+-  If ``$isDevMode`` is true caching is done in memory with the ``ArrayAdapter``. Proxy objects are recreated on every request.
+-  If ``$isDevMode`` is false, check for Caches in the order APCu, Redis (127.0.0.1:6379), Memcache (127.0.0.1:11211) unless `$cache` is passed as fourth argument.
 -  If ``$isDevMode`` is false, set then proxy classes have to be explicitly created through the command line.
 -  If third argument `$proxyDir` is not set, use the systems temporary directory.
 
+.. note::
+
+    In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
+    has to be installed as a dependency.
+
 If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
 
 .. note::
 
     You can learn more about the database connection configuration in the
-    `Doctrine DBAL connection configuration reference <https://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html>`_.
+    `Doctrine DBAL connection configuration reference <https://docs.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/configuration.html>`_.
 
 Setting up the Commandline Tool
 -------------------------------
 
 Doctrine ships with a number of command line tools that are very helpful
-during development. You can call this command from the Composer binary
-directory:
-
-.. code-block:: sh
-
-    $ php vendor/bin/doctrine
-
-You need to register your applications EntityManager to the console tool
-to make use of the tasks by creating a ``cli-config.php`` file with the
-following content:
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Tools\Console\ConsoleRunner;
-
-    // replace with file to your own project bootstrap
-    require_once 'bootstrap.php';
-
-    // replace with mechanism to retrieve EntityManager in your app
-    $entityManager = GetEntityManager();
-
-    return ConsoleRunner::createHelperSet($entityManager);
+during development. In order to make use of them, create an executable PHP
+script in your project as described in the
+:doc:`tools chapter <../reference/tools>`.

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

@@ -1531,6 +1531,8 @@ Given that there are 10 users and corresponding addresses in the database the ex
     a one-by-one basis once they are accessed.
 
 
+.. _dql_ebnf_grammar:
+
 EBNF
 ----
 
@@ -1724,7 +1726,7 @@ Literal Values
 .. code-block:: php
 
     Literal     ::= string | char | integer | float | boolean
-    InParameter ::= Literal | InputParameter
+    InParameter ::= ArithmeticExpression | InputParameter
 
 Input Parameter
 ~~~~~~~~~~~~~~~

docs/en/reference/events.rst

@@ -79,7 +79,9 @@ array of events it should be subscribed to.
 .. code-block:: php
 
     <?php
-    class TestEventSubscriber implements \Doctrine\Common\EventSubscriber
+    use Doctrine\Common\EventSubscriber;
+
+    class TestEventSubscriber implements EventSubscriber
     {
         public $preFooInvoked = false;
 
@@ -121,16 +123,17 @@ Now you can test the ``$eventSubscriber`` instance to see if the
         echo 'pre foo invoked!';
     }
 
-Registering Events
-~~~~~~~~~~~~~~~~~~
+Registering Event Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-There are two ways to register an event:
+There are two ways to set up an event handler:
 
-* *All events* can be registered by calling ``$eventManager->addEventListener()``
-or ``eventManager->addEventSubscriber()``, see
+* For *all events* you can create a Lifecycle Event Listener or Subscriber class and register
+it by calling ``$eventManager->addEventListener()`` or ``eventManager->addEventSubscriber()``,
+see
 :ref:`Listening and subscribing to Lifecycle Events<listening-and-subscribing-to-lifecycle-events>`
-* *Lifecycle Callbacks* can also be registered in the entity mapping (annotation, attribute, etc.), 
-see :ref:`Lifecycle Callbacks<lifecycle-callbacks>`
+* For *some events* (see table below), you can create a *Lifecycle Callback* method in the
+entity, see :ref:`Lifecycle Callbacks<lifecycle-callbacks>`.
 
 .. _reference-events-lifecycle-events:
 
@@ -141,33 +144,33 @@ 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       | `LifecycleEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postRemove<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `_LifecycleEventArgs`_              |
+| :ref:`postRemove<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`prePersist<reference-events-pre-persist>`                 | ``$em->persist()``    | Yes       | `_LifecycleEventArgs`_              |
+| :ref:`prePersist<reference-events-pre-persist>`                 | ``$em->persist()``    | Yes       | `LifecycleEventArgs`_               |
 |                                                                 | 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       | `LifecycleEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`preUpdate<reference-events-pre-update>`                   | ``$em->flush()``      | Yes       | `_PreUpdateEventArgs`_              |
+| :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       | `LifecycleEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postLoad<reference-events-post-load>`                     | Loading from database | Yes       | `_LifecycleEventArgs`_              |
+| :ref:`postLoad<reference-events-post-load>`                     | Loading from database | Yes       | `LifecycleEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`loadClassMetadata<reference-events-load-class-metadata>`  | Loading of mapping    | No        | `_LoadClassMetadataEventArgs`       |
+| :ref:`loadClassMetadata<reference-events-load-class-metadata>`  | Loading of mapping    | No        | `LoadClassMetadataEventArgs`_       |
 |                                                                 | metadata              |           |                                     |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| ``onClassMetadataNotFound``                                     | ``MappingException``  | No        | `_OnClassMetadataNotFoundEventArgs` |
+| ``onClassMetadataNotFound``                                     | ``MappingException``  | No        | `OnClassMetadataNotFoundEventArgs`_ |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`preFlush<reference-events-pre-flush>`                     | ``$em->flush()``      | Yes       | `_PreFlushEventArgs`_               |
+| :ref:`preFlush<reference-events-pre-flush>`                     | ``$em->flush()``      | Yes       | `PreFlushEventArgs`_                |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`onFlush<reference-events-on-flush>`                       | ``$em->flush()``      | No        | `_OnFlushEventArgs`                 |
+| :ref:`onFlush<reference-events-on-flush>`                       | ``$em->flush()``      | No        | `OnFlushEventArgs`_                 |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`postFlush<reference-events-post-flush>`                   | ``$em->flush()``      | No        | `_PostFlushEventArgs`               |
+| :ref:`postFlush<reference-events-post-flush>`                   | ``$em->flush()``      | No        | `PostFlushEventArgs`_               |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
-| :ref:`onClear<reference-events-on-clear>`                       | ``$em->clear()``      | No        | `_OnClearEventArgs`                 |
+| :ref:`onClear<reference-events-on-clear>`                       | ``$em->clear()``      | No        | `OnClearEventArgs`_                 |
 +-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
 
 Naming convention
@@ -210,7 +213,6 @@ specific to a particular entity class's lifecycle.
     .. code-block:: attribute
 
         <?php
-        
         use Doctrine\DBAL\Types\Types;
         use Doctrine\Persistence\Event\LifecycleEventArgs;
 
@@ -244,7 +246,6 @@ specific to a particular entity class's lifecycle.
     .. code-block:: annotation
 
         <?php
-        
         use Doctrine\Persistence\Event\LifecycleEventArgs;
 
         /**
@@ -503,7 +504,6 @@ result in an infinite loop.
 .. code-block:: php
 
     <?php
-
     use Doctrine\ORM\Event\PreFlushEventArgs;
 
     class PreFlushExampleListener
@@ -589,7 +589,6 @@ This event is not a lifecycle callback.
 .. code-block:: php
 
     <?php
-
     use Doctrine\ORM\Event\PostFlushEventArgs;
 
     class PostFlushExampleListener
@@ -614,7 +613,7 @@ Changes to associations of the updated entity are never allowed in
 this event, since Doctrine cannot guarantee to correctly handle
 referential integrity at this point of the flush operation. This
 event has a powerful feature however, it is executed with a
-`_PreUpdateEventArgs`_ instance, which contains a reference to the
+`PreUpdateEventArgs`_ instance, which contains a reference to the
 computed change-set of this entity.
 
 This means you have access to all the fields that have changed for
@@ -636,6 +635,8 @@ A simple example for this event looks like:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\PreUpdateEventArgs;
+
     class NeverAliceOnlyBobListener
     {
         public function preUpdate(PreUpdateEventArgs $eventArgs)
@@ -643,6 +644,9 @@ A simple example for this event looks like:
             if ($eventArgs->getEntity() instanceof User) {
                 if ($eventArgs->hasChangedField('name') && $eventArgs->getNewValue('name') == 'Alice') {
                     $eventArgs->setNewValue('name', 'Bob');
+                    // The following will only work if `status` is already present in the computed changeset.
+                    // Otherwise it will throw an InvalidArgumentException:
+                    $eventArgs->setNewValue('status', 'active');
                 }
             }
         }
@@ -655,6 +659,8 @@ lifecycle callback when there are expensive validations to call:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\PreUpdateEventArgs;
+
     class ValidCreditCardListener
     {
         public function preUpdate(PreUpdateEventArgs $eventArgs)
@@ -750,7 +756,7 @@ An entity listener is a lifecycle listener class used for an entity.
 .. configuration-block::
 
     .. code-block:: attribute
-    
+
         <?php
         namespace MyProject\Entity;
         use App\EventListener\UserListener;
@@ -806,6 +812,8 @@ An ``Entity Listener`` could be any class, by default it should be a class with
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\PreUpdateEventArgs;
+
     class UserListener
     {
         public function preUpdate(User $user, PreUpdateEventArgs $event)
@@ -822,6 +830,10 @@ you need to map the listener method using the event type mapping:
     .. code-block:: php
 
         <?php
+        use Doctrine\ORM\Event\PreUpdateEventArgs;
+        use Doctrine\ORM\Event\PreFlushEventArgs;
+        use Doctrine\Persistence\Event\LifecycleEventArgs;
+
         class UserListener
         {
             /** @PrePersist */
@@ -906,6 +918,8 @@ Specifying an entity listener instance :
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\PreUpdateEventArgs;
+
     // User.php
 
     /** @Entity @EntityListeners({"UserListener"}) */
@@ -932,12 +946,14 @@ Specifying an entity listener instance :
     $listener = $container->get('user_listener');
     $em->getConfiguration()->getEntityListenerResolver()->register($listener);
 
-Implementing your own resolver :
+Implementing your own resolver:
 
 .. code-block:: php
 
     <?php
-    class MyEntityListenerResolver extends \Doctrine\ORM\Mapping\DefaultEntityListenerResolver
+    use Doctrine\ORM\Mapping\DefaultEntityListenerResolver;
+
+    class MyEntityListenerResolver extends DefaultEntityListenerResolver
     {
         public function __construct($container)
         {
@@ -971,13 +987,15 @@ This event is not a lifecycle callback.
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Event\LoadClassMetadataEventArgs;
+
     $test = new TestEventListener();
     $evm = $em->getEventManager();
     $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $test);
 
     class TestEventListener
     {
-        public function loadClassMetadata(\Doctrine\ORM\Event\LoadClassMetadataEventArgs $eventArgs)
+        public function loadClassMetadata(LoadClassMetadataEventArgs $eventArgs)
         {
             $classMetadata = $eventArgs->getClassMetadata();
             $fieldMapping = array(
@@ -1010,13 +1028,16 @@ instance and class metadata.
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Tools\ToolEvents;
+    use Doctrine\ORM\Tools\Event\GenerateSchemaTableEventArgs;
+
     $test = new TestEventListener();
     $evm = $em->getEventManager();
-    $evm->addEventListener(\Doctrine\ORM\Tools\ToolEvents::postGenerateSchemaTable, $test);
+    $evm->addEventListener(ToolEvents::postGenerateSchemaTable, $test);
 
     class TestEventListener
     {
-        public function postGenerateSchemaTable(\Doctrine\ORM\Tools\Event\GenerateSchemaTableEventArgs $eventArgs)
+        public function postGenerateSchemaTable(GenerateSchemaTableEventArgs $eventArgs)
         {
             $classMetadata = $eventArgs->getClassMetadata();
             $schema = $eventArgs->getSchema();
@@ -1034,13 +1055,16 @@ and the EntityManager.
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Tools\ToolEvents;
+    use Doctrine\ORM\Tools\Event\GenerateSchemaEventArgs;
+
     $test = new TestEventListener();
     $evm = $em->getEventManager();
-    $evm->addEventListener(\Doctrine\ORM\Tools\ToolEvents::postGenerateSchema, $test);
+    $evm->addEventListener(ToolEvents::postGenerateSchema, $test);
 
     class TestEventListener
     {
-        public function postGenerateSchema(\Doctrine\ORM\Tools\Event\GenerateSchemaEventArgs $eventArgs)
+        public function postGenerateSchema(GenerateSchemaEventArgs $eventArgs)
         {
             $schema = $eventArgs->getSchema();
             $em = $eventArgs->getEntityManager();

docs/en/reference/metadata-drivers.rst

@@ -55,51 +55,66 @@ Implementing Metadata Drivers
 
 In addition to the included metadata drivers you can very easily
 implement your own. All you need to do is define a class which
-implements the ``Driver`` interface:
+implements the ``MappingDriver`` interface:
 
 .. code-block:: php
 
     <?php
-    namespace Doctrine\ORM\Mapping\Driver;
-    
-    use Doctrine\ORM\Mapping\ClassMetadataInfo;
-    
-    interface Driver
+
+    declare(strict_types=1);
+
+    namespace Doctrine\Persistence\Mapping\Driver;
+
+    use Doctrine\Persistence\Mapping\ClassMetadata;
+
+    /**
+     * Contract for metadata drivers.
+     */
+    interface MappingDriver
     {
         /**
          * Loads the metadata for the specified class into the provided container.
-         * 
-         * @param string $className
-         * @param ClassMetadataInfo $metadata
+         *
+         * @psalm-param class-string<T> $className
+         * @psalm-param ClassMetadata<T> $metadata
+         *
+         * @return void
+         *
+         * @template T of object
          */
-        function loadMetadataForClass($className, ClassMetadataInfo $metadata);
-    
+        public function loadMetadataForClass(string $className, ClassMetadata $metadata);
+
         /**
          * Gets the names of all mapped classes known to this driver.
-         * 
-         * @return array The names of all mapped classes known to this driver.
-         */
-        function getAllClassNames(); 
-    
-        /**
-         * Whether the class with the specified name should have its metadata loaded.
-         * This is only the case if it is either mapped as an Entity or a
-         * MappedSuperclass.
          *
-         * @param string $className
-         * @return boolean
+         * @return array<int, string> The names of all mapped classes known to this driver.
+         * @psalm-return list<class-string>
          */
-        function isTransient($className);
+        public function getAllClassNames();
+
+        /**
+         * Returns whether the class with the specified name should have its metadata loaded.
+         * This is only the case if it is either mapped as an Entity or a MappedSuperclass.
+         *
+         * @psalm-param class-string $className
+         *
+         * @return bool
+         */
+        public function isTransient(string $className);
     }
 
 If you want to write a metadata driver to parse information from
 some file format we've made your life a little easier by providing
-the ``AbstractFileDriver`` implementation for you to extend from:
+the ``FileDriver`` implementation for you to extend from:
 
 .. code-block:: php
 
     <?php
-    class MyMetadataDriver extends AbstractFileDriver
+
+    use Doctrine\Persistence\Mapping\ClassMetadata;
+    use Doctrine\Persistence\Mapping\Driver\FileDriver;
+
+    class MyMetadataDriver extends FileDriver
     {
         /**
          * {@inheritdoc}
@@ -109,11 +124,11 @@ the ``AbstractFileDriver`` implementation for you to extend from:
         /**
          * {@inheritdoc}
          */
-        public function loadMetadataForClass($className, ClassMetadataInfo $metadata)
+        public function loadMetadataForClass($className, ClassMetadata $metadata)
         {
             $data = $this->_loadMappingFile($file);
     
-            // populate ClassMetadataInfo instance from $data
+            // populate ClassMetadata instance from $data
         }
     
         /**
@@ -127,13 +142,12 @@ the ``AbstractFileDriver`` implementation for you to extend from:
 
 .. note::
 
-    When using the ``AbstractFileDriver`` it requires that you
-    only have one entity defined per file and the file named after the
-    class described inside where namespace separators are replaced by
-    periods. So if you have an entity named ``Entities\User`` and you
-    wanted to write a mapping file for your driver above you would need
-    to name the file ``Entities.User.dcm.ext`` for it to be
-    recognized.
+    When using the ``FileDriver`` it requires that you only have one
+    entity defined per file and the file named after the class described
+    inside where namespace separators are replaced by periods. So if you
+    have an entity named ``Entities\User`` and you wanted to write a
+    mapping file for your driver above you would need to name the file
+    ``Entities.User.dcm.ext`` for it to be recognized.
 
 
 Now you can use your ``MyMetadataDriver`` implementation by setting
@@ -156,14 +170,6 @@ entity when needed.
 
 You have all the methods you need to manually specify the mapping
 information instead of using some mapping file to populate it from.
-The base ``ClassMetadataInfo`` class is responsible for only data
-storage and is not meant for runtime use. It does not require that
-the class actually exists yet so it is useful for describing some
-entity before it exists and using that information to generate for
-example the entities themselves. The class ``ClassMetadata``
-extends ``ClassMetadataInfo`` and adds some functionality required
-for runtime usage and requires that the PHP class is present and
-can be autoloaded.
 
 You can read more about the API of the ``ClassMetadata`` classes in
 the PHP Mapping chapter.

docs/en/reference/php-mapping.rst

@@ -9,6 +9,11 @@ the code in PHP files or inside of a static function named
 PHP Files
 ---------
 
+.. note::
+
+   PHPDriver is deprecated and will be removed in 3.0, use StaticPHPDriver
+   instead.
+
 If you wish to write your mapping information inside PHP files that
 are named after the entity and included to populate the metadata
 for an entity you can do so by using the ``PHPDriver``:
@@ -91,6 +96,8 @@ For this you just need to use the ``StaticPHPDriver``:
 .. code-block:: php
 
     <?php
+    use Doctrine\Persistence\Mapping\Driver\StaticPHPDriver;
+
     $driver = new StaticPHPDriver('/path/to/entities');
     $em->getConfiguration()->setMetadataDriverImpl($driver);
 
@@ -180,13 +187,12 @@ It also has several methods that create builders (which are necessary for advanc
 -   ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssociationBuilder`` instance
 -   ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssociationBuilder`` instance
 
-ClassMetadataInfo API
----------------------
+ClassMetadata API
+-----------------
 
-The ``ClassMetadataInfo`` class is the base data object for storing
-the mapping metadata for a single entity. It contains all the
-getters and setters you need populate and retrieve information for
-an entity.
+The ``ClassMetadata`` class is the data object for storing the mapping
+metadata for a single entity. It contains all the getters and setters
+you need populate and retrieve information for an entity.
 
 General Setters
 ~~~~~~~~~~~~~~~
@@ -304,13 +310,11 @@ Lifecycle Callback Getters
 -  ``hasLifecycleCallbacks($lifecycleEvent)``
 -  ``getLifecycleCallbacks($event)``
 
-ClassMetadata API
------------------
+Runtime reflection methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``ClassMetadata`` class extends ``ClassMetadataInfo`` and adds
-the runtime functionality required by Doctrine. It adds a few extra
-methods related to runtime reflection for working with the entities
-themselves.
+These are methods related to runtime reflection for working with the
+entities themselves.
 
 
 -  ``getReflectionClass()``

docs/en/reference/query-builder.rst

@@ -13,7 +13,7 @@ as you want, or just pick a preferred one.
 
     The ``QueryBuilder`` is not an abstraction of DQL, but merely a tool to dynamically build it.
     You should still use plain DQL when you can, as it is simpler and more readable.
-    More about this in the :doc:`FAQ <faq>`_.
+    More about this in the :doc:`FAQ <faq>`.
 
 Constructing a new QueryBuilder object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

@@ -172,7 +172,7 @@ To enable the second-level-cache, you should provide a cache factory.
 
     <?php
     /** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
-    /** @var \Doctrine\Common\Cache\Cache $cache */
+    /** @var \Psr\Cache\CacheItemPoolInterface $cache */
     /** @var \Doctrine\ORM\Configuration $config */
 
     $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache);

docs/en/reference/tools.rst

@@ -7,24 +7,10 @@ Doctrine Console
 The Doctrine Console is a Command Line Interface tool for simplifying common
 administration tasks during the development of a project that uses ORM.
 
-Take a look at the :doc:`Installation and Configuration <configuration>`
-chapter for more information how to setup the console command.
+For the following examples, we will set up the CLI as ``bin/doctrine``.
 
-Display Help Information
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Type ``php vendor/bin/doctrine`` on the command line and you should see an
-overview of the available commands or use the --help flag to get
-information on the available commands. If you want to know more
-about the use of generate entities for example, you can call:
-
-.. code-block:: php
-
-    $> php vendor/bin/doctrine orm:generate-entities --help
-
-
-Configuration
-~~~~~~~~~~~~~
+Setting Up the Console
+~~~~~~~~~~~~~~~~~~~~~~
 
 Whenever the ``doctrine`` command line tool is invoked, it can
 access all Commands that were registered by a developer. There is no
@@ -34,25 +20,33 @@ Doctrine DBAL and ORM. If you want to use additional commands you
 have to register them yourself.
 
 All the commands of the Doctrine Console require access to the
-``EntityManager``. You have to inject it into the console application with
-``ConsoleRunner::createHelperSet``. Whenever you invoke the Doctrine
-binary, it searches the current directory for the file ``cli-config.php``.
-This file contains the project-specific configuration.
+``EntityManager``. You have to inject it into the console application.
 
-Here is an example of a the project-specific ``cli-config.php``:
+Here is an example of a the project-specific ``bin/doctrine`` binary.
 
 .. code-block:: php
 
+    #!/usr/bin/env php
     <?php
-    use Doctrine\ORM\Tools\Console\ConsoleRunner;
 
-    // replace this with the path to your own project bootstrap file.
+    use Doctrine\ORM\Tools\Console\ConsoleRunner;
+    use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;
+
+    // replace with path to your own project bootstrap file
     require_once 'bootstrap.php';
 
     // replace with mechanism to retrieve EntityManager in your app
     $entityManager = GetEntityManager();
 
-    return ConsoleRunner::createHelperSet($entityManager);
+    $commands = [
+        // If you want to add your own custom console commands,
+        // you can do so here.
+    ];
+
+    ConsoleRunner::run(
+        new SingleManagerProvider($entityManager),
+        $commands
+    );
 
 .. note::
 
@@ -60,6 +54,18 @@ Here is an example of a the project-specific ``cli-config.php``:
     and use their facilities to access the Doctrine EntityManager and
     Connection Resources.
 
+Display Help Information
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Type ``php bin/doctrine`` on the command line and you should see an
+overview of the available commands or use the ``--help`` flag to get
+information on the available commands. If you want to know more
+about the use of generate entities for example, you can call:
+
+::
+
+    $> php bin/doctrine orm:generate-entities --help
+
 Command Overview
 ~~~~~~~~~~~~~~~~
 
@@ -143,7 +149,7 @@ When using the SchemaTool class directly, create your schema using
 the ``createSchema()`` method. First create an instance of the
 ``SchemaTool`` and pass it an instance of the ``EntityManager``
 that you want to use to create the schema. This method receives an
-array of ``ClassMetadataInfo`` instances.
+array of ``ClassMetadata`` instances.
 
 .. code-block:: php
 
@@ -174,8 +180,8 @@ tables of the current model to clean up with orphaned tables.
 
 You can also use database introspection to update your schema
 easily with the ``updateSchema()`` method. It will compare your
-existing database schema to the passed array of
-``ClassMetadataInfo`` instances.
+existing database schema to the passed array of ``ClassMetadata``
+instances.
 
 .. code-block:: php
 
@@ -189,38 +195,35 @@ To create the schema use the ``create`` command:
 
 .. code-block:: php
 
-    $ php doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:create
 
 To drop the schema use the ``drop`` command:
 
 .. code-block:: php
 
-    $ php doctrine orm:schema-tool:drop
+    $ php bin/doctrine orm:schema-tool:drop
 
 If you want to drop and then recreate the schema then use both
 options:
 
 .. code-block:: php
 
-    $ php doctrine orm:schema-tool:drop
-    $ php doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:drop
+    $ php bin/doctrine orm:schema-tool:create
 
 As you would think, if you want to update your schema use the
 ``update`` command:
 
 .. code-block:: php
 
-    $ php doctrine orm:schema-tool:update
+    $ php bin/doctrine orm:schema-tool:update
 
 All of the above commands also accept a ``--dump-sql`` option that
 will output the SQL for the ran operation.
 
 .. code-block:: php
 
-    $ php doctrine orm:schema-tool:create --dump-sql
-
-Before using the orm:schema-tool commands, remember to configure
-your cli-config.php properly.
+    $ php bin/doctrine orm:schema-tool:create --dump-sql
 
 Entity Generation
 -----------------
@@ -229,9 +232,9 @@ Generate entity classes and method stubs from your mapping information.
 
 .. code-block:: php
 
-    $ php doctrine orm:generate-entities
-    $ php doctrine orm:generate-entities --update-entities
-    $ php doctrine orm:generate-entities --regenerate-entities
+    $ php bin/doctrine orm:generate-entities
+    $ php bin/doctrine orm:generate-entities --update-entities
+    $ php bin/doctrine orm:generate-entities --regenerate-entities
 
 This command is not suited for constant usage. It is a little helper and does
 not support all the mapping edge cases very well. You still have to put work
@@ -316,14 +319,14 @@ convert to and the path to generate it:
 
 .. code-block:: php
 
-    $ php doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xml
+    $ php bin/doctrine orm:convert-mapping xml /path/to/mapping-path-converted-to-xml
 
 Reverse Engineering
 -------------------
 
-You can use the ``DatabaseDriver`` to reverse engineer a database
-to an array of ``ClassMetadataInfo`` instances and generate YAML,
-XML, etc. from them.
+You can use the ``DatabaseDriver`` to reverse engineer a database to an
+array of ``ClassMetadata`` instances and generate YAML, XML, etc. from
+them.
 
 .. note::
 
@@ -366,7 +369,7 @@ You can also reverse engineer a database using the
 
 .. code-block:: php
 
-    $ php doctrine orm:convert-mapping --from-database yml /path/to/mapping-path-converted-to-yml
+    $ php bin/doctrine orm:convert-mapping --from-database yml /path/to/mapping-path-converted-to-yml
 
 .. note::
 
@@ -393,6 +396,11 @@ You can either use the Doctrine Command Line Tool:
 
     doctrine orm:validate-schema
 
+If the validation fails, you can change the verbosity level to
+check the detected errors:
+
+    doctrine orm:validate-schema -v
+
 Or you can trigger the validation manually:
 
 .. code-block:: php

docs/en/reference/xml-mapping.rst

@@ -256,6 +256,11 @@ Optional attributes:
    table? Defaults to false.
 -  nullable - Should this field allow NULL as a value? Defaults to
    false.
+-  insertable - Should this field be inserted? Defaults to true.
+-  updatable - Should this field be updated? Defaults to true.
+-  generated - Enum of the values ALWAYS, INSERT, NEVER that determines if
+   generated value must be fetched from database after INSERT or UPDATE.
+   Defaults to "NEVER".
 -  version - Should this field be used for optimistic locking? Only
    works on fields with type integer or datetime.
 -  scale - Scale of a decimal type.
@@ -689,6 +694,7 @@ specified by their respective tags:
 -  ``<cascade-merge />``
 -  ``<cascade-remove />``
 -  ``<cascade-refresh />``
+-  ``<cascade-detach />``
 
 Join Column Element
 ~~~~~~~~~~~~~~~~~~~

docs/en/tutorials/getting-started.rst

@@ -81,10 +81,11 @@ that directory with the following contents:
 
     {
         "require": {
-            "doctrine/orm": "^2.10.2",
-            "doctrine/dbal": "^3.1.1",
-            "symfony/yaml": "2.*",
-            "symfony/cache": "^5.3"
+            "doctrine/orm": "^2.11.0",
+            "doctrine/dbal": "^3.2",
+            "doctrine/annotations": "1.13.2",
+            "symfony/yaml": "^5.4",
+            "symfony/cache": "^5.4"
         },
         "autoload": {
             "psr-0": {"": "src/"}
@@ -136,8 +137,8 @@ step:
 
     <?php
     // bootstrap.php
-    use Doctrine\ORM\Tools\Setup;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
 
     require_once "vendor/autoload.php";
 
@@ -146,10 +147,10 @@ step:
     $proxyDir = null;
     $cache = null;
     $useSimpleAnnotationReader = false;
-    $config = Setup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode, $proxyDir, $cache, $useSimpleAnnotationReader);
-    // or if you prefer yaml or XML
-    // $config = Setup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
-    // $config = Setup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
+    $config = ORMSetup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode, $proxyDir, $cache, $useSimpleAnnotationReader);
+    // or if you prefer YAML or XML
+    // $config = ORMSetup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
+    // $config = ORMSetup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
 
     // database configuration parameters
     $conn = array(
@@ -172,7 +173,7 @@ The ``require_once`` statement sets up the class autoloading for Doctrine and
 its dependencies using Composer's autoloader.
 
 The second block consists of the instantiation of the ORM
-``Configuration`` object using the Setup helper. It assumes a bunch
+``Configuration`` object using the ``ORMSetup`` helper. It assumes a bunch
 of defaults that you don't have to bother about for now. You can
 read up on the configuration details in the
 :doc:`reference chapter on configuration <../reference/configuration>`.
@@ -190,22 +191,35 @@ Generating the Database Schema
 
 Doctrine has a command-line interface that allows you to access the SchemaTool,
 a component that can generate a relational database schema based entirely on the
-defined entity classes and their metadata. For this tool to work, a
-``cli-config.php`` file must exist in the project root directory:
+defined entity classes and their metadata. For this tool to work, you need to
+create an executable console script as described in the
+:doc:`tools chapter <../reference/tools>`.
+
+If you created the ``bootstrap.php`` file as described in the previous section,
+that script could look like this:
 
 .. code-block:: php
 
+    #!/usr/bin/env php
     <?php
-    // cli-config.php
-    require_once "bootstrap.php";
+    // bin/doctrine
 
-    return \Doctrine\ORM\Tools\Console\ConsoleRunner::createHelperSet($entityManager);
+    use Doctrine\ORM\Tools\Console\ConsoleRunner;
+    use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;
 
-Now call the Doctrine command-line tool:
+    // Adjust this path to your actual bootstrap.php
+    require __DIR__ . 'path/to/your/bootstrap.php';
+
+    ConsoleRunner::run(
+        new SingleManagerProvider($entityManager)
+    );
+
+In the following examples, we will assume that this script has been created as
+``bin/doctrine``.
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:create
 
 Since we haven't added any entity metadata in ``src`` yet, you'll see a message
 stating "No Metadata Classes to process." In the next section, we'll create a
@@ -217,14 +231,14 @@ You can easily recreate the database using the following commands:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:drop --force
-    $ vendor/bin/doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:drop --force
+    $ php bin/doctrine orm:schema-tool:create
 
 Or you can use the update functionality:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force
+    $ php bin/doctrine orm:schema-tool:update --force
 
 The updating of databases uses a diff algorithm for a given
 database schema. This is a cornerstone of the ``Doctrine\DBAL`` package,
@@ -570,7 +584,7 @@ let's update the database schema:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force --dump-sql
+    $ php bin/doctrine orm:schema-tool:update --force --dump-sql
 
 Specifying both flags ``--force`` and ``--dump-sql`` will cause the DDL
 statements to be executed and then printed to the screen.
@@ -1267,7 +1281,7 @@ class that holds the owning sides.
 Update your database schema by running:
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force
+    $ php bin/doctrine orm:schema-tool:update --force
 
 
 Implementing more Requirements

doctrine-mapping.xsd

@@ -288,6 +288,14 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="generated-type">
+    <xs:restriction base="xs:token">
+      <xs:enumeration value="NEVER"/>
+      <xs:enumeration value="INSERT"/>
+      <xs:enumeration value="ALWAYS"/>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="field">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
@@ -299,6 +307,10 @@
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updatable" type="xs:boolean" default="true" />
+    <xs:attribute name="generated" type="orm:generated-type" default="NEVER" />
+    <xs:attribute name="enum-type" type="xs:string" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />
@@ -622,6 +634,8 @@
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updateable" type="xs:boolean" default="true" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />

lib/Doctrine/ORM/AbstractQuery.php

@@ -4,11 +4,13 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM;
 
+use BackedEnum;
 use Countable;
 use Doctrine\Common\Cache\Psr6\CacheAdapter;
 use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
 use Doctrine\DBAL\Result;
 use Doctrine\Deprecations\Deprecation;
@@ -22,6 +24,7 @@ use Doctrine\ORM\Query\Parameter;
 use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\Mapping\MappingException;
+use LogicException;
 use Psr\Cache\CacheItemPoolInterface;
 use Traversable;
 
@@ -29,10 +32,13 @@ use function array_map;
 use function array_shift;
 use function assert;
 use function count;
+use function func_num_args;
+use function in_array;
 use function is_array;
 use function is_numeric;
 use function is_object;
 use function is_scalar;
+use function is_string;
 use function iterator_count;
 use function iterator_to_array;
 use function ksort;
@@ -91,7 +97,7 @@ abstract class AbstractQuery
     /**
      * The user-specified ResultSetMapping to use.
      *
-     * @var ResultSetMapping
+     * @var ResultSetMapping|null
      */
     protected $_resultSetMapping;
 
@@ -113,6 +119,7 @@ abstract class AbstractQuery
      * The hydration mode.
      *
      * @var string|int
+     * @psalm-var string|AbstractQuery::HYDRATE_*
      */
     protected $_hydrationMode = self::HYDRATE_OBJECT;
 
@@ -150,6 +157,7 @@ abstract class AbstractQuery
      * Second level query cache mode.
      *
      * @var int|null
+     * @psalm-var Cache::MODE_*|null
      */
     protected $cacheMode;
 
@@ -191,7 +199,7 @@ abstract class AbstractQuery
     }
 
     /**
-     * @return bool TRUE if the query results are enable for second level cache, FALSE otherwise.
+     * @return bool TRUE if the query results are enabled for second level cache, FALSE otherwise.
      */
     public function isCacheable()
     {
@@ -251,7 +259,8 @@ abstract class AbstractQuery
     }
 
     /**
-     * @return int
+     * @return int|null
+     * @psalm-return Cache::MODE_*|null
      */
     public function getCacheMode()
     {
@@ -260,6 +269,7 @@ abstract class AbstractQuery
 
     /**
      * @param int $cacheMode
+     * @psalm-param Cache::MODE_* $cacheMode
      *
      * @return $this
      */
@@ -275,7 +285,7 @@ abstract class AbstractQuery
      * The returned SQL syntax depends on the connection driver that is used
      * by this query object at the time of this method call.
      *
-     * @return string SQL query
+     * @return list<string>|string SQL query
      */
     abstract public function getSQL();
 
@@ -317,7 +327,7 @@ abstract class AbstractQuery
     /**
      * Gets a query parameter.
      *
-     * @param mixed $key The key (index or name) of the bound parameter.
+     * @param int|string $key The key (index or name) of the bound parameter.
      *
      * @return Parameter|null The value of the bound parameter, or NULL if not available.
      */
@@ -346,7 +356,6 @@ abstract class AbstractQuery
      */
     public function setParameters($parameters)
     {
-        // BC compatibility with 2.3-
         if (is_array($parameters)) {
             /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
             $parameterCollection = new ArrayCollection();
@@ -366,11 +375,11 @@ abstract class AbstractQuery
     /**
      * Sets a query parameter.
      *
-     * @param string|int  $key   The parameter position or name.
-     * @param mixed       $value The parameter value.
-     * @param string|null $type  The parameter type. If specified, the given value will be run through
-     *                           the type conversion of this type. This is usually not needed for
-     *                           strings and numeric types.
+     * @param string|int      $key   The parameter position or name.
+     * @param mixed           $value The parameter value.
+     * @param string|int|null $type  The parameter type. If specified, the given value will be run through
+     *                               the type conversion of this type. This is usually not needed for
+     *                               strings and numeric types.
      *
      * @return $this
      */
@@ -394,8 +403,7 @@ abstract class AbstractQuery
      *
      * @param mixed $value
      *
-     * @return mixed[]|string|int|float|bool
-     * @psalm-return array|scalar
+     * @return mixed
      *
      * @throws ORMInvalidArgumentException
      */
@@ -419,15 +427,20 @@ abstract class AbstractQuery
             return $value->name;
         }
 
+        if ($value instanceof BackedEnum) {
+            return $value->value;
+        }
+
         if (! is_object($value)) {
             return $value;
         }
 
         try {
+            $class = ClassUtils::getClass($value);
             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
 
             if ($value === null) {
-                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
+                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
             }
         } catch (MappingException | ORMMappingException $e) {
             /* Silence any mapping exceptions. These can occur if the object in
@@ -492,7 +505,7 @@ abstract class AbstractQuery
     /**
      * Gets the ResultSetMapping used for hydration.
      *
-     * @return ResultSetMapping
+     * @return ResultSetMapping|null
      */
     protected function getResultSetMapping()
     {
@@ -535,12 +548,21 @@ abstract class AbstractQuery
     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
     {
         if ($profile === null) {
+            if (func_num_args() < 1) {
+                Deprecation::trigger(
+                    'doctrine/orm',
+                    'https://github.com/doctrine/orm/pull/9791',
+                    'Calling %s without arguments is deprecated, pass null instead.',
+                    __METHOD__
+                );
+            }
+
             $this->_hydrationCacheProfile = null;
 
             return $this;
         }
 
-        // DBAL < 3.2
+        // DBAL 2
         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
             if (! $profile->getResultCacheDriver()) {
                 $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
@@ -579,12 +601,21 @@ abstract class AbstractQuery
     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
     {
         if ($profile === null) {
+            if (func_num_args() < 1) {
+                Deprecation::trigger(
+                    'doctrine/orm',
+                    'https://github.com/doctrine/orm/pull/9791',
+                    'Calling %s without arguments is deprecated, pass null instead.',
+                    __METHOD__
+                );
+            }
+
             $this->_queryCacheProfile = null;
 
             return $this;
         }
 
-        // DBAL < 3.2
+        // DBAL 2
         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
             if (! $profile->getResultCacheDriver()) {
                 $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
@@ -633,6 +664,15 @@ abstract class AbstractQuery
     public function setResultCache(?CacheItemPoolInterface $resultCache = null)
     {
         if ($resultCache === null) {
+            if (func_num_args() < 1) {
+                Deprecation::trigger(
+                    'doctrine/orm',
+                    'https://github.com/doctrine/orm/pull/9791',
+                    'Calling %s without arguments is deprecated, pass null instead.',
+                    __METHOD__
+                );
+            }
+
             if ($this->_queryCacheProfile) {
                 $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
             }
@@ -640,7 +680,7 @@ abstract class AbstractQuery
             return $this;
         }
 
-        // DBAL < 3.2
+        // DBAL 2
         if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
             $resultCacheDriver = DoctrineProvider::wrap($resultCache);
 
@@ -746,7 +786,7 @@ abstract class AbstractQuery
             return $this;
         }
 
-        // Compatibility for DBAL < 3.2
+        // Compatibility for DBAL 2
         if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
             $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
 
@@ -805,17 +845,22 @@ abstract class AbstractQuery
     /**
      * Change the default fetch mode of an association for this query.
      *
-     * $fetchMode can be one of ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY
-     *
-     * @param string $class
-     * @param string $assocName
-     * @param int    $fetchMode
+     * @param class-string $class
+     * @param string       $assocName
+     * @param int          $fetchMode
+     * @psalm-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
      *
      * @return $this
      */
     public function setFetchMode($class, $assocName, $fetchMode)
     {
-        if ($fetchMode !== Mapping\ClassMetadata::FETCH_EAGER) {
+        if (! in_array($fetchMode, [Mapping\ClassMetadata::FETCH_EAGER, Mapping\ClassMetadata::FETCH_LAZY], true)) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9777',
+                'Calling %s() with something else than ClassMetadata::FETCH_EAGER or ClassMetadata::FETCH_LAZY is deprecated.',
+                __METHOD__
+            );
             $fetchMode = Mapping\ClassMetadata::FETCH_LAZY;
         }
 
@@ -829,6 +874,7 @@ abstract class AbstractQuery
      *
      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
      *                                  One of the Query::HYDRATE_* constants.
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return $this
      */
@@ -843,6 +889,7 @@ abstract class AbstractQuery
      * Gets the hydration mode currently used by the query.
      *
      * @return string|int
+     * @psalm-return string|AbstractQuery::HYDRATE_*
      */
     public function getHydrationMode()
     {
@@ -855,6 +902,7 @@ abstract class AbstractQuery
      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
      *
      * @param string|int $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return mixed
      */
@@ -902,7 +950,8 @@ abstract class AbstractQuery
     /**
      * Get exactly one result or null.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
@@ -939,7 +988,8 @@ abstract class AbstractQuery
      * If the result is not unique, a NonUniqueResultException is thrown.
      * If there is no result, a NoResultException is thrown.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
@@ -1037,6 +1087,7 @@ abstract class AbstractQuery
      *
      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
      * @param string|int|null              $hydrationMode The hydration mode to use.
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
      *
      * @return IterableResult
      */
@@ -1057,7 +1108,11 @@ abstract class AbstractQuery
             $this->setParameters($parameters);
         }
 
-        $rsm  = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $stmt = $this->_doExecute();
 
         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
@@ -1070,6 +1125,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
      * @param string|int|null               $hydrationMode The hydration mode to use.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
      *
      * @return iterable<mixed>
      */
@@ -1087,6 +1143,9 @@ abstract class AbstractQuery
         }
 
         $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
 
         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
             throw QueryException::iterateWithMixedResultNotAllowed();
@@ -1103,6 +1162,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1121,6 +1181,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1165,7 +1226,11 @@ abstract class AbstractQuery
             return $stmt;
         }
 
-        $rsm  = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
 
         $setCacheEntry($data);
@@ -1177,7 +1242,7 @@ abstract class AbstractQuery
     {
         assert($this->_hydrationCacheProfile !== null);
 
-        // Support for DBAL < 3.2
+        // Support for DBAL 2
         if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
             $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
             assert($cacheDriver !== null);
@@ -1197,12 +1262,17 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
     {
-        $rsm        = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
         $queryKey   = new QueryCacheKey(
             $this->getHash(),
@@ -1237,6 +1307,7 @@ abstract class AbstractQuery
 
     private function getTimestampKey(): ?TimestampCacheKey
     {
+        assert($this->_resultSetMapping !== null);
         $entityName = reset($this->_resultSetMapping->aliasMap);
 
         if (empty($entityName)) {
@@ -1264,7 +1335,8 @@ abstract class AbstractQuery
             $parameters[$parameter->getName()] = $this->processParameterValue($parameter->getValue());
         }
 
-        $sql                    = $this->getSQL();
+        $sql = $this->getSQL();
+        assert(is_string($sql));
         $queryCacheProfile      = $this->getHydrationCacheProfile();
         $hints                  = $this->getHints();
         $hints['hydrationMode'] = $this->getHydrationMode();
@@ -1336,7 +1408,8 @@ abstract class AbstractQuery
      */
     protected function getHash()
     {
-        $query  = $this->getSQL();
+        $query = $this->getSQL();
+        assert(is_string($query));
         $hints  = $this->getHints();
         $params = array_map(function (Parameter $parameter) {
             $value = $parameter->getValue();

lib/Doctrine/ORM/Cache.php

@@ -141,6 +141,8 @@ interface Cache
      * Evicts all cached query results under the given name, or default query cache if the region name is NULL.
      *
      * @param string|null $regionName The cache name associated to the queries being cached.
+     *
+     * @return void
      */
     public function evictQueryRegion($regionName = null);
 

lib/Doctrine/ORM/Cache/AssociationCacheEntry.php

@@ -10,22 +10,26 @@ namespace Doctrine\ORM\Cache;
 class AssociationCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity identifier
      *
-     * @var array<string, mixed> The entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $identifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $class;
 
     /**
      * @param string               $class      The entity class.
      * @param array<string, mixed> $identifier The entity identifier.
+     * @psalm-param class-string $class
      */
     public function __construct($class, array $identifier)
     {

lib/Doctrine/ORM/Cache/CacheException.php

@@ -25,6 +25,8 @@ class CacheException extends ORMException
     }
 
     /**
+     * @deprecated This method is not used anymore.
+     *
      * @param string $entityName
      *
      * @return CacheException
@@ -45,6 +47,8 @@ class CacheException extends ORMException
     }
 
     /**
+     * @deprecated This method is not used anymore.
+     *
      * @param string $entityName
      * @param string $field
      *

lib/Doctrine/ORM/Cache/CacheFactory.php

@@ -31,9 +31,7 @@ interface CacheFactory
     /**
      * Build a collection persister for the given relation mapping.
      *
-     * @param EntityManagerInterface $em        The entity manager.
-     * @param CollectionPersister    $persister The collection persister that will be cached.
-     * @param mixed[]                $mapping   The association mapping.
+     * @param mixed[] $mapping The association mapping.
      *
      * @return CachedCollectionPersister
      */
@@ -42,8 +40,7 @@ interface CacheFactory
     /**
      * Build a query cache based on the given region name
      *
-     * @param EntityManagerInterface $em         The Entity manager.
-     * @param string                 $regionName The region name.
+     * @param string|null $regionName The region name.
      *
      * @return QueryCache The built query cache.
      */
@@ -52,9 +49,6 @@ interface CacheFactory
     /**
      * Build an entity hydrator
      *
-     * @param EntityManagerInterface $em       The Entity manager.
-     * @param ClassMetadata          $metadata The entity metadata.
-     *
      * @return EntityHydrator The built entity hydrator.
      */
     public function buildEntityHydrator(EntityManagerInterface $em, ClassMetadata $metadata);
@@ -62,8 +56,7 @@ interface CacheFactory
     /**
      * Build a collection hydrator
      *
-     * @param EntityManagerInterface $em      The Entity manager.
-     * @param mixed[]                $mapping The association mapping.
+     * @param mixed[] $mapping The association mapping.
      *
      * @return CollectionHydrator The built collection hydrator.
      */

lib/Doctrine/ORM/Cache/CacheKey.php

@@ -11,9 +11,10 @@ namespace Doctrine\ORM\Cache;
 abstract class CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * Unique identifier
      *
-     * @var string Unique identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      */
     public $hash;
 }

lib/Doctrine/ORM/Cache/CollectionCacheEntry.php

@@ -10,9 +10,10 @@ namespace Doctrine\ORM\Cache;
 class CollectionCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The list of entity identifiers hold by the collection
      *
-     * @var CacheKey[] The list of entity identifiers hold by the collection
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var CacheKey[]
      */
     public $identifiers;
 

lib/Doctrine/ORM/Cache/CollectionCacheKey.php

@@ -15,23 +15,27 @@ use function strtolower;
 class CollectionCacheKey extends CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The owner entity identifier
      *
-     * @var array<string, mixed> The owner entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $ownerIdentifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The owner entity class
      *
-     * @var string The owner entity class
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $entityClass;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The association name
      *
-     * @var string The association name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      */
     public $association;
 
@@ -39,6 +43,7 @@ class CollectionCacheKey extends CacheKey
      * @param string               $entityClass     The entity class.
      * @param string               $association     The field name that represents the association.
      * @param array<string, mixed> $ownerIdentifier The identifier of the owning entity.
+     * @psalm-param class-string $entityClass
      */
     public function __construct($entityClass, $association, array $ownerIdentifier)
     {

lib/Doctrine/ORM/Cache/CollectionHydrator.php

@@ -14,8 +14,6 @@ use Doctrine\ORM\PersistentCollection;
 interface CollectionHydrator
 {
     /**
-     * @param ClassMetadata            $metadata   The entity metadata.
-     * @param CollectionCacheKey       $key        The cached collection key.
      * @param array|mixed[]|Collection $collection The collection.
      *
      * @return CollectionCacheEntry
@@ -23,12 +21,7 @@ interface CollectionHydrator
     public function buildCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, $collection);
 
     /**
-     * @param ClassMetadata        $metadata   The owning entity metadata.
-     * @param CollectionCacheKey   $key        The cached collection key.
-     * @param CollectionCacheEntry $entry      The cached collection entry.
-     * @param PersistentCollection $collection The collection to load the cache into.
-     *
-     * @return mixed[]
+     * @return mixed[]|null
      */
     public function loadCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, CollectionCacheEntry $entry, PersistentCollection $collection);
 }

lib/Doctrine/ORM/Cache/ConcurrentRegion.php

@@ -18,7 +18,7 @@ interface ConcurrentRegion extends Region
      *
      * @param CacheKey $key The key of the item to lock.
      *
-     * @return Lock A lock instance or NULL if the lock already exists.
+     * @return Lock|null A lock instance or NULL if the lock already exists.
      *
      * @throws LockException Indicates a problem accessing the region.
      */
@@ -30,7 +30,7 @@ interface ConcurrentRegion extends Region
      * @param CacheKey $key  The key of the item to unlock.
      * @param Lock     $lock The lock previously obtained from {@link readLock}
      *
-     * @return void
+     * @return bool
      *
      * @throws LockException Indicates a problem accessing the region.
      */

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -29,7 +29,10 @@ class DefaultCache implements Cache
      /** @var CacheFactory */
     private $cacheFactory;
 
-    /** @var QueryCache[] */
+    /**
+     * @var QueryCache[]
+     * @psalm-var array<string, QueryCache>
+     */
     private $queryCaches = [];
 
     /** @var QueryCache|null */
@@ -260,8 +263,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * @param ClassMetadata $metadata   The entity metadata.
-     * @param mixed         $identifier The entity identifier.
+     * @param mixed $identifier The entity identifier.
      */
     private function buildEntityCacheKey(ClassMetadata $metadata, $identifier): EntityCacheKey
     {
@@ -273,9 +275,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * @param ClassMetadata $metadata        The entity metadata.
-     * @param string        $association     The field name that represents the association.
-     * @param mixed         $ownerIdentifier The identifier of the owning entity.
+     * @param mixed $ownerIdentifier The identifier of the owning entity.
      */
     private function buildCollectionCacheKey(
         ClassMetadata $metadata,
@@ -290,18 +290,20 @@ class DefaultCache implements Cache
     }
 
     /**
-     * @param ClassMetadata $metadata   The entity metadata.
-     * @param mixed         $identifier The entity identifier.
+     * @param mixed $identifier The entity identifier.
      *
      * @return array<string, mixed>
      */
     private function toIdentifierArray(ClassMetadata $metadata, $identifier): array
     {
-        if (is_object($identifier) && $this->em->getMetadataFactory()->hasMetadataFor(ClassUtils::getClass($identifier))) {
-            $identifier = $this->uow->getSingleIdentifierValue($identifier);
+        if (is_object($identifier)) {
+            $class = ClassUtils::getClass($identifier);
+            if ($this->em->getMetadataFactory()->hasMetadataFor($class)) {
+                $identifier = $this->uow->getSingleIdentifierValue($identifier);
 
-            if ($identifier === null) {
-                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
+                if ($identifier === null) {
+                    throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
+                }
             }
         }
 

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -4,9 +4,9 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
-use Doctrine\Common\Cache\Cache as CacheAdapter;
-use Doctrine\Common\Cache\CacheProvider;
-use Doctrine\Common\Cache\MultiGetCache;
+use Doctrine\Common\Cache\Cache as LegacyCache;
+use Doctrine\Common\Cache\Psr6\CacheAdapter;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Cache\Persister\Collection\NonStrictReadWriteCachedCollectionPersister;
 use Doctrine\ORM\Cache\Persister\Collection\ReadOnlyCachedCollectionPersister;
@@ -14,7 +14,6 @@ use Doctrine\ORM\Cache\Persister\Collection\ReadWriteCachedCollectionPersister;
 use Doctrine\ORM\Cache\Persister\Entity\NonStrictReadWriteCachedEntityPersister;
 use Doctrine\ORM\Cache\Persister\Entity\ReadOnlyCachedEntityPersister;
 use Doctrine\ORM\Cache\Persister\Entity\ReadWriteCachedEntityPersister;
-use Doctrine\ORM\Cache\Region\DefaultMultiGetRegion;
 use Doctrine\ORM\Cache\Region\DefaultRegion;
 use Doctrine\ORM\Cache\Region\FileLockRegion;
 use Doctrine\ORM\Cache\Region\UpdateTimestampCache;
@@ -24,15 +23,19 @@ use Doctrine\ORM\Persisters\Collection\CollectionPersister;
 use Doctrine\ORM\Persisters\Entity\EntityPersister;
 use InvalidArgumentException;
 use LogicException;
+use Psr\Cache\CacheItemPoolInterface;
+use TypeError;
 
+use function assert;
+use function get_debug_type;
 use function sprintf;
 
 use const DIRECTORY_SEPARATOR;
 
 class DefaultCacheFactory implements CacheFactory
 {
-    /** @var CacheAdapter */
-    private $cache;
+    /** @var CacheItemPoolInterface */
+    private $cacheItemPool;
 
     /** @var RegionsConfiguration */
     private $regionsConfig;
@@ -46,9 +49,33 @@ class DefaultCacheFactory implements CacheFactory
     /** @var string|null */
     private $fileLockRegionDirectory;
 
-    public function __construct(RegionsConfiguration $cacheConfig, CacheAdapter $cache)
+    /**
+     * @param CacheItemPoolInterface $cacheItemPool
+     */
+    public function __construct(RegionsConfiguration $cacheConfig, $cacheItemPool)
     {
-        $this->cache         = $cache;
+        if ($cacheItemPool instanceof LegacyCache) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9322',
+                'Passing an instance of %s to %s is deprecated, pass a %s instead.',
+                get_debug_type($cacheItemPool),
+                __METHOD__,
+                CacheItemPoolInterface::class
+            );
+
+            $this->cacheItemPool = CacheAdapter::wrap($cacheItemPool);
+        } elseif (! $cacheItemPool instanceof CacheItemPoolInterface) {
+            throw new TypeError(sprintf(
+                '%s: Parameter #2 is expected to be an instance of %s, got %s.',
+                __METHOD__,
+                CacheItemPoolInterface::class,
+                get_debug_type($cacheItemPool)
+            ));
+        } else {
+            $this->cacheItemPool = $cacheItemPool;
+        }
+
         $this->regionsConfig = $cacheConfig;
     }
 
@@ -91,6 +118,7 @@ class DefaultCacheFactory implements CacheFactory
      */
     public function buildCachedEntityPersister(EntityManagerInterface $em, EntityPersister $persister, ClassMetadata $metadata)
     {
+        assert($metadata->cache !== null);
         $region = $this->getRegion($metadata->cache);
         $usage  = $metadata->cache['usage'];
 
@@ -181,13 +209,9 @@ class DefaultCacheFactory implements CacheFactory
             return $this->regions[$cache['region']];
         }
 
-        $name         = $cache['region'];
-        $cacheAdapter = $this->createRegionCache($name);
-        $lifetime     = $this->regionsConfig->getLifetime($cache['region']);
-
-        $region = $cacheAdapter instanceof MultiGetCache
-            ? new DefaultMultiGetRegion($name, $cacheAdapter, $lifetime)
-            : new DefaultRegion($name, $cacheAdapter, $lifetime);
+        $name     = $cache['region'];
+        $lifetime = $this->regionsConfig->getLifetime($cache['region']);
+        $region   = new DefaultRegion($name, $this->cacheItemPool, $lifetime);
 
         if ($cache['usage'] === ClassMetadata::CACHE_USAGE_READ_WRITE) {
             if (
@@ -207,25 +231,6 @@ class DefaultCacheFactory implements CacheFactory
         return $this->regions[$cache['region']] = $region;
     }
 
-    private function createRegionCache(string $name): CacheAdapter
-    {
-        $cacheAdapter = clone $this->cache;
-
-        if (! $cacheAdapter instanceof CacheProvider) {
-            return $cacheAdapter;
-        }
-
-        $namespace = $cacheAdapter->getNamespace();
-
-        if ($namespace !== '') {
-            $namespace .= ':';
-        }
-
-        $cacheAdapter->setNamespace($namespace . $name);
-
-        return $cacheAdapter;
-    }
-
     /**
      * {@inheritdoc}
      */
@@ -235,7 +240,7 @@ class DefaultCacheFactory implements CacheFactory
             $name     = Cache::DEFAULT_TIMESTAMP_REGION_NAME;
             $lifetime = $this->regionsConfig->getLifetime($name);
 
-            $this->timestampRegion = new UpdateTimestampCache($name, clone $this->cache, $lifetime);
+            $this->timestampRegion = new UpdateTimestampCache($name, $this->cacheItemPool, $lifetime);
         }
 
         return $this->timestampRegion;
@@ -244,8 +249,8 @@ class DefaultCacheFactory implements CacheFactory
     /**
      * {@inheritdoc}
      */
-    public function createCache(EntityManagerInterface $em)
+    public function createCache(EntityManagerInterface $entityManager)
     {
-        return new DefaultCache($em);
+        return new DefaultCache($entityManager);
     }
 }

lib/Doctrine/ORM/Cache/DefaultCollectionHydrator.php

@@ -11,7 +11,6 @@ use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
 
-use function array_walk;
 use function assert;
 
 /**

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -12,6 +12,7 @@ use Doctrine\ORM\UnitOfWork;
 use Doctrine\ORM\Utility\IdentifierFlattener;
 
 use function array_merge;
+use function assert;
 use function is_array;
 use function is_object;
 use function reset;
@@ -55,8 +56,17 @@ class DefaultEntityHydrator implements EntityHydrator
         $data = $this->uow->getOriginalEntityData($entity);
         $data = array_merge($data, $metadata->getIdentifierValues($entity)); // why update has no identifier values ?
 
-        if ($metadata->isVersioned) {
-            $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+        if ($metadata->requiresFetchAfterChange) {
+            if ($metadata->isVersioned) {
+                assert($metadata->versionField !== null);
+                $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+            }
+
+            foreach ($metadata->fieldMappings as $name => $fieldMapping) {
+                if (isset($fieldMapping['generated'])) {
+                    $data[$name] = $metadata->getFieldValue($entity, $name);
+                }
+            }
         }
 
         foreach ($metadata->associationMappings as $name => $assoc) {

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -18,7 +18,6 @@ use Doctrine\ORM\Query;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\UnitOfWork;
 
-use function array_key_exists;
 use function array_map;
 use function array_shift;
 use function array_unshift;
@@ -45,7 +44,7 @@ class DefaultQueryCache implements QueryCache
     /** @var QueryCacheValidator */
     private $validator;
 
-    /** @var CacheLogger */
+    /** @var CacheLogger|null */
     protected $cacheLogger;
 
     /** @var array<string,mixed> */
@@ -385,7 +384,8 @@ class DefaultQueryCache implements QueryCache
     /**
      * @param object $entity
      *
-     * @return array<object>|object
+     * @return mixed[]|object|null
+     * @psalm-return list<mixed>|object|null
      */
     private function getAssociationValue(
         ResultSetMapping $rsm,
@@ -412,10 +412,11 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * @param mixed        $value
-     * @param array<mixed> $path
+     * @param mixed $value
+     * @psalm-param array<array-key, array{field: string, class: string}> $path
      *
-     * @return mixed
+     * @return mixed[]|object|null
+     * @psalm-return list<mixed>|object|null
      */
     private function getAssociationPathValue($value, array $path)
     {

lib/Doctrine/ORM/Cache/EntityCacheEntry.php

@@ -14,16 +14,18 @@ use function array_map;
 class EntityCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity map data
      *
-     * @var array<string,mixed> The entity map data
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string,mixed>
      */
     public $data;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      * @psalm-var class-string
      */
     public $class;

lib/Doctrine/ORM/Cache/EntityCacheKey.php

@@ -15,22 +15,26 @@ use function strtolower;
 class EntityCacheKey extends CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity identifier
      *
-     * @var array<string, mixed> The entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $identifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $entityClass;
 
     /**
      * @param string               $entityClass The entity class name. In a inheritance hierarchy it should always be the root entity class.
      * @param array<string, mixed> $identifier  The entity identifier
+     * @psalm-param class-string $entityClass
      */
     public function __construct($entityClass, array $identifier)
     {

lib/Doctrine/ORM/Cache/EntityHydrator.php

@@ -24,7 +24,9 @@ interface EntityHydrator
      * @param ClassMetadata    $metadata The entity metadata.
      * @param EntityCacheKey   $key      The entity cache key.
      * @param EntityCacheEntry $entry    The entity cache entry.
-     * @param object           $entity   The entity to load the cache into. If not specified, a new entity is created.
+     * @param object|null      $entity   The entity to load the cache into. If not specified, a new entity is created.
+     *
+     * @return object|null
      */
     public function loadCacheEntry(ClassMetadata $metadata, EntityCacheKey $key, EntityCacheEntry $entry, $entity = null);
 }

lib/Doctrine/ORM/Cache/Exception/CacheException.php

@@ -6,8 +6,6 @@ namespace Doctrine\ORM\Cache\Exception;
 
 use Doctrine\ORM\Cache\CacheException as BaseCacheException;
 
-use function sprintf;
-
 /**
  * Exception for cache.
  */

lib/Doctrine/ORM/Cache/Exception/CannotUpdateReadOnlyCollection.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 use function sprintf;
 
 class CannotUpdateReadOnlyCollection extends CacheException

lib/Doctrine/ORM/Cache/Exception/CannotUpdateReadOnlyEntity.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 use function sprintf;
 
 class CannotUpdateReadOnlyEntity extends CacheException

lib/Doctrine/ORM/Cache/Exception/FeatureNotImplemented.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 class FeatureNotImplemented extends CacheException
 {
     public static function scalarResults(): self

lib/Doctrine/ORM/Cache/Exception/MetadataCacheNotConfigured.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 final class MetadataCacheNotConfigured extends CacheException
 {
     public static function create(): self

lib/Doctrine/ORM/Cache/Exception/MetadataCacheUsesNonPersistentCache.php

@@ -5,16 +5,15 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache\Exception;
 
 use Doctrine\Common\Cache\Cache;
-use LogicException;
 
-use function get_class;
+use function get_debug_type;
 
 final class MetadataCacheUsesNonPersistentCache extends CacheException
 {
     public static function fromDriver(Cache $cache): self
     {
         return new self(
-            'Metadata Cache uses a non-persistent cache driver, ' . get_class($cache) . '.'
+            'Metadata Cache uses a non-persistent cache driver, ' . get_debug_type($cache) . '.'
         );
     }
 }

lib/Doctrine/ORM/Cache/Exception/NonCacheableEntity.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 use function sprintf;
 
 class NonCacheableEntity extends CacheException

lib/Doctrine/ORM/Cache/Exception/QueryCacheNotConfigured.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Exception;
 
-use LogicException;
-
 final class QueryCacheNotConfigured extends CacheException
 {
     public static function create(): self

lib/Doctrine/ORM/Cache/Exception/QueryCacheUsesNonPersistentCache.php

@@ -5,16 +5,15 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache\Exception;
 
 use Doctrine\Common\Cache\Cache;
-use LogicException;
 
-use function get_class;
+use function get_debug_type;
 
 final class QueryCacheUsesNonPersistentCache extends CacheException
 {
     public static function fromDriver(Cache $cache): self
     {
         return new self(
-            'Query Cache uses a non-persistent cache driver, ' . get_class($cache) . '.'
+            'Query Cache uses a non-persistent cache driver, ' . get_debug_type($cache) . '.'
         );
     }
 }

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

@@ -18,6 +18,8 @@ interface CacheLogger
      *
      * @param string         $regionName The name of the cache region.
      * @param EntityCacheKey $key        The cache key of the entity.
+     *
+     * @return void
      */
     public function entityCachePut($regionName, EntityCacheKey $key);
 
@@ -26,6 +28,8 @@ interface CacheLogger
      *
      * @param string         $regionName The name of the cache region.
      * @param EntityCacheKey $key        The cache key of the entity.
+     *
+     * @return void
      */
     public function entityCacheHit($regionName, EntityCacheKey $key);
 
@@ -34,6 +38,8 @@ interface CacheLogger
      *
      * @param string         $regionName The name of the cache region.
      * @param EntityCacheKey $key        The cache key of the entity.
+     *
+     * @return void
      */
     public function entityCacheMiss($regionName, EntityCacheKey $key);
 
@@ -42,6 +48,8 @@ interface CacheLogger
      *
      * @param string             $regionName The name of the cache region.
      * @param CollectionCacheKey $key        The cache key of the collection.
+     *
+     * @return void
      */
     public function collectionCachePut($regionName, CollectionCacheKey $key);
 
@@ -50,6 +58,8 @@ interface CacheLogger
      *
      * @param string             $regionName The name of the cache region.
      * @param CollectionCacheKey $key        The cache key of the collection.
+     *
+     * @return void
      */
     public function collectionCacheHit($regionName, CollectionCacheKey $key);
 
@@ -58,6 +68,8 @@ interface CacheLogger
      *
      * @param string             $regionName The name of the cache region.
      * @param CollectionCacheKey $key        The cache key of the collection.
+     *
+     * @return void
      */
     public function collectionCacheMiss($regionName, CollectionCacheKey $key);
 
@@ -66,6 +78,8 @@ interface CacheLogger
      *
      * @param string        $regionName The name of the cache region.
      * @param QueryCacheKey $key        The cache key of the query.
+     *
+     * @return void
      */
     public function queryCachePut($regionName, QueryCacheKey $key);
 
@@ -74,6 +88,8 @@ interface CacheLogger
      *
      * @param string        $regionName The name of the cache region.
      * @param QueryCacheKey $key        The cache key of the query.
+     *
+     * @return void
      */
     public function queryCacheHit($regionName, QueryCacheKey $key);
 
@@ -82,6 +98,8 @@ interface CacheLogger
      *
      * @param string        $regionName The name of the cache region.
      * @param QueryCacheKey $key        The cache key of the query.
+     *
+     * @return void
      */
     public function queryCacheMiss($regionName, QueryCacheKey $key);
 }

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

@@ -10,7 +10,7 @@ use Doctrine\ORM\Cache\QueryCacheKey;
 
 class CacheLoggerChain implements CacheLogger
 {
-    /** @var array<CacheLogger> */
+    /** @var array<string, CacheLogger> */
     private $loggers = [];
 
     /**
@@ -34,7 +34,7 @@ class CacheLoggerChain implements CacheLogger
     }
 
     /**
-     * @return array<CacheLogger>
+     * @return array<string, CacheLogger>
      */
     public function getLoggers()
     {

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

@@ -15,13 +15,13 @@ use function array_sum;
  */
 class StatisticsCacheLogger implements CacheLogger
 {
-    /** @var int[] */
+    /** @var array<string, int> */
     private $cacheMissCountMap = [];
 
-    /** @var int[] */
+    /** @var array<string, int> */
     private $cacheHitCountMap = [];
 
-    /** @var int[] */
+    /** @var array<string, int> */
     private $cachePutCountMap = [];
 
     /**
@@ -29,9 +29,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function collectionCacheMiss($regionName, CollectionCacheKey $key)
     {
-        $this->cacheMissCountMap[$regionName] = isset($this->cacheMissCountMap[$regionName])
-            ? $this->cacheMissCountMap[$regionName] + 1
-            : 1;
+        $this->cacheMissCountMap[$regionName]
+            = ($this->cacheMissCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -39,9 +38,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function collectionCacheHit($regionName, CollectionCacheKey $key)
     {
-        $this->cacheHitCountMap[$regionName] = isset($this->cacheHitCountMap[$regionName])
-            ? $this->cacheHitCountMap[$regionName] + 1
-            : 1;
+        $this->cacheHitCountMap[$regionName]
+            = ($this->cacheHitCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -49,9 +47,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function collectionCachePut($regionName, CollectionCacheKey $key)
     {
-        $this->cachePutCountMap[$regionName] = isset($this->cachePutCountMap[$regionName])
-            ? $this->cachePutCountMap[$regionName] + 1
-            : 1;
+        $this->cachePutCountMap[$regionName]
+            = ($this->cachePutCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -59,9 +56,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function entityCacheMiss($regionName, EntityCacheKey $key)
     {
-        $this->cacheMissCountMap[$regionName] = isset($this->cacheMissCountMap[$regionName])
-            ? $this->cacheMissCountMap[$regionName] + 1
-            : 1;
+        $this->cacheMissCountMap[$regionName]
+            = ($this->cacheMissCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -69,9 +65,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function entityCacheHit($regionName, EntityCacheKey $key)
     {
-        $this->cacheHitCountMap[$regionName] = isset($this->cacheHitCountMap[$regionName])
-            ? $this->cacheHitCountMap[$regionName] + 1
-            : 1;
+        $this->cacheHitCountMap[$regionName]
+            = ($this->cacheHitCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -79,9 +74,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function entityCachePut($regionName, EntityCacheKey $key)
     {
-        $this->cachePutCountMap[$regionName] = isset($this->cachePutCountMap[$regionName])
-            ? $this->cachePutCountMap[$regionName] + 1
-            : 1;
+        $this->cachePutCountMap[$regionName]
+            = ($this->cachePutCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -89,9 +83,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function queryCacheHit($regionName, QueryCacheKey $key)
     {
-        $this->cacheHitCountMap[$regionName] = isset($this->cacheHitCountMap[$regionName])
-            ? $this->cacheHitCountMap[$regionName] + 1
-            : 1;
+        $this->cacheHitCountMap[$regionName]
+            = ($this->cacheHitCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -99,9 +92,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function queryCacheMiss($regionName, QueryCacheKey $key)
     {
-        $this->cacheMissCountMap[$regionName] = isset($this->cacheMissCountMap[$regionName])
-            ? $this->cacheMissCountMap[$regionName] + 1
-            : 1;
+        $this->cacheMissCountMap[$regionName]
+            = ($this->cacheMissCountMap[$regionName] ?? 0) + 1;
     }
 
     /**
@@ -109,9 +101,8 @@ class StatisticsCacheLogger implements CacheLogger
      */
     public function queryCachePut($regionName, QueryCacheKey $key)
     {
-        $this->cachePutCountMap[$regionName] = isset($this->cachePutCountMap[$regionName])
-            ? $this->cachePutCountMap[$regionName] + 1
-            : 1;
+        $this->cachePutCountMap[$regionName]
+            = ($this->cachePutCountMap[$regionName] ?? 0) + 1;
     }
 
     /**

lib/Doctrine/ORM/Cache/MultiGetRegion.php

@@ -8,6 +8,8 @@ namespace Doctrine\ORM\Cache;
  * Defines a region that supports multi-get reading.
  *
  * With one method call we can get multiple items.
+ *
+ * @deprecated Implement {@see Region} instead.
  */
 interface MultiGetRegion
 {

lib/Doctrine/ORM/Cache/Persister/CachedPersister.php

@@ -13,11 +13,15 @@ interface CachedPersister
 {
     /**
      * Perform whatever processing is encapsulated here after completion of the transaction.
+     *
+     * @return void
      */
     public function afterTransactionComplete();
 
     /**
      * Perform whatever processing is encapsulated here after completion of the rolled-back.
+     *
+     * @return void
      */
     public function afterTransactionRolledBack();
 

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

@@ -7,6 +7,7 @@ namespace Doctrine\ORM\Cache\Persister\Collection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Util\ClassUtils;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CollectionCacheKey;
 use Doctrine\ORM\Cache\CollectionHydrator;
 use Doctrine\ORM\Cache\EntityCacheKey;
@@ -108,7 +109,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
-     * @return object[]|null
+     * {@inheritdoc}
      */
     public function loadCollectionCache(PersistentCollection $collection, CollectionCacheKey $key)
     {
@@ -224,10 +225,18 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     /**
      * Clears cache entries related to the current collection
      *
+     * @deprecated This method is not used anymore.
+     *
      * @return void
      */
     protected function evictCollectionCache(PersistentCollection $collection)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9512',
+            'The method %s() is deprecated and will be removed without replacement.'
+        );
+
         $key = new CollectionCacheKey(
             $this->sourceEntity->rootEntityName,
             $this->association['fieldName'],
@@ -242,13 +251,22 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     }
 
     /**
+     * @deprecated This method is not used anymore.
+     *
      * @param string $targetEntity
      * @param object $element
+     * @psalm-param class-string $targetEntity
      *
      * @return void
      */
     protected function evictElementCache($targetEntity, $element)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9512',
+            'The method %s() is deprecated and will be removed without replacement.'
+        );
+
         $targetPersister = $this->uow->getEntityPersister($targetEntity);
         assert($targetPersister instanceof CachedEntityPersister);
         $targetRegion = $targetPersister->getCacheRegion();

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

@@ -29,14 +29,14 @@ interface CachedCollectionPersister extends CachedPersister, CollectionPersister
     /**
      * Loads a collection from cache
      *
-     * @return PersistentCollection|null
+     * @return mixed[]|null
      */
     public function loadCollectionCache(PersistentCollection $collection, CollectionCacheKey $key);
 
     /**
      * Stores a collection into cache
      *
-     * @param array|mixed[]|Collection $elements
+     * @param mixed[]|Collection $elements
      *
      * @return void
      */

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

@@ -5,7 +5,6 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache\Persister\Collection;
 
 use Doctrine\Common\Util\ClassUtils;
-use Doctrine\ORM\Cache\CacheException;
 use Doctrine\ORM\Cache\Exception\CannotUpdateReadOnlyCollection;
 use Doctrine\ORM\PersistentCollection;
 

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

@@ -15,10 +15,7 @@ use function spl_object_id;
 class ReadWriteCachedCollectionPersister extends AbstractCollectionPersister
 {
     /**
-     * @param CollectionPersister    $persister   The collection persister that will be cached.
-     * @param ConcurrentRegion       $region      The collection region.
-     * @param EntityManagerInterface $em          The entity manager.
-     * @param mixed[]                $association The association mapping.
+     * @param mixed[] $association The association mapping.
      */
     public function __construct(CollectionPersister $persister, ConcurrentRegion $region, EntityManagerInterface $em, array $association)
     {

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

@@ -251,8 +251,8 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
      * @param string            $query
      * @param string[]|Criteria $criteria
      * @param string[]          $orderBy
-     * @param int               $limit
-     * @param int               $offset
+     * @param int|null          $limit
+     * @param int|null          $offset
      *
      * @return string
      */

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

@@ -15,12 +15,6 @@ use Doctrine\ORM\Persisters\Entity\EntityPersister;
  */
 class ReadWriteCachedEntityPersister extends AbstractEntityPersister
 {
-    /**
-     * @param EntityPersister        $persister The entity persister to cache.
-     * @param ConcurrentRegion       $region    The entity cache region.
-     * @param EntityManagerInterface $em        The entity manager.
-     * @param ClassMetadata          $class     The entity metadata.
-     */
     public function __construct(EntityPersister $persister, ConcurrentRegion $region, EntityManagerInterface $em, ClassMetadata $class)
     {
         parent::__construct($persister, $region, $em, $class);

lib/Doctrine/ORM/Cache/QueryCacheEntry.php

@@ -12,22 +12,24 @@ use function microtime;
 class QueryCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * List of entity identifiers
      *
-     * @var array<string, mixed> List of entity identifiers
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $result;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * Time creation of this cache entry
      *
-     * @var float Time creation of this cache entry
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var float
      */
     public $time;
 
     /**
      * @param array<string, mixed> $result
-     * @param float                $time
+     * @param float|null           $time
      */
     public function __construct($result, $time = null)
     {

lib/Doctrine/ORM/Cache/QueryCacheKey.php

@@ -12,26 +12,31 @@ use Doctrine\ORM\Cache;
 class QueryCacheKey extends CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * Cache key lifetime
      *
-     * @var int Cache key lifetime
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var int
      */
     public $lifetime;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * Cache mode
      *
-     * @var int Cache mode (Doctrine\ORM\Cache::MODE_*)
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var int
+     * @psalm-var Cache::MODE_*
      */
     public $cacheMode;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
      * @var TimestampCacheKey|null
      */
     public $timestampKey;
 
+    /**
+     * @psalm-param Cache::MODE_* $cacheMode
+     */
     public function __construct(
         string $cacheId,
         int $lifetime = 0,

lib/Doctrine/ORM/Cache/Region.php

@@ -45,6 +45,8 @@ interface Region extends MultiGetRegion
      * @param CacheEntry $entry The entry to cache.
      * @param Lock|null  $lock  The lock previously obtained.
      *
+     * @return bool
+     *
      * @throws CacheException Indicates a problem accessing the region.
      */
     public function put(CacheKey $key, CacheEntry $entry, ?Lock $lock = null);
@@ -54,6 +56,8 @@ interface Region extends MultiGetRegion
      *
      * @param CacheKey $key The key under which to cache the item.
      *
+     * @return bool
+     *
      * @throws CacheException Indicates a problem accessing the region.
      */
     public function evict(CacheKey $key);
@@ -61,6 +65,8 @@ interface Region extends MultiGetRegion
     /**
      * Remove all contents of this particular cache region.
      *
+     * @return bool
+     *
      * @throws CacheException Indicates problem accessing the region.
      */
     public function evictAll();

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

@@ -4,64 +4,11 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Region;
 
-use Doctrine\Common\Cache\Cache;
-use Doctrine\Common\Cache\MultiGetCache;
-use Doctrine\ORM\Cache\CacheEntry;
-use Doctrine\ORM\Cache\CollectionCacheEntry;
-
-use function assert;
-use function count;
-
 /**
  * A cache region that enables the retrieval of multiple elements with one call
+ *
+ * @deprecated Use {@link DefaultRegion} instead.
  */
 class DefaultMultiGetRegion extends DefaultRegion
 {
-    /**
-     * Note that the multiple type is due to doctrine/cache not integrating the MultiGetCache interface
-     * in its signature due to BC in 1.x
-     *
-     * @var MultiGetCache|Cache
-     */
-    protected $cache;
-
-    /**
-     * {@inheritDoc}
-     *
-     * @param MultiGetCache $cache
-     */
-    public function __construct($name, MultiGetCache $cache, $lifetime = 0)
-    {
-        assert($cache instanceof Cache);
-        parent::__construct($name, $cache, $lifetime);
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getMultiple(CollectionCacheEntry $collection)
-    {
-        $keysToRetrieve = [];
-
-        foreach ($collection->identifiers as $index => $key) {
-            $keysToRetrieve[$index] = $this->getCacheEntryKey($key);
-        }
-
-        $items = $this->cache->fetchMultiple($keysToRetrieve);
-        if (count($items) !== count($keysToRetrieve)) {
-            return null;
-        }
-
-        $returnableItems = [];
-
-        foreach ($keysToRetrieve as $index => $key) {
-            if (! $items[$key] instanceof CacheEntry) {
-                return null;
-            }
-
-            $returnableItems[$index] = $items[$key];
-        }
-
-        return $returnableItems;
-    }
 }

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

@@ -4,44 +4,94 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache\Region;
 
-use BadMethodCallException;
-use Doctrine\Common\Cache\Cache as CacheAdapter;
+use Closure;
+use Doctrine\Common\Cache\Cache as LegacyCache;
 use Doctrine\Common\Cache\CacheProvider;
-use Doctrine\Common\Cache\ClearableCache;
+use Doctrine\Common\Cache\Psr6\CacheAdapter;
+use Doctrine\Common\Cache\Psr6\DoctrineProvider;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CacheEntry;
 use Doctrine\ORM\Cache\CacheKey;
 use Doctrine\ORM\Cache\CollectionCacheEntry;
 use Doctrine\ORM\Cache\Lock;
 use Doctrine\ORM\Cache\Region;
+use Psr\Cache\CacheItemInterface;
+use Psr\Cache\CacheItemPoolInterface;
+use Traversable;
+use TypeError;
 
-use function get_class;
+use function array_map;
+use function get_debug_type;
+use function iterator_to_array;
 use function sprintf;
+use function strtr;
 
 /**
  * The simplest cache region compatible with all doctrine-cache drivers.
  */
 class DefaultRegion implements Region
 {
+    /**
+     * @internal since 2.11, this constant will be private in 3.0.
+     */
     public const REGION_KEY_SEPARATOR = '_';
-
-    /** @var CacheAdapter */
-    protected $cache;
-
-    /** @var string */
-    protected $name;
-
-    /** @var int */
-    protected $lifetime = 0;
+    private const REGION_PREFIX       = 'DC2_REGION_';
 
     /**
-     * @param string $name
-     * @param int    $lifetime
+     * @deprecated since 2.11, this property will be removed in 3.0.
+     *
+     * @var LegacyCache
      */
-    public function __construct($name, CacheAdapter $cache, $lifetime = 0)
+    protected $cache;
+
+    /**
+     * @internal since 2.11, this property will be private in 3.0.
+     *
+     * @var string
+     */
+    protected $name;
+
+    /**
+     * @internal since 2.11, this property will be private in 3.0.
+     *
+     * @var int
+     */
+    protected $lifetime = 0;
+
+    /** @var CacheItemPoolInterface */
+    private $cacheItemPool;
+
+    /**
+     * @param CacheItemPoolInterface $cacheItemPool
+     */
+    public function __construct(string $name, $cacheItemPool, int $lifetime = 0)
     {
-        $this->cache    = $cache;
-        $this->name     = (string) $name;
-        $this->lifetime = (int) $lifetime;
+        if ($cacheItemPool instanceof LegacyCache) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9322',
+                'Passing an instance of %s to %s is deprecated, pass a %s instead.',
+                get_debug_type($cacheItemPool),
+                __METHOD__,
+                CacheItemPoolInterface::class
+            );
+
+            $this->cache         = $cacheItemPool;
+            $this->cacheItemPool = CacheAdapter::wrap($cacheItemPool);
+        } elseif (! $cacheItemPool instanceof CacheItemPoolInterface) {
+            throw new TypeError(sprintf(
+                '%s: Parameter #2 is expected to be an instance of %s, got %s.',
+                __METHOD__,
+                CacheItemPoolInterface::class,
+                get_debug_type($cacheItemPool)
+            ));
+        } else {
+            $this->cache         = DoctrineProvider::wrap($cacheItemPool);
+            $this->cacheItemPool = $cacheItemPool;
+        }
+
+        $this->name     = $name;
+        $this->lifetime = $lifetime;
     }
 
     /**
@@ -53,6 +103,8 @@ class DefaultRegion implements Region
     }
 
     /**
+     * @deprecated
+     *
      * @return CacheProvider
      */
     public function getCache()
@@ -65,7 +117,7 @@ class DefaultRegion implements Region
      */
     public function contains(CacheKey $key)
     {
-        return $this->cache->contains($this->getCacheEntryKey($key));
+        return $this->cacheItemPool->hasItem($this->getCacheEntryKey($key));
     }
 
     /**
@@ -73,7 +125,8 @@ class DefaultRegion implements Region
      */
     public function get(CacheKey $key)
     {
-        $entry = $this->cache->fetch($this->getCacheEntryKey($key));
+        $item  = $this->cacheItemPool->getItem($this->getCacheEntryKey($key));
+        $entry = $item->isHit() ? $item->get() : null;
 
         if (! $entry instanceof CacheEntry) {
             return null;
@@ -87,30 +140,33 @@ class DefaultRegion implements Region
      */
     public function getMultiple(CollectionCacheEntry $collection)
     {
+        $keys = array_map(
+            Closure::fromCallable([$this, 'getCacheEntryKey']),
+            $collection->identifiers
+        );
+        /** @var iterable<string, CacheItemInterface> $items */
+        $items = $this->cacheItemPool->getItems($keys);
+        if ($items instanceof Traversable) {
+            $items = iterator_to_array($items);
+        }
+
         $result = [];
-
-        foreach ($collection->identifiers as $key) {
-            $entryKey   = $this->getCacheEntryKey($key);
-            $entryValue = $this->cache->fetch($entryKey);
-
-            if (! $entryValue instanceof CacheEntry) {
+        foreach ($keys as $arrayKey => $cacheKey) {
+            if (! isset($items[$cacheKey]) || ! $items[$cacheKey]->isHit()) {
                 return null;
             }
 
-            $result[] = $entryValue;
+            $entry = $items[$cacheKey]->get();
+            if (! $entry instanceof CacheEntry) {
+                return null;
+            }
+
+            $result[$arrayKey] = $entry;
         }
 
         return $result;
     }
 
-    /**
-     * @return string
-     */
-    protected function getCacheEntryKey(CacheKey $key)
-    {
-        return $this->name . self::REGION_KEY_SEPARATOR . $key->hash;
-    }
-
     /**
      * {@inheritdoc}
      *
@@ -118,7 +174,15 @@ class DefaultRegion implements Region
      */
     public function put(CacheKey $key, CacheEntry $entry, ?Lock $lock = null)
     {
-        return $this->cache->save($this->getCacheEntryKey($key), $entry, $this->lifetime);
+        $item = $this->cacheItemPool
+            ->getItem($this->getCacheEntryKey($key))
+            ->set($entry);
+
+        if ($this->lifetime > 0) {
+            $item->expiresAfter($this->lifetime);
+        }
+
+        return $this->cacheItemPool->save($item);
     }
 
     /**
@@ -128,7 +192,7 @@ class DefaultRegion implements Region
      */
     public function evict(CacheKey $key)
     {
-        return $this->cache->delete($this->getCacheEntryKey($key));
+        return $this->cacheItemPool->deleteItem($this->getCacheEntryKey($key));
     }
 
     /**
@@ -138,13 +202,16 @@ class DefaultRegion implements Region
      */
     public function evictAll()
     {
-        if (! $this->cache instanceof ClearableCache) {
-            throw new BadMethodCallException(sprintf(
-                'Clearing all cache entries is not supported by the supplied cache adapter of type %s',
-                get_class($this->cache)
-            ));
-        }
+        return $this->cacheItemPool->clear(self::REGION_PREFIX . $this->name);
+    }
 
-        return $this->cache->deleteAll();
+    /**
+     * @internal since 2.11, this method will be private in 3.0.
+     *
+     * @return string
+     */
+    protected function getCacheEntryKey(CacheKey $key)
+    {
+        return self::REGION_PREFIX . $this->name . self::REGION_KEY_SEPARATOR . strtr($key->hash, '{}()/\@:', '________');
     }
 }

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

@@ -228,8 +228,6 @@ class FileLockRegion implements ConcurrentRegion
 
     /**
      * {@inheritdoc}
-     *
-     * @return bool
      */
     public function unlock(CacheKey $key, Lock $lock)
     {

lib/Doctrine/ORM/Cache/TimestampCacheEntry.php

@@ -12,14 +12,13 @@ use function microtime;
 class TimestampCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
      * @var float
      */
     public $time;
 
     /**
-     * @param float $time
+     * @param float|null $time
      */
     public function __construct($time = null)
     {

lib/Doctrine/ORM/Cache/TimestampRegion.php

@@ -10,9 +10,9 @@ namespace Doctrine\ORM\Cache;
 interface TimestampRegion extends Region
 {
     /**
-     * Update an specific key into the cache region.
+     * Update a specific key into the cache region.
      *
-     * @param CacheKey $key The key of the item to update the timestamp.
+     * @return void
      *
      * @throws LockException Indicates a problem accessing the region.
      */

lib/Doctrine/ORM/Configuration.php

@@ -12,6 +12,7 @@ use Doctrine\Common\Cache\ArrayCache;
 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;
@@ -23,8 +24,10 @@ use Doctrine\ORM\Cache\Exception\QueryCacheUsesNonPersistentCache;
 use Doctrine\ORM\Exception\InvalidEntityRepository;
 use Doctrine\ORM\Exception\NamedNativeQueryNotFound;
 use Doctrine\ORM\Exception\NamedQueryNotFound;
+use Doctrine\ORM\Exception\NotSupported;
 use Doctrine\ORM\Exception\ProxyClassesAlwaysRegenerating;
 use Doctrine\ORM\Exception\UnknownEntityNamespace;
+use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\Mapping\DefaultEntityListenerResolver;
 use Doctrine\ORM\Mapping\DefaultNamingStrategy;
@@ -33,16 +36,21 @@ use Doctrine\ORM\Mapping\Driver\AnnotationDriver;
 use Doctrine\ORM\Mapping\EntityListenerResolver;
 use Doctrine\ORM\Mapping\NamingStrategy;
 use Doctrine\ORM\Mapping\QuoteStrategy;
+use Doctrine\ORM\Proxy\ProxyFactory;
+use Doctrine\ORM\Query\AST\Functions\FunctionNode;
+use Doctrine\ORM\Query\Filter\SQLFilter;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\Repository\DefaultRepositoryFactory;
 use Doctrine\ORM\Repository\RepositoryFactory;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Persistence\ObjectRepository;
+use LogicException;
 use Psr\Cache\CacheItemPoolInterface;
-use ReflectionClass;
 
 use function class_exists;
+use function is_a;
 use function method_exists;
+use function sprintf;
 use function strtolower;
 use function trim;
 
@@ -51,6 +59,8 @@ use function trim;
  * It combines all configuration options from DBAL & ORM.
  *
  * Internal note: When adding a new configuration option just write a getter/setter pair.
+ *
+ * @psalm-import-type AutogenerateMode from ProxyFactory
  */
 class Configuration extends \Doctrine\DBAL\Configuration
 {
@@ -72,10 +82,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the directory where Doctrine generates any necessary proxy class files.
      *
-     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
-     *
-     * @see https://github.com/Ocramius/ProxyManager
-     *
      * @return string|null
      */
     public function getProxyDir()
@@ -86,11 +92,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the strategy for automatically generating proxy classes.
      *
-     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
-     *
-     * @see https://github.com/Ocramius/ProxyManager
-     *
      * @return int Possible values are constants of Doctrine\Common\Proxy\AbstractProxyFactory.
+     * @psalm-return AutogenerateMode
      */
     public function getAutoGenerateProxyClasses()
     {
@@ -101,6 +104,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Sets the strategy for automatically generating proxy classes.
      *
      * @param bool|int $autoGenerate Possible values are constants of Doctrine\Common\Proxy\AbstractProxyFactory.
+     * @psalm-param bool|AutogenerateMode $autoGenerate
      * True is converted to AUTOGENERATE_ALWAYS, false to AUTOGENERATE_NEVER.
      *
      * @return void
@@ -113,10 +117,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the namespace where proxy classes reside.
      *
-     * @deprecated 2.7 We're switch to `ocramius/proxy-manager` and this method isn't applicable any longer
-     *
-     * @see https://github.com/Ocramius/ProxyManager
-     *
      * @return string|null
      */
     public function getProxyNamespace()
@@ -153,6 +153,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Adds a new default annotation driver with a correctly configured annotation reader. If $useSimpleAnnotationReader
      * is true, the notation `@Entity` will work, otherwise, the notation `@ORM\Entity` will be supported.
      *
+     * @deprecated Use {@see ORMSetup::createDefaultAnnotationDriver()} instead.
+     *
      * @param string|string[] $paths
      * @param bool            $useSimpleAnnotationReader
      * @psalm-param string|list<string> $paths
@@ -161,6 +163,22 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function newDefaultAnnotationDriver($paths = [], $useSimpleAnnotationReader = true)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9443',
+            '%s is deprecated, call %s::createDefaultAnnotationDriver() instead.',
+            __METHOD__,
+            ORMSetup::class
+        );
+
+        if (! class_exists(AnnotationReader::class)) {
+            throw new LogicException(sprintf(
+                '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) {
@@ -182,6 +200,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
     }
 
     /**
+     * @deprecated No replacement planned.
+     *
      * Adds a namespace under a certain alias.
      *
      * @param string $alias
@@ -191,6 +211,21 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function addEntityNamespace($alias, $namespace)
     {
+        if (class_exists(PersistentObject::class)) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/issues/8818',
+                'Short namespace aliases such as "%s" are deprecated and will be removed in Doctrine ORM 3.0.',
+                $alias
+            );
+        } else {
+            NotSupported::createForPersistence3(sprintf(
+                'Using short namespace alias "%s" by calling %s',
+                $alias,
+                __METHOD__
+            ));
+        }
+
         $this->_attributes['entityNamespaces'][$alias] = $namespace;
     }
 
@@ -256,7 +291,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function getResultCache(): ?CacheItemPoolInterface
     {
-        // Compatibility with DBAL < 3.2
+        // Compatibility with DBAL 2
         if (! method_exists(parent::class, 'getResultCache')) {
             $cacheImpl = $this->getResultCacheImpl();
 
@@ -271,7 +306,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function setResultCache(CacheItemPoolInterface $cache): void
     {
-        // Compatibility with DBAL < 3.2
+        // Compatibility with DBAL 2
         if (! method_exists(parent::class, 'setResultCache')) {
             $this->setResultCacheImpl(DoctrineProvider::wrap($cache));
 
@@ -510,6 +545,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Ensures that this Configuration instance contains settings that are
      * suitable for a production environment.
      *
+     * @deprecated
+     *
      * @return void
      *
      * @throws ProxyClassesAlwaysRegenerating
@@ -518,6 +555,13 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function ensureProductionSettings()
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/pull/9074',
+            '%s is deprecated',
+            __METHOD__
+        );
+
         $queryCacheImpl = $this->getQueryCacheImpl();
 
         if (! $queryCacheImpl) {
@@ -528,7 +572,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
             throw QueryCacheUsesNonPersistentCache::fromDriver($queryCacheImpl);
         }
 
-        if ($this->getAutoGenerateProxyClasses()) {
+        if ($this->getAutoGenerateProxyClasses() !== AbstractProxyFactory::AUTOGENERATE_NEVER) {
             throw ProxyClassesAlwaysRegenerating::create();
         }
 
@@ -550,8 +594,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * DQL function names are case-insensitive.
      *
-     * @param string          $name      Function name.
-     * @param string|callable $className Class name or a callable that returns the function.
+     * @param string                $name      Function name.
+     * @param class-string|callable $className Class name or a callable that returns the function.
+     * @psalm-param class-string<FunctionNode>|callable(string):FunctionNode $className
      *
      * @return void
      */
@@ -565,8 +610,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name
      *
-     * @return string|null
-     * @psalm-return ?class-string
+     * @return string|callable|null
+     * @psalm-return class-string<FunctionNode>|callable(string):FunctionNode|null
      */
     public function getCustomStringFunction($name)
     {
@@ -583,7 +628,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * Any previously added string functions are discarded.
      *
-     * @psalm-param array<string, class-string> $functions The map of custom
+     * @psalm-param array<string, class-string<FunctionNode>|callable(string):FunctionNode> $functions The map of custom
      *                                                     DQL string functions.
      *
      * @return void
@@ -602,8 +647,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * DQL function names are case-insensitive.
      *
-     * @param string          $name      Function name.
-     * @param string|callable $className Class name or a callable that returns the function.
+     * @param string                $name      Function name.
+     * @param class-string|callable $className Class name or a callable that returns the function.
+     * @psalm-param class-string<FunctionNode>|callable(string):FunctionNode $className
      *
      * @return void
      */
@@ -617,8 +663,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name
      *
-     * @return string|null
-     * @psalm-return ?class-string
+     * @return string|callable|null
+     * @psalm-return class-string|callable|null
      */
     public function getCustomNumericFunction($name)
     {
@@ -656,7 +702,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string          $name      Function name.
      * @param string|callable $className Class name or a callable that returns the function.
-     * @psalm-param class-string|callable $className
+     * @psalm-param class-string<FunctionNode>|callable(string):FunctionNode $className
      *
      * @return void
      */
@@ -670,8 +716,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name
      *
-     * @return string|null
-     * @psalm-return ?class-string $name
+     * @return string|callable|null
+     * @psalm-return class-string|callable|null $name
      */
     public function getCustomDatetimeFunction($name)
     {
@@ -689,7 +735,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Any previously added date/time functions are discarded.
      *
      * @param array $functions The map of custom DQL date/time functions.
-     * @psalm-param array<string, string> $functions
+     * @psalm-param array<string, class-string<FunctionNode>|callable(string):FunctionNode> $functions
      *
      * @return void
      */
@@ -703,7 +749,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Sets the custom hydrator modes in one pass.
      *
-     * @param array<string, class-string> $modes An array of ($modeName => $hydrator).
+     * @param array<string, class-string<AbstractHydrator>> $modes An array of ($modeName => $hydrator).
      *
      * @return void
      */
@@ -722,7 +768,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $modeName The hydration mode name.
      *
      * @return string|null The hydrator class name.
-     * @psalm-return ?class-string
+     * @psalm-return class-string<AbstractHydrator>|null
      */
     public function getCustomHydrationMode($modeName)
     {
@@ -734,7 +780,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $modeName The hydration mode name.
      * @param string $hydrator The hydrator class name.
-     * @psalm-param class-string $hydrator
+     * @psalm-param class-string<AbstractHydrator> $hydrator
      *
      * @return void
      */
@@ -774,6 +820,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name      The name of the filter.
      * @param string $className The class name of the filter.
+     * @psalm-param class-string<SQLFilter> $className
      *
      * @return void
      */
@@ -789,7 +836,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @return string|null The class name of the filter, or null if it is not
      *  defined.
-     * @psalm-return ?class-string
+     * @psalm-return class-string<SQLFilter>|null
      */
     public function getFilterClassName($name)
     {
@@ -800,6 +847,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Sets default repository class.
      *
      * @param string $className
+     * @psalm-param class-string<EntityRepository> $className
      *
      * @return void
      *
@@ -807,12 +855,20 @@ class Configuration extends \Doctrine\DBAL\Configuration
      */
     public function setDefaultRepositoryClassName($className)
     {
-        $reflectionClass = new ReflectionClass($className);
-
-        if (! $reflectionClass->implementsInterface(ObjectRepository::class)) {
+        if (! class_exists($className) || ! is_a($className, ObjectRepository::class, true)) {
             throw InvalidEntityRepository::fromClassName($className);
         }
 
+        if (! is_a($className, EntityRepository::class, true)) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9533',
+                'Configuring %s as default repository class is deprecated because it does not extend %s.',
+                $className,
+                EntityRepository::class
+            );
+        }
+
         $this->_attributes['defaultRepositoryClassName'] = $className;
     }
 
@@ -820,7 +876,7 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Get default repository class.
      *
      * @return string
-     * @psalm-return class-string
+     * @psalm-return class-string<EntityRepository>
      */
     public function getDefaultRepositoryClassName()
     {
@@ -1003,4 +1059,24 @@ class Configuration extends \Doctrine\DBAL\Configuration
     {
         $this->_attributes['defaultQueryHints'][$name] = $value;
     }
+
+    /**
+     * Gets a list of entity class names to be ignored by the SchemaTool
+     *
+     * @return list<class-string>
+     */
+    public function getSchemaIgnoreClasses(): array
+    {
+        return $this->_attributes['schemaIgnoreClasses'] ?? [];
+    }
+
+    /**
+     * Sets a list of entity class names to be ignored by the SchemaTool
+     *
+     * @param list<class-string> $schemaIgnoreClasses List of entity class names
+     */
+    public function setSchemaIgnoreClasses(array $schemaIgnoreClasses): void
+    {
+        $this->_attributes['schemaIgnoreClasses'] = $schemaIgnoreClasses;
+    }
 }

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -5,10 +5,11 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Decorator;
 
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\ORM\EntityRepository;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\ObjectManagerDecorator;
 
-use function get_class;
+use function get_debug_type;
 use function method_exists;
 use function sprintf;
 use function trigger_error;
@@ -17,12 +18,11 @@ use const E_USER_NOTICE;
 
 /**
  * Base class for EntityManager decorators
+ *
+ * @extends ObjectManagerDecorator<EntityManagerInterface>
  */
 abstract class EntityManagerDecorator extends ObjectManagerDecorator implements EntityManagerInterface
 {
-    /** @var EntityManagerInterface */
-    protected $wrapped;
-
     public function __construct(EntityManagerInterface $wrapped)
     {
         $this->wrapped = $wrapped;
@@ -44,6 +44,28 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
         return $this->wrapped->getExpressionBuilder();
     }
 
+    /**
+     * {@inheritdoc}
+     *
+     * @psalm-param class-string<T> $className
+     *
+     * @psalm-return EntityRepository<T>
+     *
+     * @template T of object
+     */
+    public function getRepository($className)
+    {
+        return $this->wrapped->getRepository($className);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getClassMetadata($className)
+    {
+        return $this->wrapped->getClassMetadata($className);
+    }
+
     /**
      * {@inheritdoc}
      */
@@ -67,7 +89,7 @@ abstract class EntityManagerDecorator extends ObjectManagerDecorator implements
     {
         if (! method_exists($this->wrapped, 'wrapInTransaction')) {
             trigger_error(
-                sprintf('Calling `transactional()` instead of `wrapInTransaction()` which is not implemented on %s', get_class($this->wrapped)),
+                sprintf('Calling `transactional()` instead of `wrapInTransaction()` which is not implemented on %s', get_debug_type($this->wrapped)),
                 E_USER_NOTICE
             );
 

lib/Doctrine/ORM/EntityManager.php

@@ -4,9 +4,11 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM;
 
+use BackedEnum;
 use BadMethodCallException;
 use Doctrine\Common\Cache\Psr6\CacheAdapter;
 use Doctrine\Common\EventManager;
+use Doctrine\Common\Persistence\PersistentObject;
 use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DriverManager;
@@ -17,6 +19,8 @@ use Doctrine\ORM\Exception\InvalidHydrationMode;
 use Doctrine\ORM\Exception\MismatchedEventManager;
 use Doctrine\ORM\Exception\MissingIdentifierField;
 use Doctrine\ORM\Exception\MissingMappingDriverImplementation;
+use Doctrine\ORM\Exception\NotSupported;
+use Doctrine\ORM\Exception\ORMException;
 use Doctrine\ORM\Exception\UnrecognizedIdentifierFields;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
@@ -31,8 +35,8 @@ use InvalidArgumentException;
 use Throwable;
 
 use function array_keys;
-use function call_user_func;
-use function get_class;
+use function class_exists;
+use function get_debug_type;
 use function gettype;
 use function is_array;
 use function is_callable;
@@ -40,6 +44,7 @@ use function is_object;
 use function is_string;
 use function ltrim;
 use function sprintf;
+use function strpos;
 
 /**
  * The EntityManager is the central access point to ORM functionality.
@@ -59,14 +64,16 @@ use function sprintf;
  *     $entityManager = EntityManager::create($dbParams, $config);
  *
  * For more information see
- * {@link http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/configuration.html}
+ * {@link http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/configuration.html}
  *
  * You should never attempt to inherit from the EntityManager: Inheritance
  * is not a valid extension point for the EntityManager. Instead you
  * should take a look at the {@see \Doctrine\ORM\Decorator\EntityManagerDecorator}
  * and wrap your entity manager in a decorator.
+ *
+ * @final
  */
-/* final */class EntityManager implements EntityManagerInterface
+class EntityManager implements EntityManagerInterface
 {
     /**
      * The used Configuration.
@@ -120,7 +127,7 @@ use function sprintf;
     /**
      * The expression builder instance used to generate query expressions.
      *
-     * @var Expr
+     * @var Expr|null
      */
     private $expressionBuilder;
 
@@ -134,22 +141,30 @@ use function sprintf;
     /**
      * Collection of query filters.
      *
-     * @var FilterCollection
+     * @var FilterCollection|null
      */
     private $filterCollection;
 
-    /** @var Cache The second level cache regions API. */
+    /**
+     * The second level cache regions API.
+     *
+     * @var Cache|null
+     */
     private $cache;
 
     /**
      * Creates a new EntityManager that operates on the given database connection
      * and uses the given Configuration and EventManager implementations.
      */
-    protected function __construct(Connection $conn, Configuration $config, EventManager $eventManager)
+    public function __construct(Connection $conn, Configuration $config)
     {
+        if (! $config->getMetadataDriverImpl()) {
+            throw MissingMappingDriverImplementation::create();
+        }
+
         $this->conn         = $conn;
         $this->config       = $config;
-        $this->eventManager = $eventManager;
+        $this->eventManager = $conn->getEventManager();
 
         $metadataFactoryClassName = $config->getClassMetadataFactoryName();
 
@@ -232,7 +247,7 @@ use function sprintf;
         $this->conn->beginTransaction();
 
         try {
-            $return = call_user_func($func, $this);
+            $return = $func($this);
 
             $this->flush();
             $this->conn->commit();
@@ -399,6 +414,7 @@ use function sprintf;
      * @param int|null $lockVersion The version of the entity to find when using
      * optimistic locking.
      * @psalm-param class-string<T> $className
+     * @psalm-param LockMode::*|null $lockMode
      *
      * @return object|null The entity instance or NULL if the entity can not be found.
      * @psalm-return ?T
@@ -427,11 +443,14 @@ use function sprintf;
         }
 
         foreach ($id as $i => $value) {
-            if (is_object($value) && $this->metadataFactory->hasMetadataFor(ClassUtils::getClass($value))) {
-                $id[$i] = $this->unitOfWork->getSingleIdentifierValue($value);
+            if (is_object($value)) {
+                $className = ClassUtils::getClass($value);
+                if ($this->metadataFactory->hasMetadataFor($className)) {
+                    $id[$i] = $this->unitOfWork->getSingleIdentifierValue($value);
 
-                if ($id[$i] === null) {
-                    throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
+                    if ($id[$i] === null) {
+                        throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($className);
+                    }
                 }
             }
         }
@@ -443,7 +462,12 @@ use function sprintf;
                 throw MissingIdentifierField::fromFieldAndClass($identifier, $class->name);
             }
 
-            $sortedId[$identifier] = $id[$identifier];
+            if ($id[$identifier] instanceof BackedEnum) {
+                $sortedId[$identifier] = $id[$identifier]->value;
+            } else {
+                $sortedId[$identifier] = $id[$identifier];
+            }
+
             unset($id[$identifier]);
         }
 
@@ -773,11 +797,39 @@ use function sprintf;
      * @return ObjectRepository|EntityRepository The repository class.
      * @psalm-return EntityRepository<T>
      *
-     * @template T
+     * @template T of object
      */
     public function getRepository($entityName)
     {
-        return $this->repositoryFactory->getRepository($this, $entityName);
+        if (strpos($entityName, ':') !== false) {
+            if (class_exists(PersistentObject::class)) {
+                Deprecation::trigger(
+                    'doctrine/orm',
+                    'https://github.com/doctrine/orm/issues/8818',
+                    'Short namespace aliases such as "%s" are deprecated and will be removed in Doctrine ORM 3.0.',
+                    $entityName
+                );
+            } else {
+                NotSupported::createForPersistence3(sprintf(
+                    'Using short namespace alias "%s" when calling %s',
+                    $entityName,
+                    __METHOD__
+                ));
+            }
+        }
+
+        $repository = $this->repositoryFactory->getRepository($this, $entityName);
+        if (! $repository instanceof EntityRepository) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9533',
+                'Not returning an instance of %s from %s::getRepository() is deprecated and will cause a TypeError on 3.0.',
+                EntityRepository::class,
+                get_debug_type($this->repositoryFactory)
+            );
+        }
+
+        return $repository;
     }
 
     /**
@@ -912,13 +964,9 @@ use function sprintf;
      */
     public static function create($connection, Configuration $config, ?EventManager $eventManager = null)
     {
-        if (! $config->getMetadataDriverImpl()) {
-            throw MissingMappingDriverImplementation::create();
-        }
-
         $connection = static::createConnection($connection, $config, $eventManager);
 
-        return new EntityManager($connection, $config, $connection->getEventManager());
+        return new EntityManager($connection, $config);
     }
 
     /**
@@ -944,7 +992,7 @@ use function sprintf;
             throw new InvalidArgumentException(
                 sprintf(
                     'Invalid $connection argument of type %s given%s.',
-                    is_object($connection) ? get_class($connection) : gettype($connection),
+                    get_debug_type($connection),
                     is_object($connection) ? '' : ': "' . $connection . '"'
                 )
             );
@@ -986,6 +1034,8 @@ use function sprintf;
     }
 
     /**
+     * @psalm-param LockMode::* $lockMode
+     *
      * @throws OptimisticLockException
      * @throws TransactionRequiredException
      */

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -8,6 +8,8 @@ use BadMethodCallException;
 use DateTimeInterface;
 use Doctrine\Common\EventManager;
 use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\LockMode;
+use Doctrine\ORM\Exception\ORMException;
 use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
 use Doctrine\ORM\Proxy\ProxyFactory;
 use Doctrine\ORM\Query\Expr;
@@ -30,7 +32,7 @@ interface EntityManagerInterface extends ObjectManager
      *
      * @psalm-return EntityRepository<T>
      *
-     * @template T
+     * @template T of object
      */
     public function getRepository($className);
 
@@ -237,6 +239,7 @@ interface EntityManagerInterface extends ObjectManager
      * @param object                     $entity
      * @param int                        $lockMode
      * @param int|DateTimeInterface|null $lockVersion
+     * @psalm-param LockMode::* $lockMode
      *
      * @return void
      *
@@ -282,6 +285,7 @@ interface EntityManagerInterface extends ObjectManager
      * @deprecated
      *
      * @param string|int $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return AbstractHydrator
      */
@@ -291,6 +295,7 @@ interface EntityManagerInterface extends ObjectManager
      * Create a new instance for the given hydration mode.
      *
      * @param string|int $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return AbstractHydrator
      *

lib/Doctrine/ORM/EntityNotFoundException.php

@@ -37,8 +37,6 @@ class EntityNotFoundException extends ORMException
 
     /**
      * Instance for which no identifier can be found
-     *
-     * @psalm-param class-string $className
      */
     public static function noIdentifierFound(string $className): self
     {

lib/Doctrine/ORM/EntityRepository.php

@@ -5,22 +5,25 @@ declare(strict_types=1);
 namespace Doctrine\ORM;
 
 use BadMethodCallException;
-use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Collections\AbstractLazyCollection;
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Collections\Selectable;
+use Doctrine\Common\Persistence\PersistentObject;
+use Doctrine\DBAL\LockMode;
 use Doctrine\Deprecations\Deprecation;
 use Doctrine\Inflector\Inflector;
 use Doctrine\Inflector\InflectorFactory;
+use Doctrine\ORM\Exception\NotSupported;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Query\ResultSetMappingBuilder;
 use Doctrine\ORM\Repository\Exception\InvalidMagicMethodCall;
-use Doctrine\ORM\Repository\InvalidFindByCall;
 use Doctrine\Persistence\ObjectRepository;
 
 use function array_slice;
+use function class_exists;
 use function lcfirst;
 use function sprintf;
-use function strpos;
+use function str_starts_with;
 use function substr;
 
 /**
@@ -30,28 +33,42 @@ use function substr;
  * This class is designed for inheritance and users can subclass this class to
  * write their own repositories with business-specific methods to locate entities.
  *
- * @template T
+ * @template T of object
  * @template-implements Selectable<int,T>
  * @template-implements ObjectRepository<T>
  */
 class EntityRepository implements ObjectRepository, Selectable
 {
-    /** @var string */
+    /**
+     * @internal This property will be private in 3.0, call {@see getEntityName()} instead.
+     *
+     * @var string
+     * @psalm-var class-string<T>
+     */
     protected $_entityName;
 
-    /** @var EntityManager */
+    /**
+     * @internal This property will be private in 3.0, call {@see getEntityManager()} instead.
+     *
+     * @var EntityManagerInterface
+     */
     protected $_em;
 
-    /** @var ClassMetadata */
+    /**
+     * @internal This property will be private in 3.0, call {@see getClassMetadata()} instead.
+     *
+     * @var ClassMetadata
+     * @psalm-var ClassMetadata<T>
+     */
     protected $_class;
 
-    /** @var Inflector */
+    /** @var Inflector|null */
     private static $inflector;
 
     /**
-     * Initializes a new <tt>EntityRepository</tt>.
+     * @psalm-param ClassMetadata<T> $class
      */
-    public function __construct(EntityManagerInterface $em, Mapping\ClassMetadata $class)
+    public function __construct(EntityManagerInterface $em, ClassMetadata $class)
     {
         $this->_entityName = $class->name;
         $this->_em         = $em;
@@ -61,8 +78,8 @@ class EntityRepository implements ObjectRepository, Selectable
     /**
      * Creates a new QueryBuilder instance that is prepopulated for this entity name.
      *
-     * @param string $alias
-     * @param string $indexBy The index for the from.
+     * @param string      $alias
+     * @param string|null $indexBy The index for the from.
      *
      * @return QueryBuilder
      */
@@ -154,6 +171,13 @@ class EntityRepository implements ObjectRepository, Selectable
             __METHOD__
         );
 
+        if (! class_exists(PersistentObject::class)) {
+            throw NotSupported::createForPersistence3(sprintf(
+                'Partial clearing of entities for class %s',
+                $this->_class->rootEntityName
+            ));
+        }
+
         $this->_em->clear($this->_class->rootEntityName);
     }
 
@@ -165,6 +189,7 @@ class EntityRepository implements ObjectRepository, Selectable
      *                              or NULL if no specific lock mode should be used
      *                              during the search.
      * @param int|null $lockVersion The lock version.
+     * @psalm-param LockMode::*|null $lockMode
      *
      * @return object|null The entity instance or NULL if the entity can not be found.
      * @psalm-return ?T
@@ -245,15 +270,15 @@ class EntityRepository implements ObjectRepository, Selectable
      */
     public function __call($method, $arguments)
     {
-        if (strpos($method, 'findBy') === 0) {
+        if (str_starts_with($method, 'findBy')) {
             return $this->resolveMagicCall('findBy', substr($method, 6), $arguments);
         }
 
-        if (strpos($method, 'findOneBy') === 0) {
+        if (str_starts_with($method, 'findOneBy')) {
             return $this->resolveMagicCall('findOneBy', substr($method, 9), $arguments);
         }
 
-        if (strpos($method, 'countBy') === 0) {
+        if (str_starts_with($method, 'countBy')) {
             return $this->resolveMagicCall('count', substr($method, 7), $arguments);
         }
 
@@ -266,6 +291,7 @@ class EntityRepository implements ObjectRepository, Selectable
 
     /**
      * @return string
+     * @psalm-return class-string<T>
      */
     protected function getEntityName()
     {
@@ -273,7 +299,7 @@ class EntityRepository implements ObjectRepository, Selectable
     }
 
     /**
-     * @return string
+     * {@inheritdoc}
      */
     public function getClassName()
     {
@@ -281,7 +307,7 @@ class EntityRepository implements ObjectRepository, Selectable
     }
 
     /**
-     * @return EntityManager
+     * @return EntityManagerInterface
      */
     protected function getEntityManager()
     {
@@ -289,7 +315,8 @@ class EntityRepository implements ObjectRepository, Selectable
     }
 
     /**
-     * @return Mapping\ClassMetadata
+     * @return ClassMetadata
+     * @psalm-return ClassMetadata<T>
      */
     protected function getClassMetadata()
     {
@@ -300,8 +327,8 @@ class EntityRepository implements ObjectRepository, Selectable
      * Select all elements from a selectable that match the expression and
      * return a new collection containing these elements.
      *
-     * @return LazyCriteriaCollection
-     * @psalm-return Collection<int, T>
+     * @return AbstractLazyCollection
+     * @psalm-return AbstractLazyCollection<int, T>&Selectable<int, T>
      */
     public function matching(Criteria $criteria)
     {

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -4,34 +4,71 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\ORM\EntityManager;
+use Doctrine\Deprecations\Deprecation;
+use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
 
 /**
  * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions
  * of entities.
  *
- * @link   www.doctrine-project.org
+ * @deprecated This class will be removed in ORM 3.0. Use "\Doctrine\Persistence\Event\LifecycleEventArgs" instead.
+ *
+ * @extends BaseLifecycleEventArgs<EntityManagerInterface>
  */
 class LifecycleEventArgs extends BaseLifecycleEventArgs
 {
+    /**
+     * @param object $object
+     */
+    public function __construct($object, EntityManagerInterface $objectManager)
+    {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'The %s class is deprecated and will be removed in ORM 3.0. Use %s instead.',
+            self::class,
+            BaseLifecycleEventArgs::class
+        );
+
+        parent::__construct($object, $objectManager);
+    }
+
     /**
      * Retrieves associated Entity.
      *
+     * @deprecated 2.13. Use {@see getObject} instead.
+     *
      * @return object
      */
     public function getEntity()
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
         return $this->getObject();
     }
 
     /**
      * Retrieves associated EntityManager.
      *
-     * @return EntityManager
+     * @deprecated 2.13. Use {@see getObjectManager} instead.
+     *
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
         return $this->getObjectManager();
     }
 }

lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php

@@ -4,22 +4,21 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\ORM\EntityManager;
+use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\Persistence\Event\LoadClassMetadataEventArgs as BaseLoadClassMetadataEventArgs;
 
 /**
  * Class that holds event arguments for a loadMetadata event.
  *
- * @method __construct(ClassMetadata $classMetadata, EntityManager $objectManager)
- * @method ClassMetadata getClassMetadata()
+ * @extends BaseLoadClassMetadataEventArgs<ClassMetadata<object>, EntityManagerInterface>
  */
 class LoadClassMetadataEventArgs extends BaseLoadClassMetadataEventArgs
 {
     /**
      * Retrieve associated EntityManager.
      *
-     * @return EntityManager
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {

lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php

@@ -4,15 +4,21 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
+use Doctrine\Deprecations\Deprecation;
+use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\Persistence\Event\ManagerEventArgs;
 use Doctrine\Persistence\Mapping\ClassMetadata;
 use Doctrine\Persistence\ObjectManager;
 
+use function func_num_args;
+
 /**
  * Class that holds event arguments for a `onClassMetadataNotFound` event.
  *
  * This object is mutable by design, allowing callbacks having access to it to set the
  * found metadata in it, and therefore "cancelling" a `onClassMetadataNotFound` event
+ *
+ * @extends ManagerEventArgs<EntityManagerInterface>
  */
 class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
 {
@@ -23,7 +29,8 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
     private $foundMetadata;
 
     /**
-     * @param string $className
+     * @param string                 $className
+     * @param EntityManagerInterface $objectManager
      */
     public function __construct($className, ObjectManager $objectManager)
     {
@@ -37,6 +44,15 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
      */
     public function setFoundMetadata(?ClassMetadata $classMetadata = null)
     {
+        if (func_num_args() < 1) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9791',
+                'Calling %s without arguments is deprecated, pass null instead.',
+                __METHOD__
+            );
+        }
+
         $this->foundMetadata = $classMetadata;
     }
 

lib/Doctrine/ORM/Event/OnClearEventArgs.php

@@ -4,19 +4,19 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\EventArgs;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\Event\OnClearEventArgs as BaseOnClearEventArgs;
 
 /**
  * Provides event arguments for the onClear event.
  *
  * @link        www.doctrine-project.org
+ *
+ * @extends BaseOnClearEventArgs<EntityManagerInterface>
  */
-class OnClearEventArgs extends EventArgs
+class OnClearEventArgs extends BaseOnClearEventArgs
 {
-    /** @var EntityManagerInterface */
-    private $em;
-
     /** @var string|null */
     private $entityClass;
 
@@ -25,23 +25,35 @@ class OnClearEventArgs extends EventArgs
      */
     public function __construct(EntityManagerInterface $em, $entityClass = null)
     {
-        $this->em          = $em;
+        parent::__construct($em);
+
         $this->entityClass = $entityClass;
     }
 
     /**
      * Retrieves associated EntityManager.
      *
+     * @deprecated 2.13. Use {@see getObjectManager} instead.
+     *
      * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
-        return $this->em;
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
+        return $this->getObjectManager();
     }
 
     /**
      * Name of the entity class that is cleared, or empty if all are cleared.
      *
+     * @deprecated Clearing the entity manager partially is deprecated. This method will be removed in 3.0.
+     *
      * @return string|null
      */
     public function getEntityClass()
@@ -52,6 +64,8 @@ class OnClearEventArgs extends EventArgs
     /**
      * Checks if event clears all entities.
      *
+     * @deprecated Clearing the entity manager partially is deprecated. This method will be removed in 3.0.
+     *
      * @return bool
      */
     public function clearsAllEntities()

lib/Doctrine/ORM/Event/OnFlushEventArgs.php

@@ -4,31 +4,35 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\EventArgs;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 
 /**
  * Provides event arguments for the preFlush event.
  *
  * @link        www.doctrine-project.org
+ *
+ * @extends ManagerEventArgs<EntityManagerInterface>
  */
-class OnFlushEventArgs extends EventArgs
+class OnFlushEventArgs extends ManagerEventArgs
 {
-    /** @var EntityManagerInterface */
-    private $em;
-
-    public function __construct(EntityManagerInterface $em)
-    {
-        $this->em = $em;
-    }
-
     /**
      * Retrieve associated EntityManager.
      *
+     * @deprecated 2.13. Use {@see getObjectManager} instead.
+     *
      * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
-        return $this->em;
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
+        return $this->getObjectManager();
     }
 }

lib/Doctrine/ORM/Event/PostFlushEventArgs.php

@@ -4,32 +4,35 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\EventArgs;
-use Doctrine\ORM\EntityManager;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 
 /**
  * Provides event arguments for the postFlush event.
  *
  * @link        www.doctrine-project.org
+ *
+ * @extends ManagerEventArgs<EntityManagerInterface>
  */
-class PostFlushEventArgs extends EventArgs
+class PostFlushEventArgs extends ManagerEventArgs
 {
-    /** @var EntityManager */
-    private $em;
-
-    public function __construct(EntityManagerInterface $em)
-    {
-        $this->em = $em;
-    }
-
     /**
      * Retrieves associated EntityManager.
      *
-     * @return EntityManager
+     * @deprecated 2.13. Use {@see getObjectManager} instead.
+     *
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
-        return $this->em;
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
+        return $this->getObjectManager();
     }
 }

lib/Doctrine/ORM/Event/PreFlushEventArgs.php

@@ -4,30 +4,33 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Event;
 
-use Doctrine\Common\EventArgs;
-use Doctrine\ORM\EntityManager;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
+use Doctrine\Persistence\Event\ManagerEventArgs;
 
 /**
  * Provides event arguments for the preFlush event.
  *
  * @link        www.doctrine-project.com
+ *
+ * @extends ManagerEventArgs<EntityManagerInterface>
  */
-class PreFlushEventArgs extends EventArgs
+class PreFlushEventArgs extends ManagerEventArgs
 {
-    /** @var EntityManager */
-    private $em;
-
-    public function __construct(EntityManagerInterface $em)
-    {
-        $this->em = $em;
-    }
-
     /**
-     * @return EntityManager
+     * @deprecated 2.13. Use {@see getObjectManager} instead.
+     *
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
-        return $this->em;
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/9875',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getObjectManager() instead.',
+            __METHOD__
+        );
+
+        return $this->getObjectManager();
     }
 }

lib/Doctrine/ORM/Event/PreUpdateEventArgs.php

@@ -8,7 +8,7 @@ use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\PersistentCollection;
 use InvalidArgumentException;
 
-use function get_class;
+use function get_debug_type;
 use function sprintf;
 
 /**
@@ -108,7 +108,7 @@ class PreUpdateEventArgs extends LifecycleEventArgs
             throw new InvalidArgumentException(sprintf(
                 'Field "%s" is not a valid field of the entity "%s" in PreUpdateEventArgs.',
                 $field,
-                get_class($this->getEntity())
+                get_debug_type($this->getObject())
             ));
         }
     }

lib/Doctrine/ORM/Exception/EntityManagerClosed.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Exception;
 
-use RuntimeException;
-
 final class EntityManagerClosed extends ORMException implements ManagerException
 {
     public static function create(): self

lib/Doctrine/ORM/Exception/EntityMissingAssignedId.php

@@ -4,7 +4,7 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Exception;
 
-use function get_class;
+use function get_debug_type;
 
 final class EntityMissingAssignedId extends ORMException
 {
@@ -13,7 +13,7 @@ final class EntityMissingAssignedId extends ORMException
      */
     public static function forField($entity, string $field): self
     {
-        return new self('Entity of type ' . get_class($entity) . " is missing an assigned ID for field  '" . $field . "'. " .
+        return new self('Entity of type ' . get_debug_type($entity) . " is missing an assigned ID for field  '" . $field . "'. " .
             'The identifier generation strategy for this entity requires the ID field to be populated before ' .
             'EntityManager#persist() is called. If you want automatically generated identifiers instead ' .
             'you need to adjust the metadata mapping accordingly.');