Merge pull request #8916 from greg0ire/failing-test-8914

Check current class' discriminator map

.doctrine-project.json

@@ -12,21 +12,27 @@
             "upcoming": true
         },
         {
-            "name": "2.9",
-            "branchName": "2.9.x",
-            "slug": "2.9",
+            "name": "2.10",
+            "branchName": "2.10.x",
+            "slug": "2.10",
             "upcoming": true
         },
         {
-            "name": "2.8",
-            "branchName": "2.8.x",
-            "slug": "2.8",
+            "name": "2.9",
+            "branchName": "2.9.x",
+            "slug": "2.9",
             "current": true,
             "aliases": [
                 "current",
                 "stable"
             ]
         },
+        {
+            "name": "2.8",
+            "branchName": "2.8.x",
+            "slug": "2.8",
+            "maintained": false
+        },
         {
             "name": "2.7",
             "branchName": "2.7",

.gitattributes

@@ -2,10 +2,9 @@
 /tools export-ignore
 /docs export-ignore
 /.github export-ignore
+.doctrine-project.json export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
-.gitmodules export-ignore
-.travis.yml export-ignore
 build.properties export-ignore
 build.properties.dev export-ignore
 build.xml export-ignore
@@ -15,4 +14,6 @@ run-all.sh export-ignore
 phpcs.xml.dist export-ignore
 phpbench.json export-ignore
 phpstan.neon export-ignore
+phpstan-baseline.neon export-ignore
 psalm.xml export-ignore
+psalm-baseline.xml export-ignore

.github/ISSUE_TEMPLATE/BC_Break.md

@@ -0,0 +1,37 @@
+---
+name: 💥 BC Break
+about: Have you encountered an issue during upgrade? 💣
+---
+
+<!--
+Before reporting a BC break, please consult the upgrading document to make sure it's not an expected change: https://github.com/doctrine/orm/blob/2.9.x/UPGRADE.md
+-->
+
+### BC Break Report
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| BC Break    | yes
+| Version     | x.y.z
+
+#### Summary
+
+<!-- Provide a summary describing the problem you are experiencing. -->
+
+#### Previous behavior
+
+<!-- What was the previous (working) behavior? -->
+
+#### Current behavior
+
+<!-- What is the current (broken) behavior? -->
+
+#### How to reproduce
+
+<!--
+Provide steps to reproduce the BC break.
+If possible, also add a code snippet with relevant configuration, entity mappings, DQL etc.
+Adding a failing Unit or Functional Test would help us a lot - you can submit it in a Pull Request separately, referencing this bug report.
+-->

.github/ISSUE_TEMPLATE/Bug.md

@@ -0,0 +1,34 @@
+---
+name: 🐞 Bug Report
+about: Something is broken? 🔨
+---
+
+### Bug Report
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| BC Break    | yes/no
+| Version     | x.y.z
+
+#### Summary
+
+<!-- Provide a summary describing the problem you are experiencing. -->
+
+#### Current behavior
+
+<!-- What is the current (buggy) behavior? -->
+
+#### How to reproduce
+
+<!--
+Provide steps to reproduce the bug.
+If possible, also add a code snippet with relevant configuration, entity mappings, DQL etc.
+Adding a failing Unit or Functional Test would help us a lot - you can submit one in a Pull Request separately, referencing this bug report.
+-->
+
+#### Expected behavior
+
+<!-- What was the expected (correct) behavior? -->
+

.github/ISSUE_TEMPLATE/Feature_Request.md

@@ -0,0 +1,18 @@
+---
+name: 🎉 Feature Request
+about: You have a neat idea that should be implemented? 🎩
+---
+
+### Feature Request
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| New Feature | yes
+| RFC         | yes/no
+| BC Break    | yes/no
+
+#### Summary
+
+<!-- Provide a summary of the feature you would like to see implemented. -->

.github/ISSUE_TEMPLATE/Support_Question.md

@@ -0,0 +1,6 @@
+---
+name: ❓ Support Question
+about: Have a problem that you can't figure out? 🤔
+---
+
+Please use https://github.com/doctrine/orm/discussions instead.

.github/PULL_REQUEST_TEMPLATE/Failing_Test.md

@@ -0,0 +1,19 @@
+---
+name: 🐞 Failing Test
+about: You found a bug and have a failing Unit or Functional test? 🔨
+---
+
+### Failing Test
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| BC Break    | yes/no
+| Version     | x.y.z
+
+
+#### Summary
+
+<!-- Provide a summary of the failing scenario. -->
+

.github/PULL_REQUEST_TEMPLATE/Improvement.md

@@ -0,0 +1,18 @@
+---
+name: ⚙ Improvement
+about: You have some improvement to make Doctrine better? 🎁
+---
+
+### Improvement
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| New Feature | yes
+| RFC         | yes/no
+| BC Break    | yes/no
+
+#### Summary
+
+<!-- Provide a summary of the improvement you are submitting. -->

.github/PULL_REQUEST_TEMPLATE/New_Feature.md

@@ -0,0 +1,26 @@
+---
+name: 🎉 New Feature
+about: You have implemented some neat idea that you want to make part of Doctrine? 🎩
+---
+
+<!--
+Thank you for submitting new feature!
+Pick the target branch based according to these criteria:
+  * submitting a bugfix: target the lowest active stable branch: 2.9.x
+  * submitting a new feature: target the next minor branch: 2.10.x
+  * submitting a BC-breaking change: target the next major branch: 3.0.x
+-->
+
+### New Feature
+
+<!-- Fill in the relevant information below to help triage your issue. -->
+
+|    Q        |   A
+|------------ | ------
+| New Feature | yes
+| RFC         | yes/no
+| BC Break    | yes/no
+
+#### Summary
+
+<!-- Provide a summary of the feature you have implemented. -->

.github/workflows/continuous-integration.yml

@@ -19,11 +19,6 @@ jobs:
           - "7.3"
           - "7.4"
           - "8.0"
-        deps:
-          - "highest"
-        include:
-          - deps: "lowest"
-            php-version: "7.3"
 
     steps:
       - name: "Checkout"
@@ -41,8 +36,6 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
-        with:
-          dependency-versions: "${{ matrix.deps }}"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --coverage-clover=coverage-no-cache.xml"
@@ -57,7 +50,7 @@ jobs:
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v2"
         with:
-          name: "phpunit-sqlite-${{ matrix.deps }}-${{ matrix.php-version }}-coverage"
+          name: "phpunit-sqlite-${{ matrix.php-version }}-coverage"
           path: "coverage*.xml"
 
 
@@ -228,6 +221,38 @@ jobs:
           name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-coverage"
           path: "coverage*.xml"
 
+  phpunit-lower-php-versions:
+    name: "PHPUnit with SQLite"
+    runs-on: "ubuntu-20.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.1"
+        deps:
+          - "highest"
+          - "lowest"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          ini-values: "zend.assertions=1"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v1"
+        with:
+          dependency-versions: "${{ matrix.deps }}"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml"
+
   upload_coverage:
     name: "Upload coverage to Codecov"
     runs-on: "ubuntu-20.04"

.github/workflows/phpbench.yml

@@ -0,0 +1,49 @@
+
+name: "Performance benchmark"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+  push:
+    branches:
+      - "*.x"
+
+env:
+  fail-fast: true
+
+jobs:
+  phpbench:
+    name: "PHPBench"
+    runs-on: "ubuntu-20.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.4"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v2"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          coverage: "pcov"
+          ini-values: "zend.assertions=1"
+
+      - name: "Cache dependencies installed with composer"
+        uses: "actions/cache@v2"
+        with:
+          path: "~/.composer/cache"
+          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
+          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
+
+      - name: "Install dependencies with composer"
+        run: "composer update --no-interaction --no-progress"
+
+      - name: "Run PHPBench"
+        run: "vendor/bin/phpbench run --report=default"

.github/workflows/static-analysis.yml

@@ -1,17 +1,23 @@
-name: Static Analysis
+
+name: "Static Analysis"
 
 on:
   pull_request:
+    branches:
+      - "*.x"
+  push:
+    branches:
+      - "*.x"
 
 jobs:
   static-analysis-phpstan:
-    name: "PHPStan"
-    runs-on: "ubuntu-latest"
+    name: "Static Analysis with PHPStan"
+    runs-on: "ubuntu-20.04"
 
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.0"
 
     steps:
       - name: "Checkout code"
@@ -22,22 +28,23 @@ jobs:
         with:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
-          tools: cs2pr
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          dependency-versions: "highest"
 
       - name: "Run a static analysis with phpstan/phpstan"
-        run: "php vendor/bin/phpstan analyse --error-format=checkstyle | cs2pr"
+        run: "vendor/bin/phpstan analyse"
 
   static-analysis-psalm:
-    name: "Psalm"
-    runs-on: "ubuntu-latest"
+    name: "Static Analysis with Psalm"
+    runs-on: "ubuntu-20.04"
 
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.0"
 
     steps:
       - name: "Checkout code"
@@ -51,6 +58,8 @@ jobs:
 
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
+        with:
+          dependency-versions: "highest"
 
       - name: "Run a static analysis with vimeo/psalm"
         run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc)"

.gitignore

@@ -16,3 +16,4 @@ vendor/
 /.phpcs-cache
 composer.lock
 /.phpunit.result.cache
+/*.phpunit.xml

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2006-2015 Doctrine Project
+Copyright (c) Doctrine Project
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

README.md

@@ -1,7 +1,7 @@
-| [3.0.x][3.0] | [2.9.x][2.9] | [2.8.x][2.8] |
+| [3.0.x][3.0] | [2.10.x][2.10] | [2.9.x][2.9] |
 |:----------------:|:----------------:|:----------:|
-| [![Build status][3.0 image]][3.0] | [![Build status][2.9 image]][2.9] | [![Build status][2.8 image]][2.8] |
-| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.9 coverage image]][2.9 coverage]  | [![Coverage Status][2.8 coverage image]][2.8 coverage] |
+| [![Build status][3.0 image]][3.0] | [![Build status][2.10 image]][2.10] | [![Build status][2.9 image]][2.9] |
+| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.10 coverage image]][2.10 coverage] | [![Coverage Status][2.9 coverage image]][2.9 coverage]  |
 
 Doctrine 2 is an object-relational mapper (ORM) 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
@@ -24,7 +24,7 @@ without requiring unnecessary code duplication.
   [2.9]: https://github.com/doctrine/orm/tree/2.9.x
   [2.9 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.9.x/graph/badge.svg
   [2.9 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.9.x
-  [2.8 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg
-  [2.8]: https://github.com/doctrine/orm/tree/2.8
-  [2.8 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.8.x/graph/badge.svg
-  [2.8 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.8.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

UPGRADE.md

@@ -1,3 +1,31 @@
+# Upgrade to 2.9
+
+## Minor BC BREAK: Setup tool needs cache implementation
+
+With the deprecation of doctrine/cache, the setup tool might no longer work as expected without a different cache
+implementation. To work around this:
+* Install symfony/cache: `composer require symfony/cache`. This will keep previous behaviour without any changes
+* Instantiate caches yourself: to use a different cache implementation, pass a cache instance when calling any
+  configuration factory in the setup tool:
+  ```diff
+  - $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode, $proxyDir);
+  + $cache = \Doctrine\Common\Cache\Psr6\DoctrineProvider::wrap($anyPsr6Implementation);
+  + $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode, $proxyDir, $cache);
+  ```
+* As a quick workaround, you can lock the doctrine/cache dependency to work around this: `composer require doctrine/cache ^1.11`.
+  Note that this is only recommended as a bandaid fix, as future versions of ORM will no longer work with doctrine/cache
+  1.11.
+  
+## Deprecated: doctrine/cache for metadata caching
+
+The `Doctrine\ORM\Configuration#setMetadataCacheImpl()` method is deprecated and should no longer be used. Please use
+`Doctrine\ORM\Configuration#setMetadataCache()` with any PSR-6 cache adapter instead.
+
+## Removed: flushing metadata cache
+
+To support PSR-6 caches, the `--flush` option for the `orm:clear-cache:metadata` command is ignored. Metadata cache is
+now always cleared regardless of the cache adapter being used.
+
 # Upgrade to 2.8
 
 ## Minor BC BREAK: Failed commit now throw OptimisticLockException

composer.json

@@ -16,29 +16,36 @@
         "sort-packages": true
     },
     "require": {
-        "php": "^7.2|^8.0",
+        "php": "^7.1 ||^8.0",
+        "ext-ctype": "*",
         "ext-pdo": "*",
         "composer/package-versions-deprecated": "^1.8",
-        "doctrine/annotations": "^1.11.1",
-        "doctrine/cache": "^1.9.1",
+        "doctrine/annotations": "^1.13",
+        "doctrine/cache": "^1.12.1 || ^2.1.1",
         "doctrine/collections": "^1.5",
         "doctrine/common": "^3.0.3",
-        "doctrine/dbal": "^2.10.0",
+        "doctrine/dbal": "^2.13.0",
+        "doctrine/deprecations": "^0.5.3",
         "doctrine/event-manager": "^1.1",
-        "doctrine/inflector": "^1.4|^2.0",
+        "doctrine/inflector": "^1.4 || ^2.0",
         "doctrine/instantiator": "^1.3",
         "doctrine/lexer": "^1.0",
-        "doctrine/persistence": "^2.0",
-        "symfony/console": "^3.0|^4.0|^5.0"
+        "doctrine/persistence": "^2.2",
+        "psr/cache": "^1 || ^2 || ^3",
+        "symfony/console": "^3.0 || ^4.0 || ^5.0 || ^6.0"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^8.0",
-        "phpstan/phpstan": "^0.12.18",
-        "phpunit/phpunit": "^8.5|^9.4",
-        "symfony/yaml": "^3.4|^4.0|^5.0",
-        "vimeo/psalm": "4.1.1"
+        "doctrine/coding-standard": "^9.0",
+        "phpbench/phpbench": "^0.16.10 || ^1.0",
+        "phpstan/phpstan": "0.12.94",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.4",
+        "squizlabs/php_codesniffer": "3.6.0",
+        "symfony/cache": "^4.4 || ^5.2",
+        "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
+        "vimeo/psalm": "4.7.0"
     },
     "suggest": {
+        "symfony/cache": "Provides cache support for Setup Tool with doctrine/cache 2.0",
         "symfony/yaml": "If you want to use YAML Metadata Mapping Driver"
     },
     "autoload": {
@@ -47,6 +54,7 @@
     "autoload-dev": {
         "psr-4": {
             "Doctrine\\Tests\\": "tests/Doctrine/Tests",
+            "Doctrine\\StaticAnalysis\\": "tests/Doctrine/StaticAnalysis",
             "Doctrine\\Performance\\": "tests/Doctrine/Performance"
         }
     },

docs/LICENSE.md

@@ -1,4 +1,4 @@
-The Doctrine ORM documentation is licensed under [CC BY-NC-SA 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_US)
+The Doctrine ORM documentation is licensed under [CC BY-NC-SA 3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/deed.en_US)
 
 Creative Commons Legal Code
 
@@ -359,5 +359,4 @@ Creative Commons Notice
     available upon request from time to time. For the avoidance of doubt,
     this trademark restriction does not form part of this License.
 
-    Creative Commons may be contacted at http://creativecommons.org/.
-   
+    Creative Commons may be contacted at https://creativecommons.org/.

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

@@ -193,7 +193,7 @@ object into a string representation before saving to the database (in the
 value from the database (in the ``convertToPHPValue`` method).
 
 The format of the string representation format is called
-`Well-known text (WKT) <http://en.wikipedia.org/wiki/Well-known_text>`_.
+`Well-known text (WKT) <https://en.wikipedia.org/wiki/Well-known_text>`_.
 The advantage of this format is, that it is both human readable and parsable by MySQL.
 
 Internally, MySQL stores geometry values in a binary format that is not 

docs/en/cookbook/decorator-pattern.rst

@@ -5,7 +5,7 @@ Persisting the Decorator Pattern
 
 This recipe will show you a simple example of how you can use
 Doctrine ORM to persist an implementation of the
-`Decorator Pattern <http://en.wikipedia.org/wiki/Decorator_pattern>`_
+`Decorator Pattern <https://en.wikipedia.org/wiki/Decorator_pattern>`_
 
 Component
 ---------

docs/en/cookbook/dql-custom-walkers.rst

@@ -14,7 +14,7 @@ In Doctrine 1 the DQL language was not implemented using a real
 parser. This made modifications of the DQL by the user impossible.
 Doctrine ORM in contrast has a real parser for the DQL language,
 which transforms the DQL statement into an
-`Abstract Syntax Tree <http://en.wikipedia.org/wiki/Abstract_syntax_tree>`_
+`Abstract Syntax Tree <https://en.wikipedia.org/wiki/Abstract_syntax_tree>`_
 and generates the appropriate SQL statement for it. Since this
 process is deterministic Doctrine heavily caches the SQL that is
 generated from any given DQL query, which reduces the performance

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

@@ -132,7 +132,7 @@ dql statement.
 
 The ``ArithmeticPrimary`` method call is the most common
 denominator of valid EBNF tokens taken from the
-`DQL EBNF grammar <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#ebnf>`_
+`DQL EBNF grammar <https://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#ebnf>`_
 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
@@ -246,6 +246,6 @@ vendor sql functions and extend the DQL languages scope.
 
 Code for this Extension to DQL and other Doctrine Extensions can be
 found
-`in the GitHub DoctrineExtensions repository <http://github.com/beberlei/DoctrineExtensions>`_.
+`in the GitHub DoctrineExtensions repository <https://github.com/beberlei/DoctrineExtensions>`_.
 
 

docs/en/cookbook/entities-in-session.rst

@@ -3,42 +3,69 @@ Entities in the Session
 
 There are several use-cases to save entities in the session, for example:
 
-1.  User object
+1.  User data
 2.  Multi-step forms
 
 To achieve this with Doctrine you have to pay attention to some details to get
 this working.
 
-Merging entity into an EntityManager
-------------------------------------
+Updating an entity
+------------------
 
 In Doctrine an entity objects has to be "managed" by an EntityManager to be
-updateable. Entities saved into the session are not managed in the next request
-anymore. This means that you have to register these entities with an
-EntityManager again if you want to change them or use them as part of
-references between other entities. You can achieve this by calling
-``EntityManager#merge()``.
+updatable. Entities saved into the session are not managed in the next request
+anymore. This means that you have to update the entities with the stored session
+data after you fetch the entities from the EntityManager again.
 
-For a representative User object the code to get turn an instance from
-the session into a managed Doctrine object looks like this:
+For a representative User object the code to get data from the session into a
+managed Doctrine object can look like these examples:
+
+Working with scalars
+~~~~~~~~~~~~~~~~~~~~
+
+In simpler applications there is no need to work with objects in sessions and you can use
+separate session elements.
 
 .. code-block:: php
 
     <?php
     require_once 'bootstrap.php';
-    $em = GetEntityManager(); // creates an EntityManager 
 
     session_start();
-    if (isset($_SESSION['user']) && $_SESSION['user'] instanceof User) {
-        $user = $_SESSION['user']; 
-        $user = $em->merge($user);
+    if (isset($_SESSION['userId']) && is_int($_SESSION['userId'])) {
+        $userId = $_SESSION['userId'];
+
+        $em = GetEntityManager(); // creates an EntityManager
+        $user = $em->find(User::class, $userId);
+
+        $user->setValue($_SESSION['storedValue']);
+
+        $em->flush();
     }
 
-.. note::
+Working with custom data transfer objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    A frequent mistake is not to get the merged user object from the return
-    value of ``EntityManager#merge()``. The entity object passed to merge is
-    not necessarily the same object that is returned from the method.
+If objects are needed, we discourage the storage of entity objects in the session. It's
+preferable to use a `DTO (data transfer object) <https://en.wikipedia.org/wiki/Data_transfer_object>`_
+instead and merge the DTO data later with the entity.
+
+.. code-block:: php
+
+    <?php
+    require_once 'bootstrap.php';
+
+    session_start();
+    if (isset($_SESSION['user']) && $_SESSION['user'] instanceof UserDto) {
+        $userDto = $_SESSION['user'];
+
+        $em = GetEntityManager(); // creates an EntityManager
+        $userEntity = $em->find(User::class, $userDto->getId());
+
+        $userEntity->populateFromDto($userDto);
+
+        $em->flush();
+    }
 
 Serializing entity into the session
 -----------------------------------
@@ -47,22 +74,20 @@ Entities that are serialized into the session normally contain references to
 other entities as well. Think of the user entity has a reference to their
 articles, groups, photos or many other different entities. If you serialize
 this object into the session then you don't want to serialize the related
-entities as well. This is why you should call ``EntityManager#detach()`` on this
-object or implement the __sleep() magic method on your entity.
+entities as well. This is why you shouldn't serialize an entity and use
+only the needed values of it. This can happen with the help of a DTO.
 
 .. code-block:: php
 
     <?php
     require_once 'bootstrap.php';
+
     $em = GetEntityManager(); // creates an EntityManager 
 
     $user = $em->find("User", 1);
-    $em->detach($user);
-    $_SESSION['user'] = $user;
+    $userDto = new UserDto($user->getId(), $user->getFirstName(), $user->getLastName());
+    // or "UserDto::createFrom($user);", but don't store an entity in a property. Only its values without relations.
 
-.. note::
+    $_SESSION['user'] = $userDto;
 
-    When you called detach on your objects they get "unmanaged" with that
-    entity manager. This means you cannot use them as part of write operations
-    during ``EntityManager#flush()`` anymore in this request.
 

docs/en/cookbook/implementing-arrayaccess-for-domain-objects.rst

@@ -6,7 +6,7 @@ Implementing ArrayAccess for Domain Objects
 This recipe will show you how to implement ArrayAccess for your
 domain objects in order to allow more uniform access, for example
 in templates. In these examples we will implement ArrayAccess on a
-`Layer Supertype <http://martinfowler.com/eaaCatalog/layerSupertype.html>`_
+`Layer Supertype <https://martinfowler.com/eaaCatalog/layerSupertype.html>`_
 for all our domain objects.
 
 Option 1

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

@@ -7,9 +7,14 @@ The NOTIFY change-tracking policy is the most effective
 change-tracking policy provided by Doctrine but it requires some
 boilerplate code. This recipe will show you how this boilerplate
 code should look like. We will implement it on a
-`Layer Supertype <http://martinfowler.com/eaaCatalog/layerSupertype.html>`_
+`Layer Supertype <https://martinfowler.com/eaaCatalog/layerSupertype.html>`_
 for all our domain objects.
 
+.. note::
+
+    The notify change tracking policy is deprecated and will be removed in ORM 3.0.
+    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+
 Implementing NotifyPropertyChanged
 ----------------------------------
 

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

@@ -4,7 +4,7 @@ Implementing Wakeup or Clone
 .. sectionauthor:: Roman Borschel (roman@code-factory.org)
 
 As explained in the
-`restrictions for entity classes in the manual <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/architecture.html#entities>`_,
+`restrictions for entity classes in the manual <https://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/architecture.html#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
@@ -23,7 +23,7 @@ implementation code in an identity check as follows:
     class MyEntity
     {
         private $id; // This is the identifier of the entity.
-        //...
+        // ...
     
         public function __wakeup()
         {
@@ -34,7 +34,7 @@ implementation code in an identity check as follows:
             // otherwise do nothing, do NOT throw an exception!
         }
     
-        //...
+        // ...
     }
 
 Safely implementing __clone
@@ -48,7 +48,7 @@ Safely implementing ``__clone`` is pretty much the same:
     class MyEntity
     {
         private $id; // This is the identifier of the entity.
-        //...
+        // ...
     
         public function __clone()
         {
@@ -59,7 +59,7 @@ Safely implementing ``__clone`` is pretty much the same:
             // otherwise do nothing, do NOT throw an exception!
         }
     
-        //...
+        // ...
     }
 
 Summary

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

@@ -61,7 +61,7 @@ to manage this mess,
 however let me crush your expectations fast. There is not a single database out there (supported by Doctrine ORM)
 that supports timezones correctly. Correctly here means that you can cover all the use-cases that
 can come up with timezones. If you don't believe me you should read up on `Storing DateTime
-in Databases <http://derickrethans.nl/storing-date-time-in-database.html>`_.
+in Databases <https://derickrethans.nl/storing-date-time-in-database.html>`_.
 
 The problem is simple. Not a single database vendor saves the timezone, only the differences to UTC.
 However with frequent daylight saving and political timezone changes you can have a UTC offset that moves

docs/en/index.rst

@@ -41,6 +41,7 @@ Mapping Objects onto a Database
 
 * **Drivers**:
   :doc:`Docblock Annotations <reference/annotations-reference>` |
+  :doc:`Attributes <reference/attributes-reference>` |
   :doc:`XML <reference/xml-mapping>` |
   :doc:`YAML <reference/yaml-mapping>` |
   :doc:`PHP <reference/php-mapping>`

docs/en/reference/advanced-configuration.rst

@@ -50,7 +50,7 @@ steps of configuration.
     conversions with the query cache. These 2 caches require only an
     absolute minimum of memory yet they heavily improve the runtime
     performance of Doctrine. The recommended cache driver to use with
-    Doctrine is `APC <http://www.php.net/apc>`_. APC provides you with
+    Doctrine is `APC <https://php.net/apc>`_. APC provides you with
     an opcode-cache (which is highly recommended anyway) and a very
     fast in-memory cache storage that you can use for the metadata and
     query caches as seen in the previous code snippet.
@@ -101,10 +101,11 @@ Gets or sets the metadata driver implementation that is used by
 Doctrine to acquire the object-relational metadata for your
 classes.
 
-There are currently 4 available implementations:
+There are currently 5 available implementations:
 
 
 -  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
+-  ``Doctrine\ORM\Mapping\Driver\AttributeDriver``
 -  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\YamlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\DriverChain``

docs/en/reference/annotations-reference.rst

@@ -89,7 +89,7 @@ as part of the lifecycle of the instance variables entity-class.
 Required attributes:
 
 -  **type**: Name of the Doctrine Type which is converted between PHP
-   and Database representation.
+   and Database representation. Default to ``string`` or :ref:`Type from PHP property type <reference-php-mapping-types>`
 
 Optional attributes:
 
@@ -350,7 +350,7 @@ in order to specify that it is an embedded class.
 
 Required attributes:
 
--  **class**: The embeddable class
+-  **class**: The embeddable class. You can omit this value if you use a PHP property type instead.
 
 
 .. code-block:: php
@@ -398,11 +398,11 @@ Example:
 
     <?php
     /**
-     * @Entity(repositoryClass="MyProject\UserRepository")
+     * @Entity(repositoryClass="MyProject\UserRepository", readOnly=true)
      */
     class User
     {
-        //...
+        // ...
     }
 
 .. _annref_entity_result:
@@ -455,7 +455,8 @@ Optional attributes:
 
 
 -  **strategy**: Set the name of the identifier generation strategy.
-   Valid values are AUTO, SEQUENCE, TABLE, IDENTITY, UUID, CUSTOM and NONE.
+   Valid values are ``AUTO``, ``SEQUENCE``, ``TABLE``, ``IDENTITY``, ``UUID``, ``CUSTOM`` and ``NONE``, explained
+   in the :ref:`Identifier Generation Strategies <identifier-generation-strategies>` section.
    If not specified, default value is AUTO.
 
 Example:
@@ -513,7 +514,8 @@ Required attributes:
 
 
 -  **name**: Name of the Index
--  **columns**: Array of columns.
+-  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
+-  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
@@ -535,6 +537,19 @@ Basic example:
     {
     }
 
+Basic example using fields:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     * @Table(name="ecommerce_products",indexes={@Index(name="search_idx", fields={"name", "email"})})
+     */
+    class ECommerceProduct
+    {
+    }
+
 Example with partial indexes:
 
 .. code-block:: php
@@ -715,6 +730,7 @@ Required attributes:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
+   You can omit this value if you use a PHP property type instead.
    *IMPORTANT:* No leading backslash!
 
 Optional attributes:
@@ -840,6 +856,11 @@ Example:
 
 @NamedNativeQuery
 ~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    Named Native Queries are deprecated as of version 2.9 and will be removed in ORM 3.0
+
 Is used to specify a native SQL named query.
 The NamedNativeQuery annotation can be applied to an entity or mapped superclass.
 
@@ -923,6 +944,7 @@ Required attributes:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
+   When typed properties are used it is inherited from PHP type.
    *IMPORTANT:* No leading backslash!
 
 Optional attributes:
@@ -1263,7 +1285,8 @@ Required attributes:
 
 
 -  **name**: Name of the Index
--  **columns**: Array of columns.
+-  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
+-  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
@@ -1285,6 +1308,19 @@ Basic example:
     {
     }
 
+Basic example using fields:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     * @Table(name="ecommerce_products",uniqueConstraints={@UniqueConstraint(name="search_idx", fields={"name", "email"})})
+     */
+    class ECommerceProduct
+    {
+    }
+
 Example with partial indexes:
 
 .. code-block:: php

docs/en/reference/architecture.rst

@@ -83,7 +83,7 @@ be any regular PHP class observing the following restrictions:
 -  An entity class must not implement ``__wakeup`` or
    :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
    Also consider implementing
-   `Serializable <http://php.net/manual/en/class.serializable.php>`_
+   `Serializable <https://php.net/manual/en/class.serializable.php>`_
    instead.
 -  Any two entity classes in a class hierarchy that inherit
    directly or indirectly from one another must not have a mapped
@@ -189,7 +189,7 @@ The Unit of Work
 
 Internally an ``EntityManager`` uses a ``UnitOfWork``, which is a
 typical implementation of the
-`Unit of Work pattern <http://martinfowler.com/eaaCatalog/unitOfWork.html>`_,
+`Unit of Work pattern <https://martinfowler.com/eaaCatalog/unitOfWork.html>`_,
 to keep track of all the things that need to be done the next time
 ``flush`` is invoked. You usually do not directly interact with a
 ``UnitOfWork`` but with the ``EntityManager`` instead.

docs/en/reference/association-mapping.rst

@@ -22,9 +22,9 @@ One tip for working with relations is to read the relation from left to right, w
 - ManyToOne - Many instances of the current Entity refer to One instance of the referred Entity.
 - OneToOne - One instance of the current Entity refers to One instance of the referred Entity.
 
-See below for all the possible relations. 
+See below for all the possible relations.
 
-An association is considered to be unidirectional if only one side of the association has 
+An association is considered to be unidirectional if only one side of the association has
 a property referring to the other side.
 
 To gain a full understanding of associations you should also read about :doc:`owning and
@@ -182,7 +182,7 @@ Here is a one-to-one relationship between a ``Customer`` and a
 ``Cart``. The ``Cart`` has a reference back to the ``Customer`` so
 it is bidirectional.
 
-Here we see the ``mappedBy`` and ``inversedBy`` annotations for the first time.
+Here we see the ``mappedBy`` and ``inversedBy`` attributes for the first time.
 They are used to tell Doctrine which property on the other side refers to the
 object.
 
@@ -259,6 +259,7 @@ Generated MySQL Schema:
     CREATE TABLE Cart (
         id INT AUTO_INCREMENT NOT NULL,
         customer_id INT DEFAULT NULL,
+        UNIQUE INDEX UNIQ_BA388B79395C3F3 (customer_id),
         PRIMARY KEY(id)
     ) ENGINE = InnoDB;
     CREATE TABLE Customer (
@@ -977,10 +978,10 @@ similar defaults. As an example, consider this mapping:
         <?php
         class User
         {
-            //...
+            // ...
             /** @ManyToMany(targetEntity="Group") */
             private $groups;
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -1008,7 +1009,7 @@ This is essentially the same as the following, more verbose, mapping:
         <?php
         class User
         {
-            //...
+            // ...
             /**
              * Many Users have Many Groups.
              * @ManyToMany(targetEntity="Group")
@@ -1018,7 +1019,7 @@ This is essentially the same as the following, more verbose, mapping:
              *      )
              */
             private $groups;
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -1061,6 +1062,70 @@ join columns default to the simple, unqualified class name of the
 targeted class followed by "\_id". The referencedColumnName always
 defaults to "id", just as in one-to-one or many-to-one mappings.
 
+Additionally, when using typed properties with Doctrine 2.9 or newer
+you can skip ``targetEntity`` in ``ManyToOne`` and ``OneToOne``
+associations as they will be set based on type. Also ``nullable``
+attribute on ``JoinColumn`` will be inherited from PHP type. So that:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /** @OneToOne */
+        private Shipment $shipment;
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity class="Product">
+                <one-to-one field="shipment" />
+            </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment: ~
+
+Is essentially the same as following:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        /**
+         * One Product has One Shipment.
+         * @OneToOne(targetEntity="Shipment")
+         * @JoinColumn(name="shipment_id", referencedColumnName="id", nullable=false)
+         */
+        private Shipment $shipment;
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity class="Product">
+                <one-to-one field="shipment" target-entity="Shipment">
+                    <join-column name="shipment_id" referenced-column-name="id" nulable=false />
+                </one-to-one>
+            </entity>
+        </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment:
+              targetEntity: Shipment
+              joinColumn:
+                name: shipment_id
+                referencedColumnName: id
+                nullable: false
+
 If you accept these defaults, you can reduce the mapping code to a
 minimum.
 

docs/en/reference/basic-mapping.rst

@@ -51,6 +51,7 @@ Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
 -  :doc:`Docblock Annotations <annotations-reference>`
+-  :doc:`Attributes <attributes-reference>`
 -  :doc:`XML <xml-mapping>`
 -  :doc:`YAML <yaml-mapping>`
 -  :doc:`PHP code <php-mapping>`
@@ -76,7 +77,7 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
         /** @Entity */
         class Message
         {
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -108,7 +109,7 @@ You can change this by configuring information about the table:
          */
         class Message
         {
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -211,6 +212,27 @@ list:
 - ``options``: (optional) Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
+.. _reference-php-mapping-types:
+
+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.
+
+Additionally, Doctrine will map PHP types to ``type`` attribute as follows:
+
+- ``DateInterval``: ``dateinterval``
+- ``DateTime``: ``datetime``
+- ``DateTimeImmutable``: ``datetime_immutable``
+- ``array``: ``json``
+- ``bool``: ``boolean``
+- ``float``: ``float``
+- ``int``: ``integer``
+- ``string`` or any other type: ``string``
+
 .. _reference-mapping-types:
 
 Doctrine Mapping Types
@@ -270,7 +292,7 @@ A cookbook article shows how to define :doc:`your own custom mapping types
 .. warning::
 
     All Date types assume that you are exclusively using the default timezone
-    set by `date_default_timezone_set() <http://php.net/manual/en/function.date-default-timezone-set.php>`_
+    set by `date_default_timezone_set() <https://php.net/manual/en/function.date-default-timezone-set.php>`_
     or by the php.ini configuration ``date.timezone``. Working with
     different timezones will cause troubles and unexpected behavior.
 
@@ -300,7 +322,7 @@ annotation.
              * @GeneratedValue
              */
             private $id;
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -328,9 +350,11 @@ annotation.
 
 In most cases using the automatic generator strategy (``@GeneratedValue``) is
 what you want. It defaults to the identifier generation mechanism your current
-database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL 
+database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL
 and Oracle and so on.
 
+.. _identifier-generation-strategies:
+
 Identifier Generation Strategies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -387,7 +411,7 @@ besides specifying the sequence's name:
              * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
              */
             protected $id = null;
-            //...
+            // ...
         }
 
     .. code-block:: xml

docs/en/reference/batch-processing.rst

@@ -51,7 +51,7 @@ internally but also mean more work during ``flush``.
             $em->clear(); // Detaches all objects from Doctrine!
         }
     }
-    $em->flush(); //Persist objects that did not make up an entire batch
+    $em->flush(); // Persist objects that did not make up an entire batch
     $em->clear();
 
 Bulk Updates
@@ -89,11 +89,11 @@ with the batching strategy that was already used for bulk inserts:
     foreach ($q->toIterable() as $user) {
         $user->increaseCredit();
         $user->calculateNewBonuses();
+        ++$i;
         if (($i % $batchSize) === 0) {
             $em->flush(); // Executes all updates.
             $em->clear(); // Detaches all objects from Doctrine!
         }
-        ++$i;
     }
     $em->flush();
 
@@ -147,11 +147,11 @@ The following example shows how to do this:
     $q = $em->createQuery('select u from MyProject\Model\User u');
     foreach($q->toIterable() as $row) {
         $em->remove($row);
+        ++$i;
         if (($i % $batchSize) === 0) {
             $em->flush(); // Executes all deletions.
             $em->clear(); // Detaches all objects from Doctrine!
         }
-        ++$i;
     }
     $em->flush();
 

docs/en/reference/caching.rst

@@ -74,7 +74,7 @@ Memcache
 
 In order to use the Memcache cache driver you must have it compiled
 and enabled in your php.ini. You can read about Memcache
-`on the PHP website <http://php.net/memcache>`_. It will
+`on the PHP website <https://php.net/memcache>`_. It will
 give you a little background information about what it is and how
 you can use it as well as how to install it.
 
@@ -99,7 +99,7 @@ Memcache.
 
 In order to use the Memcached cache driver you must have it compiled
 and enabled in your php.ini. You can read about Memcached
-`on the PHP website <http://php.net/memcached>`_. It will
+`on the PHP website <https://php.net/memcached>`_. It will
 give you a little background information about what it is and how
 you can use it as well as how to install it.
 
@@ -121,7 +121,7 @@ Redis
 
 In order to use the Redis cache driver you must have it compiled
 and enabled in your php.ini. You can read about what Redis is
-`from here <http://redis.io/>`_. Also check
+`from here <https://redis.io/>`_. Also check
 `A PHP extension for Redis <https://github.com/nicolasff/phpredis/>`_ for how you can use
 and install the Redis PHP extension.
 
@@ -286,9 +286,8 @@ Result Cache
 ~~~~~~~~~~~~
 
 The result cache can be used to cache the results of your queries
-so that we don't have to query the database or hydrate the data
-again after the first time. You just need to configure the result
-cache implementation.
+so that we don't have to query the database again after the first time.
+You just need to configure the result cache implementation.
 
 .. code-block:: php
 

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

@@ -61,6 +61,11 @@ This policy can be configured as follows:
 Notify
 ~~~~~~
 
+.. note::
+
+    The notify change tracking policy is deprecated and will be removed in ORM 3.0.
+    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+
 This policy is based on the assumption that the entities notify
 interested listeners of changes to their properties. For that
 purpose, a class that wants to use this policy needs to implement

docs/en/reference/configuration.rst

@@ -95,7 +95,7 @@ If you want to configure Doctrine in more detail, take a look at the :doc:`Advan
 .. note::
 
     You can learn more about the database connection configuration in the
-    `Doctrine DBAL connection configuration reference <http://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/latest/reference/configuration.html>`_.
 
 Setting up the Commandline Tool
 -------------------------------

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

@@ -1,5 +1,5 @@
 Doctrine Query Language
-===========================
+=======================
 
 DQL stands for Doctrine Query Language and is an Object
 Query Language derivative that is very similar to the Hibernate
@@ -487,6 +487,26 @@ where you can generate an arbitrary join with the following syntax:
     <?php
     $query = $em->createQuery('SELECT u FROM User u JOIN Banlist b WITH u.email = b.email');
 
+With an arbitrary join the result differs from the joins using a mapped property.
+The result of an arbitrary join is an one dimensional array with a mix of the entity from the ``SELECT``
+and the joined entity fitting to the filtering of the query. In case of the example with ``User``
+and ``Blacklist``, it can look like this:
+
+- User
+- Blacklist
+- Blacklist
+- User
+- Blacklist
+- User
+- Blacklist
+- Blacklist
+- Blacklist
+
+In this form of join, the ``Blacklist`` entities found by the filtering in the ``WITH`` part are not fetched by an accessor
+method on ``User``, but are already part of the result. In case the accessor method for Blacklists is invoked on a User instance,
+it loads all the related ``Blacklist`` objects corresponding to this ``User``. This change of behaviour needs to be considered
+when the DQL is switched to an arbitrary join.
+
 .. note::
     The differences between WHERE, WITH and HAVING clauses may be
     confusing.
@@ -603,6 +623,13 @@ then phonenumber-id:
               ...
           'nameUpper' => string 'JWAGE' (length=5)
 
+You can also index by a to-one association, which will use the id of
+the associated entity (the join column) as the key in the result set:
+
+.. code-block:: sql
+
+    SELECT p, u FROM Participant INDEX BY p.user JOIN p.user u WHERE p.event = 3
+
 UPDATE queries
 --------------
 
@@ -673,29 +700,35 @@ The following functions are supported in SELECT, WHERE and HAVING
 clauses:
 
 
--  IDENTITY(single\_association\_path\_expression [, fieldMapping]) - Retrieve the foreign key column of association of the owning side
--  ABS(arithmetic\_expression)
--  CONCAT(str1, str2)
--  CURRENT\_DATE() - Return the current date
--  CURRENT\_TIME() - Returns the current time
--  CURRENT\_TIMESTAMP() - Returns a timestamp of the current date
+-  ``IDENTITY(single_association_path_expression [, fieldMapping])`` -
+   Retrieve the foreign key column of association of the owning side
+-  ``ABS(arithmetic_expression)``
+-  ``CONCAT(str1, str2)``
+-  ``CURRENT_DATE()`` - Return the current date
+-  ``CURRENT_TIME()`` - Returns the current time
+-  ``CURRENT_TIMESTAMP()`` - Returns a timestamp of the current date
    and time.
--  LENGTH(str) - Returns the length of the given string
--  LOCATE(needle, haystack [, offset]) - Locate the first
+-  ``LENGTH(str)`` - Returns the length of the given string
+-  ``LOCATE(needle, haystack [, offset])`` - Locate the first
    occurrence of the substring in the string.
--  LOWER(str) - returns the string lowercased.
--  MOD(a, b) - Return a MOD b.
--  SIZE(collection) - Return the number of elements in the
+-  ``LOWER(str)`` - returns the string lowercased.
+-  ``MOD(a, b)`` - Return a MOD b.
+-  ``SIZE(collection)`` - Return the number of elements in the
    specified collection
--  SQRT(q) - Return the square-root of q.
--  SUBSTRING(str, start [, length]) - Return substring of given
+-  ``SQRT(q)`` - Return the square-root of q.
+-  ``SUBSTRING(str, start [, length])`` - Return substring of given
    string.
--  TRIM([LEADING \| TRAILING \| BOTH] ['trchar' FROM] str) - Trim
+-  ``TRIM([LEADING \| TRAILING \| BOTH] ['trchar' FROM] str)`` - Trim
    the string by the given trim char, defaults to whitespaces.
--  UPPER(str) - Return the upper-case of the given string.
--  DATE_ADD(date, value, unit) - Add the given time to a given date. (Supported units are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR)
--  DATE_SUB(date, value, unit) - Subtract the given time from a given date. (Supported units are SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR)
--  DATE_DIFF(date1, date2) - Calculate the difference in days between date1-date2.
+-  ``UPPER(str)`` - Return the upper-case of the given string.
+-  ``DATE_ADD(date, value, unit)`` - Add the given time to a given date.
+   (Supported units are ``SECOND``, ``MINUTE``, ``HOUR``, ``DAY``,
+   ``WEEK``, ``MONTH``, ``YEAR``)
+-  ``DATE_SUB(date, value, unit)`` - Subtract the given time from a
+   given date. (Supported units are ``SECOND``, ``MINUTE``, ``HOUR``,
+   ``DAY``, ``WEEK``, ``MONTH``, ``YEAR``)
+-  ``DATE_DIFF(date1, date2)`` - Calculate the difference in days
+   between date1-date2.
 
 Arithmetic operators
 ~~~~~~~~~~~~~~~~~~~~
@@ -805,7 +838,7 @@ what type of results to expect.
 Single Table
 ~~~~~~~~~~~~
 
-`Single Table Inheritance <http://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
+`Single Table Inheritance <https://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
 is an inheritance mapping strategy where all classes of a hierarchy
 are mapped to a single database table. In order to distinguish
 which row represents which type in the hierarchy a so-called
@@ -898,7 +931,7 @@ entities:
 Class Table Inheritance
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-`Class Table Inheritance <http://martinfowler.com/eaaCatalog/classTableInheritance.html>`_
+`Class Table Inheritance <https://martinfowler.com/eaaCatalog/classTableInheritance.html>`_
 is an inheritance mapping strategy where each class in a hierarchy
 is mapped to several tables: its own table and the tables of all
 parent classes. The table of a child class is linked to the table
@@ -1147,10 +1180,10 @@ make best use of the different result formats:
 The constants for the different hydration modes are:
 
 
--  Query::HYDRATE\_OBJECT
--  Query::HYDRATE\_ARRAY
--  Query::HYDRATE\_SCALAR
--  Query::HYDRATE\_SINGLE\_SCALAR
+-  ``Query::HYDRATE_OBJECT``
+-  ``Query::HYDRATE_ARRAY``
+-  ``Query::HYDRATE_SCALAR``
+-  ``Query::HYDRATE_SINGLE_SCALAR``
 
 Object Hydration
 ^^^^^^^^^^^^^^^^
@@ -1216,7 +1249,7 @@ Scalar Hydration:
 
 
 1. Fields from classes are prefixed by the DQL alias in the result.
-   A query of the kind 'SELECT u.name ..' returns a key 'u\_name' in
+   A query of the kind 'SELECT u.name ..' returns a key 'u_name' in
    the result rows.
 
 Single Scalar Hydration
@@ -1364,21 +1397,22 @@ userland. However the following few hints are to be used in
 userland:
 
 
--  Query::HINT\_FORCE\_PARTIAL\_LOAD - Allows to hydrate objects
+-  ``Query::HINT_FORCE_PARTIAL_LOAD`` - Allows to hydrate objects
    although not all their columns are fetched. This query hint can be
    used to handle memory consumption problems with large result-sets
    that contain char or binary data. Doctrine has no way of implicitly
    reloading this data. Partially loaded objects have to be passed to
    ``EntityManager::refresh()`` if they are to be reloaded fully from
-   the database.
--  Query::HINT\_REFRESH - This query is used internally by
+   the database. This query hint is deprecated and will be removed
+   in the future (`Details <https://github.com/doctrine/orm/issues/8471>`_)
+-  ``Query::HINT_REFRESH`` - This query is used internally by
    ``EntityManager::refresh()`` and can be used in userland as well.
    If you specify this hint and a query returns the data for an entity
    that is already managed by the UnitOfWork, the fields of the
    existing entity will be refreshed. In normal operation a result-set
    that loads data of an already existing entity is discarded in favor
    of the already existing entity.
--  Query::HINT\_CUSTOM\_TREE\_WALKERS - An array of additional
+-  ``Query::HINT_CUSTOM_TREE_WALKERS`` - An array of additional
    ``Doctrine\ORM\Query\TreeWalker`` instances that are attached to
    the DQL query parsing process.
 
@@ -1615,7 +1649,7 @@ From, Join and Index by
     RangeVariableDeclaration                   ::= AbstractSchemaName ["AS"] AliasIdentificationVariable
     JoinAssociationDeclaration                 ::= JoinAssociationPathExpression ["AS"] AliasIdentificationVariable [IndexBy]
     Join                                       ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN" (JoinAssociationDeclaration | RangeVariableDeclaration) ["WITH" ConditionalExpression]
-    IndexBy                                    ::= "INDEX" "BY" StateFieldPathExpression
+    IndexBy                                    ::= "INDEX" "BY" SingleValuedPathExpression
 
 Select Expressions
 ~~~~~~~~~~~~~~~~~~
@@ -1733,7 +1767,7 @@ QUANTIFIED/BETWEEN/COMPARISON/LIKE/NULL/EXISTS
     QuantifiedExpression     ::= ("ALL" | "ANY" | "SOME") "(" Subselect ")"
     BetweenExpression        ::= ArithmeticExpression ["NOT"] "BETWEEN" ArithmeticExpression "AND" ArithmeticExpression
     ComparisonExpression     ::= ArithmeticExpression ComparisonOperator ( QuantifiedExpression | ArithmeticExpression )
-    InExpression             ::= SingleValuedPathExpression ["NOT"] "IN" "(" (InParameter {"," InParameter}* | Subselect) ")"
+    InExpression             ::= ArithmeticExpression ["NOT"] "IN" "(" (InParameter {"," InParameter}* | Subselect) ")"
     InstanceOfExpression     ::= IdentificationVariable ["NOT"] "INSTANCE" ["OF"] (InstanceOfParameter | "(" InstanceOfParameter {"," InstanceOfParameter}* ")")
     InstanceOfParameter      ::= AbstractSchemaName | InputParameter
     LikeExpression           ::= StringExpression ["NOT"] "LIKE" StringPrimary ["ESCAPE" char]

docs/en/reference/events.rst

@@ -329,9 +329,9 @@ XML would look something like this:
 
     <?xml version="1.0" encoding="UTF-8"?>
 
-    <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+    <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
         <entity name="User">

docs/en/reference/faq.rst

@@ -52,7 +52,7 @@ or adding entities to a collection twice. You have to check for both conditions
 in the code before calling ``$em->flush()`` if you know that unique constraint failures
 can occur.
 
-In `Symfony2 <http://www.symfony.com>`_ for example there is a Unique Entity Validator
+In `Symfony2 <https://www.symfony.com>`_ for example there is a Unique Entity Validator
 to achieve this task.
 
 For collections you can check with ``$collection->contains($entity)`` if an entity is already
@@ -112,8 +112,8 @@ over this collection using a LIMIT statement (or vendor equivalent).
 Doctrine does not offer a solution for this out of the box but there are several extensions
 that do:
 
-* `DoctrineExtensions <http://github.com/beberlei/DoctrineExtensions>`_
-* `Pagerfanta <http://github.com/whiteoctober/pagerfanta>`_
+* `DoctrineExtensions <https://github.com/beberlei/DoctrineExtensions>`_
+* `Pagerfanta <https://github.com/whiteoctober/pagerfanta>`_
 
 Why does pagination not work correctly with fetch joins?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/en/reference/filters.rst

@@ -53,6 +53,9 @@ proper quoting of parameters.
         }
     }
 
+If the parameter is an array and should be quoted as a list of values for an IN query
+this is possible with the alternative ``SQLFilter#setParameterList()`` and
+``SQLFilter#getParameterList()`` functions.
 
 Configuration
 -------------

docs/en/reference/improving-performance.rst

@@ -44,13 +44,35 @@ Read-Only Entities
 ------------------
 
 You can mark entities as read only (See metadata mapping
-references for details). This means that the entity marked as read only is never considered
-for updates, which means when you call flush on the EntityManager these entities are skipped
-even if properties changed. Read-Only allows to persist new entities of a kind and remove existing
-ones, they are just not considered for updates.
+references for details).
+
+This means that the entity marked as read only is never considered for updates.
+During flush on the EntityManager these entities are skipped even if properties
+changed.
+
+Read-Only allows to persist new entities of a kind and remove existing ones,
+they are just not considered for updates.
 
 See :ref:`annref_entity`
 
+You can also explicitly mark individual entities read only directly on the
+UnitOfWork via a call to ``markReadOnly()``:
+
+.. code-block:: php
+
+   $user = $entityManager->find(User::class, $id);
+   $entityManager->getUnitOfWork()->markReadOnly($user);
+
+Or you can set all objects that are the result of a query hydration to be
+marked as read only with the following query hint:
+
+.. code-block:: php
+
+   $query = $entityManager->createQuery('SELECT u FROM App\\Entity\\User u');
+   $query->setHint(Query::HINT_READ_ONLY, true);
+
+   $users = $query->getResult();
+
 Extra-Lazy Collections
 ----------------------
 
@@ -75,4 +97,4 @@ See :doc:`Best Practices <reference/best-practices>`
 Change Tracking policies
 ------------------------
 
-See: :doc:`Change Tracking Policies <reference/change-tracking-policies>`
+See: :doc:`Change Tracking Policies <change-tracking-policies>`

docs/en/reference/inheritance-mapping.rst

@@ -31,24 +31,31 @@ Example:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\JoinColumn;
+    use Doctrine\ORM\Mapping\OneToOne;
+    use Doctrine\ORM\Mapping\Id;
+    use Doctrine\ORM\Mapping\MappedSuperclass;
+    use Doctrine\ORM\Mapping\Entity;
+
     /** @MappedSuperclass */
-    class MappedSuperclassBase
+    class Person
     {
         /** @Column(type="integer") */
         protected $mapped1;
         /** @Column(type="string") */
         protected $mapped2;
         /**
-         * @OneToOne(targetEntity="MappedSuperclassRelated1")
-         * @JoinColumn(name="related1_id", referencedColumnName="id")
+         * @OneToOne(targetEntity="Toothbrush")
+         * @JoinColumn(name="toothbrush_id", referencedColumnName="id")
          */
-        protected $mappedRelated1;
-    
+        protected $toothbrush;
+
         // ... more fields and methods
     }
     
     /** @Entity */
-    class EntitySubClass extends MappedSuperclassBase
+    class Employee extends Person
     {
         /** @Id @Column(type="integer") */
         private $id;
@@ -58,6 +65,15 @@ Example:
         // ... more fields and methods
     }
 
+    /** @Entity */
+    class Toothbrush
+    {
+        /** @Id @Column(type="integer") */
+        private $id;
+
+        // ... more fields and methods
+    }
+
 The DDL for the corresponding database schema would look something
 like this (this is for SQLite):
 
@@ -73,7 +89,7 @@ defined on that class directly.
 Single Table Inheritance
 ------------------------
 
-`Single Table Inheritance <http://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
+`Single Table Inheritance <https://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
 is an inheritance mapping strategy where all classes of a hierarchy
 are mapped to a single database table. In order to distinguish
 which row represents which type in the hierarchy a so-called
@@ -181,7 +197,7 @@ the root entity of the single-table inheritance hierarchy.
 Class Table Inheritance
 -----------------------
 
-`Class Table Inheritance <http://martinfowler.com/eaaCatalog/classTableInheritance.html>`_
+`Class Table Inheritance <https://martinfowler.com/eaaCatalog/classTableInheritance.html>`_
 is an inheritance mapping strategy where each class in a hierarchy
 is mapped to several tables: its own table and the tables of all
 parent classes. The table of a child class is linked to the table
@@ -274,6 +290,9 @@ be a leaf entity in the inheritance hierarchy, (ie. have no subclasses).
 Otherwise Doctrine *CANNOT* create proxy instances
 of this entity and will *ALWAYS* load the entity eagerly.
 
+There is also another important performance consideration that it is *NOT POSSIBLE* 
+to query for the base entity without any LEFT JOINs to the sub-types.
+
 SQL Schema considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -321,7 +340,7 @@ Example:
          */
         class User
         {
-            //other fields mapping
+            // other fields mapping
 
             /**
              * @ManyToMany(targetEntity="Group", inversedBy="users")
@@ -460,7 +479,7 @@ Things to note:
 -  This feature is available for all kind of associations. (OneToOne, OneToMany, ManyToOne, ManyToMany)
 -  The association type *CANNOT* be changed.
 -  The override could redefine the joinTables or joinColumns depending on the association type.
--  The override could redefine inversedBy to reference more than one extended entity.
+-  The override could redefine ``inversedBy`` to reference more than one extended entity.
 -  The override could redefine fetch to modify the fetch strategy of the extended entity.
 
 Attribute Override

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

@@ -112,10 +112,10 @@ in the core library. We don't think behaviors add more value than
 they cost pain and debugging hell. Please see the many different
 blog posts we have written on this topics:
 
--  `Doctrine2 "Behaviors" in a Nutshell <http://www.doctrine-project.org/2010/02/17/doctrine2-behaviours-nutshell.html>`_
--  `A re-usable Versionable behavior for Doctrine2 <http://www.doctrine-project.org/2010/02/24/doctrine2-versionable.html>`_
--  `Write your own ORM on top of Doctrine2 <http://www.doctrine-project.org/2010/07/19/your-own-orm-doctrine2.html>`_
--  `Doctrine ORM Behavioral Extensions <http://www.doctrine-project.org/2010/11/18/doctrine2-behavioral-extensions.html>`_
+-  `Doctrine2 "Behaviors" in a Nutshell <https://www.doctrine-project.org/2010/02/17/doctrine2-behaviours-nutshell.html>`_
+-  `A re-usable Versionable behavior for Doctrine2 <https://www.doctrine-project.org/2010/02/24/doctrine2-versionable.html>`_
+-  `Write your own ORM on top of Doctrine2 <https://www.doctrine-project.org/2010/07/19/your-own-orm-doctrine2.html>`_
+-  `Doctrine ORM Behavioral Extensions <https://www.doctrine-project.org/2010/11/18/doctrine2-behavioral-extensions.html>`_
 
 Doctrine ORM has enough hooks and extension points so that **you** can
 add whatever you want on top of it. None of this will ever become
@@ -131,8 +131,8 @@ extensions out there that offer support for Nested Set with
 ORM:
 
 
--  `Doctrine2 Hierarchical-Structural Behavior <http://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
--  `Doctrine2 NestedSet <http://github.com/blt04/doctrine2-nestedset>`_
+-  `Doctrine2 Hierarchical-Structural Behavior <https://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
+-  `Doctrine2 NestedSet <https://github.com/blt04/doctrine2-nestedset>`_
 
 Known Issues
 ------------

docs/en/reference/metadata-drivers.rst

@@ -14,6 +14,7 @@ metadata:
 
 -  **XML files** (XmlDriver)
 -  **Class DocBlock Annotations** (AnnotationDriver)
+-  **Attributes** (AttributeDriver)
 -  **YAML files** (YamlDriver)
 -  **PHP Code in files or static functions** (PhpDriver)
 

docs/en/reference/native-sql.rst

@@ -71,7 +71,7 @@ with inheritance hierarchies.
 
     use Doctrine\ORM\Query\ResultSetMappingBuilder;
 
-    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " . 
+    $sql = "SELECT u.id, u.name, a.id AS address_id, a.street, a.city " .
            "FROM users u INNER JOIN address a ON u.address_id = a.id";
 
     $rsm = new ResultSetMappingBuilder($entityManager);
@@ -265,7 +265,7 @@ detail:
     <?php
     /**
      * Adds a meta column (foreign key or discriminator column) to the result set.
-     * 
+     *
      * @param string  $alias
      * @param string  $columnAlias
      * @param string  $columnName
@@ -320,10 +320,10 @@ entity.
     $rsm->addEntityResult('User', 'u');
     $rsm->addFieldResult('u', 'id', 'id');
     $rsm->addFieldResult('u', 'name', 'name');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 The result would look like this:
@@ -356,10 +356,10 @@ thus owns the foreign key.
     $rsm->addFieldResult('u', 'id', 'id');
     $rsm->addFieldResult('u', 'name', 'name');
     $rsm->addMetaResult('u', 'address_id', 'address_id');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name, address_id FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 Foreign keys are used by Doctrine for lazy-loading purposes when
@@ -385,12 +385,12 @@ associations that are lazy.
     $rsm->addFieldResult('a', 'address_id', 'id');
     $rsm->addFieldResult('a', 'street', 'street');
     $rsm->addFieldResult('a', 'city', 'city');
-    
+
     $sql = 'SELECT u.id, u.name, a.id AS address_id, a.street, a.city FROM users u ' .
            'INNER JOIN address a ON u.address_id = a.id WHERE u.name = ?';
     $query = $this->_em->createNativeQuery($sql, $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 In this case the nested entity ``Address`` is registered with the
@@ -420,10 +420,10 @@ to map the hierarchy (both use a discriminator column).
     $rsm->addFieldResult('u', 'name', 'name');
     $rsm->addMetaResult('u', 'discr', 'discr'); // discriminator column
     $rsm->setDiscriminatorColumn('u', 'discr');
-    
+
     $query = $this->_em->createNativeQuery('SELECT id, name, discr FROM users WHERE name = ?', $rsm);
     $query->setParameter(1, 'romanb');
-    
+
     $users = $query->getResult();
 
 Note that in the case of Class Table Inheritance, an example as
@@ -435,6 +435,10 @@ strategy but with native SQL it is your responsibility.
 Named Native Query
 ------------------
 
+.. note::
+
+    Named Native Queries are deprecated as of version 2.9 and will be removed in ORM 3.0
+
 You can also map a native query using a named native query mapping.
 
 To achieve that, you must describe the SQL resultset structure
@@ -789,7 +793,7 @@ followed by a dot ("."), followed by the name or the field or property of the pr
                     6:
                       name: address.country
                       column: a_country
-                    
+
 
 
 If you retrieve a single entity and if you use the default mapping,

docs/en/reference/partial-objects.rst

@@ -1,6 +1,14 @@
 Partial Objects
 ===============
 
+
+.. note::
+
+    Creating Partial Objects through DQL is deprecated and
+    will be removed in the future, use data transfer object
+    support in DQL instead. (`Details
+    <https://github.com/doctrine/orm/issues/8471>`_)
+
 A partial object is an object whose state is not fully initialized
 after being reconstituted from the database and that is
 disconnected from the rest of its data. The following section will

docs/en/reference/query-builder.rst

@@ -520,6 +520,9 @@ complete list of supported helper methods available:
         // Example - $qb->expr()->sqrt('u.currentBalance')
         public function sqrt($x); // Returns Expr\Func
 
+        // Example - $qb->expr()->mod('u.currentBalance', '10')
+        public function mod($x); // Returns Expr\Func
+
         // Example - $qb->expr()->count('u.firstname')
         public function count($x); // Returns Expr\Func
 
@@ -540,7 +543,7 @@ using ``addCriteria``:
     // ...
 
     $criteria = Criteria::create()
-        ->orderBy(['firstName', 'ASC']);
+        ->orderBy(['firstName' => Criteria::ASC]);
 
     // $qb instanceof QueryBuilder
     $qb->addCriteria($criteria);

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

@@ -114,7 +114,7 @@ Timestamp region
 
 Tracks the timestamps of the most recent updates to particular entity.
 
-`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/TimestampRegion.html>`_.
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/TimestampRegion.html>`_.
 
 .. _reference-second-level-cache-mode:
 
@@ -177,10 +177,11 @@ To enable the second-level-cache, you should provide a cache factory.
 .. code-block:: php
 
     <?php
-    /* @var $config \Doctrine\ORM\Cache\RegionsConfiguration */
-    /* @var $cache \Doctrine\Common\Cache\Cache */
+    /** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
+    /** @var \Doctrine\Common\Cache\Cache $cache */
+    /** @var \Doctrine\ORM\Configuration $config */
 
-    $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($config, $cache);
+    $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache);
 
     // Enable second-level-cache
     $config->setSecondLevelCacheEnabled();
@@ -208,7 +209,7 @@ It allows you to provide a specific implementation of the following components :
 ``CollectionHydrator``
     transforms collections into cache entries and cache entries into collections
 
-`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.
 
 Region Lifetime
 ~~~~~~~~~~~~~~~
@@ -218,8 +219,9 @@ To specify a default lifetime for all regions or specify a different lifetime fo
 .. code-block:: php
 
     <?php
-    /* @var $config \Doctrine\ORM\Configuration */
-    /* @var $cacheConfig \Doctrine\ORM\Cache\CacheConfiguration */
+    /** @var \Doctrine\ORM\Configuration $config */
+    /** @var \Doctrine\ORM\Cache\CacheConfiguration $cacheConfig */
+    /** @var \Doctrine\ORM\Cache\RegionsConfiguration $regionConfig */
     $cacheConfig  =  $config->getSecondLevelCacheConfiguration();
     $regionConfig =  $cacheConfig->getRegionsConfiguration();
 
@@ -270,7 +272,7 @@ If you want to get more information you should implement
 ``\Doctrine\ORM\Cache\Logging\CacheLogger`` and collect
 all the information you want.
 
-`See API Doc <http://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Logging/CacheLogger.html>`_.
+`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Logging/CacheLogger.html>`_.
 
 
 Entity cache definition
@@ -313,7 +315,7 @@ level cache region.
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="Country">
             <cache usage="READ_ONLY" region="my_entity_region" />
             <id name="id" type="integer" column="id">
@@ -389,7 +391,7 @@ It caches the primary keys of association and cache each element will be cached
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="State">
 
             <cache usage="NONSTRICT_READ_WRITE" />
@@ -464,8 +466,8 @@ Basic entity cache
 
     $country1  = $em->find('Country', 1); // Retrieve item from cache
 
-    $country->setName("New Name");
-    $em->persist($country);
+    $country1->setName("New Name");
+    
     $em->flush();                         // Hit database to update the row and update cache
 
     $em->clear();                         // Clear entity manager

docs/en/reference/security.rst

@@ -10,7 +10,7 @@ we cannot protect you from SQL injection.
 Please also read the documentation chapter on Security in Doctrine DBAL. This
 page only handles Security issues in the ORM.
 
-- `DBAL Security Page <http://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/security.html>`
+- `DBAL Security Page <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/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

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

@@ -68,7 +68,7 @@ looks like this:
     // $em instanceof EntityManager
     $em->getConnection()->beginTransaction(); // suspend auto-commit
     try {
-        //... do some work
+        // ... do some work
         $user = new User;
         $user->setName('George');
         $em->persist($user);
@@ -98,7 +98,7 @@ functionally equivalent to the previously shown code looks as follows:
     <?php
     // $em instanceof EntityManager
     $em->transactional(function($em) {
-        //... do some work
+        // ... do some work
         $user = new User;
         $user->setName('George');
         $em->persist($user);

docs/en/reference/unitofwork-associations.rst

@@ -16,11 +16,11 @@ Bidirectional Associations
 The following rules apply to **bidirectional** associations:
 
 - The inverse side has to have the ``mappedBy`` attribute of the OneToOne,
-  OneToMany, or ManyToMany mapping declaration. The mappedBy
+  OneToMany, or ManyToMany mapping declaration. The ``mappedBy``
   attribute contains the name of the association-field on the owning side.
 - The owning side has to have the ``inversedBy`` attribute of the
-  OneToOne, ManyToOne, or ManyToMany mapping declaration. 
-  The inversedBy attribute contains the name of the association-field
+  OneToOne, ManyToOne, or ManyToMany mapping declaration.
+  The ``inversedBy`` attribute contains the name of the association-field
   on the inverse-side.
 - ManyToOne is always the owning side of a bidirectional association.
 - OneToMany is always the inverse side of a bidirectional association.

docs/en/reference/unitofwork.rst

@@ -134,6 +134,10 @@ optimize the performance of the Flush Operation:
   explicit strategies of notifying the UnitOfWork what objects/properties
   changed.
 
+.. note::
+
+    Flush only a single entity with ``$entityManager->flush($entity)`` is deprecated and will be removed in ORM 3.0.
+    (`Details <https://github.com/doctrine/orm/issues/8459>`_)
 
 Query Internals
 ---------------

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

@@ -291,7 +291,7 @@ example that encapsulate much of the association management code:
     <?php
     class User
     {
-        //...
+        // ...
         public function markCommentRead(Comment $comment) {
             // Collections implement ArrayAccess
             $this->commentsRead[] = $comment;
@@ -463,14 +463,14 @@ If you then set up the cascading to the ``User#commentsAuthored`` property...
     <?php
     class User
     {
-        //...
+        // ...
         /**
          * Bidirectional - One-To-Many (INVERSE SIDE)
          *
          * @OneToMany(targetEntity="Comment", mappedBy="author", cascade={"persist", "remove"})
          */
         private $commentsAuthored;
-        //...
+        // ...
     }
 
 ...you can now create a user and an associated comment like this:

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

@@ -338,7 +338,7 @@ in multiple ways with very different performance impacts.
 
 .. note::
 
-    Calling ``remove`` on an entity will remove the object from the identiy
+    Calling ``remove`` on an entity will remove the object from the identity
     map and therefore detach it. Querying the same entity again, for example 
     via a lazy loaded relation, will return a new object. 
 
@@ -388,8 +388,7 @@ automatically without invoking the ``detach`` method:
    currently managed by the EntityManager instance become detached.
 -  When serializing an entity. The entity retrieved upon subsequent
    unserialization will be detached (This is the case for all entities
-   that are serialized and stored in some cache, i.e. when using the
-   Query Result Cache).
+   that are serialized and stored in some cache).
 
 The ``detach`` operation is usually not as frequently needed and
 used as ``persist`` and ``remove``.

docs/en/reference/xml-mapping.rst

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

docs/en/sidebar.rst

@@ -41,9 +41,10 @@
       reference/native-sql
       reference/change-tracking-policies
       reference/partial-objects
+      reference/annotations-reference
+      reference/attributes-reference
       reference/xml-mapping
       reference/yaml-mapping
-      reference/annotations-reference
       reference/php-mapping
       reference/caching
       reference/improving-performance

docs/en/toc.rst

@@ -43,9 +43,10 @@ Reference Guide
    reference/native-sql
    reference/change-tracking-policies
    reference/partial-objects
+   reference/annotations-reference
+   reference/attributes-reference
    reference/xml-mapping
    reference/yaml-mapping
-   reference/annotations-reference
    reference/php-mapping
    reference/caching
    reference/improving-performance

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

@@ -58,9 +58,9 @@ and year of production as primary keys:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="VehicleCatalogue\Model\Car">
@@ -194,9 +194,9 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="Application\Model\ArticleAttribute">
@@ -302,7 +302,7 @@ of products purchased and maybe even the current price.
         private $items;
 
         /** @Column(type="boolean") */
-        private $payed = false;
+        private $paid = false;
         /** @Column(type="boolean") */
         private $shipped = false;
         /** @Column(type="datetime") */

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

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

docs/en/tutorials/getting-started.rst

@@ -82,7 +82,8 @@ that directory with the following contents:
     {
         "require": {
             "doctrine/orm": "^2.6.2",
-            "symfony/yaml": "2.*"
+            "symfony/yaml": "2.*",
+            "symfony/cache": "^5.3"
         },
         "autoload": {
             "psr-0": {"": "src/"}
@@ -138,8 +139,8 @@ step:
     $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 = Setup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
+    // $config = Setup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
 
     // database configuration parameters
     $conn = array(
@@ -235,44 +236,246 @@ entity definition:
         /**
          * @var int
          */
-        protected $id;
+        private $id;
         /**
          * @var string
          */
-        protected $name;
-
-        public function getId()
-        {
-            return $this->id;
-        }
-
-        public function getName()
-        {
-            return $this->name;
-        }
-
-        public function setName($name)
-        {
-            $this->name = $name;
-        }
+        private $name;
     }
 
-When creating entity classes, all of the fields should be ``protected`` or ``private``
-(not ``public``), with getter and setter methods for each one (except ``$id``).
-The use of mutators allows Doctrine to hook into calls which
-manipulate the entities in ways that it could not if you just
-directly set the values with ``entity#field = foo;``
+When creating entity classes, all of the fields should be ``private``.
+
+Use ``protected`` when strictly needed and very rarely if not ever ``public``.
+
+Adding behavior to Entities
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two options to define methods in entities:
+**getters/setters**, or **mutators and DTOs**,
+respectively for **anemic entities** or **rich entities**.
+
+**Anemic entities: Getters and setters**
+
+The most popular method is to create two kinds of methods to
+**read** (getter) and **update** (setter) the object's properties.
 
 The id field has no setter since, generally speaking, your code
 should not set this value since it represents a database id value.
 (Note that Doctrine itself can still set the value using the
 Reflection API instead of a defined setter function.)
 
-The next step for persistence with Doctrine is to describe the
-structure of the ``Product`` entity to Doctrine using a metadata
-language. The metadata language describes how entities, their
-properties and references should be persisted and what constraints
-should be applied to them.
+.. note::
+
+    Doctrine ORM does not use any of the methods you defined: it uses
+    reflection to read and write values to your objects, and will never
+    call methods, not even ``__construct``.
+
+This approach is mostly used when you want to focus on behavior-less
+entities, and when you want to have all your business logic in your
+services rather than in the objects themselves.
+
+Getters and setters are a common convention which makes it possible to
+expose each field of your entity to the external world, while allowing
+you to keep some type safety in place.
+
+Such an approach is a good choice for RAD (rapid application development),
+but may lead to problems later down the road, because providing such an
+easy way to modify any field in your entity means that the entity itself
+cannot guarantee validity of its internal state. Having any object in
+invalid state is dangerous:
+
+- An invalid state can bring bugs in your business logic.
+- The state can be implicitly saved in the database: any forgotten ``flush``
+  can persist the broken state.
+- If persisted, the corrupted data will be retrieved later in your application
+  when the data is loaded again, thereby leading to bugs in your business logic.
+- When bugs occur after corrupted data is persisted, troubleshooting will
+  become much harder, and you might be aware of the bug too late to fix it in a
+  proper manner.
+
+implicitly saved in database, thereby leading to corrupted or inconsistent
+data in your storage, and later in your application when the data is loaded again.
+
+.. note::
+
+    This method, although very common, is inappropriate for Domain Driven
+    Design (`DDD <https://en.wikipedia.org/wiki/Domain-driven_design>`)
+    where methods should represent real business operations and not simple
+    property change, And business invariants should be maintained both in the
+    application state (entities in this case) and in the database, with no
+    space for data corruption.
+
+Here is an example of a simple **anemic entity**:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        class User
+        {
+            private $username;
+            private $passwordHash;
+            private $bans;
+
+            public function getUsername(): string
+            {
+                return $this->username;
+            }
+
+            public function setUsername(string $username): void
+            {
+                $this->username = $username;
+            }
+
+            public function getPasswordHash(): string
+            {
+                return $this->passwordHash;
+            }
+
+            public function setPasswordHash(string $passwordHash): void
+            {
+                $this->passwordHash = $passwordHash;
+            }
+
+            public function getBans(): array
+            {
+                return $this->bans;
+            }
+
+            public function addBan(Ban $ban): void
+            {
+                $this->bans[] = $ban;
+            }
+        }
+
+In the example above, we avoid all possible logic in the entity and only care
+about putting and retrieving data into it without validation (except the one
+provided by type-hints) nor consideration about the object's state.
+
+As Doctrine ORM is a persistence tool for your domain, the state of an object is
+really important. This is why we strongly recommend using rich entities.
+
+**Rich entities: Mutators and DTOs**
+
+We recommend using a rich entity design and rely on more complex mutators,
+and if needed based on DTOs.
+In this design, you should **not** use getters nor setters, and instead,
+implement methods that represent the **behavior** of your domain.
+
+For example, when having a ``User`` entity, we could foresee
+the following kind of optimization.
+
+Example of a rich entity with proper accessors and mutators:
+
+.. configuration-block::
+
+    .. code-block:: php
+        <?php
+        class User
+        {
+            private $banned;
+            private $username;
+            private $passwordHash;
+            private $bans;
+
+            public function toNickname(): string
+            {
+                return $this->username;
+            }
+
+            public function authenticate(string $password, callable $checkHash): bool
+            {
+                return $checkHash($password, $this->passwordHash) && ! $this->hasActiveBans();
+            }
+
+            public function changePassword(string $password, callable $hash): void
+            {
+                $this->passwordHash = $hash($password);
+            }
+
+            public function ban(\DateInterval $duration): void
+            {
+                assert($duration->invert !== 1);
+
+                $this->bans[] = new Ban($this);
+            }
+        }
+
+.. note::
+
+    Please note that this example is only a stub. When going further in the
+    documentation, we will update this object with more behavior and maybe
+    update some methods.
+
+The entities should only mutate state after checking that all business logic
+invariants are being respected.
+Additionally, our entities should never see their state change without
+validation. For example, creating a ``new Product()`` object without any data
+makes it an **invalid object**.
+Rich entities should represent **behavior**, not **data**, therefore
+they should be valid even after a ``__construct()`` call.
+
+To help creating such objects, we can rely on ``DTOs``, and/or make
+our entities always up-to-date. This can be performed with static constructors,
+or rich mutators that accept ``DTOs`` as parameters.
+
+The role of the ``DTO`` is to maintain the entity's state and to help us rely
+upon objects that correctly represent the data that is used to mutate the
+entity.
+
+.. note::
+
+    A `DTO <https://en.wikipedia.org/wiki/Data_transfer_object>` is an object
+    that only carries data without any logic. Its only goal is to be transferred
+    from one service to another.
+    A ``DTO`` often represents data sent by a client and that has to be validated,
+    but can also be used as simple data carrier for other cases.
+
+By using ``DTOs``, if we take our previous ``User`` example, we could create
+a ``ProfileEditingForm`` DTO that will be a plain model, totally unrelated to
+our database, that will be populated via a form and validated.
+Then we can add a new mutator to our ``User``:
+
+.. configuration-block::
+
+    .. code-block:: php
+        <?php
+        class User
+        {
+            public function updateFromProfile(ProfileEditingDTO $profileFormDTO): void
+            {
+                // ...
+            }
+
+            public static function createFromRegistration(UserRegistrationDTO $registrationDTO): self
+            {
+                // ...
+            }
+        }
+
+There are several advantages to using such a model:
+
+* **Entity state is always valid.** Since no setters exist, this means that we
+only update portions of the entity that should already be valid.
+
+* Instead of having plain getters and setters, our entity now has
+**real behavior**: it is much easier to determine the logic in the domain.
+
+* DTOs can be reused in other components, for example deserializing mixed
+content, using forms...
+
+* Classic and static constructors can be used to manage different ways to
+create our objects, and they can also use DTOs.
+
+* Anemic entities tend to isolate the entity from logic, whereas rich
+entities allow putting the logic in the object itself, including data
+validation.
+
+The next step for persistence with Doctrine is to describe the structure of
+the ``Product`` entity to Doctrine using a metadata language. The metadata
+language describes how entities, their properties and references should be
+persisted and what constraints should be applied to them.
 
 Metadata for an Entity can be configured using DocBlock annotations directly
 in the Entity class itself, or in an external XML or YAML file. This Getting
@@ -299,11 +502,11 @@ but you only need to choose one.
              * @ORM\Column(type="integer")
              * @ORM\GeneratedValue
              */
-            protected $id;
+            private $id;
             /**
              * @ORM\Column(type="string")
              */
-            protected $name;
+            private $name;
 
             // .. (other code)
         }
@@ -311,9 +514,9 @@ but you only need to choose one.
     .. code-block:: xml
 
         <!-- config/xml/Product.dcm.xml -->
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Product" table="products">
@@ -494,25 +697,25 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
          * @ORM\GeneratedValue
          * @var int
          */
-        protected $id;
+        private $id;
 
         /**
          * @ORM\Column(type="string")
          * @var string
          */
-        protected $description;
+        private $description;
 
         /**
          * @ORM\Column(type="datetime")
          * @var DateTime
          */
-        protected $created;
+        private $created;
 
         /**
          * @ORM\Column(type="string")
          * @var string
          */
-        protected $status;
+        private $status;
 
         public function getId()
         {
@@ -569,13 +772,13 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
          * @ORM\Column(type="integer")
          * @var int
          */
-        protected $id;
+        private $id;
 
         /**
          * @ORM\Column(type="string")
          * @var string
          */
-        protected $name;
+        private $name;
 
         public function getId()
         {
@@ -622,7 +825,7 @@ domain model to match the requirements:
     {
         // ... (previous code)
 
-        protected $products;
+        private $products;
 
         public function __construct()
         {
@@ -640,8 +843,8 @@ domain model to match the requirements:
     {
         // ... (previous code)
 
-        protected $reportedBugs;
-        protected $assignedBugs;
+        private $reportedBugs;
+        private $assignedBugs;
 
         public function __construct()
         {
@@ -716,8 +919,8 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        protected $engineer;
-        protected $reporter;
+        private $engineer;
+        private $reporter;
 
         public function setEngineer(User $engineer)
         {
@@ -750,8 +953,8 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        protected $reportedBugs;
-        protected $assignedBugs;
+        private $reportedBugs;
+        private $assignedBugs;
 
         public function addReportedBug(Bug $bug)
         {
@@ -802,7 +1005,7 @@ the database that points from Bugs to Products.
     {
         // ... (previous code)
 
-        protected $products;
+        private $products;
 
         public function assignToProduct(Product $product)
         {
@@ -838,37 +1041,37 @@ the ``Product`` before:
              * @ORM\Column(type="integer")
              * @ORM\GeneratedValue
              */
-            protected $id;
+            private $id;
 
             /**
              * @ORM\Column(type="string")
              */
-            protected $description;
+            private $description;
 
             /**
              * @ORM\Column(type="datetime")
              */
-            protected $created;
+            private $created;
 
             /**
              * @ORM\Column(type="string")
              */
-            protected $status;
+            private $status;
 
             /**
              * @ORM\ManyToOne(targetEntity="User", inversedBy="assignedBugs")
              */
-            protected $engineer;
+            private $engineer;
 
             /**
              * @ORM\ManyToOne(targetEntity="User", inversedBy="reportedBugs")
              */
-            protected $reporter;
+            private $reporter;
 
             /**
              * @ORM\ManyToMany(targetEntity="Product")
              */
-            protected $products;
+            private $products;
 
             // ... (other code)
         }
@@ -876,9 +1079,9 @@ the ``Product`` before:
     .. code-block:: xml
 
         <!-- config/xml/Bug.dcm.xml -->
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Bug" table="bugs">
@@ -976,25 +1179,25 @@ Finally, we'll add metadata mappings for the ``User`` entity.
              * @ORM\Column(type="integer")
              * @var int
              */
-            protected $id;
+            private $id;
 
             /**
              * @ORM\Column(type="string")
              * @var string
              */
-            protected $name;
+            private $name;
 
             /**
              * @ORM\OneToMany(targetEntity="Bug", mappedBy="reporter")
              * @var Bug[] An ArrayCollection of Bug objects.
              */
-            protected $reportedBugs;
+            private $reportedBugs;
 
             /**
              * @ORM\OneToMany(targetEntity="Bug", mappedBy="engineer")
              * @var Bug[] An ArrayCollection of Bug objects.
              */
-            protected $assignedBugs;
+            private $assignedBugs;
 
             // .. (other code)
         }
@@ -1002,9 +1205,9 @@ Finally, we'll add metadata mappings for the ``User`` entity.
     .. code-block:: xml
 
         <!-- config/xml/User.dcm.xml -->
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="User" table="users">
@@ -1188,9 +1391,9 @@ The console output of this script is then:
     use-case. Don't we use an ORM to get rid of all the endless
     hand-writing of SQL? Doctrine introduces DQL which is best
     described as **object-query-language** and is a dialect of
-    `OQL <http://en.wikipedia.org/wiki/Object_Query_Language>`_ and
+    `OQL <https://en.wikipedia.org/wiki/Object_Query_Language>`_ and
     similar to `HQL <http://www.hibernate.org>`_ or
-    `JPQL <http://en.wikipedia.org/wiki/Java_Persistence_Query_Language>`_.
+    `JPQL <https://en.wikipedia.org/wiki/Java_Persistence_Query_Language>`_.
     It does not know the concept of columns and tables, but only those
     of Entity-Class and property. Using the Metadata we defined before
     it allows for very short distinctive and powerful queries.
@@ -1444,7 +1647,7 @@ Entity Repositories
 For now we have not discussed how to separate the Doctrine query logic from your model.
 In Doctrine 1 there was the concept of ``Doctrine_Table`` instances for this
 separation. The similar concept in Doctrine2 is called Entity Repositories, integrating
-the `repository pattern <http://martinfowler.com/eaaCatalog/repository.html>`_ at the heart of Doctrine.
+the `repository pattern <https://martinfowler.com/eaaCatalog/repository.html>`_ at the heart of Doctrine.
 
 Every Entity uses a default repository by default and offers a bunch of convenience
 methods that you can use to query for instances of that Entity. Take for example
@@ -1540,14 +1743,14 @@ we have to adjust the metadata slightly.
          **/
         class Bug
         {
-            //...
+            // ...
         }
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Bug" table="bugs" repository-class="BugRepository">

docs/en/tutorials/pagination.rst

@@ -39,3 +39,7 @@ collection. You can disable this behavior by setting the
 ``$fetchJoinCollection`` flag to ``false``; in that case only 2 instead of the 3 queries
 described are executed. We hope to automate the detection for this in
 the future.
+
+.. note::
+
+    ``$fetchJoinCollection`` flag set to ``true`` might affect results if you use aggregations in your query.

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

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

doctrine-mapping.xsd

@@ -309,7 +309,7 @@
 
   <xs:complexType name="embedded">
     <xs:attribute name="name" type="xs:string" use="required" />
-    <xs:attribute name="class" type="orm:fqcn" use="required" />
+    <xs:attribute name="class" type="orm:fqcn" use="optional" />
     <xs:attribute name="column-prefix" type="xs:string" use="optional" />
     <xs:attribute name="use-column-prefix" type="xs:boolean" default="true" use="optional" />
   </xs:complexType>
@@ -332,7 +332,8 @@
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:sequence>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional"/>
-    <xs:attribute name="columns" type="xs:string" use="required"/>
+    <xs:attribute name="columns" type="xs:string" use="optional"/>
+    <xs:attribute name="fields" type="xs:string" use="optional"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
@@ -351,6 +352,7 @@
     </xs:sequence>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional"/>
     <xs:attribute name="columns" type="xs:string" use="required"/>
+    <xs:attribute name="fields" type="xs:string" use="optional"/>
     <xs:attribute name="flags" type="xs:string" use="optional"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
@@ -539,7 +541,7 @@
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:sequence>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
-    <xs:attribute name="target-entity" type="xs:string" use="required" />
+    <xs:attribute name="target-entity" type="xs:string" />
     <xs:attribute name="inversed-by" type="xs:NMTOKEN" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />
     <xs:anyAttribute namespace="##other"/>
@@ -557,7 +559,7 @@
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:sequence>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
-    <xs:attribute name="target-entity" type="xs:string" use="required" />
+    <xs:attribute name="target-entity" type="xs:string" />
     <xs:attribute name="mapped-by" type="xs:NMTOKEN" />
     <xs:attribute name="inversed-by" type="xs:NMTOKEN" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />

lib/Doctrine/ORM/AbstractQuery.php

@@ -24,7 +24,8 @@ use Countable;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
-use Doctrine\DBAL\Driver\Statement;
+use Doctrine\DBAL\Driver\ResultStatement;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\Logging\CacheLogger;
 use Doctrine\ORM\Cache\QueryCacheKey;
 use Doctrine\ORM\Cache\TimestampCacheKey;
@@ -49,9 +50,6 @@ use function ksort;
 use function reset;
 use function serialize;
 use function sha1;
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
 
 /**
  * Base contract for ORM queries. Base class for Query and NativeQuery.
@@ -123,7 +121,7 @@ abstract class AbstractQuery
      */
     protected $_hydrationMode = self::HYDRATE_OBJECT;
 
-    /** @var QueryCacheProfile */
+    /** @var QueryCacheProfile|null */
     protected $_queryCacheProfile;
 
     /**
@@ -289,7 +287,7 @@ abstract class AbstractQuery
     /**
      * Retrieves the associated EntityManager of this Query instance.
      *
-     * @return EntityManager
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {
@@ -314,6 +312,7 @@ abstract class AbstractQuery
      * Get all defined parameters.
      *
      * @return ArrayCollection The defined query parameters.
+     * @psalm-return ArrayCollection<int, Parameter>
      */
     public function getParameters()
     {
@@ -325,7 +324,7 @@ abstract class AbstractQuery
      *
      * @param mixed $key The key (index or name) of the bound parameter.
      *
-     * @return Query\Parameter|null The value of the bound parameter, or NULL if not available.
+     * @return Parameter|null The value of the bound parameter, or NULL if not available.
      */
     public function getParameter($key)
     {
@@ -346,10 +345,9 @@ abstract class AbstractQuery
      * Sets a collection of query parameters.
      *
      * @param ArrayCollection|mixed[] $parameters
+     * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
      *
      * @return static This query instance.
-     *
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
      */
     public function setParameters($parameters)
     {
@@ -402,10 +400,9 @@ abstract class AbstractQuery
      * @param mixed $value
      *
      * @return mixed[]|string|int|float|bool
+     * @psalm-return array|scalar
      *
      * @throws ORMInvalidArgumentException
-     *
-     * @psalm-return array|scalar
      */
     public function processParameterValue($value)
     {
@@ -509,10 +506,8 @@ abstract class AbstractQuery
 
     /**
      * Allows to translate entity namespaces to full qualified names.
-     *
-     * @return void
      */
-    private function translateNamespaces(Query\ResultSetMapping $rsm)
+    private function translateNamespaces(Query\ResultSetMapping $rsm): void
     {
         $translate = function ($alias): string {
             return $this->_em->getClassMetadata($alias)->getName();
@@ -593,6 +588,7 @@ abstract class AbstractQuery
      */
     public function setResultCacheDriver($resultCacheDriver = null)
     {
+        /** @phpstan-ignore-next-line */
         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
             throw ORMException::invalidResultCacheDriver();
         }
@@ -626,9 +622,9 @@ abstract class AbstractQuery
      *
      * @deprecated 2.7 Use {@see enableResultCache} and {@see disableResultCache} instead.
      *
-     * @param bool   $useCache
-     * @param int    $lifetime
-     * @param string $resultCacheId
+     * @param bool   $useCache      Whether or not to cache the results of this query.
+     * @param int    $lifetime      How long the cache entry is valid, in seconds.
+     * @param string $resultCacheId ID to use for the cache entry.
      *
      * @return static This query instance.
      */
@@ -671,7 +667,7 @@ abstract class AbstractQuery
     /**
      * Defines how long the result cache will be active before expire.
      *
-     * @param int|null $lifetime How long the cache entry is valid.
+     * @param int|null $lifetime How long the cache entry is valid, in seconds.
      *
      * @return static This query instance.
      */
@@ -723,7 +719,7 @@ abstract class AbstractQuery
     }
 
     /**
-     * @return QueryCacheProfile
+     * @return QueryCacheProfile|null
      */
     public function getQueryCacheProfile()
     {
@@ -860,7 +856,7 @@ abstract class AbstractQuery
      * @return mixed
      *
      * @throws NonUniqueResultException If the query result is not unique.
-     * @throws NoResultException        If the query returned no result and hydration mode is not HYDRATE_SINGLE_SCALAR.
+     * @throws NoResultException        If the query returned no result.
      */
     public function getSingleResult($hydrationMode = null)
     {
@@ -890,6 +886,7 @@ abstract class AbstractQuery
      *
      * @throws NoResultException        If the query returned no result.
      * @throws NonUniqueResultException If the query result is not unique.
+     * @throws NoResultException        If the query returned no result.
      */
     public function getSingleScalarResult()
     {
@@ -949,7 +946,7 @@ abstract class AbstractQuery
      * Executes the query and returns an IterableResult that can be used to incrementally
      * iterate over the result.
      *
-     * @deprecated
+     * @deprecated 2.8 Use {@see toIterable} instead. See https://github.com/doctrine/orm/issues/8463
      *
      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
      * @param string|int|null              $hydrationMode The hydration mode to use.
@@ -958,9 +955,11 @@ abstract class AbstractQuery
      */
     public function iterate($parameters = null, $hydrationMode = null)
     {
-        @trigger_error(
-            'Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
-            E_USER_DEPRECATED
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8463',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
+            __METHOD__
         );
 
         if ($hydrationMode !== null) {
@@ -981,8 +980,9 @@ abstract class AbstractQuery
      * Executes the query and returns an iterable that can be used to incrementally
      * iterate over the result.
      *
-     * @param ArrayCollection|mixed[] $parameters    The query parameters.
-     * @param string|int|null         $hydrationMode The hydration mode to use.
+     * @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
      *
      * @return iterable<mixed>
      */
@@ -1015,6 +1015,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
      *
      * @return mixed
      */
@@ -1032,6 +1033,7 @@ abstract class AbstractQuery
      *
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
+     * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
      *
      * @return mixed
      */
@@ -1045,7 +1047,7 @@ abstract class AbstractQuery
             $this->setParameters($parameters);
         }
 
-        $setCacheEntry = static function (): void {
+        $setCacheEntry = static function ($data): void {
         };
 
         if ($this->_hydrationCacheProfile !== null) {
@@ -1091,6 +1093,7 @@ abstract class AbstractQuery
      *
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
+     * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
      *
      * @return mixed
      */
@@ -1129,10 +1132,7 @@ abstract class AbstractQuery
         return $result;
     }
 
-    /**
-     * @return TimestampCacheKey|null
-     */
-    private function getTimestampKey()
+    private function getTimestampKey(): ?TimestampCacheKey
     {
         $entityName = reset($this->_resultSetMapping->aliasMap);
 
@@ -1203,7 +1203,9 @@ abstract class AbstractQuery
     /**
      * Executes the query and returns a the resulting Statement object.
      *
-     * @return Statement The executed database statement that holds the results.
+     * @return ResultStatement|int The executed database statement that holds
+     *                             the results, or an integer indicating how
+     *                             many rows were affected.
      */
     abstract protected function _doExecute();
 

lib/Doctrine/ORM/Cache/CacheConfiguration.php

@@ -63,6 +63,9 @@ class CacheConfiguration
          return $this->cacheLogger;
     }
 
+    /**
+     * @return void
+     */
     public function setCacheLogger(CacheLogger $logger)
     {
         $this->cacheLogger = $logger;
@@ -80,6 +83,9 @@ class CacheConfiguration
         return $this->regionsConfig;
     }
 
+    /**
+     * @return void
+     */
     public function setRegionsConfiguration(RegionsConfiguration $regionsConfig)
     {
         $this->regionsConfig = $regionsConfig;
@@ -99,6 +105,9 @@ class CacheConfiguration
          return $this->queryValidator;
     }
 
+    /**
+     * @return void
+     */
     public function setQueryValidator(QueryCacheValidator $validator)
     {
         $this->queryValidator = $validator;

lib/Doctrine/ORM/Cache/CollectionHydrator.php

@@ -30,9 +30,9 @@ use Doctrine\ORM\PersistentCollection;
 interface CollectionHydrator
 {
     /**
-     * @param ClassMetadata      $metadata   The entity metadata.
-     * @param CollectionCacheKey $key        The cached collection key.
-     * @param mixed[]|Collection $collection The collection.
+     * @param ClassMetadata            $metadata   The entity metadata.
+     * @param CollectionCacheKey       $key        The cached collection key.
+     * @param array|mixed[]|Collection $collection The collection.
      *
      * @return CollectionCacheEntry
      */

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -48,7 +48,7 @@ class DefaultCache implements Cache
     /** @var QueryCache[] */
     private $queryCaches = [];
 
-    /** @var QueryCache */
+    /** @var QueryCache|null */
     private $defaultQueryCache;
 
     public function __construct(EntityManagerInterface $em)
@@ -278,10 +278,8 @@ class DefaultCache implements Cache
      /**
       * @param ClassMetadata $metadata   The entity metadata.
       * @param mixed         $identifier The entity identifier.
-      *
-      * @return EntityCacheKey
       */
-    private function buildEntityCacheKey(ClassMetadata $metadata, $identifier)
+    private function buildEntityCacheKey(ClassMetadata $metadata, $identifier): EntityCacheKey
     {
         if (! is_array($identifier)) {
             $identifier = $this->toIdentifierArray($metadata, $identifier);
@@ -294,11 +292,12 @@ 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.
-     *
-     * @return CollectionCacheKey
      */
-    private function buildCollectionCacheKey(ClassMetadata $metadata, $association, $ownerIdentifier)
-    {
+    private function buildCollectionCacheKey(
+        ClassMetadata $metadata,
+        string $association,
+        $ownerIdentifier
+    ): CollectionCacheKey {
         if (! is_array($ownerIdentifier)) {
             $ownerIdentifier = $this->toIdentifierArray($metadata, $ownerIdentifier);
         }
@@ -312,7 +311,7 @@ class DefaultCache implements Cache
      *
      * @return array<string, mixed>
      */
-    private function toIdentifierArray(ClassMetadata $metadata, $identifier)
+    private function toIdentifierArray(ClassMetadata $metadata, $identifier): array
     {
         if (is_object($identifier) && $this->em->getMetadataFactory()->hasMetadataFor(ClassUtils::getClass($identifier))) {
             $identifier = $this->uow->getSingleIdentifierValue($identifier);

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -70,6 +70,8 @@ class DefaultCacheFactory implements CacheFactory
 
     /**
      * @param string $fileLockRegionDirectory
+     *
+     * @return void
      */
     public function setFileLockRegionDirectory($fileLockRegionDirectory)
     {
@@ -84,11 +86,17 @@ class DefaultCacheFactory implements CacheFactory
         return $this->fileLockRegionDirectory;
     }
 
+    /**
+     * @return void
+     */
     public function setRegion(Region $region)
     {
         $this->regions[$region->getName()] = $region;
     }
 
+    /**
+     * @return void
+     */
     public function setTimestampRegion(TimestampRegion $region)
     {
         $this->timestampRegion = $region;
@@ -111,6 +119,10 @@ class DefaultCacheFactory implements CacheFactory
         }
 
         if ($usage === ClassMetadata::CACHE_USAGE_READ_WRITE) {
+            if (! $region instanceof ConcurrentRegion) {
+                throw new InvalidArgumentException(sprintf('Unable to use access strategy type of [%s] without a ConcurrentRegion', $usage));
+            }
+
             return new ReadWriteCachedEntityPersister($persister, $region, $em, $metadata);
         }
 
@@ -134,6 +146,10 @@ class DefaultCacheFactory implements CacheFactory
         }
 
         if ($usage === ClassMetadata::CACHE_USAGE_READ_WRITE) {
+            if (! $region instanceof ConcurrentRegion) {
+                throw new InvalidArgumentException(sprintf('Unable to use access strategy type of [%s] without a ConcurrentRegion', $usage));
+            }
+
             return new ReadWriteCachedCollectionPersister($persister, $region, $em, $mapping);
         }
 
@@ -201,18 +217,13 @@ class DefaultCacheFactory implements CacheFactory
             }
 
             $directory = $this->fileLockRegionDirectory . DIRECTORY_SEPARATOR . $cache['region'];
-            $region    = new FileLockRegion($region, $directory, $this->regionsConfig->getLockLifetime($cache['region']));
+            $region    = new FileLockRegion($region, $directory, (string) $this->regionsConfig->getLockLifetime($cache['region']));
         }
 
         return $this->regions[$cache['region']] = $region;
     }
 
-    /**
-     * @param string $name
-     *
-     * @return CacheAdapter
-     */
-    private function createRegionCache($name)
+    private function createRegionCache(string $name): CacheAdapter
     {
         $cacheAdapter = clone $this->cache;
 

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -345,10 +345,9 @@ class DefaultQueryCache implements QueryCache
      * @param mixed               $assocValue
      *
      * @return mixed[]|null
-     *
-     * @psalm-return array{targetEntity: string, type: mixed, list?: array[], identifier?: array}|null
+     * @psalm-return array{targetEntity: class-string, type: mixed, list?: array[], identifier?: array}|null
      */
-    private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocValue)
+    private function storeAssociationCache(QueryCacheKey $key, array $assoc, $assocValue): ?array
     {
         $assocPersister = $this->uow->getEntityPersister($assoc['targetEntity']);
         $assocMetadata  = $assocPersister->getClassMetadata();
@@ -398,13 +397,15 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * @param string $assocAlias
      * @param object $entity
      *
      * @return array<object>|object
      */
-    private function getAssociationValue(ResultSetMapping $rsm, $assocAlias, $entity)
-    {
+    private function getAssociationValue(
+        ResultSetMapping $rsm,
+        string $assocAlias,
+        $entity
+    ) {
         $path  = [];
         $alias = $assocAlias;
 
@@ -441,7 +442,7 @@ class DefaultQueryCache implements QueryCache
             return null;
         }
 
-        if (empty($path)) {
+        if ($path === []) {
             return $value;
         }
 

lib/Doctrine/ORM/Cache/EntityCacheEntry.php

@@ -40,12 +40,14 @@ class EntityCacheEntry implements CacheEntry
      * READ-ONLY: Public only for performance reasons, it should be considered immutable.
      *
      * @var string The entity class name
+     * @psalm-var class-string
      */
     public $class;
 
     /**
      * @param string              $class The entity class.
      * @param array<string,mixed> $data  The entity data.
+     * @psalm-param class-string $class
      */
     public function __construct($class, array $data)
     {

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

@@ -34,6 +34,8 @@ class CacheLoggerChain implements CacheLogger
 
     /**
      * @param string $name
+     *
+     * @return void
      */
     public function setLogger($name, CacheLogger $logger)
     {

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

@@ -194,6 +194,8 @@ class StatisticsCacheLogger implements CacheLogger
      * Clear region statistics
      *
      * @param string $regionName The name of the cache region.
+     *
+     * @return void
      */
     public function clearRegionStats($regionName)
     {
@@ -204,6 +206,8 @@ class StatisticsCacheLogger implements CacheLogger
 
     /**
      * Clear all statistics
+     *
+     * @return void
      */
     public function clearStats()
     {

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

@@ -72,7 +72,7 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     /** @var CollectionHydrator */
     protected $hydrator;
 
-    /** @var CacheLogger */
+    /** @var CacheLogger|null */
     protected $cacheLogger;
 
     /**
@@ -239,6 +239,8 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
 
     /**
      * Clears cache entries related to the current collection
+     *
+     * @return void
      */
     protected function evictCollectionCache(PersistentCollection $collection)
     {
@@ -258,6 +260,8 @@ abstract class AbstractCollectionPersister implements CachedCollectionPersister
     /**
      * @param string $targetEntity
      * @param object $element
+     *
+     * @return void
      */
     protected function evictElementCache($targetEntity, $element)
     {

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

@@ -52,7 +52,7 @@ interface CachedCollectionPersister extends CachedPersister, CollectionPersister
     /**
      * Stores a collection into cache
      *
-     * @param mixed[]|Collection $elements
+     * @param array|mixed[]|Collection $elements
      *
      * @return void
      */

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

@@ -75,7 +75,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     /** @var Cache */
     protected $cache;
 
-    /** @var CacheLogger */
+    /** @var CacheLogger|null */
     protected $cacheLogger;
 
     /** @var string */
@@ -226,7 +226,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
     /**
      * @param object $entity
      */
-    private function storeJoinedAssociations($entity)
+    private function storeJoinedAssociations($entity): void
     {
         if ($this->joinedAssociations === null) {
             $associations = [];
@@ -344,7 +344,7 @@ abstract class AbstractEntityPersister implements CachedEntityPersister
      */
     public function load(array $criteria, $entity = null, $assoc = null, array $hints = [], $lockMode = null, $limit = null, ?array $orderBy = null)
     {
-        if ($entity !== null || $assoc !== null || ! empty($hints) || $lockMode !== null) {
+        if ($entity !== null || $assoc !== null || $hints !== [] || $lockMode !== null) {
             return $this->persister->load($criteria, $entity, $assoc, $hints, $lockMode, $limit, $orderBy);
         }
 

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

@@ -100,17 +100,14 @@ class NonStrictReadWriteCachedEntityPersister extends AbstractEntityPersister
 
     /**
      * @param object $entity
-     * @param bool   $isChanged
-     *
-     * @return bool
      */
-    private function updateCache($entity, $isChanged)
+    private function updateCache($entity, bool $isChanged): bool
     {
         $class     = $this->metadataFactory->getMetadataFor(get_class($entity));
         $key       = new EntityCacheKey($class->rootEntityName, $this->uow->getEntityIdentifier($entity));
         $entry     = $this->hydrator->buildCacheEntry($class, $key, $entity);
         $cached    = $this->region->put($key, $entry);
-        $isChanged = $isChanged ?: $cached;
+        $isChanged = $isChanged || $cached;
 
         if ($this->cacheLogger && $cached) {
             $this->cacheLogger->entityCachePut($this->regionName, $key);

lib/Doctrine/ORM/Cache/Region.php

@@ -57,7 +57,7 @@ interface Region extends MultiGetRegion
      *
      * @param CacheKey   $key   The key under which to cache the item.
      * @param CacheEntry $entry The entry to cache.
-     * @param Lock       $lock  The lock previously obtained.
+     * @param Lock|null  $lock  The lock previously obtained.
      *
      * @throws CacheException Indicates a problem accessing the region.
      */

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

@@ -129,6 +129,8 @@ class DefaultRegion implements Region
 
     /**
      * {@inheritdoc}
+     *
+     * @return bool
      */
     public function put(CacheKey $key, CacheEntry $entry, ?Lock $lock = null)
     {
@@ -137,6 +139,8 @@ class DefaultRegion implements Region
 
     /**
      * {@inheritdoc}
+     *
+     * @return bool
      */
     public function evict(CacheKey $key)
     {
@@ -145,6 +149,8 @@ class DefaultRegion implements Region
 
     /**
      * {@inheritdoc}
+     *
+     * @return bool
      */
     public function evictAll()
     {

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

@@ -63,8 +63,8 @@ class FileLockRegion implements ConcurrentRegion
     private $lockLifetime;
 
     /**
-     * @param string $directory
-     * @param string $lockLifetime
+     * @param string         $directory
+     * @param numeric-string $lockLifetime
      *
      * @throws InvalidArgumentException
      */
@@ -83,10 +83,7 @@ class FileLockRegion implements ConcurrentRegion
         $this->lockLifetime = $lockLifetime;
     }
 
-    /**
-     * @return bool
-     */
-    private function isLocked(CacheKey $key, ?Lock $lock = null)
+    private function isLocked(CacheKey $key, ?Lock $lock = null): bool
     {
         $filename = $this->getLockFileName($key);
 
@@ -117,30 +114,23 @@ class FileLockRegion implements ConcurrentRegion
         return true;
     }
 
-    /**
-     * @return string
-     */
-    private function getLockFileName(CacheKey $key)
+    private function getLockFileName(CacheKey $key): string
     {
         return $this->directory . DIRECTORY_SEPARATOR . $key->hash . '.' . self::LOCK_EXTENSION;
     }
 
     /**
-     * @param string $filename
-     *
-     * @return string
+     * @return string|false
      */
-    private function getLockContent($filename)
+    private function getLockContent(string $filename)
     {
         return @file_get_contents($filename);
     }
 
     /**
-     * @param string $filename
-     *
-     * @return int
+     * @return int|false
      */
-    private function getLockTime($filename)
+    private function getLockTime(string $filename)
     {
         return @fileatime($filename);
     }

lib/Doctrine/ORM/Cache/RegionsConfiguration.php

@@ -57,6 +57,8 @@ class RegionsConfiguration
 
     /**
      * @param int $defaultLifetime
+     *
+     * @return void
      */
     public function setDefaultLifetime($defaultLifetime)
     {
@@ -73,6 +75,8 @@ class RegionsConfiguration
 
     /**
      * @param int $defaultLockLifetime
+     *
+     * @return void
      */
     public function setDefaultLockLifetime($defaultLockLifetime)
     {
@@ -92,6 +96,8 @@ class RegionsConfiguration
     /**
      * @param string $name
      * @param int    $lifetime
+     *
+     * @return void
      */
     public function setLifetime($name, $lifetime)
     {
@@ -111,6 +117,8 @@ class RegionsConfiguration
     /**
      * @param string $name
      * @param int    $lifetime
+     *
+     * @return void
      */
     public function setLockLifetime($name, $lifetime)
     {

lib/Doctrine/ORM/Cache/TimestampQueryCacheValidator.php

@@ -48,10 +48,7 @@ class TimestampQueryCacheValidator implements QueryCacheValidator
         return $entry->time + $key->lifetime > microtime(true);
     }
 
-    /**
-     * @return bool
-     */
-    private function regionUpdated(QueryCacheKey $key, QueryCacheEntry $entry)
+    private function regionUpdated(QueryCacheKey $key, QueryCacheEntry $entry): bool
     {
         if ($key->timestampKey === null) {
             return false;

lib/Doctrine/ORM/Configuration.php

@@ -26,7 +26,10 @@ use Doctrine\Common\Annotations\CachedReader;
 use Doctrine\Common\Annotations\SimpleAnnotationReader;
 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\Proxy\AbstractProxyFactory;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache\CacheConfiguration;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\Mapping\DefaultEntityListenerResolver;
@@ -41,8 +44,10 @@ use Doctrine\ORM\Repository\DefaultRepositoryFactory;
 use Doctrine\ORM\Repository\RepositoryFactory;
 use Doctrine\Persistence\Mapping\Driver\MappingDriver;
 use Doctrine\Persistence\ObjectRepository;
+use Psr\Cache\CacheItemPoolInterface;
 use ReflectionClass;
 
+use function class_exists;
 use function strtolower;
 use function trim;
 
@@ -150,11 +155,11 @@ 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.
      *
-     * @param bool $useSimpleAnnotationReader
+     * @param string|string[] $paths
+     * @param bool            $useSimpleAnnotationReader
+     * @psalm-param string|list<string> $paths
      *
      * @return AnnotationDriver
-     *
-     * @psalm-param string|list<string> $paths
      */
     public function newDefaultAnnotationDriver($paths = [], $useSimpleAnnotationReader = true)
     {
@@ -164,13 +169,16 @@ class Configuration extends \Doctrine\DBAL\Configuration
             // Register the ORM Annotations in the AnnotationRegistry
             $reader = new SimpleAnnotationReader();
             $reader->addNamespace('Doctrine\ORM\Mapping');
-            $cachedReader = new CachedReader($reader, new ArrayCache());
+        } else {
+            $reader = new AnnotationReader();
+        }
 
-            return new AnnotationDriver($cachedReader, (array) $paths);
+        if (class_exists(ArrayCache::class)) {
+            $reader = new CachedReader($reader, new ArrayCache());
         }
 
         return new AnnotationDriver(
-            new CachedReader(new AnnotationReader(), new ArrayCache()),
+            $reader,
             (array) $paths
         );
     }
@@ -209,9 +217,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Sets the entity alias map.
      *
-     * @return void
-     *
      * @psalm-param array<string, string> $entityNamespaces
+     *
+     * @return void
      */
     public function setEntityNamespaces(array $entityNamespaces)
     {
@@ -283,21 +291,55 @@ class Configuration extends \Doctrine\DBAL\Configuration
     /**
      * Gets the cache driver implementation that is used for metadata caching.
      *
+     * @deprecated Deprecated in favor of getMetadataCache
+     *
      * @return CacheDriver|null
      */
     public function getMetadataCacheImpl()
     {
-        return $this->_attributes['metadataCacheImpl'] ?? null;
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8650',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use getMetadataCache() instead.',
+            __METHOD__
+        );
+
+        if (isset($this->_attributes['metadataCacheImpl'])) {
+            return $this->_attributes['metadataCacheImpl'];
+        }
+
+        return isset($this->_attributes['metadataCache']) ? DoctrineProvider::wrap($this->_attributes['metadataCache']) : null;
     }
 
     /**
      * Sets the cache driver implementation that is used for metadata caching.
      *
+     * @deprecated Deprecated in favor of setMetadataCache
+     *
      * @return void
      */
     public function setMetadataCacheImpl(CacheDriver $cacheImpl)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8650',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use setMetadataCache() instead.',
+            __METHOD__
+        );
+
         $this->_attributes['metadataCacheImpl'] = $cacheImpl;
+        $this->_attributes['metadataCache']     = CacheAdapter::wrap($cacheImpl);
+    }
+
+    public function getMetadataCache(): ?CacheItemPoolInterface
+    {
+        return $this->_attributes['metadataCache'] ?? null;
+    }
+
+    public function setMetadataCache(CacheItemPoolInterface $cache): void
+    {
+        $this->_attributes['metadataCache']     = $cache;
+        $this->_attributes['metadataCacheImpl'] = DoctrineProvider::wrap($cache);
     }
 
     /**
@@ -350,13 +392,11 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name The name of the query.
      *
-     * @throws ORMException
+     * @return mixed[]
+     * @psalm-return array{string, ResultSetMapping} A tuple with the first element being the SQL string and the second
+     *                                               element being the ResultSetMapping.
      *
-     * @psalm-return array{string, ResultSetMapping} A tuple with the first
-     *                                               element being the SQL
-     *                                               string and the second
-     *                                               element being the
-     *                                               ResultSetMapping.
+     * @throws ORMException
      */
     public function getNamedNativeQuery($name)
     {
@@ -388,19 +428,19 @@ class Configuration extends \Doctrine\DBAL\Configuration
             throw ORMException::queryCacheUsesNonPersistentCache($queryCacheImpl);
         }
 
-        $metadataCacheImpl = $this->getMetadataCacheImpl();
+        if ($this->getAutoGenerateProxyClasses()) {
+            throw ORMException::proxyClassesAlwaysRegenerating();
+        }
 
-        if (! $metadataCacheImpl) {
+        if (! $this->getMetadataCache()) {
             throw ORMException::metadataCacheNotConfigured();
         }
 
+        $metadataCacheImpl = $this->getMetadataCacheImpl();
+
         if ($metadataCacheImpl instanceof ArrayCache) {
             throw ORMException::metadataCacheUsesNonPersistentCache($metadataCacheImpl);
         }
-
-        if ($this->getAutoGenerateProxyClasses()) {
-            throw ORMException::proxyClassesAlwaysRegenerating();
-        }
     }
 
     /**
@@ -426,7 +466,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
-     *
      * @psalm-return ?class-string
      */
     public function getCustomStringFunction($name)
@@ -444,10 +483,10 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * Any previously added string functions are discarded.
      *
-     * @return void
-     *
      * @psalm-param array<string, class-string> $functions The map of custom
      *                                                     DQL string functions.
+     *
+     * @return void
      */
     public function setCustomStringFunctions(array $functions)
     {
@@ -479,7 +518,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
-     *
      * @psalm-return ?class-string
      */
     public function getCustomNumericFunction($name)
@@ -497,10 +535,10 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * Any previously added numeric functions are discarded.
      *
-     * @return void
-     *
      * @psalm-param array<string, class-string> $functions The map of custom
      *                                                     DQL numeric functions.
+     *
+     * @return void
      */
     public function setCustomNumericFunctions(array $functions)
     {
@@ -518,10 +556,9 @@ 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
      *
      * @return void
-     *
-     * @psalm-param class-string|callable $className
      */
     public function addCustomDatetimeFunction($name, $className)
     {
@@ -534,7 +571,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $name
      *
      * @return string|null
-     *
      * @psalm-return ?class-string $name
      */
     public function getCustomDatetimeFunction($name)
@@ -553,10 +589,9 @@ 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
      *
      * @return void
-     *
-     * @psalm-param array<string, string> $functions
      */
     public function setCustomDatetimeFunctions(array $functions)
     {
@@ -587,7 +622,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * @param string $modeName The hydration mode name.
      *
      * @return string|null The hydrator class name.
-     *
      * @psalm-return ?class-string
      */
     public function getCustomHydrationMode($modeName)
@@ -599,10 +633,10 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Adds a custom hydration mode.
      *
      * @param string $modeName The hydration mode name.
+     * @param string $hydrator The hydrator class name.
+     * @psalm-param class-string $hydrator
      *
      * @return void
-     *
-     * @psalm-param class-string $hydrator The hydrator class name.
      */
     public function addCustomHydrationMode($modeName, $hydrator)
     {
@@ -613,10 +647,9 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Sets a class metadata factory.
      *
      * @param string $cmfName
+     * @psalm-param class-string $cmfName
      *
      * @return void
-     *
-     * @psalm-param class-string $cmfName
      */
     public function setClassMetadataFactoryName($cmfName)
     {
@@ -625,7 +658,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
     /**
      * @return string
-     *
      * @psalm-return class-string
      */
     public function getClassMetadataFactoryName()
@@ -642,6 +674,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name      The name of the filter.
      * @param string $className The class name of the filter.
+     *
+     * @return void
      */
     public function addFilter($name, $className)
     {
@@ -655,7 +689,6 @@ 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
      */
     public function getFilterClassName($name)
@@ -687,7 +720,6 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Get default repository class.
      *
      * @return string
-     *
      * @psalm-return class-string
      */
     public function getDefaultRepositoryClassName()
@@ -745,6 +777,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
     /**
      * Set the entity listener resolver.
+     *
+     * @return void
      */
     public function setEntityListenerResolver(EntityListenerResolver $resolver)
     {
@@ -767,6 +801,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
 
     /**
      * Set the entity repository factory.
+     *
+     * @return void
      */
     public function setRepositoryFactory(RepositoryFactory $repositoryFactory)
     {
@@ -835,6 +871,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      * Sets array of query hints, which will be applied to every query in application
      *
      * @psalm-param array<string, mixed> $defaultQueryHints
+     *
+     * @return void
      */
     public function setDefaultQueryHints(array $defaultQueryHints)
     {
@@ -858,6 +896,8 @@ class Configuration extends \Doctrine\DBAL\Configuration
      *
      * @param string $name  The name of the hint.
      * @param mixed  $value The value of the hint.
+     *
+     * @return void
      */
     public function setDefaultQueryHint($name, $value)
     {

lib/Doctrine/ORM/EntityManager.php

@@ -21,11 +21,14 @@
 namespace Doctrine\ORM;
 
 use BadMethodCallException;
+use Doctrine\Common\Cache\Psr6\CacheAdapter;
+use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\EventManager;
 use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\LockMode;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\ClassMetadataFactory;
 use Doctrine\ORM\Proxy\ProxyFactory;
@@ -47,10 +50,8 @@ use function is_callable;
 use function is_object;
 use function is_string;
 use function ltrim;
+use function method_exists;
 use function sprintf;
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
 
 /**
  * The EntityManager is the central access point to ORM functionality.
@@ -166,7 +167,8 @@ use const E_USER_DEPRECATED;
 
         $this->metadataFactory = new $metadataFactoryClassName();
         $this->metadataFactory->setEntityManager($this);
-        $this->metadataFactory->setCacheDriver($this->config->getMetadataCacheImpl());
+
+        $this->configureMetadataCache();
 
         $this->repositoryFactory = $config->getRepositoryFactory();
         $this->unitOfWork        = new UnitOfWork($this);
@@ -284,9 +286,7 @@ use const E_USER_DEPRECATED;
      *
      * Internal note: Performance-sensitive method.
      *
-     * @param string $className
-     *
-     * @return ClassMetadata
+     * {@inheritDoc}
      */
     public function getClassMetadata($className)
     {
@@ -365,9 +365,11 @@ use const E_USER_DEPRECATED;
     public function flush($entity = null)
     {
         if ($entity !== null) {
-            @trigger_error(
-                'Calling ' . __METHOD__ . '() with any arguments to flush specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
-                E_USER_DEPRECATED
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/issues/8459',
+                'Calling %s() with any arguments to flush specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                __METHOD__
             );
         }
 
@@ -386,8 +388,10 @@ use const E_USER_DEPRECATED;
      *    during the search.
      * @param int|null $lockVersion The version of the entity to find when using
      * optimistic locking.
+     * @psalm-param class-string<T> $className
      *
      * @return object|null The entity instance or NULL if the entity can not be found.
+     * @psalm-return ?T
      *
      * @throws OptimisticLockException
      * @throws ORMInvalidArgumentException
@@ -395,8 +399,6 @@ use const E_USER_DEPRECATED;
      * @throws ORMException
      *
      * @template T
-     * @psalm-param class-string<T> $className
-     * @psalm-return ?T
      */
     public function find($className, $id, $lockMode = null, $lockVersion = null)
     {
@@ -575,9 +577,11 @@ use const E_USER_DEPRECATED;
         }
 
         if ($entityName !== null) {
-            @trigger_error(
-                'Calling ' . __METHOD__ . '() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
-                E_USER_DEPRECATED
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/issues/8460',
+                'Calling %s() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                __METHOD__
             );
         }
 
@@ -678,8 +682,6 @@ use const E_USER_DEPRECATED;
      * Entities which previously referenced the detached entity will continue to
      * reference it.
      *
-     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
-     *
      * @param object $entity The entity to detach.
      *
      * @return void
@@ -688,8 +690,6 @@ use const E_USER_DEPRECATED;
      */
     public function detach($entity)
     {
-        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
-
         if (! is_object($entity)) {
             throw ORMInvalidArgumentException::invalidObject('EntityManager#detach()', $entity);
         }
@@ -713,7 +713,12 @@ use const E_USER_DEPRECATED;
      */
     public function merge($entity)
     {
-        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8461',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0.',
+            __METHOD__
+        );
 
         if (! is_object($entity)) {
             throw ORMInvalidArgumentException::invalidObject('EntityManager#merge()', $entity);
@@ -729,7 +734,12 @@ use const E_USER_DEPRECATED;
      */
     public function copy($entity, $deep = false)
     {
-        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8462',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0.',
+            __METHOD__
+        );
 
         throw new BadMethodCallException('Not implemented.');
     }
@@ -746,12 +756,12 @@ use const E_USER_DEPRECATED;
      * Gets the repository for an entity class.
      *
      * @param string $entityName The name of the entity.
+     * @psalm-param class-string<T> $entityName
      *
      * @return ObjectRepository|EntityRepository The repository class.
+     * @psalm-return EntityRepository<T>
      *
      * @template T
-     * @psalm-param class-string<T> $entityName
-     * @psalm-return EntityRepository<T>
      */
     public function getRepository($entityName)
     {
@@ -791,11 +801,9 @@ use const E_USER_DEPRECATED;
     /**
      * Throws an exception if the EntityManager is closed or currently not active.
      *
-     * @return void
-     *
      * @throws ORMException If the EntityManager is closed.
      */
-    private function errorIfClosed()
+    private function errorIfClosed(): void
     {
         if ($this->closed) {
             throw ORMException::entityManagerClosed();
@@ -877,9 +885,10 @@ use const E_USER_DEPRECATED;
     /**
      * Factory method to create EntityManager instances.
      *
-     * @param array<string, mixed>|Connection $connection   An array with the connection parameters or an existing Connection instance.
-     * @param Configuration                   $config       The Configuration instance to use.
-     * @param EventManager                    $eventManager The EventManager instance to use.
+     * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
+     * @param Configuration      $config       The Configuration instance to use.
+     * @param EventManager|null  $eventManager The EventManager instance to use.
+     * @psalm-param array<string, mixed>|Connection $connection
      *
      * @return EntityManager The created EntityManager.
      *
@@ -900,9 +909,10 @@ use const E_USER_DEPRECATED;
     /**
      * Factory method to create Connection instances.
      *
-     * @param array<string, mixed>|Connection $connection   An array with the connection parameters or an existing Connection instance.
-     * @param Configuration                   $config       The Configuration instance to use.
-     * @param EventManager                    $eventManager The EventManager instance to use.
+     * @param mixed[]|Connection $connection   An array with the connection parameters or an existing Connection instance.
+     * @param Configuration      $config       The Configuration instance to use.
+     * @param EventManager|null  $eventManager The EventManager instance to use.
+     * @psalm-param array<string, mixed>|Connection $connection
      *
      * @return Connection
      *
@@ -980,4 +990,42 @@ use const E_USER_DEPRECATED;
                 }
         }
     }
+
+    private function configureMetadataCache(): void
+    {
+        $metadataCache = $this->config->getMetadataCache();
+        if (! $metadataCache) {
+            $this->configureLegacyMetadataCache();
+
+            return;
+        }
+
+        // We have a PSR-6 compatible metadata factory. Use cache directly
+        if (method_exists($this->metadataFactory, 'setCache')) {
+            $this->metadataFactory->setCache($metadataCache);
+
+            return;
+        }
+
+        // Wrap PSR-6 cache to provide doctrine/cache interface
+        $this->metadataFactory->setCacheDriver(DoctrineProvider::wrap($metadataCache));
+    }
+
+    private function configureLegacyMetadataCache(): void
+    {
+        $metadataCache = $this->config->getMetadataCacheImpl();
+        if (! $metadataCache) {
+            return;
+        }
+
+        // Metadata factory is not PSR-6 compatible. Use cache directly
+        if (! method_exists($this->metadataFactory, 'setCache')) {
+            $this->metadataFactory->setCacheDriver($metadataCache);
+
+            return;
+        }
+
+        // Wrap doctrine/cache to provide PSR-6 interface
+        $this->metadataFactory->setCache(CacheAdapter::wrap($metadataCache));
+    }
 }

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -34,10 +34,21 @@ use Doctrine\Persistence\ObjectManager;
 /**
  * EntityManager interface
  *
- * @method Mapping\ClassMetadata getClassMetadata($className)
+ * @method Mapping\ClassMetadataFactory getMetadataFactory()
  */
 interface EntityManagerInterface extends ObjectManager
 {
+    /**
+     * {@inheritdoc}
+     *
+     * @psalm-param class-string<T> $className
+     *
+     * @psalm-return EntityRepository<T>
+     *
+     * @template T
+     */
+    public function getRepository($className);
+
     /**
      * Returns the cache API for managing the second level cache regions or NULL if the cache is not enabled.
      *
@@ -155,14 +166,14 @@ interface EntityManagerInterface extends ObjectManager
      *
      * @param string $entityName The name of the entity type.
      * @param mixed  $id         The entity identifier.
+     * @psalm-param class-string<T> $entityName
      *
      * @return object|null The entity reference.
+     * @psalm-return ?T
      *
      * @throws ORMException
      *
      * @template T
-     * @psalm-param class-string<T> $entityName
-     * @psalm-return ?T
      */
     public function getReference($entityName, $id);
 
@@ -305,4 +316,18 @@ interface EntityManagerInterface extends ObjectManager
      * @return bool True, if the EM has a filter collection.
      */
     public function hasFilters();
+
+    /**
+     * {@inheritDoc}
+     *
+     * @psalm-param string|class-string<T> $className
+     * @phpstan-param string $className
+     *
+     * @return Mapping\ClassMetadata
+     * @psalm-return Mapping\ClassMetadata<T>
+     * @phpstan-return Mapping\ClassMetadata<object>
+     *
+     * @psalm-template T of object
+     */
+    public function getClassMetadata($className);
 }

lib/Doctrine/ORM/EntityNotFoundException.php

@@ -21,6 +21,7 @@
 namespace Doctrine\ORM;
 
 use function implode;
+use function sprintf;
 
 /**
  * Exception thrown when a Proxy fails to retrieve an Entity result.
@@ -47,4 +48,17 @@ class EntityNotFoundException extends ORMException
             'Entity of type \'' . $className . '\'' . ($ids ? ' for IDs ' . implode(', ', $ids) : '') . ' was not found'
         );
     }
+
+    /**
+     * Instance for which no identifier can be found
+     *
+     * @psalm-param class-string $className
+     */
+    public static function noIdentifierFound(string $className): self
+    {
+        return new self(sprintf(
+            'Unable to find "%s" entity identifier associated with the UnitOfWork',
+            $className
+        ));
+    }
 }

lib/Doctrine/ORM/EntityRepository.php

@@ -24,6 +24,7 @@ use BadMethodCallException;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Collections\Selectable;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\Inflector\Inflector;
 use Doctrine\Inflector\InflectorFactory;
 use Doctrine\ORM\Mapping\ClassMetadata;
@@ -35,9 +36,6 @@ use function lcfirst;
 use function sprintf;
 use function strpos;
 use function substr;
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
 
 /**
  * An EntityRepository serves as a repository for entities with generic as well as
@@ -66,8 +64,6 @@ class EntityRepository implements ObjectRepository, Selectable
 
     /**
      * Initializes a new <tt>EntityRepository</tt>.
-     *
-     * @psalm-param Mapping\ClassMetadata $class
      */
     public function __construct(EntityManagerInterface $em, Mapping\ClassMetadata $class)
     {
@@ -111,24 +107,44 @@ class EntityRepository implements ObjectRepository, Selectable
     /**
      * Creates a new Query instance based on a predefined metadata named query.
      *
+     * @deprecated
+     *
      * @param string $queryName
      *
      * @return Query
      */
     public function createNamedQuery($queryName)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryName,
+            $this->_class->name
+        );
+
         return $this->_em->createQuery($this->_class->getNamedQuery($queryName));
     }
 
     /**
      * Creates a native SQL query.
      *
+     * @deprecated
+     *
      * @param string $queryName
      *
      * @return NativeQuery
      */
     public function createNativeNamedQuery($queryName)
     {
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8592',
+            'Named Native Queries are deprecated, here "%s" on entity %s. Move the query logic into EntityRepository',
+            $queryName,
+            $this->_class->name
+        );
+
         $queryMapping = $this->_class->getNamedNativeQuery($queryName);
         $rsm          = new Query\ResultSetMappingBuilder($this->_em);
         $rsm->addNamedNativeQueryMapping($this->_class, $queryMapping);
@@ -145,7 +161,12 @@ class EntityRepository implements ObjectRepository, Selectable
      */
     public function clear()
     {
-        @trigger_error('Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0.', E_USER_DEPRECATED);
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8460',
+            'Calling %s() is deprecated and will not be supported in Doctrine ORM 3.0.',
+            __METHOD__
+        );
 
         $this->_em->clear($this->_class->rootEntityName);
     }
@@ -160,7 +181,6 @@ class EntityRepository implements ObjectRepository, Selectable
      * @param int|null $lockVersion The lock version.
      *
      * @return object|null The entity instance or NULL if the entity can not be found.
-     *
      * @psalm-return ?T
      */
     public function find($id, $lockMode = null, $lockVersion = null)
@@ -183,10 +203,11 @@ class EntityRepository implements ObjectRepository, Selectable
      *
      * @param int|null $limit
      * @param int|null $offset
-     *
      * @psalm-param array<string, mixed> $criteria
-     * @psalm-param list<string>|null $orderBy
-     * @psalm-return list<T> The objects.
+     * @psalm-param array<string, string>|null $orderBy
+     *
+     * @return object[] The objects.
+     * @psalm-return list<T>
      */
     public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null)
     {
@@ -198,10 +219,10 @@ class EntityRepository implements ObjectRepository, Selectable
     /**
      * Finds a single entity by a set of criteria.
      *
-     * @return object|null The entity instance or NULL if the entity can not be found.
-     *
      * @psalm-param array<string, mixed> $criteria
      * @psalm-param array<string, string>|null $orderBy
+     *
+     * @return object|null The entity instance or NULL if the entity can not be found.
      * @psalm-return ?T
      */
     public function findOneBy(array $criteria, ?array $orderBy = null)
@@ -214,9 +235,10 @@ class EntityRepository implements ObjectRepository, Selectable
     /**
      * Counts entities by a set of criteria.
      *
+     * @psalm-param array<string, mixed> $criteria
+     *
      * @return int The cardinality of the objects that match the given criteria.
      *
-     * @psalm-param array<string, mixed> $criteria
      * @todo Add this method to `ObjectRepository` interface in the next major release
      */
     public function count(array $criteria)
@@ -227,14 +249,14 @@ class EntityRepository implements ObjectRepository, Selectable
     /**
      * Adds support for magic method calls.
      *
-     * @param string $method
+     * @param string  $method
+     * @param mixed[] $arguments
+     * @psalm-param list<mixed> $arguments
      *
      * @return mixed The returned value from the resolved method.
      *
      * @throws ORMException
      * @throws BadMethodCallException If the method called is invalid.
-     *
-     * @psalm-param list<mixed> $arguments
      */
     public function __call($method, $arguments)
     {
@@ -293,6 +315,7 @@ 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>
      */
     public function matching(Criteria $criteria)
@@ -307,12 +330,11 @@ class EntityRepository implements ObjectRepository, Selectable
      *
      * @param string $method The method to call
      * @param string $by     The property name used as condition
+     * @psalm-param list<mixed> $arguments The arguments to pass at method call
      *
      * @return mixed
      *
      * @throws ORMException If the method called is invalid or the requested field/association does not exist.
-     *
-     * @psalm-param list<mixed> $arguments The arguments to pass at method call
      */
     private function resolveMagicCall(string $method, string $by, array $arguments)
     {

lib/Doctrine/ORM/Event/ListenersInvoker.php

@@ -90,6 +90,8 @@ class ListenersInvoker
      * @param object        $entity    The Entity on which the event occurred.
      * @param EventArgs     $event     The Event args.
      * @param int           $invoke    Bitmask to invoke listeners.
+     *
+     * @return void
      */
     public function invoke(ClassMetadata $metadata, $eventName, $entity, EventArgs $event, $invoke)
     {

lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php

@@ -48,6 +48,9 @@ class OnClassMetadataNotFoundEventArgs extends ManagerEventArgs
         parent::__construct($objectManager);
     }
 
+    /**
+     * @return void
+     */
     public function setFoundMetadata(?ClassMetadata $classMetadata = null)
     {
         $this->foundMetadata = $classMetadata;

lib/Doctrine/ORM/Event/OnClearEventArgs.php

@@ -21,7 +21,6 @@
 namespace Doctrine\ORM\Event;
 
 use Doctrine\Common\EventArgs;
-use Doctrine\ORM\EntityManager;
 use Doctrine\ORM\EntityManagerInterface;
 
 /**
@@ -49,7 +48,7 @@ class OnClearEventArgs extends EventArgs
     /**
      * Retrieves associated EntityManager.
      *
-     * @return EntityManager
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {

lib/Doctrine/ORM/Event/OnFlushEventArgs.php

@@ -21,7 +21,6 @@
 namespace Doctrine\ORM\Event;
 
 use Doctrine\Common\EventArgs;
-use Doctrine\ORM\EntityManager;
 use Doctrine\ORM\EntityManagerInterface;
 
 /**
@@ -42,7 +41,7 @@ class OnFlushEventArgs extends EventArgs
     /**
      * Retrieve associated EntityManager.
      *
-     * @return EntityManager
+     * @return EntityManagerInterface
      */
     public function getEntityManager()
     {

lib/Doctrine/ORM/Event/PreUpdateEventArgs.php

@@ -113,13 +113,9 @@ class PreUpdateEventArgs extends LifecycleEventArgs
     /**
      * Asserts the field exists in changeset.
      *
-     * @param string $field
-     *
-     * @return void
-     *
      * @throws InvalidArgumentException
      */
-    private function assertValidField($field)
+    private function assertValidField(string $field): void
     {
         if (! isset($this->entityChangeSet[$field])) {
             throw new InvalidArgumentException(sprintf(

lib/Doctrine/ORM/Id/SequenceGenerator.php

@@ -103,27 +103,43 @@ class SequenceGenerator extends AbstractIdGenerator implements Serializable
 
     /**
      * @return string
+     *
+     * @final
      */
     public function serialize()
     {
-        return serialize(
-            [
-                'allocationSize' => $this->_allocationSize,
-                'sequenceName'   => $this->_sequenceName,
-            ]
-        );
+        return serialize($this->__serialize());
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function __serialize(): array
+    {
+        return [
+            'allocationSize' => $this->_allocationSize,
+            'sequenceName' => $this->_sequenceName,
+        ];
     }
 
     /**
      * @param string $serialized
      *
      * @return void
+     *
+     * @final
      */
     public function unserialize($serialized)
     {
-        $array = unserialize($serialized);
+        $this->__unserialize(unserialize($serialized));
+    }
 
-        $this->_sequenceName   = $array['sequenceName'];
-        $this->_allocationSize = $array['allocationSize'];
+    /**
+     * @param array<string, mixed> $data
+     */
+    public function __unserialize(array $data): void
+    {
+        $this->_sequenceName   = $data['sequenceName'];
+        $this->_allocationSize = $data['allocationSize'];
     }
 }

lib/Doctrine/ORM/Internal/CommitOrderCalculator.php

@@ -146,10 +146,8 @@ class CommitOrderCalculator
      * Visit a given node definition for reordering.
      *
      * {@internal Highly performance-sensitive method.}
-     *
-     * @param stdClass $vertex
      */
-    private function visit($vertex)
+    private function visit(stdClass $vertex): void
     {
         $vertex->state = self::IN_PROGRESS;
 

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

@@ -24,12 +24,14 @@ use Doctrine\DBAL\Driver\ResultStatement;
 use Doctrine\DBAL\FetchMode;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Events;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\Tools\Pagination\LimitSubqueryWalker;
 use Doctrine\ORM\UnitOfWork;
+use Generator;
 use PDO;
 use ReflectionClass;
 
@@ -38,9 +40,6 @@ use function array_merge;
 use function count;
 use function end;
 use function in_array;
-use function trigger_error;
-
-use const E_USER_DEPRECATED;
 
 /**
  * Base class for all hydrators. A hydrator is a class that provides some form
@@ -123,16 +122,17 @@ abstract class AbstractHydrator
      *
      * @param object $stmt
      * @param object $resultSetMapping
+     * @psalm-param array<string, mixed> $hints
      *
      * @return IterableResult
-     *
-     * @psalm-param array<string, mixed> $hints
      */
     public function iterate($stmt, $resultSetMapping, array $hints = [])
     {
-        @trigger_error(
-            'Method ' . __METHOD__ . '() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
-            E_USER_DEPRECATED
+        Deprecation::trigger(
+            'doctrine/orm',
+            'https://github.com/doctrine/orm/issues/8463',
+            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0. Use toIterable() instead.',
+            __METHOD__
         );
 
         $this->_stmt  = $stmt;
@@ -151,9 +151,9 @@ abstract class AbstractHydrator
     /**
      * Initiates a row-by-row hydration.
      *
-     * @return iterable<mixed>
-     *
      * @psalm-param array<string, mixed> $hints
+     *
+     * @return Generator<int, mixed>
      */
     public function toIterable(ResultStatement $stmt, ResultSetMapping $resultSetMapping, array $hints = []): iterable
     {
@@ -195,10 +195,9 @@ abstract class AbstractHydrator
      *
      * @param object $stmt
      * @param object $resultSetMapping
+     * @psalm-param array<string, string> $hints
      *
      * @return mixed[]
-     *
-     * @psalm-param array<string, string> $hints
      */
     public function hydrateAll($stmt, $resultSetMapping, array $hints = [])
     {
@@ -222,7 +221,7 @@ abstract class AbstractHydrator
      * Hydrates a single row returned by the current statement instance during
      * row-by-row hydration with {@link iterate()} or {@link toIterable()}.
      *
-     * @return mixed
+     * @return mixed[]|false
      */
     public function hydrateRow()
     {
@@ -322,14 +321,13 @@ abstract class AbstractHydrator
      * the values applied. Scalar values are kept in a specific key 'scalars'.
      *
      * @param mixed[] $data SQL Result Row.
+     * @psalm-param array<string, string> $id                 Dql-Alias => ID-Hash.
+     * @psalm-param array<string, bool>   $nonemptyComponents Does this DQL-Alias has at least one non NULL value?
      *
      * @return array<string, array<string, mixed>> An array with all the fields
      *                                             (name => value) of the data
      *                                             row, grouped by their
      *                                             component alias.
-     *
-     * @psalm-param array<string, string> $id                 Dql-Alias => ID-Hash.
-     * @psalm-param array<string, bool>   $nonemptyComponents Does this DQL-Alias has at least one non NULL value?
      * @psalm-return array{
      *                   data: array<array-key, array>,
      *                   newObjects?: array<array-key, array{
@@ -414,8 +412,11 @@ abstract class AbstractHydrator
      * values according to their types. The resulting row has the same number
      * of elements as before.
      *
+     * @param mixed[] $data
      * @psalm-param array<string, mixed> $data
-     * @psalm-return array<string, mixed> The processed row.
+     *
+     * @return mixed[] The processed row.
+     * @psalm-return array<string, mixed>
      */
     protected function gatherScalarRowData(&$data)
     {
@@ -449,6 +450,7 @@ abstract class AbstractHydrator
      *
      * @param string $key Column name
      *
+     * @return mixed[]|null
      * @psalm-return array<string, mixed>|null
      */
     protected function hydrateColumnInfo($key)
@@ -541,6 +543,7 @@ abstract class AbstractHydrator
 
     /**
      * @return string[]
+     * @psalm-return non-empty-list<string>
      */
     private function getDiscriminatorValues(ClassMetadata $classMetadata): array
     {

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

@@ -259,15 +259,16 @@ class ArrayHydrator extends AbstractHydrator
      * Updates the result pointer for an Entity. The result pointers point to the
      * last seen instance of each Entity type. This is used for graph construction.
      *
-     * @param mixed[]  $coll     The element.
-     * @param bool|int $index    Index of the element in the collection.
-     * @param string   $dqlAlias
-     * @param bool     $oneToOne Whether it is a single-valued association or not.
-     *
-     * @return void
+     * @param mixed[]|null $coll     The element.
+     * @param bool|int     $index    Index of the element in the collection.
+     * @param bool         $oneToOne Whether it is a single-valued association or not.
      */
-    private function updateResultPointer(array &$coll, $index, $dqlAlias, $oneToOne)
-    {
+    private function updateResultPointer(
+        ?array &$coll,
+        $index,
+        string $dqlAlias,
+        bool $oneToOne
+    ): void {
         if ($coll === null) {
             unset($this->_resultPointers[$dqlAlias]); // Ticket #1228
 

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

@@ -99,11 +99,11 @@ class HydrationException extends ORMException
     }
 
     /**
-     * @param string $discrValue
+     * @param string   $discrValue
+     * @param string[] $discrMap
+     * @psalm-param array<string, string> $discrMap
      *
      * @return HydrationException
-     *
-     * @psalm-param array<string, string> $discrMap
      */
     public static function invalidDiscriminatorValue($discrValue, $discrMap)
     {

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

@@ -21,6 +21,7 @@
 namespace Doctrine\ORM\Internal\Hydration;
 
 use Iterator;
+use ReturnTypeWillChange;
 
 /**
  * Represents a result structure that can be iterated over, hydrating row-by-row
@@ -39,7 +40,7 @@ class IterableResult implements Iterator
     /** @var int */
     private $_key = -1;
 
-    /** @var object|null */
+    /** @var mixed[]|null */
     private $_current = null;
 
     /**
@@ -55,6 +56,7 @@ class IterableResult implements Iterator
      *
      * @throws HydrationException
      */
+    #[ReturnTypeWillChange]
     public function rewind()
     {
         if ($this->_rewinded === true) {
@@ -70,6 +72,7 @@ class IterableResult implements Iterator
      *
      * @return mixed[]|false
      */
+    #[ReturnTypeWillChange]
     public function next()
     {
         $this->_current = $this->_hydrator->hydrateRow();
@@ -81,6 +84,7 @@ class IterableResult implements Iterator
     /**
      * @return mixed
      */
+    #[ReturnTypeWillChange]
     public function current()
     {
         return $this->_current;
@@ -89,6 +93,7 @@ class IterableResult implements Iterator
     /**
      * @return int
      */
+    #[ReturnTypeWillChange]
     public function key()
     {
         return $this->_key;
@@ -97,6 +102,7 @@ class IterableResult implements Iterator
     /**
      * @return bool
      */
+    #[ReturnTypeWillChange]
     public function valid()
     {
         return $this->_current !== false;

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

@@ -21,9 +21,9 @@
 namespace Doctrine\ORM\Internal\Hydration;
 
 use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Proxy\Proxy;
 use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\PersistentCollection;
-use Doctrine\ORM\Proxy\Proxy;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
 use PDO;
@@ -171,15 +171,16 @@ class ObjectHydrator extends AbstractHydrator
     /**
      * Initializes a related collection.
      *
-     * @param object        $entity         The entity to which the collection belongs.
-     * @param ClassMetadata $class
-     * @param string        $fieldName      The name of the field on the entity that holds the collection.
-     * @param string        $parentDqlAlias Alias of the parent fetch joining this collection.
-     *
-     * @return PersistentCollection
+     * @param object $entity         The entity to which the collection belongs.
+     * @param string $fieldName      The name of the field on the entity that holds the collection.
+     * @param string $parentDqlAlias Alias of the parent fetch joining this collection.
      */
-    private function initRelatedCollection($entity, $class, $fieldName, $parentDqlAlias)
-    {
+    private function initRelatedCollection(
+        $entity,
+        ClassMetadata $class,
+        string $fieldName,
+        string $parentDqlAlias
+    ): PersistentCollection {
         $oid      = spl_object_hash($entity);
         $relation = $class->associationMappings[$fieldName];
         $value    = $class->reflFields[$fieldName]->getValue($entity);
@@ -223,14 +224,13 @@ class ObjectHydrator extends AbstractHydrator
      * Gets an entity instance.
      *
      * @param string $dqlAlias The DQL alias of the entity's class.
+     * @psalm-param array<string, mixed> $data     The instance data.
      *
-     * @return object The entity.
+     * @return object
      *
      * @throws HydrationException
-     *
-     * @psalm-param array<string, mixed> $data     The instance data.
      */
-    private function getEntity(array $data, $dqlAlias)
+    private function getEntity(array $data, string $dqlAlias)
     {
         $className = $this->_rsm->aliasMap[$dqlAlias];
 
@@ -273,13 +273,12 @@ class ObjectHydrator extends AbstractHydrator
     }
 
     /**
-     * @param string $className
+     * @psalm-param class-string $className
+     * @psalm-param array<string, mixed> $data
      *
      * @return mixed
-     *
-     * @psalm-param array<string, mixed> $data
      */
-    private function getEntityFromIdentityMap($className, array $data)
+    private function getEntityFromIdentityMap(string $className, array $data)
     {
         // TODO: Abstract this code and UnitOfWork::createEntity() equivalent?
         $class = $this->_metadataCache[$className];
@@ -433,7 +432,7 @@ class ObjectHydrator extends AbstractHydrator
                     // PATH B: Single-valued association
                     $reflFieldValue = $reflField->getValue($parentObject);
 
-                    if (! $reflFieldValue || isset($this->_hints[Query::HINT_REFRESH]) || ($reflFieldValue instanceof Proxy && ! $reflFieldValue->__isInitialized__)) {
+                    if (! $reflFieldValue || isset($this->_hints[Query::HINT_REFRESH]) || ($reflFieldValue instanceof Proxy && ! $reflFieldValue->__isInitialized())) {
                         // we only need to take action if this value is null,
                         // we refresh the entity or its an uninitialized proxy.
                         if (isset($nonemptyComponents[$dqlAlias])) {