Conditionally extend the old AnnotationDriver class (#9671)

* 2.11.x:
  ScalarColumnHydrator: prevent early-bail on falsy values (#9663)

.doctrine-project.json

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

.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/coding-standard.yml

@@ -10,30 +10,6 @@ on:
 
 jobs:
   coding-standards:
-    name: "Coding Standards"
-    runs-on: "ubuntu-20.04"
-
-    strategy:
-      matrix:
-        php-version:
-          - "7.4"
-
-    steps:
-      - name: "Checkout"
-        uses: "actions/checkout@v2"
-
-      - name: "Install PHP"
-        uses: "shivammathur/setup-php@v2"
-        with:
-          coverage: "none"
-          php-version: "${{ matrix.php-version }}"
-          tools: "cs2pr"
-
-      - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
-        with:
-          dependency-versions: "highest"
-
-      # https://github.com/doctrine/.github/issues/3
-      - name: "Run PHP_CodeSniffer"
-        run: "vendor/bin/phpcs -q --no-colors --report=checkstyle | cs2pr"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@1.4.1"
+    with:
+      php-version: "8.1"

.github/workflows/continuous-integration.yml

@@ -2,7 +2,11 @@ name: "Continuous Integration"
 
 on:
   pull_request:
+    branches:
+      - "*.x"
   push:
+    branches:
+      - "*.x"
 
 env:
   fail-fast: true
@@ -19,6 +23,14 @@ jobs:
           - "7.3"
           - "7.4"
           - "8.0"
+          - "8.1"
+        dbal-version:
+          - "default"
+        include:
+          - php-version: "8.0"
+            dbal-version: "2.13"
+          - php-version: "8.1"
+            dbal-version: "3@dev"
 
     steps:
       - name: "Checkout"
@@ -30,10 +42,14 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: "pdo, pdo_sqlite"
+          extensions: "apcu, pdo, pdo_sqlite"
           coverage: "pcov"
           ini-values: "zend.assertions=1"
 
+      - name: "Require specific DBAL version"
+        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
+        if: "${{ matrix.dbal-version != 'default' }}"
+
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
 
@@ -50,7 +66,7 @@ jobs:
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v2"
         with:
-          name: "phpunit-sqlite-${{ matrix.php-version }}-coverage"
+          name: "phpunit-sqlite-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage*.xml"
 
 
@@ -62,10 +78,16 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
+        dbal-version:
+          - "default"
         postgres-version:
           - "9.6"
-          - "13"
+          - "14"
+        include:
+          - php-version: "8.0"
+            dbal-version: "2.13"
+            postgres-version: "14"
 
     services:
       postgres:
@@ -92,6 +114,10 @@ jobs:
           coverage: "pcov"
           ini-values: "zend.assertions=1"
 
+      - name: "Require specific DBAL version"
+        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
+        if: "${{ matrix.dbal-version != 'default' }}"
+
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
 
@@ -101,7 +127,7 @@ jobs:
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v2"
         with:
-          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-coverage"
+          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage.xml"
 
 
@@ -113,12 +139,19 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
+        dbal-version:
+          - "default"
         mariadb-version:
-          - "10.5"
+          - "10.6"
         extension:
           - "mysqli"
           - "pdo_mysql"
+        include:
+          - php-version: "8.0"
+            dbal-version: "2.13"
+            mariadb-version: "10.6"
+            extension: "pdo_mysql"
 
     services:
       mariadb:
@@ -139,6 +172,10 @@ jobs:
         with:
           fetch-depth: 2
 
+      - name: "Require specific DBAL version"
+        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
+        if: "${{ matrix.dbal-version != 'default' }}"
+
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
@@ -156,7 +193,7 @@ jobs:
       - name: "Upload coverage file"
         uses: "actions/upload-artifact@v2"
         with:
-          name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-coverage"
+          name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage.xml"
 
 
@@ -168,13 +205,20 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
+        dbal-version:
+          - "default"
         mysql-version:
           - "5.7"
           - "8.0"
         extension:
           - "mysqli"
           - "pdo_mysql"
+        include:
+          - php-version: "8.0"
+            dbal-version: "2.13"
+            mysql-version: "8.0"
+            extension: "pdo_mysql"
 
     services:
       mysql:
@@ -202,6 +246,10 @@ jobs:
           ini-values: "zend.assertions=1"
           extensions: "${{ matrix.extension }}"
 
+      - name: "Require specific DBAL version"
+        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
+        if: "${{ matrix.dbal-version != 'default' }}"
+
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
 
@@ -218,9 +266,10 @@ jobs:
       - name: "Upload coverage files"
         uses: "actions/upload-artifact@v2"
         with:
-          name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-coverage"
+          name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage*.xml"
 
+
   phpunit-lower-php-versions:
     name: "PHPUnit with SQLite"
     runs-on: "ubuntu-20.04"
@@ -253,6 +302,7 @@ jobs:
       - 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/release-on-milestone-closed.yml

@@ -7,40 +7,9 @@ on:
 
 jobs:
   release:
-    name: "Git tag, release & create merge-up PR"
-    runs-on: "ubuntu-20.04"
-
-    steps:
-      - name: "Checkout"
-        uses: "actions/checkout@v2"
-
-      - name: "Release"
-        uses: "laminas/automatic-releases@v1"
-        with:
-          command-name: "laminas:automatic-releases:release"
-        env:
-          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
-          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
-          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
-          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
-          "SHELL_VERBOSITY": "3"
-
-      - name: "Create Merge-Up Pull Request"
-        uses: "laminas/automatic-releases@v1"
-        with:
-          command-name: "laminas:automatic-releases:create-merge-up-pull-request"
-        env:
-          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
-          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
-          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
-          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
-
-      - name: "Create new milestones"
-        uses: "laminas/automatic-releases@v1"
-        with:
-          command-name: "laminas:automatic-releases:create-milestones"
-        env:
-          "GITHUB_TOKEN": ${{ secrets.GITHUB_TOKEN }}
-          "SIGNING_SECRET_KEY": ${{ secrets.SIGNING_SECRET_KEY }}
-          "GIT_AUTHOR_NAME": ${{ secrets.GIT_AUTHOR_NAME }}
-          "GIT_AUTHOR_EMAIL": ${{ secrets.GIT_AUTHOR_EMAIL }}
+    uses: "doctrine/.github/.github/workflows/release-on-milestone-closed.yml@1.4.1"
+    secrets:
+      GIT_AUTHOR_EMAIL: ${{ secrets.GIT_AUTHOR_EMAIL }}
+      GIT_AUTHOR_NAME: ${{ secrets.GIT_AUTHOR_NAME }}
+      ORGANIZATION_ADMIN_TOKEN: ${{ secrets.ORGANIZATION_ADMIN_TOKEN }}
+      SIGNING_SECRET_KEY: ${{ secrets.SIGNING_SECRET_KEY }}

.github/workflows/static-analysis.yml

@@ -15,9 +15,21 @@ jobs:
     runs-on: "ubuntu-20.04"
 
     strategy:
+      fail-fast: false
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
+        dbal-version:
+          - "default"
+        persistence-version:
+          - "default"
+        include:
+          - php-version: "8.1"
+            dbal-version: "2.13"
+            persistence-version: "default"
+          - php-version: "8.1"
+            dbal-version: "default"
+            persistence-version: "2.5"
 
     steps:
       - name: "Checkout code"
@@ -29,6 +41,14 @@ jobs:
           coverage: "none"
           php-version: "${{ matrix.php-version }}"
 
+      - name: "Require specific DBAL version"
+        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
+        if: "${{ matrix.dbal-version != 'default' }}"
+
+      - name: "Require specific persistence version"
+        run: "composer require doctrine/persistence ^${{ matrix.persistence-version }} --no-update"
+        if: "${{ matrix.persistence-version != 'default' }}"
+
       - name: "Install dependencies with Composer"
         uses: "ramsey/composer-install@v1"
         with:
@@ -36,15 +56,25 @@ jobs:
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version == 'default'}}"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -c phpstan-dbal2.neon"
+        if: "${{ matrix.dbal-version == '2.13' }}"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -c phpstan-persistence2.neon"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version != 'default'}}"
 
   static-analysis-psalm:
     name: "Static Analysis with Psalm"
     runs-on: "ubuntu-20.04"
 
     strategy:
+      fail-fast: false
       matrix:
         php-version:
-          - "7.4"
+          - "8.1"
 
     steps:
       - name: "Checkout code"

.gitignore

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

CONTRIBUTING.md

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

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,9 @@
-| [3.0.x][3.0] | [2.9.x][2.9] | [2.8.x][2.8] |
+| [3.0.x][3.0] | [2.12.x][2.12] | [2.11.x][2.11] |
 |:----------------:|:----------------:|:----------:|
-| [![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.12 image]][2.12] | [![Build status][2.11 image]][2.11] |
+| [![Coverage Status][3.0 coverage image]][3.0 coverage]| [![Coverage Status][2.12 coverage image]][2.12 coverage] | [![Coverage Status][2.11 coverage image]][2.11 coverage]  |
+
+[<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
 
 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
@@ -13,18 +15,18 @@ without requiring unnecessary code duplication.
 ## More resources:
 
 * [Website](http://www.doctrine-project.org)
-* [Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/latest/index.html)
+* [Documentation](https://www.doctrine-project.org/projects/doctrine-orm/en/stable/index.html)
 
 
   [3.0 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0.x
   [3.0]: https://github.com/doctrine/orm/tree/3.0.x
   [3.0 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.0.x/graph/badge.svg
   [3.0 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.0.x
-  [2.9 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.9.x
-  [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.12 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.12.x
+  [2.12]: https://github.com/doctrine/orm/tree/2.12.x
+  [2.12 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.12.x/graph/badge.svg
+  [2.12 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.12.x
+  [2.11 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.11.x
+  [2.11]: https://github.com/doctrine/orm/tree/2.11.x
+  [2.11 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.11.x/graph/badge.svg
+  [2.11 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.11.x

SECURITY.md

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

UPGRADE.md

@@ -1,3 +1,235 @@
+# Upgrade to 2.12
+
+## Deprecated the `doctrine` binary.
+
+The documentation explains how the console tools can be bootstrapped for
+standalone usage.
+
+The method `ConsoleRunner::printCliConfigTemplate()` is deprecated because it
+was only useful in the context of the `doctrine` binary.
+
+## Deprecate omitting `$class` argument to `ORMInvalidArgumentException::invalidIdentifierBindingEntity()`
+
+To make it easier to identify understand the cause for that exception, it is
+deprecated to omit the class name when calling
+`ORMInvalidArgumentException::invalidIdentifierBindingEntity()`.
+
+## Deprecate `Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper`
+
+Using a console helper to provide the ORM's console commands with one or
+multiple entity managers had been deprecated with 2.9 already. This leaves
+The `EntityManagerHelper` class with no purpose which is why it is now
+deprecated too. Applications that still rely on the `em` console helper, can
+easily recreate that class in their own codebase.
+
+## Deprecate custom repository classes that don't extend `EntityRepository`
+
+Although undocumented, it is currently possible to configure a custom repository
+class that implements `ObjectRepository` but does not extend the
+`EntityRepository` base class.
+
+This is now deprecated. Please extend `EntityRepository` instead.
+
+## Deprecated more APIs related to entity namespace aliases
+
+```diff
+-$config = $entityManager->getConfiguration();
+-$config->addEntityNamespace('CMS', 'My\App\Cms');
++use My\App\Cms\CmsUser;
+
+-$entityManager->getRepository('CMS:CmsUser');
++$entityManager->getRepository(CmsUser::class);
+```
+
+## Deprecate `AttributeDriver::getReader()` and `AnnotationDriver::getReader()`
+
+That method was inherited from the abstract `AnnotationDriver` class of
+`doctrine/persistence`, and does not seem to serve any purpose.
+
+## Un-deprecate `Doctrine\ORM\Proxy\Proxy`
+
+Because no forward-compatible new proxy solution had been implemented yet, the
+current proxy mechanism is not considered deprecated anymore for the time
+being. This applies to the following interfaces/classes:
+
+* `Doctrine\ORM\Proxy\Proxy`
+* `Doctrine\ORM\Proxy\ProxyFactory`
+
+These methods have been un-deprecated:
+
+* `Doctrine\ORM\Configuration::getAutoGenerateProxyClasses()`
+* `Doctrine\ORM\Configuration::getProxyDir()`
+* `Doctrine\ORM\Configuration::getProxyNamespace()`
+
+Note that the `Doctrine\ORM\Proxy\Autoloader` remains deprecated and will be removed in 3.0.
+
+## Deprecate helper methods from `AbstractCollectionPersister`
+
+The following protected methods of
+`Doctrine\ORM\Cache\Persister\Collection\AbstractCollectionPersister`
+are not in use anymore and will be removed.
+
+* `evictCollectionCache()`
+* `evictElementCache()`
+
+## Deprecate `Doctrine\ORM\Query\TreeWalkerChainIterator`
+
+This class won't have a replacement.
+
+## Deprecate `OnClearEventArgs::getEntityClass()` and `OnClearEventArgs::clearsAllEntities()`
+
+These methods will be removed in 3.0 along with the ability to partially clear
+the entity manager.
+
+## Deprecate `Doctrine\ORM\Configuration::newDefaultAnnotationDriver`
+
+This functionality has been moved to the new `ORMSetup` class. Call
+`Doctrine\ORM\ORMSetup::createDefaultAnnotationDriver()` to create
+a new annotation driver.
+
+## Deprecate `Doctrine\ORM\Tools\Setup`
+
+In our effort to migrate from Doctrine Cache to PSR-6, the `Setup` class which
+accepted a Doctrine Cache instance in each method has been deprecated.
+
+The replacement is `Doctrine\ORM\ORMSetup` which accepts a PSR-6
+cache instead.
+
+## Deprecate `Doctrine\ORM\Cache\MultiGetRegion`
+
+The interface will be merged with `Doctrine\ORM\Cache\Region` in 3.0.
+
+# Upgrade to 2.11
+
+## Rename `AbstractIdGenerator::generate()` to `generateId()`
+
+Implementations of `AbstractIdGenerator` have to override the method
+`generateId()` without calling the parent implementation. Not doing so is
+deprecated. Calling `generate()` on any `AbstractIdGenerator` implementation
+is deprecated.
+
+## PSR-6-based second level cache
+
+The second level cache has been reworked to consume a PSR-6 cache. Using a
+Doctrine Cache instance is deprecated.
+
+* `DefaultCacheFactory`: The constructor expects a PSR-6 cache item pool as
+  second argument now.
+* `DefaultMultiGetRegion`: This class is deprecated in favor of `DefaultRegion`.
+* `DefaultRegion`:
+  * The constructor expects a PSR-6 cache item pool as second argument now.
+  * The protected `$cache` property is deprecated.
+  * The properties `$name` and `$lifetime` as well as the constant
+   `REGION_KEY_SEPARATOR` and the method `getCacheEntryKey()` are flagged as
+   `@internal` now. They all will become `private` in 3.0.
+  * The method `getCache()` is deprecated without replacement.
+
+## Deprecated: `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
+You can convert mappings with the `orm:convert-mapping` command or more simply
+in this case, `include` the metadata file from the `loadMetadata` static method
+used by the `StaticPHPDriver`.
+
+## Deprecated: `Setup::registerAutoloadDirectory()`
+
+Use Composer's autoloader instead.
+
+## Deprecated: `AbstractHydrator::hydrateRow()`
+
+Following the deprecation of the method `AbstractHydrator::iterate()`, the
+method `hydrateRow()` has been deprecated as well.
+
+## Deprecate cache settings inspection
+
+Doctrine does not provide its own cache implementation anymore and relies on
+the PSR-6 standard instead. As a consequence, we cannot determine anymore
+whether a given cache adapter is suitable for a production environment.
+Because of that, functionality that aims to do so has been deprecated:
+
+* `Configuration::ensureProductionSettings()`
+* the `orm:ensure-production-settings` console command
+
+# Upgrade to 2.10
+
+## BC Break: `UnitOfWork` now relies on SPL object IDs, not hashes
+
+When calling the following methods, you are now supposed to use the result of
+`spl_object_id()`, and not `spl_object_hash()`:
+- `UnitOfWork::clearEntityChangeSet()`
+- `UnitOfWork::setOriginalEntityProperty()`
+
+## BC Break: Removed `TABLE` id generator strategy
+
+The implementation was unfinished for 14 years.
+It is now deprecated to rely on:
+- `Doctrine\ORM\Id\TableGenerator`;
+- `Doctrine\ORM\Mapping\ClassMetadata::GENERATOR_TYPE_TABLE`;
+- `Doctrine\ORM\Mapping\ClassMetadata::$tableGeneratorDefinition`;
+- or `Doctrine\ORM\Mapping\ClassMetadata::isIdGeneratorTable()`.
+
+## New method `Doctrine\ORM\EntityManagerInterface#wrapInTransaction($func)`
+
+Works the same as `Doctrine\ORM\EntityManagerInterface#transactional()` but returns any value returned from `$func` closure rather than just _non-empty value returned from the closure or true_.
+
+Because of BC policy, the method does not exist on the interface yet. This is the example of safe usage:
+
+```php
+function foo(EntityManagerInterface $entityManager, callable $func) {
+    if (method_exists($entityManager, 'wrapInTransaction')) {
+        return $entityManager->wrapInTransaction($func);
+    }
+    
+    return $entityManager->transactional($func);
+}
+```
+
+`Doctrine\ORM\EntityManagerInterface#transactional()` has been deprecated.
+
+## Minor BC BREAK: some exception methods have been removed
+
+The following methods were not in use and are very unlikely to be used by
+downstream packages or applications, and were consequently removed:
+
+- `ORMException::entityMissingForeignAssignedId`
+- `ORMException::entityMissingAssignedIdForField`
+- `ORMException::invalidFlushMode`
+
+## Deprecated: database-side UUID generation
+
+[DB-generated UUIDs are deprecated as of `doctrine/dbal` 2.8][DBAL deprecation].
+As a consequence, using the `UUID` strategy for generating identifiers is deprecated as well.
+Furthermore, relying on the following classes and methods is deprecated:
+
+- `Doctrine\ORM\Id\UuidGenerator`
+- `Doctrine\ORM\Mapping\ClassMetadataInfo::isIdentifierUuid()`
+
+[DBAL deprecation]: https://github.com/doctrine/dbal/pull/3212
+
+## Minor BC BREAK: Custom hydrators and `toIterable()`
+
+The type declaration of the `$stmt` parameter of `AbstractHydrator::toIterable()` has been removed. This change might
+break custom hydrator implementations that override this very method.
+
+Overriding this method is not recommended, which is why the method is documented as `@final` now.
+
+```diff
+- public function toIterable(ResultStatement $stmt, ResultSetMapping $resultSetMapping, array $hints = []): iterable
++ public function toIterable($stmt, ResultSetMapping $resultSetMapping, array $hints = []): iterable
+```
+
+## Deprecated: Entity Namespace Aliases
+
+Entity namespace aliases are deprecated, use the magic ::class constant to abbreviate full class names
+in EntityManager, EntityRepository and DQL.
+
+```diff
+-  $entityManager->find('MyBundle:User', $id);
++  $entityManager->find(User::class, $id);
+```
+
 # Upgrade to 2.9
 
 ## Minor BC BREAK: Setup tool needs cache implementation
@@ -33,10 +265,10 @@ now always cleared regardless of the cache adapter being used.
 Method `Doctrine\ORM\UnitOfWork#commit()` can throw an OptimisticLockException when a commit silently fails and returns false
 since `Doctrine\DBAL\Connection#commit()` signature changed from returning void to boolean
 
-## Deprecated: `Doctrine\ORM\AbstractQuery#iterator()`
+## Deprecated: `Doctrine\ORM\AbstractQuery#iterate()`
 
-The method `Doctrine\ORM\AbstractQuery#iterator()` is deprecated in favor of `Doctrine\ORM\AbstractQuery#toIterable()`.
-Note that `toIterable()` yields results of the query, unlike `iterator()` which yielded each result wrapped into an array.
+The method `Doctrine\ORM\AbstractQuery#iterate()` is deprecated in favor of `Doctrine\ORM\AbstractQuery#toIterable()`.
+Note that `toIterable()` yields results of the query, unlike `iterate()` which yielded each result wrapped into an array.
 
 # Upgrade to 2.7
 
@@ -104,27 +336,18 @@ These methods have been deprecated:
 ## Deprecated `Doctrine\ORM\Version`
 
 The `Doctrine\ORM\Version` class is now deprecated and will be removed in Doctrine ORM 3.0:
-please refrain from checking the ORM version at runtime or use
-[ocramius/package-versions](https://github.com/Ocramius/PackageVersions/).
+please refrain from checking the ORM version at runtime or use Composer's [runtime API](https://getcomposer.org/doc/07-runtime.md#knowing-whether-package-x-is-installed-in-version-y).
 
-## Deprecated `EntityManager#merge()` and `EntityManager#detach()` methods
+## Deprecated `EntityManager#merge()` method
 
-Merge and detach semantics were a poor fit for the PHP "share-nothing" architecture.
-In addition to that, merging/detaching caused multiple issues with data integrity
+Merge semantics was a poor fit for the PHP "share-nothing" architecture.
+In addition to that, merging caused multiple issues with data integrity
 in the managed entity graph, which was constantly spawning more edge-case bugs/scenarios.
 
 The following API methods were therefore deprecated:
 
 * `EntityManager#merge()`
-* `EntityManager#detach()`
 * `UnitOfWork#merge()`
-* `UnitOfWork#detach()`
-
-Users are encouraged to migrate `EntityManager#detach()` calls to `EntityManager#clear()`.
-
-In order to maintain performance on batch processing jobs, it is endorsed to enable
-the second level cache (http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html)
-on entities that are frequently reused across multiple `EntityManager#clear()` calls.
 
 An alternative to `EntityManager#merge()` will not be provided by ORM 3.0, since the merging
 semantics should be part of the business domain rather than the persistence domain of an
@@ -167,8 +390,8 @@ If you would still like to perform batching operations over small `UnitOfWork`
 instances, it is suggested to follow these paths instead:
 
  * eagerly use `EntityManager#clear()` in conjunction with a specific second level
-   cache configuration (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/second-level-cache.html)
- * use an explicit change tracking policy (see http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/change-tracking-policies.html)
+   cache configuration (see http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/second-level-cache.html)
+ * use an explicit change tracking policy (see http://docs.doctrine-project.org/projects/doctrine-orm/en/stable/reference/change-tracking-policies.html)
 
 ## Deprecated `YAML` mapping drivers.
 

bin/doctrine-pear.php

@@ -1,21 +1,14 @@
 <?php
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the LGPL. For more information, see
- * <http://www.doctrine-project.org>.
- */
+
+fwrite(
+    STDERR,
+    '[Warning] The use of this script is discouraged. See'
+    . ' https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#doctrine-console'
+    . ' for instructions on bootstrapping the console runner.'
+    . PHP_EOL
+);
+
+echo PHP_EOL . PHP_EOL;
 
 require_once 'Doctrine/Common/ClassLoader.php';
 

bin/doctrine.php

@@ -1,25 +1,18 @@
 <?php
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
 
 use Symfony\Component\Console\Helper\HelperSet;
 use Doctrine\ORM\Tools\Console\ConsoleRunner;
 
+fwrite(
+    STDERR,
+    '[Warning] The use of this script is discouraged. See'
+    . ' https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/tools.html#doctrine-console'
+    . ' for instructions on bootstrapping the console runner.'
+    . PHP_EOL
+);
+
+echo PHP_EOL . PHP_EOL;
+
 $autoloadFiles = [
     __DIR__ . '/../vendor/autoload.php',
     __DIR__ . '/../../../autoload.php'

ci/github/phpunit/mysqli.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
          beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
+         convertDeprecationsToExceptions="true"
 >
     <php>
+        <ini name="error_reporting" value="-1" />
         <var name="db_driver" value="mysqli"/>
         <var name="db_host" value="127.0.0.1" />
         <var name="db_port" value="3306"/>

ci/github/phpunit/pdo_mysql.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
          beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
+         convertDeprecationsToExceptions="true"
 >
     <php>
+        <ini name="error_reporting" value="-1" />
         <var name="db_driver" value="pdo_mysql"/>
         <var name="db_host" value="127.0.0.1" />
         <var name="db_port" value="3306"/>

ci/github/phpunit/pdo_pgsql.xml

@@ -1,12 +1,14 @@
 <?xml version="1.0" encoding="utf-8"?>
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-         xsi:noNamespaceSchemaLocation="../../vendor/phpunit/phpunit/phpunit.xsd"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
          beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
+         convertDeprecationsToExceptions="true"
 >
     <php>
+        <ini name="error_reporting" value="-1" />
         <var name="db_driver" value="pdo_pgsql"/>
         <var name="db_host" value="localhost" />
         <var name="db_user" value="postgres" />

ci/github/phpunit/sqlite.xml

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

composer.json

@@ -13,34 +13,45 @@
         {"name": "Marco Pivetta", "email": "ocramius@gmail.com"}
     ],
     "config": {
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true,
+            "dealerdirect/phpcodesniffer-composer-installer": true
+        },
         "sort-packages": true
     },
     "require": {
-        "php": "^7.1|^8.0",
-        "ext-pdo": "*",
-        "composer/package-versions-deprecated": "^1.8",
-        "doctrine/annotations": "^1.13",
-        "doctrine/cache": "^1.11.3|^2.0.3",
+        "php": "^7.1 || ^8.0",
+        "composer-runtime-api": "^2",
+        "ext-ctype": "*",
+        "doctrine/cache": "^1.12.1 || ^2.1.1",
         "doctrine/collections": "^1.5",
         "doctrine/common": "^3.0.3",
-        "doctrine/dbal": "^2.13.0",
+        "doctrine/dbal": "^2.13.1 || ^3.2",
         "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.2",
+        "doctrine/lexer": "^1.2.3",
+        "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^3.0|^4.0|^5.0|^6.0"
+        "symfony/console": "^3.0 || ^4.0 || ^5.0 || ^6.0",
+        "symfony/polyfill-php72": "^1.23",
+        "symfony/polyfill-php80": "^1.16"
     },
     "require-dev": {
+        "doctrine/annotations": "^1.13",
         "doctrine/coding-standard": "^9.0",
-        "phpstan/phpstan": "^0.12.83",
-        "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"
+        "phpbench/phpbench": "^0.16.10 || ^1.0",
+        "phpstan/phpstan": "~1.4.10 || 1.5.0",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.4",
+        "psr/log": "^1 || ^2 || ^3",
+        "squizlabs/php_codesniffer": "3.6.2",
+        "symfony/cache": "^4.4 || ^5.4 || ^6.0",
+        "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0",
+        "vimeo/psalm": "4.22.0"
+    },
+    "conflict": {
+        "doctrine/annotations": "<1.13 || >= 2.0"
     },
     "suggest": {
         "symfony/cache": "Provides cache support for Setup Tool with doctrine/cache 2.0",
@@ -52,6 +63,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/conf.py

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

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

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

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

@@ -4,7 +4,7 @@ Advanced field value conversion using custom mapping types
 .. sectionauthor:: Jan Sorgalla <jsorgalla@googlemail.com>
 
 When creating entities, you sometimes have the need to transform field values
-before they are saved to the database. In Doctrine you can use Custom Mapping 
+before they are saved to the database. In Doctrine you can use Custom Mapping
 Types to solve this (see: :ref:`reference-basic-mapping-custom-mapping-types`).
 
 There are several ways to achieve this: converting the value inside the Type
@@ -15,7 +15,7 @@ type `Point <https://dev.mysql.com/doc/refman/8.0/en/gis-class-point.html>`_.
 
 The ``Point`` type is part of the `Spatial extension <https://dev.mysql.com/doc/refman/8.0/en/spatial-extensions.html>`_
 of MySQL and enables you to store a single location in a coordinate space by
-using x and y coordinates. You can use the Point type to store a 
+using x and y coordinates. You can use the Point type to store a
 longitude/latitude pair to represent a geographic location.
 
 The entity
@@ -29,9 +29,9 @@ The entity class:
 .. code-block:: php
 
     <?php
-    
+
     namespace Geo\Entity;
- 
+
     /**
      * @Entity
      */
@@ -84,7 +84,7 @@ The entity class:
         }
     }
 
-We use the custom type ``point`` in the ``@Column``  docblock annotation of the 
+We use the custom type ``point`` in the ``@Column``  docblock annotation of the
 ``$point`` field. We will create this custom mapping type in the next chapter.
 
 The point class:
@@ -92,7 +92,7 @@ The point class:
 .. code-block:: php
 
     <?php
-    
+
     namespace Geo\ValueObject;
 
     class Point
@@ -193,10 +193,10 @@ 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 
+Internally, MySQL stores geometry values in a binary format that is not
 identical to the WKT format. So, we need to let MySQL transform the WKT
 representation into its internal format.
 
@@ -210,13 +210,13 @@ which convert WKT strings to and from the internal format of MySQL.
 
 .. note::
 
-    When using DQL queries, the ``convertToPHPValueSQL`` and  
+    When using DQL queries, the ``convertToPHPValueSQL`` and
     ``convertToDatabaseValueSQL`` methods only apply to identification variables
-    and path expressions in SELECT clauses. Expressions in  WHERE clauses are 
+    and path expressions in SELECT clauses. Expressions in  WHERE clauses are
     **not** wrapped!
 
     If you want to use Point values in WHERE clauses, you have to implement a
-    :doc:`user defined function <dql-user-defined-functions>` for 
+    :doc:`user defined function <dql-user-defined-functions>` for
     ``PointFromText``.
 
 Example usage
@@ -252,5 +252,5 @@ Example usage
     $query = $em->createQuery("SELECT l FROM Geo\Entity\Location l WHERE l.address = '1600 Amphitheatre Parkway, Mountain View, CA'");
     $location = $query->getSingleResult();
 
-    /* @var Geo\ValueObject\Point */
+    /** @var Geo\ValueObject\Point */
     $point = $location->getPoint();

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
@@ -33,8 +33,8 @@ the DQL parser:
    is only ever one of them. We implemented the default SqlWalker
    implementation for it.
 -  A tree walker. There can be many tree walkers, they cannot
-   generate the sql, however they can modify the AST before its
-   rendered to sql.
+   generate the SQL, however they can modify the AST before its
+   rendered to SQL.
 
 Now this is all awfully technical, so let me come to some use-cases
 fast to keep you motivated. Using walker implementation you can for
@@ -50,7 +50,7 @@ example:
 -  Modify the Output walker to pretty print the SQL for debugging
    purposes.
 
-In this cookbook-entry I will show examples on the first two
+In this cookbook-entry I will show examples of the first two
 points. There are probably much more use-cases.
 
 Generic count query for pagination
@@ -64,7 +64,7 @@ like:
 
     SELECT p, c, a FROM BlogPost p JOIN p.category c JOIN p.author a WHERE ...
 
-Now in this query the blog post is the root entity, meaning its the
+Now in this query the blog post is the root entity, meaning it's the
 one that is hydrated directly from the query and returned as an
 array of blog posts. In contrast the comment and author are loaded
 for deeper use in the object tree.
@@ -79,7 +79,7 @@ query for pagination would look like:
     SELECT count(DISTINCT p.id) FROM BlogPost p JOIN p.category c JOIN p.author a WHERE ...
 
 Now you could go and write each of these queries by hand, or you
-can use a tree walker to modify the AST for you. Lets see how the
+can use a tree walker to modify the AST for you. Let's see how the
 API would look for this use-case:
 
 .. code-block:: php
@@ -88,7 +88,7 @@ API would look for this use-case:
     $pageNum = 1;
     $query = $em->createQuery($dql);
     $query->setFirstResult( ($pageNum-1) * 20)->setMaxResults(20);
-    
+
     $totalResults = Paginate::count($query);
     $results = $query->getResult();
 
@@ -101,12 +101,12 @@ The ``Paginate::count(Query $query)`` looks like:
     {
         static public function count(Query $query)
         {
-            /* @var $countQuery Query */
+            /** @var Query $countQuery */
             $countQuery = clone $query;
-    
+
             $countQuery->setHint(Query::HINT_CUSTOM_TREE_WALKERS, array('DoctrineExtensions\Paginate\CountSqlWalker'));
             $countQuery->setFirstResult(null)->setMaxResults(null);
-    
+
             return $countQuery->getSingleScalarResult();
         }
     }
@@ -137,13 +137,13 @@ implementation is:
                     break;
                 }
             }
-    
+
             $pathExpression = new PathExpression(
                 PathExpression::TYPE_STATE_FIELD | PathExpression::TYPE_SINGLE_VALUED_ASSOCIATION, $parentName,
                 $parent['metadata']->getSingleIdentifierFieldName()
             );
             $pathExpression->type = PathExpression::TYPE_STATE_FIELD;
-    
+
             $AST->selectClause->selectExpressions = array(
                 new SelectExpression(
                     new AggregateExpression('count', $pathExpression, true), null
@@ -196,7 +196,7 @@ modify the generation of the SELECT clause, adding the
         public function walkSelectClause($selectClause)
         {
             $sql = parent::walkSelectClause($selectClause);
-    
+
             if ($this->getQuery()->getHint('mysqlWalker.sqlNoCache') === true) {
                 if ($selectClause->isDistinct) {
                     $sql = str_replace('SELECT DISTINCT', 'SELECT DISTINCT SQL_NO_CACHE', $sql);
@@ -204,7 +204,7 @@ modify the generation of the SELECT clause, adding the
                     $sql = str_replace('SELECT', 'SELECT SQL_NO_CACHE', $sql);
                 }
             }
-    
+
             return $sql;
         }
     }

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

@@ -45,7 +45,7 @@ configuration:
     $config->addCustomStringFunction($name, $class);
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
-    
+
     $em = EntityManager::create($dbParams, $config);
 
 The ``$name`` is the name the function will be referred to in the
@@ -96,7 +96,7 @@ discuss it step by step:
         // (1)
         public $firstDateExpression = null;
         public $secondDateExpression = null;
-    
+
         public function parse(\Doctrine\ORM\Query\Parser $parser)
         {
             $parser->match(Lexer::T_IDENTIFIER); // (2)
@@ -106,7 +106,7 @@ discuss it step by step:
             $this->secondDateExpression = $parser->ArithmeticPrimary(); // (6)
             $parser->match(Lexer::T_CLOSE_PARENTHESIS); // (3)
         }
-    
+
         public function getSql(\Doctrine\ORM\Query\SqlWalker $sqlWalker)
         {
             return 'DATEDIFF(' .
@@ -131,8 +131,8 @@ generation of a DateDiff FunctionNode somewhere in the AST of the
 dql statement.
 
 The ``ArithmeticPrimary`` method call is the most common
-denominator of valid EBNF tokens taken from the
-`DQL EBNF grammar <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#ebnf>`_
+denominator of valid EBNF tokens taken from the :ref:`DQL EBNF grammar
+<dql_ebnf_grammar>`
 that matches our requirements for valid input into the DateDiff Dql
 function. Picking the right tokens for your methods is a tricky
 business, but the EBNF grammar is pretty helpful finding it, as is
@@ -180,28 +180,28 @@ I'll skip the blah and show the code for this function:
         public $firstDateExpression = null;
         public $intervalExpression = null;
         public $unit = null;
-    
+
         public function parse(\Doctrine\ORM\Query\Parser $parser)
         {
             $parser->match(Lexer::T_IDENTIFIER);
             $parser->match(Lexer::T_OPEN_PARENTHESIS);
-    
+
             $this->firstDateExpression = $parser->ArithmeticPrimary();
-    
+
             $parser->match(Lexer::T_COMMA);
             $parser->match(Lexer::T_IDENTIFIER);
-    
+
             $this->intervalExpression = $parser->ArithmeticPrimary();
-    
+
             $parser->match(Lexer::T_IDENTIFIER);
-    
-            /* @var $lexer Lexer */
+
+            /** @var Lexer $lexer */
             $lexer = $parser->getLexer();
             $this->unit = $lexer->token['value'];
-    
+
             $parser->match(Lexer::T_CLOSE_PARENTHESIS);
         }
-    
+
         public function getSql(\Doctrine\ORM\Query\SqlWalker $sqlWalker)
         {
             return 'DATE_ADD(' .
@@ -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,7 +7,7 @@ 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::

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

@@ -3,8 +3,8 @@ Implementing Wakeup or Clone
 
 .. sectionauthor:: Roman Borschel (roman@code-factory.org)
 
-As explained in the
-`restrictions for entity classes in the manual <http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/architecture.html#entities>`_,
+As explained in the :ref:`restrictions for entity classes in the manual
+<terminology_entities>`,
 it is usually not allowed for an entity to implement ``__wakeup``
 or ``__clone``, because Doctrine makes special use of them.
 However, it is quite easy to make use of these methods in a safe
@@ -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

@@ -16,7 +16,6 @@ Doctrine ORM don't panic. You can get help from different sources:
 -  The `Doctrine Mailing List <https://groups.google.com/group/doctrine-user>`_
 -  Slack chat room `#orm <https://www.doctrine-project.org/slack>`_
 -  Report a bug on `GitHub <https://github.com/doctrine/orm/issues>`_.
--  On `Twitter <https://twitter.com/search/%23doctrine2>`_ with ``#doctrine2``
 -  On `StackOverflow <https://stackoverflow.com/questions/tagged/doctrine-orm>`_
 
 If you need more structure over the different topics you can browse the :doc:`table
@@ -41,6 +40,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

@@ -9,22 +9,28 @@ steps of configuration.
 .. code-block:: php
 
     <?php
-    use Doctrine\ORM\EntityManager,
-        Doctrine\ORM\Configuration;
+
+    use Doctrine\ORM\Configuration;
+    use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
+    use Symfony\Component\Cache\Adapter\ArrayAdapter;
+    use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
 
     // ...
 
     if ($applicationMode == "development") {
-        $cache = new \Doctrine\Common\Cache\ArrayCache;
+        $queryCache = new ArrayAdapter();
+        $metadataCache = new ArrayAdapter();
     } else {
-        $cache = new \Doctrine\Common\Cache\ApcCache;
+        $queryCache = new PhpFilesAdapter('doctrine_queries');
+        $metadataCache = new PhpFilesAdapter('doctrine_metadata');
     }
 
     $config = new Configuration;
-    $config->setMetadataCacheImpl($cache);
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    $config->setMetadataCache($metadataCache);
+    $driverImpl = ORMSetup::createDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
     $config->setMetadataDriverImpl($driverImpl);
-    $config->setQueryCacheImpl($cache);
+    $config->setQueryCache($queryCache);
     $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
     $config->setProxyNamespace('MyProject\Proxies');
 
@@ -41,19 +47,22 @@ steps of configuration.
 
     $em = EntityManager::create($connectionOptions, $config);
 
+Doctrine and Caching
+--------------------
+
+Doctrine is optimized for working with caches. The main parts in Doctrine
+that are optimized for caching are the metadata mapping information with
+the metadata cache and the DQL to SQL conversions with the query cache.
+These 2 caches require only an absolute minimum of memory yet they heavily
+improve the runtime performance of Doctrine.
+
+Doctrine does not bundle its own cache implementation anymore. Instead,
+the PSR-6 standard interfaces are used to access the cache. In the examples
+in this documentation, Symfony Cache is used as a reference implementation.
+
 .. note::
 
     Do not use Doctrine without a metadata and query cache!
-    Doctrine is optimized for working with caches. The main
-    parts in Doctrine that are optimized for caching are the metadata
-    mapping information with the metadata cache and the DQL to SQL
-    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
-    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.
 
 Configuration Options
 ---------------------
@@ -121,7 +130,9 @@ the ``Doctrine\ORM\Configuration``:
 .. code-block:: php
 
     <?php
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    use Doctrine\ORM\ORMSetup;
+
+    $driverImpl = ORMSetup::createDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
     $config->setMetadataDriverImpl($driverImpl);
 
 The path information to the entities is required for the annotation
@@ -137,30 +148,21 @@ Metadata Cache (***RECOMMENDED***)
 .. code-block:: php
 
     <?php
-    $config->setMetadataCacheImpl($cache);
-    $config->getMetadataCacheImpl();
+    $config->setMetadataCache($cache);
+    $config->getMetadataCache();
 
-Gets or sets the cache implementation to use for caching metadata
+Gets or sets the cache adapter to use for caching metadata
 information, that is, all the information you supply via
 annotations, xml or yaml, so that they do not need to be parsed and
 loaded from scratch on every single request which is a waste of
-resources. The cache implementation must implement the
-``Doctrine\Common\Cache\Cache`` interface.
+resources. The cache implementation must implement the PSR-6
+``Psr\Cache\CacheItemPoolInterface`` interface.
 
 Usage of a metadata cache is highly recommended.
 
-The recommended implementations for production are:
-
-
--  ``Doctrine\Common\Cache\ApcCache``
--  ``Doctrine\Common\Cache\ApcuCache``
--  ``Doctrine\Common\Cache\MemcacheCache``
--  ``Doctrine\Common\Cache\XcacheCache``
--  ``Doctrine\Common\Cache\RedisCache``
-
-For development you should use the
-``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
-per-request basis.
+For development you should use an array cache like
+``Symfony\Component\Cache\Adapter\ArrayAdapter``
+which only caches data on a per-request basis.
 
 Query Cache (***RECOMMENDED***)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -168,8 +170,8 @@ Query Cache (***RECOMMENDED***)
 .. code-block:: php
 
     <?php
-    $config->setQueryCacheImpl($cache);
-    $config->getQueryCacheImpl();
+    $config->setQueryCache($cache);
+    $config->getQueryCache();
 
 Gets or sets the cache implementation to use for caching DQL
 queries, that is, the result of a DQL parsing process that includes
@@ -181,18 +183,9 @@ minimal memory usage in your cache).
 
 Usage of a query cache is highly recommended.
 
-The recommended implementations for production are:
-
-
--  ``Doctrine\Common\Cache\ApcCache``
--  ``Doctrine\Common\Cache\ApcuCache``
--  ``Doctrine\Common\Cache\MemcacheCache``
--  ``Doctrine\Common\Cache\XcacheCache``
--  ``Doctrine\Common\Cache\RedisCache``
-
-For development you should use the
-``Doctrine\Common\Cache\ArrayCache`` which only caches data on a
-per-request basis.
+For development you should use an array cache like
+``Symfony\Component\Cache\Adapter\ArrayAdapter``
+which only caches data on a per-request basis.
 
 SQL Logger (***Optional***)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -205,10 +198,7 @@ SQL Logger (***Optional***)
 
 Gets or sets the logger to use for logging all SQL statements
 executed by Doctrine. The logger class must implement the
-``Doctrine\DBAL\Logging\SQLLogger`` interface. A simple default
-implementation that logs to the standard output using ``echo`` and
-``var_dump`` can be found at
-``Doctrine\DBAL\Logging\EchoSQLLogger``.
+deprecated ``Doctrine\DBAL\Logging\SQLLogger`` interface.
 
 Auto-generating Proxy Classes (***OPTIONAL***)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -269,10 +259,10 @@ Development vs Production Configuration
 
 You should code your Doctrine2 bootstrapping with two different
 runtime models in mind. There are some serious benefits of using
-APC or Memcache in production. In development however this will
+APCu or Memcache in production. In development however this will
 frequently give you fatal errors, when you change your entities and
 the cache still keeps the outdated metadata. That is why we
-recommend the ``ArrayCache`` for development.
+recommend an array cache for development.
 
 Furthermore you should have the Auto-generating Proxy Classes
 option to true in development and to false in production. If this
@@ -450,22 +440,22 @@ That will be available for all entities without a custom repository class.
 The default value is ``Doctrine\ORM\EntityRepository``.
 Any repository class must be a subclass of EntityRepository otherwise you got an ORMException
 
-Setting up the Console
-----------------------
+Ignoring entities (***OPTIONAL***)
+-----------------------------------
 
-Doctrine uses the Symfony Console component for generating the command
-line interface. You can take a look at the ``vendor/bin/doctrine.php``
-script and the ``Doctrine\ORM\Tools\Console\ConsoleRunner`` command
-for inspiration how to setup the cli.
-
-In general the required code looks like this:
+Specifies the Entity FQCNs to ignore.
+SchemaTool will then skip these (e.g. when comparing schemas).
 
 .. code-block:: php
 
     <?php
-    $cli = new Application('Doctrine Command Line Interface', \Doctrine\ORM\Version::VERSION);
-    $cli->setCatchExceptions(true);
-    $cli->setHelperSet($helperSet);
-    Doctrine\ORM\Tools\Console\ConsoleRunner::addCommands($cli);
-    $cli->run();
+    $config->setSchemaIgnoreClasses([$fqcn]);
+    $config->getSchemaIgnoreClasses();
 
+
+Setting up the Console
+----------------------
+
+Doctrine uses the Symfony Console component for generating the command
+line interface. You can take a look at the
+:doc:`tools chapter <../reference/tools>` for inspiration how to setup the cli.

docs/en/reference/annotations-reference.rst

@@ -1,6 +1,11 @@
 Annotations Reference
 =====================
 
+.. note::
+
+    To be able to use annotations, you will have to install an extra
+    package called ``doctrine/annotations``.
+
 You've probably used docblock annotations in some form already,
 most likely to provide documentation metadata for a tool like
 ``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a
@@ -13,12 +18,15 @@ chances of clashes with other docblock annotations, the Doctrine ORM
 docblock annotations feature an alternative syntax that is heavily
 inspired by the Annotation syntax introduced in Java 5.
 
-The implementation of these enhanced docblock annotations is
-located in the ``Doctrine\Common\Annotations`` namespace and
-therefore part of the Common package. Doctrine ORM docblock
-annotations support namespaces and nested annotations among other
-things. The Doctrine ORM ORM defines its own set of docblock
-annotations for supplying object-relational mapping metadata.
+The implementation of these enhanced docblock annotations is located in
+the ``doctrine/annotations`` package, but in the
+``Doctrine\Common\Annotations`` namespace for backwards compatibility
+reasons. Note that ``doctrine/annotations`` is not required by Doctrine
+ORM, and you will need to require that package if you want to use
+annotations. Doctrine ORM docblock annotations support namespaces and
+nested annotations among other things. The Doctrine ORM defines its
+own set of docblock annotations for supplying object-relational mapping
+metadata.
 
 .. note::
 
@@ -115,6 +123,18 @@ Optional attributes:
 
 -  **nullable**: Determines if NULL values allowed for this column. If not specified, default value is false.
 
+-  **insertable**: Boolean value to determine if the column should be
+   included when inserting a new row into the underlying entities table. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -185,6 +205,13 @@ Examples:
      */
     protected $loginCount;
 
+    /**
+     * Generated column
+     * @Column(type="string", name="user_fullname", insertable=false, updatable=false)
+     * MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+     */
+    protected $fullname;
+
 .. _annref_column_result:
 
 @ColumnResult
@@ -398,11 +425,11 @@ Example:
 
     <?php
     /**
-     * @Entity(repositoryClass="MyProject\UserRepository")
+     * @Entity(repositoryClass="MyProject\UserRepository", readOnly=true)
      */
     class User
     {
-        //...
+        // ...
     }
 
 .. _annref_entity_result:
@@ -455,7 +482,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``, ``IDENTITY``, ``UUID`` (deprecated), ``CUSTOM`` and ``NONE``, explained
+   in the :ref:`Identifier Generation Strategies <identifier-generation-strategies>` section.
    If not specified, default value is AUTO.
 
 Example:

docs/en/reference/architecture.rst

@@ -66,6 +66,8 @@ The root namespace of the ORM package is ``Doctrine\ORM``.
 Terminology
 -----------
 
+.. _terminology_entities:
+
 Entities
 ~~~~~~~~
 
@@ -82,9 +84,13 @@ be any regular PHP class observing the following restrictions:
    :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
 -  An entity class must not implement ``__wakeup`` or
    :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
-   Also consider implementing
-   `Serializable <http://php.net/manual/en/class.serializable.php>`_
-   instead.
+   You can also consider implementing
+   `Serializable <https://php.net/manual/en/class.serializable.php>`_,
+   but be aware that it is deprecated since PHP 8.1. We do not recommend its usage.
+-  PHP 7.4 introduces :doc:`the new magic method <https://php.net/manual/en/language.oop5.magic.php#object.unserialize>`
+   ``__unserialize``, which changes the execution priority between
+   ``__wakeup`` and itself when used. This can cause unexpected behaviour in
+   an Entity.
 -  Any two entity classes in a class hierarchy that inherit
    directly or indirectly from one another must not have a mapped
    property with the same name. That is, if B inherits from A then B
@@ -93,6 +99,7 @@ be any regular PHP class observing the following restrictions:
 -  An entity cannot make use of func_get_args() to implement variable parameters.
    Generated proxies do not support this for performance reasons and your code might
    actually fail to work when violating this restriction.
+-  Entity cannot access private/protected properties/methods of another entity of the same class or :doc:`do so safely <../cookbook/accessing-private-properties-of-the-same-class-from-different-instance>`.
 
 Entities support inheritance, polymorphic associations, and
 polymorphic queries. Both abstract and concrete classes can be
@@ -161,7 +168,8 @@ possible for ``__sleep`` to return names of private properties in
 parent classes. On the other hand it is not a solution for proxy
 objects to implement ``Serializable`` because Serializable does not
 work well with any potential cyclic object references (at least we
-did not find a way yet, if you did, please contact us).
+did not find a way yet, if you did, please contact us). The
+``Serializable`` interface is also deprecated beginning with PHP 8.1.
 
 The EntityManager
 ~~~~~~~~~~~~~~~~~
@@ -184,12 +192,14 @@ in well defined units of work. Work with your objects and modify
 them as usual and when you're done call ``EntityManager#flush()``
 to make your changes persistent.
 
+.. _unit-of-work:
+
 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

@@ -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 (
@@ -429,7 +430,7 @@ The following example sets up such a unidirectional one-to-many association:
             // ...
 
             /**
-             * Many User have Many Phonenumbers.
+             * Many Users have Many Phonenumbers.
              * @ManyToMany(targetEntity="Phonenumber")
              * @JoinTable(name="users_phonenumbers",
              *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
@@ -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

docs/en/reference/attributes-reference.rst

@@ -10,6 +10,8 @@ annotation metadata supported since the first version 2.0.
 Index
 -----
 
+-  :ref:`#[AssociationOverride] <attrref_associationoverride]`
+-  :ref:`#[AttributeOverride] <attrref_attributeoverride]`
 -  :ref:`#[Column] <attrref_column>`
 -  :ref:`#[Cache] <attrref_cache>`
 -  :ref:`#[ChangeTrackingPolicy <attrref_changetrackingpolicy>`
@@ -49,6 +51,93 @@ Index
 Reference
 ---------
 
+.. _attrref_associationoverride:
+
+#[AssociationOverride]
+~~~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+assocation mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AssociationOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+
+Optional parameters:
+
+-  **joinColumns**: A list of nested ``#[JoinColumn]`` declarations.
+-  **joinTable**: A nested ``#[JoinTable]`` declaration in case of a many-to-many overwrite.
+-  **inversedBy**: The name of the inversedBy field on the target entity side.
+-  **fetch**: The fetch strategy, one of: EAGER, LAZY, EXTRA_LAZY.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AssociationOverride;
+    use Doctrine\ORM\Mapping\AssociationOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[AssociationOverrides([
+        new AssociationOverride(
+            name: "groups",
+            joinTable: new JoinTable(
+                name: "ddc964_users_admingroups",
+            ),
+            joinColumns: [new JoinColumn(name: "adminuser_id")],
+            inverseJoinColumns: [new JoinColumn(name: "admingroup_id")]
+        ),
+        new AssociationOverride(
+            name: "address",
+            joinColumns: [new JoinColumn(name: "adminaddress_id", referencedColumnName: "id")]
+        )
+    ])]
+    class DDC964Admin extends DDC964User
+    {
+    }
+
+.. _attrref_attributeoverride:
+
+#[AttributeOverride]
+~~~~~~~~~~~~~~~~~~~~
+
+In an inheritance hierarchy this attribute allows to override the
+field mapping definitions of the parent mappings. It needs to be nested
+within a ``#[AttributeOverrides]`` on the class level.
+
+Required parameters:
+
+-  **name**: Name of the association mapping to overwrite.
+-  **column**: A nested ``#[Column]`` attribute with the overwritten field settings.
+
+Examples:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\AttributeOverride;
+    use Doctrine\ORM\Mapping\AttributeOverrides;
+    use Doctrine\ORM\Mapping\Column;
+    use Doctrine\ORM\Mapping\Entity;
+
+    #[Entity]
+    #[AttributeOverrides([
+        new AttributeOverride(
+            name: "id",
+            column: new Column(name: "guest_id", type: "integer", length: 140)
+        ),
+        new AttributeOverride(
+            name: "name",
+            column: new Column(name: "guest_name", nullable: false, unique: true, length: 240)
+        )]
+    )]
+    class DDC964Guest extends DDC964User
+    {
+    }
+
 .. _attrref_column:
 
 #[Column]
@@ -59,12 +148,12 @@ inside the instance variables PHP DocBlock comment. Any value hold
 inside this variable will be saved to and loaded from the database
 as part of the lifecycle of the instance variables entity-class.
 
-Required attributes:
+Required parameters:
 
 -  **type**: Name of the DBAL Type which does the conversion between PHP
    and Database representation.
 
-Optional attributes:
+Optional parameters:
 
 -  **name**: By default the property name is used for the database
    column name also, however the ``name`` attribute allows you to
@@ -89,6 +178,18 @@ Optional attributes:
 -  **nullable**: Determines if NULL values allowed for this column.
     If not specified, default value is ``false``.
 
+-  **insertable**: Boolean value to determine if the column should be
+   included when inserting a new row into the underlying entities table. 
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -159,13 +260,22 @@ Examples:
     )]
     protected $loginCount;
 
+    // MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+    #[Column(
+        type: "string",
+        name: "user_fullname",
+        insertable: false,
+        updatable: false
+    )]
+    protected $fullname;
+
 .. _attrref_cache:
 
 #[Cache]
 ~~~~~~~~
 Add caching strategy to a root entity or a collection.
 
-Optional attributes:
+Optional parameters:
 
 -  **usage**: One of ``READ_ONLY``, ``READ_WRITE`` or ``NONSTRICT_READ_WRITE``, By default this is ``READ_ONLY``.
 -  **region**: An specific region name
@@ -210,7 +320,7 @@ Example:
 
 This attribute allows you to specify a user-provided class to generate identifiers. This attribute only works when both :ref:`#[Id] <attrref_id>` and :ref:`#[GeneratedValue(strategy: "CUSTOM")] <attrref_generatedvalue>` are specified.
 
-Required attributes:
+Required parameters:
 
 -  **class**: name of the class which should extend Doctrine\ORM\Id\AbstractIdGenerator
 
@@ -244,13 +354,13 @@ actually instantiated as.
 If this attribute is not specified, the discriminator column defaults
 to a string column of length 255 called ``dtype``.
 
-Required attributes:
+Required parameters:
 
 
 -  **name**: The column name of the discriminator. This name is also
    used during Array hydration as key to specify the class-name.
 
-Optional attributes:
+Optional parameters:
 
 
 -  **type**: By default this is string.
@@ -319,7 +429,7 @@ attribute to establish the relationship between the two classes.
 The embedded attribute is required on an entity's member variable,
 in order to specify that it is an embedded class.
 
-Required attributes:
+Required parameters:
 
 -  **class**: The embeddable class
 
@@ -331,7 +441,7 @@ Required attributes:
 Required attribute to mark a PHP class as an entity. Doctrine manages
 the persistence of all classes marked as entities.
 
-Optional attributes:
+Optional parameters:
 
 -  **repositoryClass**: Specifies the FQCN of a subclass of the
    ``EntityRepository``. Use of repositories for entities is encouraged to keep
@@ -352,10 +462,10 @@ Example:
     #[Entity(repositoryClass: UserRepository::class, readOnly: false)]
     class User
     {
-        //...
+        // ...
     }
 
-.. _attrref_entity_result:
+.. _attrref_generatedvalue:
 
 #[GeneratedValue]
 ~~~~~~~~~~~~~~~~~
@@ -368,11 +478,11 @@ conjunction with #[Id].
 If this attribute is not specified with ``#[Id]`` the ``NONE`` strategy is
 used as default.
 
-Optional attributes:
+Optional parameters:
 
 -  **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``, ``IDENTITY``, ``UUID``
+   (deprecated), ``CUSTOM`` and ``NONE``.
    If not specified, the default value is ``AUTO``.
 
 Example:
@@ -384,7 +494,7 @@ Example:
     use Doctrine\ORM\Mapping\GeneratedValue;
     use Doctrine\ORM\Mapping\Id;
 
-    #[Id, Column(type: "integer"), GeneratedValue(strategy="IDENTITY")]
+    #[Id, Column(type: "integer"), GeneratedValue(strategy: "IDENTITY")]
     protected $id = null;
 
 .. _attrref_haslifecyclecallbacks:
@@ -424,12 +534,14 @@ Attribute is used on the entity-class level. It provides a hint to the SchemaToo
 generate a database index on the specified table columns. It only
 has meaning in the ``SchemaTool`` schema generation context.
 
-Required attributes:
+Required parameters:
 
 -  **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:
+
+Optional parameters:
 
 -  **options**: Array of platform specific options:
 
@@ -446,6 +558,7 @@ Basic example:
 
     #[Entity]
     #[Index(name: "category_idx", columns: ["category"])]
+    #[Index(name: "brand_idx", fields: ["brand"])]
     class ECommerceProduct
     {
     }
@@ -457,7 +570,7 @@ Example with partial indexes:
     <?php
     use Doctrine\ORM\Mapping\Index;
 
-    #[Index(name: "search_idx", columns: {"category"},
+    #[Index(name: "search_idx", columns: ["category"],
         options: [
             "where": "((category IS NOT NULL))"
         ]
@@ -485,7 +598,7 @@ Example:
     use Doctrine\ORM\Mapping\Column;
     use Doctrine\ORM\Mapping\Id;
 
-    #[Id, Column(type="integer")]
+    #[Id, Column(type: "integer")]
     protected $id = null;
 
 .. _attrref_inheritancetype:
@@ -514,8 +627,8 @@ Examples:
 
     #[Entity]
     #[InheritanceType("SINGLE_TABLE")]
-    #[DiscriminatorColumn(name="discr", type="string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorColumn(name: "discr", type: "string")]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -523,8 +636,8 @@ Examples:
 
     #[Entity]
     #[InheritanceType("JOINED")]
-    #[DiscriminatorColumn(name="discr", type="string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorColumn(name: "discr", type: "string")]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -543,9 +656,10 @@ are missing they will be computed considering the field's name and the current
 
 The ``#[InverseJoinColumn]`` is the same as ``#[JoinColumn]`` and is used in the context
 of a ``#[ManyToMany]`` attribute declaration to specifiy the details of the join table's
-column information used for the join to the inverse entity.
+column information used for the join to the inverse entity. This is only required
+on PHP 8.0, where nested attributes are not yet supported.
 
-Optional attributes:
+Optional parameters:
 
 -  **name**: Column name that holds the foreign key identifier for
    this relation. In the context of ``#[JoinTable]`` it specifies the column
@@ -593,7 +707,7 @@ details of the database join table. If you do not specify
 using the affected table and the column names.
 
 A notable difference to the annotation metadata support, ``#[JoinColumn]``
-and ``#[InverseJoinColumn]`` are specified at the property level and are not
+and ``#[InverseJoinColumn]`` can be specified at the property level and are not
 nested within the ``#[JoinTable]`` attribute.
 
 Required attribute:
@@ -620,14 +734,14 @@ Example:
 Defines that the annotated instance variable holds a reference that
 describes a many-to-one relationship between two entities.
 
-Required attributes:
+Required parameters:
 
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 
 -  **cascade**: Cascade Option
@@ -656,14 +770,14 @@ additional, optional attribute that has reasonable default
 configuration values using the table and names of the two related
 entities.
 
-Required attributes:
+Required parameters:
 
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 
 -  **mappedBy**: This option specifies the property name on the
@@ -717,7 +831,7 @@ The ``#[MappedSuperclass]`` attribute cannot be used in conjunction with
 ``#[Entity]``. See the Inheritance Mapping section for
 :doc:`more details on the restrictions of mapped superclasses <inheritance-mapping>`.
 
-Optional attributes:
+Optional parameters:
 
 -  **repositoryClass**: Specifies the FQCN of a subclass of the EntityRepository.
    That will be inherited for all subclasses of that Mapped Superclass.
@@ -736,7 +850,7 @@ Example:
         // ... fields and methods
     }
 
-    #[Entiy]
+    #[Entity]
     class EntitySubClassFoo extends BaseEntity
     {
         // ... fields and methods
@@ -753,13 +867,13 @@ be specified. When no
 :ref:`#[JoinColumn] <attrref_joincolumn>` is specified it defaults to using the target entity table and
 primary key column names and the current naming strategy to determine a name for the join column.
 
-Required attributes:
+Required parameters:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 -  **cascade**: Cascade Option
 -  **fetch**: One of LAZY or EAGER
@@ -783,13 +897,13 @@ Example:
 #[OneToMany]
 ~~~~~~~~~~~~
 
-Required attributes:
+Required parameters:
 
 -  **targetEntity**: FQCN of the referenced target entity. Can be the
    unqualified class name if both classes are in the same namespace.
    *IMPORTANT:* No leading backslash!
 
-Optional attributes:
+Optional parameters:
 
 -  **cascade**: Cascade Option
 -  **orphanRemoval**: Boolean that specifies if orphans, inverse
@@ -913,11 +1027,11 @@ For use with ``#[GeneratedValue(strategy: "SEQUENCE")]`` this
 attribute allows to specify details about the sequence, such as
 the increment size and initial values of the sequence.
 
-Required attributes:
+Required parameters:
 
 -  **sequenceName**: Name of the sequence
 
-Optional attributes:
+Optional parameters:
 
 -  **allocationSize**: Increment the sequence by the allocation size
    when its fetched. A value larger than 1 allows optimization for
@@ -951,11 +1065,11 @@ placed on the entity-class level and is optional. If it is
 not specified the table name will default to the entity's
 unqualified classname.
 
-Required attributes:
+Required parameters:
 
 -  **name**: Name of the table
 
-Optional attributes:
+Optional parameters:
 
 -  **schema**: Name of the schema the table lies in.
 
@@ -982,12 +1096,12 @@ generate a database unique constraint on the specified table
 columns. It only has meaning in the SchemaTool schema generation
 context.
 
-Required attributes:
+Required parameters:
 
 -  **name**: Name of the Index
 -  **columns**: Array of columns.
 
-Optional attributes:
+Optional parameters:
 
 -  **options**: Array of platform specific options:
 
@@ -1003,7 +1117,7 @@ Basic example:
     use Doctrine\ORM\Mapping\UniqueConstraint;
 
     #[Entity]
-    #[UniqueConstraint(name: "ean", columns=["ean"])]
+    #[UniqueConstraint(name: "ean", columns: ["ean"])]
     class ECommerceProduct
     {
     }

docs/en/reference/basic-mapping.rst

@@ -14,17 +14,11 @@ After working through this guide you should know:
 Mapping of associations will be covered in the next chapter on
 :doc:`Association Mapping <association-mapping>`.
 
-Guide Assumptions
------------------
-
-You should have already :doc:`installed and configure <configuration>`
-Doctrine.
-
 Creating Classes for the Database
 ---------------------------------
 
 Every PHP object that you want to save in the database using Doctrine
-is called an "Entity". The term "Entity" describes objects
+is called an *Entity*. The term "Entity" describes objects
 that have an identity over many independent requests. This identity is
 usually achieved by assigning a unique identifier to an entity.
 In this tutorial the following ``Message`` PHP class will serve as the
@@ -50,10 +44,11 @@ that describes your entity.
 Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
+-  :doc:`Attributes <attributes-reference>`
 -  :doc:`Docblock Annotations <annotations-reference>`
 -  :doc:`XML <xml-mapping>`
--  :doc:`YAML <yaml-mapping>`
 -  :doc:`PHP code <php-mapping>`
+-  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via docblock annotations, though
 many examples also show the equivalent configuration in YAML and XML.
@@ -61,8 +56,8 @@ many examples also show the equivalent configuration in YAML and XML.
 .. note::
 
     All metadata drivers perform equally. Once the metadata of a class has been
-    read from the source (annotations, xml or yaml) it is stored in an instance
-    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
+    read from the source (attributes, annotations, XML, etc.) it is stored in an instance
+    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class which are
     stored in the metadata cache.  If you're not using a metadata cache (not
     recommended!) then the XML driver is the fastest.
 
@@ -70,13 +65,26 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+
+        #[Entity]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+
         /** @Entity */
         class Message
         {
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -99,16 +107,32 @@ You can change this by configuring information about the table:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
+        #[Entity]
+        #[Table(name: 'message')]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
         /**
          * @Entity
          * @Table(name="message")
          */
         class Message
         {
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -131,19 +155,38 @@ Now the class ``Message`` will be saved and fetched from the table ``message``.
 Property Mapping
 ----------------
 
-The next step after marking a PHP class as an entity is mapping its properties
-to columns in a table.
+The next step is mapping its properties to columns in the table.
 
-To configure a property use the ``@Column`` docblock annotation. The ``type``
+To configure a property use the ``Column`` docblock annotation. The ``type``
 attribute specifies the :ref:`Doctrine Mapping Type <reference-mapping-types>`
 to use for the field. If the type is not specified, ``string`` is used as the
 default.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Column;
+        use Doctrine\DBAL\Types\Types;
+
+        #[Entity]
+        class Message
+        {
+            #[Column(type: Types::INTEGER)]
+            private $id;
+            #[Column(length: 140)]
+            private $text;
+            #[Column(name: 'posted_at', type: Types::DATETIME)]
+            private $postedAt;
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Column;
+
         /** @Entity */
         class Message
         {
@@ -179,36 +222,34 @@ default.
               column: posted_at
 
 When we don't explicitly specify a column name via the ``name`` option, Doctrine
-assumes the field name is also the column name. This means that:
+assumes the field name is also the column name. So in this example:
 
 * the ``id`` property will map to the column ``id`` using the type ``integer``;
 * the ``text`` property will map to the column ``text`` with the default mapping type ``string``;
 * the ``postedAt`` property will map to the ``posted_at`` column with the ``datetime`` type.
 
-The Column annotation has some more attributes. Here is a complete
-list:
+Here is a complete list of ``Column``s attributes (all optional):
 
-- ``type``: (optional, defaults to 'string') The mapping type to
-  use for the column.
-- ``name``: (optional, defaults to field name) The name of the
-  column in the database.
-- ``length``: (optional, default 255) The length of the column in
-  the database. (Applies only if a string-valued column is used).
-- ``unique``: (optional, default FALSE) Whether the column is a
-  unique key.
-- ``nullable``: (optional, default FALSE) Whether the database
-  column is nullable.
-- ``precision``: (optional, default 0) The precision for a decimal
-  (exact numeric) column (applies only for decimal column),
+- ``type`` (default: 'string'): The mapping type to use for the column.
+- ``name`` (default: name of property): The name of the column in the database.
+- ``length`` (default: 255): The length of the column in the database.
+  Applies only if a string-valued column is used.
+- ``unique`` (default: ``false``): Whether the column is a unique key.
+- ``nullable`` (default: ``false``): Whether the column is nullable.
+- ``insertable`` (default: ``true``): Whether the column should be inserted.
+- ``updatable`` (default: ``true``): Whether the column should be updated.
+- ``enumType`` (requires PHP 8.1 and ``doctrine/orm`` 2.11): The PHP enum class name to convert the database value into.
+- ``precision`` (default: 0): The precision for a decimal (exact numeric) column
+  (applies only for decimal column),
   which is the maximum number of digits that are stored for the values.
-- ``scale``: (optional, default 0) The scale for a decimal (exact
+- ``scale`` (default: 0): The scale for a decimal (exact
   numeric) column (applies only for decimal column), which represents
   the number of digits to the right of the decimal point and must
-  not be greater than *precision*.
-- ``columnDefinition``: (optional) Allows to define a custom
+  not be greater than ``precision``.
+- ``columnDefinition``: Allows to define a custom
   DDL snippet that is used to create the column. Warning: This normally
-  confuses the SchemaTool to always detect the column as changed.
-- ``options``: (optional) Key-value pairs of options that get passed
+  confuses the :doc:`SchemaTool <tools>` to always detect the column as changed.
+- ``options``: Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
 .. _reference-php-mapping-types:
@@ -216,19 +257,35 @@ list:
 PHP Types Mapping
 _________________
 
-Since version 2.9 Doctrine can determine usable defaults from property types
-on entity classes. When property type is nullable the default for ``nullable``
-Column attribute is set to TRUE. Additionally, Doctrine will map PHP types
-to ``type`` attribute as follows:
+.. versionadded:: 2.9
 
-- ``DateInterval``: ``dateinterval``
-- ``DateTime``: ``datetime``
-- ``DateTimeImmutable``: ``datetime_immutable``
-- ``array``: ``json``
-- ``bool``: ``boolean``
-- ``float``: ``float``
-- ``int``: ``integer``
-- ``string`` or any other type: ``string``
+The column types can be inferred automatically from PHP's property types.
+However, when the property type is nullable this has no effect on the ``nullable`` Column attribute.
+
+These are the "automatic" mapping rules:
+
++-----------------------+-------------------------------+
+| PHP property type     | Doctrine column type          |
++=======================+===============================+
+| ``DateInterval``      | ``Types::DATEINTERVAL``       |
++-----------------------+-------------------------------+
+| ``DateTime``          | ``Types::DATETIME_MUTABLE``   |
++-----------------------+-------------------------------+
+| ``DateTimeImmutable`` | ``Types::DATETIME_IMMUTABLE`` |
++-----------------------+-------------------------------+
+| ``array``             | ``Types::JSON``               |
++-----------------------+-------------------------------+
+| ``bool``              | ``Types::BOOLEAN``            |
++-----------------------+-------------------------------+
+| ``float``             | ``Types::FLOAT``              |
++-----------------------+-------------------------------+
+| ``int``               | ``Types::INTEGER``            |
++-----------------------+-------------------------------+
+| Any other type        | ``Types::STRING``             |
++-----------------------+-------------------------------+
+
+As of version 2.11 Doctrine can also automatically map typed properties using a
+PHP 8.1 enum to set the right ``type`` and ``enumType``.
 
 .. _reference-mapping-types:
 
@@ -289,7 +346,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.
 
@@ -319,7 +376,7 @@ annotation.
              * @GeneratedValue
              */
             private $id;
-            //...
+            // ...
         }
 
     .. code-block:: xml
@@ -350,6 +407,8 @@ what you want. It defaults to the identifier generation mechanism your current
 database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL
 and Oracle and so on.
 
+.. _identifier-generation-strategies:
+
 Identifier Generation Strategies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -374,11 +433,8 @@ Here is the list of possible generation strategies:
    strategy does currently not provide full portability and is
    supported by the following platforms: MySQL/SQLite/SQL Anywhere
    (AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
--  ``UUID``: Tells Doctrine to use the built-in Universally Unique Identifier
-   generator. This strategy provides full portability.
--  ``TABLE``: Tells Doctrine to use a separate table for ID
-   generation. This strategy provides full portability.
-   ***This strategy is not yet implemented!***
+-  ``UUID`` (deprecated): Tells Doctrine to use the built-in Universally
+   Unique Identifier generator. This strategy provides full portability.
 -  ``NONE``: Tells Doctrine that the identifiers are assigned (and
    thus generated) by your code. The assignment must take place before
    a new entity is passed to ``EntityManager#persist``. NONE is the
@@ -406,7 +462,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

docs/en/reference/caching.rst

@@ -1,266 +1,14 @@
 Caching
 =======
 
-Doctrine provides cache drivers in the ``doctrine/cache`` package for some
-of the most popular caching implementations such as APCu, Memcache
-and Xcache. We also provide an ``ArrayCache`` driver which stores
-the data in a PHP array. Obviously, when using ``ArrayCache``, the 
-cache does not persist between requests, but this is useful for 
-testing in a development environment.
+The Doctrine ORM package can leverage cache adapters implementing the PSR-6
+standard to allow you to improve the performance of various aspects of
+Doctrine by simply making some additional configurations and method calls.
 
-Cache Drivers
--------------
+.. _types-of-caches:
 
-The cache drivers follow a simple interface that is defined in
-``Doctrine\Common\Cache\Cache``. All the cache drivers extend a
-base class ``Doctrine\Common\Cache\CacheProvider`` which implements
-this interface.
-
-The interface defines the following public methods for you to implement:
-
-
--  fetch($id) - Fetches an entry from the cache
--  contains($id) - Test if an entry exists in the cache
--  save($id, $data, $lifeTime = false) - Puts data into the cache for x seconds. 0 = infinite time
--  delete($id) - Deletes a cache entry
-
-Each driver extends the ``CacheProvider`` class which defines a few
-abstract protected methods that each of the drivers must
-implement:
-
-
--  doFetch($id)
--  doContains($id)
--  doSave($id, $data, $lifeTime = false)
--  doDelete($id)
-
-The public methods ``fetch()``, ``contains()`` etc. use the
-above protected methods which are implemented by the drivers. The
-code is organized this way so that the protected methods in the
-drivers do the raw interaction with the cache implementation and
-the ``CacheProvider`` can build custom functionality on top of
-these methods.
-
-This documentation does not cover every single cache driver included
-with Doctrine. For an up-to-date-list, see the
-`cache directory on GitHub <https://github.com/doctrine/cache/tree/2.8.x/lib/Doctrine/Common/Cache>`_.
-
-PhpFileCache
-~~~~~~~~~~~~
-
-The preferred cache driver for metadata and query caches is ``PhpFileCache``.
-This driver serializes cache items and writes them to a file. This allows for
-opcode caching to be used and provides high performance in most scenarios.
-
-In order to use the ``PhpFileCache`` driver it must be able to write to
-a directory.
-
-Below is an example of how to use the ``PhpFileCache`` driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
-        '/path/to/writable/directory'
-    );
-    $cacheDriver->save('cache_id', 'my_data');
-
-The PhpFileCache is not distributed across multiple machines if you are running
-your application in a distributed setup. This is ok for the metadata and query
-cache but is not a good approach for the result cache.
-
-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
-give you a little background information about what it is and how
-you can use it as well as how to install it.
-
-Below is a simple example of how you could use the Memcache cache
-driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $memcache = new Memcache();
-    $memcache->connect('memcache_host', 11211);
-    
-    $cacheDriver = new \Doctrine\Common\Cache\MemcacheCache();
-    $cacheDriver->setMemcache($memcache);
-    $cacheDriver->save('cache_id', 'my_data');
-
-Memcached
-~~~~~~~~~
-
-Memcached is a more recent and complete alternative extension to
-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
-give you a little background information about what it is and how
-you can use it as well as how to install it.
-
-Below is a simple example of how you could use the Memcached cache
-driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $memcached = new Memcached();
-    $memcached->addServer('memcache_host', 11211);
-    
-    $cacheDriver = new \Doctrine\Common\Cache\MemcachedCache();
-    $cacheDriver->setMemcached($memcached);
-    $cacheDriver->save('cache_id', 'my_data');
-
-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
-`A PHP extension for Redis <https://github.com/nicolasff/phpredis/>`_ for how you can use
-and install the Redis PHP extension.
-
-Below is a simple example of how you could use the Redis cache
-driver by itself.
-
-.. code-block:: php
-
-    <?php
-    $redis = new Redis();
-    $redis->connect('redis_host', 6379);
-
-    $cacheDriver = new \Doctrine\Common\Cache\RedisCache();
-    $cacheDriver->setRedis($redis);
-    $cacheDriver->save('cache_id', 'my_data');
-
-Using Cache Drivers
--------------------
-
-In this section we'll describe how you can fully utilize the API of
-the cache drivers to save data to a cache, check if some cached data 
-exists, fetch the cached data and delete the cached data. We'll use the
-``ArrayCache`` implementation as our example here.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver = new \Doctrine\Common\Cache\ArrayCache();
-
-Saving
-~~~~~~
-
-Saving some data to the cache driver is as simple as using the
-``save()`` method.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver->save('cache_id', 'my_data');
-
-The ``save()`` method accepts three arguments which are described
-below:
-
-
--  ``$id`` - The cache id
--  ``$data`` - The cache entry/data.
--  ``$lifeTime`` - The lifetime. If != false, sets a specific
-   lifetime for this cache entry (null => infinite lifeTime).
-
-You can save any type of data whether it be a string, array,
-object, etc.
-
-.. code-block:: php
-
-    <?php
-    $array = array(
-        'key1' => 'value1',
-        'key2' => 'value2'
-    );
-    $cacheDriver->save('my_array', $array);
-
-Checking
-~~~~~~~~
-
-Checking whether cached data exists is very simple: just use the
-``contains()`` method. It accepts a single argument which is the ID
-of the cache entry.
-
-.. code-block:: php
-
-    <?php
-    if ($cacheDriver->contains('cache_id')) {
-        echo 'cache exists';
-    } else {
-        echo 'cache does not exist';
-    }
-
-Fetching
-~~~~~~~~
-
-Now if you want to retrieve some cache entry you can use the
-``fetch()`` method. It also accepts a single argument just like
-``contains()`` which is again the ID of the cache entry.
-
-.. code-block:: php
-
-    <?php
-    $array = $cacheDriver->fetch('my_array');
-
-Deleting
-~~~~~~~~
-
-As you might guess, deleting is just as easy as saving, checking
-and fetching. You can delete by an individual ID, or you can 
-delete all entries.
-
-By Cache ID
-^^^^^^^^^^^
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver->delete('my_array');
-
-All
-^^^
-
-If you simply want to delete all cache entries you can do so with
-the ``deleteAll()`` method.
-
-.. code-block:: php
-
-    <?php
-    $deleted = $cacheDriver->deleteAll();
-
-Namespaces
-~~~~~~~~~~
-
-If you heavily use caching in your application and use it in
-multiple parts of your application, or use it in different
-applications on the same server you may have issues with cache
-naming collisions. This can be worked around by using namespaces.
-You can set the namespace a cache driver should use by using the
-``setNamespace()`` method.
-
-.. code-block:: php
-
-    <?php
-    $cacheDriver->setNamespace('my_namespace_');
-
-.. _integrating-with-the-orm:
-
-Integrating with the ORM
-------------------------
-
-The Doctrine ORM package is tightly integrated with the cache
-drivers to allow you to improve the performance of various aspects of
-Doctrine by simply making some additional configurations and
-method calls.
+Types of Caches
+---------------
 
 Query Cache
 ~~~~~~~~~~~
@@ -276,28 +24,27 @@ use on your ORM configuration.
 .. code-block:: php
 
     <?php
-    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
-        '/path/to/writable/directory'
-    );
+    $cache = new \Symfony\Component\Cache\Adapter\PhpFilesAdapter('doctrine_queries');
     $config = new \Doctrine\ORM\Configuration();
-    $config->setQueryCacheImpl($cacheDriver);
+    $config->setQueryCache($cache);
 
 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
 
     <?php
-    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+    $cache = new \Symfony\Component\Cache\Adapter\PhpFilesAdapter(
+        'doctrine_results',
+        0,
         '/path/to/writable/directory'
     );
     $config = new \Doctrine\ORM\Configuration();
-    $config->setResultCacheImpl($cacheDriver);
+    $config->setResultCache($cache);
 
 Now when you're executing DQL queries you can configure them to use
 the result cache.
@@ -314,10 +61,12 @@ result cache driver.
 .. code-block:: php
 
     <?php
-    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+    $cache = new \Symfony\Component\Cache\Adapter\PhpFilesAdapter(
+        'doctrine_results',
+        0,
         '/path/to/writable/directory'
     );
-    $query->setResultCacheDriver($cacheDriver);
+    $query->setResultCache($cache);
 
 .. note::
 
@@ -369,11 +118,13 @@ first.
 .. code-block:: php
 
     <?php
-    $cacheDriver = new \Doctrine\Common\Cache\PhpFileCache(
+    $cache = \Symfony\Component\Cache\Adapter\PhpFilesAdapter(
+        'doctrine_metadata',
+        0,
         '/path/to/writable/directory'
     );
     $config = new \Doctrine\ORM\Configuration();
-    $config->setMetadataCacheImpl($cacheDriver);
+    $config->setMetadataCache($cache);
 
 Now the metadata information will only be parsed once and stored in
 the cache driver.
@@ -423,30 +174,15 @@ requested many times in a single PHP request. Even though this data
 may be stored in a fast memory cache, often that cache is over a
 network link leading to sizable network traffic.
 
-The ChainCache class allows multiple caches to be registered at once.
-For example, a per-request ArrayCache can be used first, followed by
-a (relatively) slower MemcacheCache if the ArrayCache misses.
-ChainCache automatically handles pushing data up to faster caches in
+A chain cache class allows multiple caches to be registered at once.
+For example, a per-request array cache can be used first, followed by
+a (relatively) slower Memcached cache if the array cache misses.
+The chain cache automatically handles pushing data up to faster caches in
 the chain and clearing data in the entire stack when it is deleted.
 
-A ChainCache takes a simple array of CacheProviders in the order that
-they should be used.
-
-.. code-block:: php
-
-    $arrayCache = new \Doctrine\Common\Cache\ArrayCache();
-    $memcache = new Memcache();
-    $memcache->connect('memcache_host', 11211);
-    $chainCache = new \Doctrine\Common\Cache\ChainCache([
-        $arrayCache,
-        $memcache,
-    ]);
-
-ChainCache itself extends the CacheProvider interface, so it is
-possible to create chains of chains. While this may seem like an easy
-way to build a simple high-availability cache, ChainCache does not
-implement any exception handling so using it as a high-availability
-mechanism is not recommended.
+Symfony Cache provides such a chain cache. To find out how to use it,
+please have a look at the
+`Symfony Documentation <https://symfony.com/doc/current/components/cache/adapters/chain_adapter.html>`_.
 
 Cache Slams
 -----------

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

@@ -134,6 +134,32 @@ The check whether the new value is different from the old one is
 not mandatory but recommended. That way you also have full control
 over when you consider a property changed.
 
+If your entity contains an embeddable, you will need to notify 
+separately for each property in the embeddable when it changes 
+for example:
+
+.. code-block:: php
+
+    <?php
+    // ...
+    
+    class MyEntity implements NotifyPropertyChanged
+    {
+        public function setEmbeddable(MyValueObject $embeddable)
+        {
+            if (!$embeddable->equals($this->embeddable)) {
+                // notice the entityField.embeddableField notation for referencing the property
+                $this->_onPropertyChanged('embeddable.prop1', $this->embeddable->getProp1(), $embeddable->getProp1());
+                $this->_onPropertyChanged('embeddable.prop2', $this->embeddable->getProp2(), $embeddable->getProp2());
+                $this->embeddable = $embeddable;
+            }
+        }
+    }
+
+This would update all the fields of the embeddable, you may wish to
+implement a diff method on your embedded object which returns only
+the changed fields.
+
 The negative point of this policy is obvious: You need implement an
 interface and write some plumbing code. But also note that we tried
 hard to keep this notification functionality abstract. Strictly

docs/en/reference/configuration.rst

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

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

@@ -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 ``Banlist``, it can look like this:
+
+- User
+- Banlist
+- Banlist
+- User
+- Banlist
+- User
+- Banlist
+- Banlist
+- Banlist
+
+In this form of join, the ``Banlist`` 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 Banlists is invoked on a User instance,
+it loads all the related ``Banlist`` 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.
@@ -650,11 +670,23 @@ The same restrictions apply for the reference of related entities.
 
 .. warning::
 
-    DQL DELETE statements are ported directly into a
-    Database DELETE statement and therefore bypass any events and checks for the
-    version column if they are not explicitly added to the WHERE clause
-    of the query. Additionally Deletes of specified entities are *NOT*
-    cascaded to related entities even if specified in the metadata.
+    DQL DELETE statements are ported directly into an SQL DELETE statement.
+    Therefore, some limitations apply:
+    
+    - Lifecycle events for the affected entities are not executed.
+    - A cascading ``remove`` operation (as indicated e. g. by ``cascade={"remove"}`` 
+      or ``cascade={"all"}`` in the mapping configuration) is not being performed 
+      for associated entities. You can rely on database level cascade operations by
+      configuring each join column with the ``onDelete`` option.
+    - Checks for the version column are bypassed if they are not explicitly added
+      to the WHERE clause of the query.
+      
+    When you rely on one of these features, one option is to use the 
+    ``EntityManager#remove($entity)`` method. This, however, is costly performance-wise: 
+    It means collections and related entities are fetched into memory 
+    (even if they are marked as lazy). Pulling object graphs into memory on cascade
+    can cause considerable performance overhead, especially when the cascaded collections
+    are large. Make sure to weigh the benefits and downsides.
 
 Comments in queries
 -------------------
@@ -680,29 +712,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
 ~~~~~~~~~~~~~~~~~~~~
@@ -812,7 +850,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
@@ -905,7 +943,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
@@ -1154,10 +1192,11 @@ 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``
+-  ``Query::HYDRATE_SCALAR_COLUMN``
 
 Object Hydration
 ^^^^^^^^^^^^^^^^
@@ -1223,7 +1262,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
@@ -1246,6 +1285,25 @@ You can use the ``getSingleScalarResult()`` shortcut as well:
     <?php
     $numArticles = $query->getSingleScalarResult();
 
+Scalar Column Hydration
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you have a query which returns a one-dimensional array of scalar values
+you can use scalar column hydration:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT a.id FROM CmsUser u');
+    $ids = $query->getResult(Query::HYDRATE_SCALAR_COLUMN);
+
+You can use the ``getSingleColumnResult()`` shortcut as well:
+
+.. code-block:: php
+
+    <?php
+    $ids = $query->getSingleColumnResult();
+
 Custom Hydration Modes
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -1257,13 +1315,14 @@ creating a class which extends ``AbstractHydrator``:
     <?php
     namespace MyProject\Hydrators;
 
+    use Doctrine\DBAL\FetchMode;
     use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
 
     class CustomHydrator extends AbstractHydrator
     {
         protected function _hydrateAll()
         {
-            return $this->_stmt->fetchAll(PDO::FETCH_ASSOC);
+            return $this->_stmt->fetchAll(FetchMode::FETCH_ASSOC);
         }
     }
 
@@ -1371,7 +1430,7 @@ 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
@@ -1379,14 +1438,14 @@ userland:
    ``EntityManager::refresh()`` if they are to be reloaded fully from
    the database. This query hint is deprecated and will be removed
    in the future (`Details <https://github.com/doctrine/orm/issues/8471>`_)
--  Query::HINT\_REFRESH - This query is used internally by
+-  ``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.
 
@@ -1472,6 +1531,8 @@ Given that there are 10 users and corresponding addresses in the database the ex
     a one-by-one basis once they are accessed.
 
 
+.. _dql_ebnf_grammar:
+
 EBNF
 ----
 
@@ -1500,7 +1561,6 @@ Terminals
 
 -  identifier (name, email, ...) must match ``[a-z_][a-z0-9_]*``
 -  fully_qualified_name (Doctrine\Tests\Models\CMS\CmsUser) matches PHP's fully qualified class names
--  aliased_name (CMS:CmsUser) uses two identifiers, one for the namespace alias and one for the class inside it
 -  string ('foo', 'bar''s house', '%ninja%', ...)
 -  char ('/', '\\', ' ', ...)
 -  integer (-1, 0, 1, 34, ...)
@@ -1666,7 +1726,7 @@ Literal Values
 .. code-block:: php
 
     Literal     ::= string | char | integer | float | boolean
-    InParameter ::= Literal | InputParameter
+    InParameter ::= ArithmeticExpression | InputParameter
 
 Input Parameter
 ~~~~~~~~~~~~~~~
@@ -1741,7 +1801,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

@@ -121,6 +121,56 @@ Now you can test the ``$eventSubscriber`` instance to see if the
         echo 'pre foo invoked!';
     }
 
+Registering Event Handlers
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two ways to set up an event handler:
+
+* For *all events* you can create a Lifecycle Event Listener or Subscriber class and register
+it by calling ``$eventManager->addEventListener()`` or ``eventManager->addEventSubscriber()``,
+see
+:ref:`Listening and subscribing to Lifecycle Events<listening-and-subscribing-to-lifecycle-events>`
+* For *some events* (see table below), you can create a *Lifecycle Callback* method in the
+entity, see :ref:`Lifecycle Callbacks<lifecycle-callbacks>`.
+
+.. _reference-events-lifecycle-events:
+
+Events Overview
+---------------
+
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| Event                                                           | Dispatched by         | Lifecycle | Passed                              |
+|                                                                 |                       | Callback  | Argument                            |
++=================================================================+=======================+===========+=====================================+
+| :ref:`preRemove<reference-events-pre-remove>`                   | ``$em->remove()``     | Yes       | `LifecycleEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`postRemove<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`prePersist<reference-events-pre-persist>`                 | ``$em->persist()``    | Yes       | `LifecycleEventArgs`_               |
+|                                                                 | on *initial* persist  |           |                                     |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`postPersist<reference-events-post-update-remove-persist>` | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`preUpdate<reference-events-pre-update>`                   | ``$em->flush()``      | Yes       | `PreUpdateEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`postUpdate<reference-events-post-update-remove-persist>`  | ``$em->flush()``      | Yes       | `LifecycleEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`postLoad<reference-events-post-load>`                     | Loading from database | Yes       | `LifecycleEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`loadClassMetadata<reference-events-load-class-metadata>`  | Loading of mapping    | No        | `LoadClassMetadataEventArgs`_       |
+|                                                                 | metadata              |           |                                     |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| ``onClassMetadataNotFound``                                     | ``MappingException``  | No        | `OnClassMetadataNotFoundEventArgs`_ |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`preFlush<reference-events-pre-flush>`                     | ``$em->flush()``      | Yes       | `PreFlushEventArgs`_                |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`onFlush<reference-events-on-flush>`                       | ``$em->flush()``      | No        | `OnFlushEventArgs`_                 |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`postFlush<reference-events-post-flush>`                   | ``$em->flush()``      | No        | `PostFlushEventArgs`_               |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+| :ref:`onClear<reference-events-on-clear>`                       | ``$em->clear()``      | No        | `OnClearEventArgs`_                 |
++-----------------------------------------------------------------+-----------------------+-----------+-------------------------------------+
+
 Naming convention
 ~~~~~~~~~~~~~~~~~
 
@@ -140,103 +190,7 @@ several reasons:
 An example for a correct notation can be found in the example
 ``TestEvent`` above.
 
-.. _reference-events-lifecycle-events:
-
-Lifecycle Events
-----------------
-
-The ``EntityManager`` and ``UnitOfWork`` classes trigger a bunch of
-events during the life-time of their registered entities.
-
-
-
--  ``preRemove`` - The ``preRemove`` event occurs for a given entity
-   before the respective ``EntityManager`` remove operation for that
-   entity is executed.  It is not called for a DQL ``DELETE`` statement.
--  ``postRemove`` - The ``postRemove`` event occurs for an entity after the
-   entity has been deleted. It will be invoked after the database
-   delete operations. It is not called for a DQL ``DELETE`` statement.
--  ``prePersist`` - The ``prePersist`` event occurs for a given entity
-   before the respective ``EntityManager`` persist operation for that
-   entity is executed. It should be noted that this event is only triggered on
-   *initial* persist of an entity (i.e. it does not trigger on future updates).
--  ``postPersist`` - The ``postPersist`` event occurs for an entity after
-   the entity has been made persistent. It will be invoked after the
-   database insert operations. Generated primary key values are
-   available in the postPersist event.
--  ``preUpdate`` - The ``preUpdate`` event occurs before the database
-   update operations to entity data. It is not called for a DQL
-   ``UPDATE`` statement nor when the computed changeset is empty.
--  ``postUpdate`` - The ``postUpdate`` event occurs after the database
-   update operations to entity data. It is not called for a DQL
-   ``UPDATE`` statement.
--  ``postLoad`` - The postLoad event occurs for an entity after the
-   entity has been loaded into the current ``EntityManager`` from the
-   database or after the refresh operation has been applied to it.
--  ``loadClassMetadata`` - The ``loadClassMetadata`` event occurs after the
-   mapping metadata for a class has been loaded from a mapping source
-   (annotations/xml/yaml). This event is not a lifecycle callback.
--  ``onClassMetadataNotFound`` - Loading class metadata for a particular
-   requested class name failed. Manipulating the given event args instance
-   allows providing fallback metadata even when no actual metadata exists
-   or could be found. This event is not a lifecycle callback.
--  ``preFlush`` - The ``preFlush`` event occurs at the very beginning of
-   a flush operation.
--  ``onFlush`` - The ``onFlush`` event occurs after the change-sets of all
-   managed entities are computed. This event is not a lifecycle
-   callback.
--  ``postFlush`` - The ``postFlush`` event occurs at the end of a flush operation. This
-   event is not a lifecycle callback.
--  ``onClear`` - The ``onClear`` event occurs when the
-   ``EntityManager#clear()`` operation is invoked, after all references
-   to entities have been removed from the unit of work. This event is not
-   a lifecycle callback.
-
-
-.. warning::
-
-    Note that, when using ``Doctrine\ORM\AbstractQuery#toIterable()``, ``postLoad``
-    events will be executed immediately after objects are being hydrated, and therefore
-    associations are not guaranteed to be initialized. It is not safe to combine
-    usage of ``Doctrine\ORM\AbstractQuery#toIterable()`` and ``postLoad`` event
-    handlers.
-
-.. warning::
-
-    Note that the ``postRemove`` event or any events triggered after an entity removal
-    can receive an uninitializable proxy in case you have configured an entity to
-    cascade remove relations. In this case, you should load yourself the proxy in
-    the associated pre event.
-
-You can access the Event constants from the ``Events`` class in the
-ORM package.
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Events;
-    echo Events::preUpdate;
-
-These can be hooked into by two different types of event
-listeners:
-
--  Lifecycle Callbacks are methods on the entity classes that are
-   called when the event is triggered. They receive some kind
-   of ``EventArgs`` instance.
--  Lifecycle Event Listeners and Subscribers are classes with specific callback
-   methods that receives some kind of ``EventArgs`` instance.
-
-The ``EventArgs`` instance received by the listener gives access to the entity,
-``EntityManager`` instance and other relevant data.
-
-.. note::
-
-    All Lifecycle events that happen during the ``flush()`` of
-    an ``EntityManager`` have very specific constraints on the allowed
-    operations that can be executed. Please read the
-    :ref:`reference-events-implementing-listeners` section very carefully
-    to understand which operations are allowed in which lifecycle event.
-
+.. _lifecycle-callbacks:
 
 Lifecycle Callbacks
 -------------------
@@ -250,138 +204,110 @@ specific to a particular entity class's lifecycle.
 
 .. note::
 
-    Note that Licecycle Callbacks are not supported for Embeddables.
+    Lifecycle Callbacks are not supported for :doc:`Embeddables </tutorials/embeddables>`.
 
-.. code-block:: php
+.. configuration-block::
 
-    <?php
+    .. code-block:: attribute
 
-    /** @Entity @HasLifecycleCallbacks */
-    class User
-    {
-        // ...
+        <?php
+        
+        use Doctrine\DBAL\Types\Types;
+        use Doctrine\Persistence\Event\LifecycleEventArgs;
+
+        #[Entity]
+        #[HasLifecycleCallbacks]
+        class User
+        {
+            // ...
+
+            #[Column(type: Types::STRING, length: 255)]
+            public $value;
+
+            #[PrePersist]
+            public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
+            {
+                $this->createdAt = date('Y-m-d H:i:s');
+            }
+
+            #[PrePersist]
+            public function doOtherStuffOnPrePersist()
+            {
+                $this->value = 'changed from prePersist callback!';
+            }
+
+            #[PreUpdate]
+            public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs)
+            {
+                $this->value = 'changed from preUpdate callback!';
+            }
+        }
+    .. code-block:: annotation
+
+        <?php
+        
+        use Doctrine\Persistence\Event\LifecycleEventArgs;
 
         /**
-         * @Column(type="string", length=255)
+         * @Entity
+         * @HasLifecycleCallbacks
          */
-        public $value;
-
-        /** @Column(name="created_at", type="string", length=255) */
-        private $createdAt;
-
-        /** @PrePersist */
-        public function doStuffOnPrePersist()
-        {
-            $this->createdAt = date('Y-m-d H:i:s');
-        }
-
-        /** @PrePersist */
-        public function doOtherStuffOnPrePersist()
-        {
-            $this->value = 'changed from prePersist callback!';
-        }
-
-        /** @PostPersist */
-        public function doStuffOnPostPersist()
-        {
-            $this->value = 'changed from postPersist callback!';
-        }
-
-        /** @PostLoad */
-        public function doStuffOnPostLoad()
-        {
-            $this->value = 'changed from postLoad callback!';
-        }
-
-        /** @PreUpdate */
-        public function doStuffOnPreUpdate()
-        {
-            $this->value = 'changed from preUpdate callback!';
-        }
-    }
-
-Note that the methods set as lifecycle callbacks need to be public and,
-when using these annotations, you have to apply the
-``@HasLifecycleCallbacks`` marker annotation on the entity class.
-
-If you want to register lifecycle callbacks from YAML or XML you
-can do it with the following.
-
-.. code-block:: yaml
-
-    User:
-      type: entity
-      fields:
-    # ...
-        name:
-          type: string(50)
-      lifecycleCallbacks:
-        prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
-        postPersist: [ doStuffOnPostPersist ]
-
-In YAML the ``key`` of the lifecycleCallbacks entry is the event that you
-are triggering on and the value is the method (or methods) to call. The allowed
-event types are the ones listed in the previous Lifecycle Events section.
-
-XML would look something 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
-                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-
-        <entity name="User">
-
-            <lifecycle-callbacks>
-                <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
-                <lifecycle-callback type="postPersist" method="doStuffOnPostPersist"/>
-            </lifecycle-callbacks>
-
-        </entity>
-
-    </doctrine-mapping>
-
-In XML the ``type`` of the lifecycle-callback entry is the event that you
-are triggering on and the ``method`` is the method to call. The allowed event
-types are the ones listed in the previous Lifecycle Events section.
-
-When using YAML or XML you need to remember to create public methods to match the
-callback names you defined. E.g. in these examples ``doStuffOnPrePersist()``,
-``doOtherStuffOnPrePersist()`` and ``doStuffOnPostPersist()`` methods need to be
-defined on your ``User`` model.
-
-.. code-block:: php
-
-    <?php
-    // ...
-
-    class User
-    {
-        // ...
-
-        public function doStuffOnPrePersist()
+        class User
         {
             // ...
-        }
 
-        public function doOtherStuffOnPrePersist()
-        {
-            // ...
-        }
+            /** @Column(type="string", length=255) */
+            public $value;
 
-        public function doStuffOnPostPersist()
-        {
-            // ...
-        }
-    }
+            /** @PrePersist */
+            public function doStuffOnPrePersist(LifecycleEventArgs $eventArgs)
+            {
+                $this->createdAt = date('Y-m-d H:i:s');
+            }
 
+            /** @PrePersist */
+            public function doOtherStuffOnPrePersist()
+            {
+                $this->value = 'changed from prePersist callback!';
+            }
+
+            /** @PreUpdate */
+            public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs)
+            {
+                $this->value = 'changed from preUpdate callback!';
+            }
+        }
+    .. code-block:: xml
+
+        <?xml version="1.0" encoding="UTF-8"?>
+
+        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+            <entity name="User">
+                <!-- ... -->
+                <lifecycle-callbacks>
+                    <lifecycle-callback type="prePersist" method="doStuffOnPrePersist"/>
+                    <lifecycle-callback type="prePersist" method="doOtherStuffOnPrePersist"/>
+                    <lifecycle-callback type="preUpdate" method="doStuffOnPreUpdate"/>
+                </lifecycle-callbacks>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            # ...
+            value:
+              type: string(255)
+          lifecycleCallbacks:
+            prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
+            preUpdate: [ doStuffOnPreUpdate ]
 
 Lifecycle Callbacks Event Argument
------------------------------------
+----------------------------------
 
 The triggered event is also given to the lifecycle-callback.
 
@@ -403,6 +329,8 @@ With the additional argument you have access to the
         }
     }
 
+.. _listening-and-subscribing-to-lifecycle-events:
+
 Listening and subscribing to Lifecycle Events
 ---------------------------------------------
 
@@ -413,7 +341,7 @@ behaviors across different entity classes.
 
 Note that they require much more detailed knowledge about the inner
 workings of the ``EntityManager`` and ``UnitOfWork`` classes. Please
-read the :ref:`reference-events-implementing-listeners` section
+read the :ref:`Implementing Event Listeners<reference-events-implementing-listeners>` section
 carefully if you are trying to write your own listener.
 
 For event subscribers, there are no surprises. They declare the
@@ -482,8 +410,10 @@ EventManager that is passed to the EntityManager factory:
 .. code-block:: php
 
     <?php
+    use Doctrine\ORM\Events;
+
     $eventManager = new EventManager();
-    $eventManager->addEventListener(array(Events::preUpdate), new MyEventListener());
+    $eventManager->addEventListener([Events::preUpdate], new MyEventListener());
     $eventManager->addEventSubscriber(new MyEventSubscriber());
 
     $entityManager = EntityManager::create($dbOpts, $config, $eventManager);
@@ -494,7 +424,9 @@ EntityManager was created:
 .. code-block:: php
 
     <?php
-    $entityManager->getEventManager()->addEventListener(array(Events::preUpdate), new MyEventListener());
+    use Doctrine\ORM\Events;
+
+    $entityManager->getEventManager()->addEventListener([Events::preUpdate], new MyEventListener());
     $entityManager->getEventManager()->addEventSubscriber(new MyEventSubscriber());
 
 .. _reference-events-implementing-listeners:
@@ -514,24 +446,28 @@ the restrictions apply as well, with the additional restriction
 that (prior to version 2.4) you do not have access to the
 ``EntityManager`` or ``UnitOfWork`` APIs inside these events.
 
+.. _reference-events-pre-persist:
+
 prePersist
 ~~~~~~~~~~
 
-There are two ways for the ``prePersist`` event to be triggered.
-One is obviously when you call ``EntityManager#persist()``. The
-event is also called for all cascaded associations.
+There are two ways for the ``prePersist`` event to be triggered:
 
-There is another way for ``prePersist`` to be called, inside the
+- One is obviously when you call ``EntityManager::persist()``. The
+event is also called for all :ref:`cascaded associations<transitive-persistence>`.
+- The other is inside the
 ``flush()`` method when changes to associations are computed and
-this association is marked as cascade persist. Any new entity found
+this association is marked as :ref:`cascade: persist<transitive-persistence>`. Any new entity found
 during this operation is also persisted and ``prePersist`` called
-on it. This is called "persistence by reachability".
+on it. This is called :ref:`persistence by reachability<persistence-by-reachability>`.
 
 In both cases you get passed a ``LifecycleEventArgs`` instance
 which has access to the entity and the entity manager.
 
-The following restrictions apply to ``prePersist``:
+This event is only triggered on *initial* persist of an entity
+(i.e. it does not trigger on future updates).
 
+The following restrictions apply to ``prePersist``:
 
 -  If you are using a PrePersist Identity Generator such as
    sequences the ID value will *NOT* be available within any
@@ -540,24 +476,30 @@ The following restrictions apply to ``prePersist``:
    event. This includes modifications to
    collections such as additions, removals or replacement.
 
+.. _reference-events-pre-remove:
+
 preRemove
 ~~~~~~~~~
 
-The ``preRemove`` event is called on every entity when its passed
-to the ``EntityManager#remove()`` method. It is cascaded for all
-associations that are marked as cascade delete.
+The ``preRemove`` event is called on every entity immediately when it is passed
+to the ``EntityManager::remove()`` method. It is cascaded for all
+associations that are marked as :ref:`cascade: remove<transitive-persistence>`
+
+It is not called for a DQL ``DELETE`` statement.
 
 There are no restrictions to what methods can be called inside the
 ``preRemove`` event, except when the remove method itself was
 called during a flush operation.
 
+.. _reference-events-pre-flush:
+
 preFlush
 ~~~~~~~~
 
-``preFlush`` is called at ``EntityManager#flush()`` before
-anything else. ``EntityManager#flush()`` should not be called inside
-its listeners, since `preFlush` event is dispatched in it, which would
-result in infinite loop.
+``preFlush`` is called inside ``EntityManager::flush()`` before
+anything else. ``EntityManager::flush()`` must not be called inside
+its listeners, since it would fire the ``preFlush`` event again, which would
+result in an infinite loop.
 
 .. code-block:: php
 
@@ -573,15 +515,16 @@ result in infinite loop.
         }
     }
 
+.. _reference-events-on-flush:
+
 onFlush
 ~~~~~~~
 
-OnFlush is a very powerful event. It is called inside
-``EntityManager#flush()`` after the changes to all the managed
+``onFlush`` is a very powerful event. It is called inside
+``EntityManager::flush()`` after the changes to all the managed
 entities and their associations have been computed. This means, the
 ``onFlush`` event has access to the sets of:
 
-
 -  Entities scheduled for insert
 -  Entities scheduled for update
 -  Entities scheduled for removal
@@ -589,7 +532,7 @@ entities and their associations have been computed. This means, the
 -  Collections scheduled for removal
 
 To make use of the ``onFlush`` event you have to be familiar with the
-internal ``UnitOfWork`` API, which grants you access to the previously
+internal :ref:`UnitOfWork<unit-of-work>` API, which grants you access to the previously
 mentioned sets. See this example:
 
 .. code-block:: php
@@ -624,11 +567,10 @@ mentioned sets. See this example:
         }
     }
 
-The following restrictions apply to the onFlush event:
-
+The following restrictions apply to the ``onFlush`` event:
 
 -  If you create and persist a new entity in ``onFlush``, then
-   calling ``EntityManager#persist()`` is not enough.
+   calling ``EntityManager::persist()`` is not enough.
    You have to execute an additional call to
    ``$unitOfWork->computeChangeSet($classMetadata, $entity)``.
 -  Changing primitive fields or associations requires you to
@@ -636,11 +578,14 @@ The following restrictions apply to the onFlush event:
    affected entity. This can be done by calling
    ``$unitOfWork->recomputeSingleEntityChangeSet($classMetadata, $entity)``.
 
+.. _reference-events-post-flush:
+
 postFlush
 ~~~~~~~~~
 
-``postFlush`` is called at the end of ``EntityManager#flush()``.
-``EntityManager#flush()`` can **NOT** be called safely inside its listeners.
+``postFlush`` is called at the end of ``EntityManager::flush()``.
+``EntityManager::flush()`` can **NOT** be called safely inside its listeners.
+This event is not a lifecycle callback.
 
 .. code-block:: php
 
@@ -656,26 +601,27 @@ postFlush
         }
     }
 
+.. _reference-events-pre-update:
+
 preUpdate
 ~~~~~~~~~
 
-PreUpdate is the most restrictive to use event, since it is called
-right before an update statement is called for an entity inside the
-``EntityManager#flush()`` method. Note that this event is not
-triggered when the computed changeset is empty.
+PreUpdate is called inside the ``EntityManager::flush()`` method,
+right before an SQL ``UPDATE`` statement. This event is not
+triggered when the computed changeset is empty, nor for a DQL
+   ``UPDATE`` statement.
 
 Changes to associations of the updated entity are never allowed in
 this event, since Doctrine cannot guarantee to correctly handle
 referential integrity at this point of the flush operation. This
 event has a powerful feature however, it is executed with a
-``PreUpdateEventArgs`` instance, which contains a reference to the
+`_PreUpdateEventArgs`_ instance, which contains a reference to the
 computed change-set of this entity.
 
 This means you have access to all the fields that have changed for
 this entity with their old and new value. The following methods are
 available on the ``PreUpdateEventArgs``:
 
-
 -  ``getEntity()`` to get access to the actual entity.
 -  ``getEntityChangeSet()`` to get a copy of the changeset array.
    Changes to this returned array do not affect updating.
@@ -729,32 +675,70 @@ lifecycle callback when there are expensive validations to call:
 
 Restrictions for this event:
 
-
 -  Changes to associations of the passed entities are not
    recognized by the flush operation anymore.
 -  Changes to fields of the passed entities are not recognized by
    the flush operation anymore, use the computed change-set passed to
    the event to modify primitive field values, e.g. use
    ``$eventArgs->setNewValue($field, $value);`` as in the Alice to Bob example above.
--  Any calls to ``EntityManager#persist()`` or
-   ``EntityManager#remove()``, even in combination with the ``UnitOfWork``
+-  Any calls to ``EntityManager::persist()`` or
+   ``EntityManager::remove()``, even in combination with the ``UnitOfWork``
    API are strongly discouraged and don't work as expected outside the
    flush operation.
 
+.. _reference-events-post-update-remove-persist:
+
 postUpdate, postRemove, postPersist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The three post events are called inside ``EntityManager#flush()``.
+These three post* events are called inside ``EntityManager::flush()``.
 Changes in here are not relevant to the persistence in the
 database, but you can use these events to alter non-persistable items,
 like non-mapped fields, logging or even associated classes that are
 not directly mapped by Doctrine.
 
+-  The ``postUpdate`` event occurs after the database
+   update operations to entity data. It is not called for a DQL
+   ``UPDATE`` statement.
+-  The ``postPersist`` event occurs for an entity after
+   the entity has been made persistent. It will be invoked after the
+   database insert operations. Generated primary key values are
+   available in the postPersist event.
+-  The ``postRemove`` event occurs for an entity after the
+   entity has been deleted. It will be invoked after the database
+   delete operations. It is not called for a DQL ``DELETE`` statement.
+
+.. warning::
+
+    The ``postRemove`` event or any events triggered after an entity removal
+    can receive an uninitializable proxy in case you have configured an entity to
+    cascade remove relations. In this case, you should load yourself the proxy in
+    the associated ``pre*`` event.
+
+.. _reference-events-post-load:
+
 postLoad
 ~~~~~~~~
 
-This event is called after an entity is constructed by the
-EntityManager.
+The postLoad event occurs after the entity has been loaded into the current
+``EntityManager`` from the database or after ``refresh()`` has been applied to it.
+
+.. warning::
+
+    When using ``Doctrine\ORM\AbstractQuery::toIterable()``, ``postLoad``
+    events will be executed immediately after objects are being hydrated, and therefore
+    associations are not guaranteed to be initialized. It is not safe to combine
+    usage of ``Doctrine\ORM\AbstractQuery::toIterable()`` and ``postLoad`` event
+    handlers.
+
+.. _reference-events-on-clear:
+
+onClear
+~~~~~~~~
+
+The ``onClear`` event occurs when the ``EntityManager::clear()`` operation is invoked,
+after all references to entities have been removed from the unit of work.
+This event is not a lifecycle callback.
 
 Entity listeners
 ----------------
@@ -766,7 +750,19 @@ An entity listener is a lifecycle listener class used for an entity.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+    
+        <?php
+        namespace MyProject\Entity;
+        use App\EventListener\UserListener;
+
+        #[Entity]
+        #[EntityListeners([UserListener::class])]
+        class User
+        {
+            // ....
+        }
+    .. code-block:: annotation
 
         <?php
         namespace MyProject\Entity;
@@ -900,7 +896,7 @@ you need to map the listener method using the event type mapping:
 
 
 Entity listeners resolver
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 Doctrine invokes the listener resolver to get the listener instance.
 
 - A resolver allows you register a specific entity listener instance.
@@ -962,22 +958,25 @@ Implementing your own resolver :
     $configurations->setEntityListenerResolver(new MyEntityListenerResolver);
     EntityManager::create(.., $configurations, ..);
 
+.. _reference-events-load-class-metadata:
+
 Load ClassMetadata Event
 ------------------------
 
-When the mapping information for an entity is read, it is populated
-in to a ``ClassMetadataInfo`` instance. You can hook in to this
-process and manipulate the instance.
+``loadClassMetadata`` - The ``loadClassMetadata`` event occurs after the
+mapping metadata for a class has been loaded from a mapping source
+(annotations/xml/yaml) in to a ``Doctrine\ORM\Mapping\ClassMetadata`` instance.
+You can hook in to this process and manipulate the instance.
+This event is not a lifecycle callback.
 
 .. code-block:: php
 
     <?php
-    $test = new TestEvent();
-    $metadataFactory = $em->getMetadataFactory();
+    $test = new TestEventListener();
     $evm = $em->getEventManager();
-    $evm->addEventListener(Events::loadClassMetadata, $test);
+    $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $test);
 
-    class TestEvent
+    class TestEventListener
     {
         public function loadClassMetadata(\Doctrine\ORM\Event\LoadClassMetadataEventArgs $eventArgs)
         {
@@ -991,3 +990,69 @@ process and manipulate the instance.
         }
     }
 
+If not class metadata can be found, an ``onClassMetadataNotFound`` event is dispatched.
+Manipulating the given event args instance
+allows providing fallback metadata even when no actual metadata exists
+or could be found. This event is not a lifecycle callback.
+
+SchemaTool Events
+-----------------
+
+It is possible to access the schema metadata during schema changes that are happening in ``Doctrine\ORM\Tools\SchemaTool``.
+There are two different events where you can hook in.
+
+postGenerateSchemaTable
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This event is fired for each ``Doctrine\DBAL\Schema\Table`` instance, after one was created and built up with the current class metadata
+of an entity. It is possible to access to the current state of ``Doctrine\DBAL\Schema\Schema``, the current table schema
+instance and class metadata.
+
+.. code-block:: php
+
+    <?php
+    $test = new TestEventListener();
+    $evm = $em->getEventManager();
+    $evm->addEventListener(\Doctrine\ORM\Tools\ToolEvents::postGenerateSchemaTable, $test);
+
+    class TestEventListener
+    {
+        public function postGenerateSchemaTable(\Doctrine\ORM\Tools\Event\GenerateSchemaTableEventArgs $eventArgs)
+        {
+            $classMetadata = $eventArgs->getClassMetadata();
+            $schema = $eventArgs->getSchema();
+            $table = $eventArgs->getClassTable();
+        }
+    }
+
+postGenerateSchema
+~~~~~~~~~~~~~~~~~~
+
+This event is fired after the schema instance was successfully built and before SQL queries are generated from the
+schema information of ``Doctrine\DBAL\Schema\Schema``. It allows to access the full object representation of the database schema
+and the EntityManager.
+
+.. code-block:: php
+
+    <?php
+    $test = new TestEventListener();
+    $evm = $em->getEventManager();
+    $evm->addEventListener(\Doctrine\ORM\Tools\ToolEvents::postGenerateSchema, $test);
+
+    class TestEventListener
+    {
+        public function postGenerateSchema(\Doctrine\ORM\Tools\Event\GenerateSchemaEventArgs $eventArgs)
+        {
+            $schema = $eventArgs->getSchema();
+            $em = $eventArgs->getEntityManager();
+        }
+    }
+
+.. _LifecycleEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/LifecycleEventArgs.php
+.. _PreUpdateEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreUpdateEventArgs.php
+.. _PreFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PreFlushEventArgs.php
+.. _PostFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/PostFlushEventArgs.php
+.. _OnFlushEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnFlushEventArgs.php
+.. _OnClearEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnClearEventArgs.php
+.. _LoadClassMetadataEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/LoadClassMetadataEventArgs.php
+.. _OnClassMetadataNotFoundEventArgs: https://github.com/doctrine/orm/blob/HEAD/lib/Doctrine/ORM/Event/OnClassMetadataNotFoundEventArgs.php

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/improving-performance.rst

@@ -11,7 +11,7 @@ request and can greatly improve performance.
     "If you care about performance and don't use a bytecode
     cache then you don't really care about performance. Please get one
     and start using it."
-    
+
     *Stas Malyshev, Core Contributor to PHP and Zend Employee*
 
 
@@ -27,11 +27,13 @@ Doctrine will need to load your mapping information on every single
 request and has to parse each DQL query on every single request.
 This is a waste of resources.
 
-The preferred cache driver for metadata and query caches is ``PhpFileCache``. 
-This driver serializes cache items and writes them to a file. 
+The preferred cache adapter for metadata and query caches is a PHP file
+cache like Symfony's
+`PHP files adapter <https://symfony.com/doc/current/components/cache/adapters/php_files_adapter.html>`_.
+This kind of cache serializes cache items and writes them to a file.
 This allows for opcode caching to be used and provides high performance in most scenarios.
 
-See :ref:`integrating-with-the-orm`
+See :ref:`types-of-caches`
 
 Alternative Query Result Formats
 --------------------------------
@@ -97,4 +99,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
@@ -324,7 +340,7 @@ Example:
          */
         class User
         {
-            //other fields mapping
+            // other fields mapping
 
             /**
              * @ManyToMany(targetEntity="Group", inversedBy="users")
@@ -463,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

@@ -39,8 +39,9 @@ an entity.
         $em->getConfiguration()->setMetadataCacheImpl(new ApcuCache());
 
 
-If you want to use one of the included core metadata drivers you
-just need to configure it. All the drivers are in the
+If you want to use one of the included core metadata drivers you need to
+configure it. If you pick the annotation driver, you will additionally
+need to install ``doctrine/annotations``. All the drivers are in the
 ``Doctrine\ORM\Mapping\Driver`` namespace:
 
 .. code-block:: php

docs/en/reference/php-mapping.rst

@@ -9,6 +9,11 @@ the code in PHP files or inside of a static function named
 PHP Files
 ---------
 
+.. note::
+
+   PHPDriver is deprecated and will be removed in 3.0, use StaticPHPDriver
+   instead.
+
 If you wish to write your mapping information inside PHP files that
 are named after the entity and included to populate the metadata
 for an entity you can do so by using the ``PHPDriver``:

docs/en/reference/query-builder.rst

@@ -13,7 +13,7 @@ as you want, or just pick a preferred one.
 
     The ``QueryBuilder`` is not an abstraction of DQL, but merely a tool to dynamically build it.
     You should still use plain DQL when you can, as it is simpler and more readable.
-    More about this in the :doc:`FAQ <faq>`_.
+    More about this in the :doc:`FAQ <faq>`.
 
 Constructing a new QueryBuilder object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -252,8 +252,8 @@ while the named placeholders start with a : followed by a string.
 Calling ``setParameter()`` automatically infers which type you are setting as
 value. This works for integers, arrays of strings/integers, DateTime instances
 and for managed entities. If you want to set a type explicitly you can call
-the third argument to ``setParameter()`` explicitly. It accepts either a PDO
-type or a DBAL Type name for conversion.
+the third argument to ``setParameter()`` explicitly. It accepts either a DBAL
+Doctrine\DBAL\ParameterType::* or a DBAL Type name for conversion.
 
 .. note::
 
@@ -543,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

@@ -31,31 +31,31 @@ Each cache region resides in a specific cache namespace and has its own lifetime
 Notice that when caching collection and queries only identifiers are stored.
 The entity values will be stored in its own region
 
-Something like below for an entity region :
+Something like below for an entity region:
 
 .. code-block:: php
 
     <?php
     [
-      'region_name:entity_1_hash' => ['id'=> 1, 'name' => 'FooBar', 'associationName'=>null],
-      'region_name:entity_2_hash' => ['id'=> 2, 'name' => 'Foo', 'associationName'=>['id'=>11]],
-      'region_name:entity_3_hash' => ['id'=> 3, 'name' => 'Bar', 'associationName'=>['id'=>22]]
+      'region_name:entity_1_hash' => ['id' => 1, 'name' => 'FooBar', 'associationName' => null],
+      'region_name:entity_2_hash' => ['id' => 2, 'name' => 'Foo', 'associationName' => ['id' => 11]],
+      'region_name:entity_3_hash' => ['id' => 3, 'name' => 'Bar', 'associationName' => ['id' => 22]]
     ];
 
 
 If the entity holds a collection that also needs to be cached.
-An collection region could look something like :
+An collection region could look something like:
 
 .. code-block:: php
 
     <?php
     [
-      'region_name:entity_1_coll_assoc_name_hash' => ['ownerId'=> 1, 'list' => [1, 2, 3]],
-      'region_name:entity_2_coll_assoc_name_hash' => ['ownerId'=> 2, 'list' => [2, 3]],
-      'region_name:entity_3_coll_assoc_name_hash' => ['ownerId'=> 3, 'list' => [2, 4]]
+      'region_name:entity_1_coll_assoc_name_hash' => ['ownerId' => 1, 'list' => [1, 2, 3]],
+      'region_name:entity_2_coll_assoc_name_hash' => ['ownerId' => 2, 'list' => [2, 3]],
+      'region_name:entity_3_coll_assoc_name_hash' => ['ownerId' => 3, 'list' => [2, 4]]
     ];
 
-A query region might be something like :
+A query region might be something like:
 
 .. code-block:: php
 
@@ -93,8 +93,6 @@ Cache region
 ``Doctrine\ORM\Cache\Region`` defines a contract for accessing a particular
 cache region.
 
-`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/Region.html>`_.
-
 Concurrent cache region
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -105,8 +103,6 @@ If you want to use an ``READ_WRITE`` cache, you should consider providing your o
 
 ``Doctrine\ORM\Cache\ConcurrentRegion`` defines a contract for concurrently managed data region.
 
-`See API Doc <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/ConcurrentRegion.html>`_.
-
 Timestamp region
 ~~~~~~~~~~~~~~~~
 
@@ -114,8 +110,6 @@ 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>`_.
-
 .. _reference-second-level-cache-mode:
 
 Caching mode
@@ -132,7 +126,7 @@ Caching mode
 
   * Read Write Cache doesn’t employ any locks but can do reads, inserts, updates and deletes.
   * Good if the application needs to update data rarely.
-    
+
 
 * ``READ_WRITE``
 
@@ -147,21 +141,21 @@ Built-in cached persisters
 
 Cached persisters are responsible to access cache regions.
 
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | Cache Usage           | Persister                                                                                 |
-    +=======================+===========================================================================================+
-    | READ_ONLY             | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadOnlyCachedEntityPersister                    |
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | READ_WRITE            | Doctrine\\ORM\\Cache\\Persister\\Entity\\ReadWriteCachedEntityPersister                   |
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | NONSTRICT_READ_WRITE  | Doctrine\\ORM\\Cache\\Persister\\Entity\\NonStrictReadWriteCachedEntityPersister          |
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | READ_ONLY             | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadOnlyCachedCollectionPersister            |
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | READ_WRITE            | Doctrine\\ORM\\Cache\\Persister\\Collection\\ReadWriteCachedCollectionPersister           |
-    +-----------------------+-------------------------------------------------------------------------------------------+
-    | NONSTRICT_READ_WRITE  | Doctrine\\ORM\\Cache\\Persister\\Collection\\NonStrictReadWriteCachedCollectionPersister  |
-    +-----------------------+-------------------------------------------------------------------------------------------+
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | Cache Usage           | Persister                                                                                |
+    +=======================+==========================================================================================+
+    | READ_ONLY             | ``Doctrine\ORM\Cache\Persister\Entity\ReadOnlyCachedEntityPersister``                    |
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | READ_WRITE            | ``Doctrine\ORM\Cache\Persister\Entity\ReadWriteCachedEntityPersister``                   |
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | NONSTRICT_READ_WRITE  | ``Doctrine\ORM\Cache\Persister\Entity\NonStrictReadWriteCachedEntityPersister``          |
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | READ_ONLY             | ``Doctrine\ORM\Cache\Persister\Collection\ReadOnlyCachedCollectionPersister``            |
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | READ_WRITE            | ``Doctrine\ORM\Cache\Persister\Collection\ReadWriteCachedCollectionPersister``           |
+    +-----------------------+------------------------------------------------------------------------------------------+
+    | NONSTRICT_READ_WRITE  | ``Doctrine\ORM\Cache\Persister\Collection\NonStrictReadWriteCachedCollectionPersister``  |
+    +-----------------------+------------------------------------------------------------------------------------------+
 
 Configuration
 -------------
@@ -172,15 +166,16 @@ Enable Second Level Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To enable the second-level-cache, you should provide a cache factory.
-``\Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.
+``Doctrine\ORM\Cache\DefaultCacheFactory`` is the default implementation.
 
 .. code-block:: php
 
     <?php
-    /* @var $config \Doctrine\ORM\Cache\RegionsConfiguration */
-    /* @var $cache \Doctrine\Common\Cache\Cache */
+    /** @var \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
+    /** @var \Psr\Cache\CacheItemPoolInterface $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();
@@ -195,7 +190,7 @@ Cache Factory
 
 Cache Factory is the main point of extension.
 
-It allows you to provide a specific implementation of the following components :
+It allows you to provide a specific implementation of the following components:
 
 ``QueryCache``
     stores and retrieves query cache results.
@@ -208,8 +203,6 @@ 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>`_.
-
 Region Lifetime
 ~~~~~~~~~~~~~~~
 
@@ -218,8 +211,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();
 
@@ -232,12 +226,12 @@ Cache Log
 ~~~~~~~~~
 By providing a cache logger you should be able to get information about all cache operations such as hits, misses and puts.
 
-``\Doctrine\ORM\Cache\Logging\StatisticsCacheLogger`` is a built-in implementation that provides basic statistics.
+``Doctrine\ORM\Cache\Logging\StatisticsCacheLogger`` is a built-in implementation that provides basic statistics.
 
  .. code-block:: php
 
     <?php
-    /* @var $config \Doctrine\ORM\Configuration */
+    /** @var \Doctrine\ORM\Configuration $config */
     $logger = new \Doctrine\ORM\Cache\Logging\StatisticsCacheLogger();
 
     // Cache logger
@@ -267,12 +261,9 @@ By providing a cache logger you should be able to get information about all cach
     $logger->getMissCount();
 
 If you want to get more information you should implement
-``\Doctrine\ORM\Cache\Logging\CacheLogger`` and collect
+``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>`_.
-
-
 Entity cache definition
 -----------------------
 * Entity cache configuration allows you to define the caching strategy and region for an entity.
@@ -313,7 +304,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">
@@ -328,8 +319,8 @@ level cache region.
         Country:
           type: entity
           cache:
-            usage : READ_ONLY
-            region : my_entity_region
+            usage: READ_ONLY
+            region: my_entity_region
           id:
             id:
               type: integer
@@ -389,7 +380,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" />
@@ -399,7 +390,7 @@ It caches the primary keys of association and cache each element will be cached
             </id>
 
             <field name="name" type="string" column="name"/>
-            
+
             <many-to-one field="country" target-entity="Country">
               <cache usage="NONSTRICT_READ_WRITE" />
 
@@ -419,7 +410,7 @@ It caches the primary keys of association and cache each element will be cached
         State:
           type: entity
           cache:
-            usage : NONSTRICT_READ_WRITE
+            usage: NONSTRICT_READ_WRITE
           id:
             id:
               type: integer
@@ -437,17 +428,18 @@ It caches the primary keys of association and cache each element will be cached
                 country_id:
                   referencedColumnName: id
               cache:
-                usage : NONSTRICT_READ_WRITE
+                usage: NONSTRICT_READ_WRITE
 
           oneToMany:
             cities:
               targetEntity:City
               mappedBy: state
               cache:
-                usage : NONSTRICT_READ_WRITE
+                usage: NONSTRICT_READ_WRITE
 
+.. note::
 
-> Note: for this to work, the target entity must also be marked as cacheable.
+    for this to work, the target entity must also be marked as cacheable.
 
 Cache usage
 ~~~~~~~~~~~
@@ -464,8 +456,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
@@ -490,7 +482,7 @@ Association cache
     $state = $em->find('State', 1);
 
     // Hit database to update the row and update cache entry
-    $state->setName("New Name");
+    $state->setName('New Name');
     $em->persist($state);
     $em->flush();
 
@@ -541,14 +533,14 @@ The query cache stores the results of the query but as identifiers, entity value
 .. code-block:: php
 
     <?php
-    /* @var $em \Doctrine\ORM\EntityManager */
+    /** @var \Doctrine\ORM\EntityManager $em */
 
     // Execute database query, store query cache and entity cache
     $result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
         ->setCacheable(true)
         ->getResult();
 
-    $em->clear()
+    $em->clear();
 
     // Check if query result is valid and load entities from cache
     $result2 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
@@ -568,16 +560,16 @@ The Cache Mode controls how a particular query interacts with the second-level c
 .. code-block:: php
 
     <?php
-    /* @var $em \Doctrine\ORM\EntityManager */
+    /** @var \Doctrine\ORM\EntityManager $em */
     // Will refresh the query cache and all entities the cache as it reads from the database.
     $result1 = $em->createQuery('SELECT c FROM Country c ORDER BY c.name')
-        ->setCacheMode(Cache::MODE_GET)
+        ->setCacheMode(\Doctrine\ORM\Cache::MODE_GET)
         ->setCacheable(true)
         ->getResult();
 
 .. note::
 
-    The the default query cache mode is ```Cache::MODE_NORMAL```
+    The default query cache mode is ```Cache::MODE_NORMAL```
 
 DELETE / UPDATE queries
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -595,7 +587,7 @@ Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_
     <?php
     // Execute and invalidate
     $this->_em->createQuery("UPDATE Entity\Country u SET u.name = 'unknown' WHERE u.id = 1")
-        ->setHint(Query::HINT_CACHE_EVICT, true)
+        ->setHint(\Doctrine\ORM\Query::HINT_CACHE_EVICT, true)
         ->execute();
 
 
@@ -657,7 +649,7 @@ However, you can use the cache API to check / invalidate cache entries.
 .. code-block:: php
 
     <?php
-    /* @var $cache \Doctrine\ORM\Cache */
+    /** @var \Doctrine\ORM\Cache $cache */
     $cache = $em->getCache();
 
     $cache->containsEntity('Entity\State', 1)      // Check if the cache exists
@@ -702,19 +694,19 @@ For performance reasons the cache API does not extract from composite primary ke
     }
 
     // Supported
-    /* @var $article Article */
+    /** @var Article $article */
     $article = $em->find('Article', 1);
 
     // Supported
-    /* @var $article Article */
+    /** @var Article $article */
     $article = $em->find('Article', $article);
 
     // Supported
-    $id        = array('source' => 1, 'target' => 2);
+    $id        = ['source' => 1, 'target' => 2];
     $reference = $em->find('Reference', $id);
 
     // NOT Supported
-    $id        = array('source' => new Article(1), 'target' => new Article(2));
+    $id        = ['source' => new Article(1), 'target' => new Article(2)];
     $reference = $em->find('Reference', $id);
 
 Distributed environments

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/tools.rst

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

docs/en/reference/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/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:
@@ -521,6 +521,8 @@ For each cascade operation that gets activated, Doctrine also
 applies that operation to the association, be it single or
 collection valued.
 
+.. _persistence-by-reachability:
+
 Persistence by Reachability: Cascade Persist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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

@@ -27,7 +27,7 @@ Work that have not yet been persisted are lost.
 
 .. note::
 
-    Doctrine does NEVER touch the public API of methods in your entity
+    Doctrine NEVER touches the public API of methods in your entity
     classes (like getters and setters) nor the constructor method.
     Instead, it uses reflection to get/set data from/to your entity objects.
     When Doctrine fetches data from DB and saves it back,
@@ -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">
@@ -256,6 +256,11 @@ Optional attributes:
    table? Defaults to false.
 -  nullable - Should this field allow NULL as a value? Defaults to
    false.
+-  insertable - Should this field be inserted? Defaults to true.
+-  updatable - Should this field be updated? Defaults to true.
+-  generated - Enum of the values ALWAYS, INSERT, NEVER that determines if
+   generated value must be fetched from database after INSERT or UPDATE.
+   Defaults to "NEVER".
 -  version - Should this field be used for optimistic locking? Only
    works on fields with type integer or datetime.
 -  scale - Scale of a decimal type.
@@ -689,6 +694,7 @@ specified by their respective tags:
 -  ``<cascade-merge />``
 -  ``<cascade-remove />``
 -  ``<cascade-refresh />``
+-  ``<cascade-detach />``
 
 Join Column Element
 ~~~~~~~~~~~~~~~~~~~
@@ -763,9 +769,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

@@ -40,7 +40,7 @@ easily using a combination of ``count`` and ``slice``.
    ``removeElement`` directly issued DELETE queries to the database from
    version 2.4.0 to 2.7.0.  This circumvents the flush operation and might run
    outside a transactional boundary if you don't create one yourself. We
-   consider this a critical bug in the assumptio of how the ORM works and
+   consider this a critical bug in the assumption of how the ORM works and
    reverted ``removeElement`` EXTRA_LAZY behavior in 2.7.1.
 
 
@@ -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

@@ -81,8 +81,11 @@ that directory with the following contents:
 
     {
         "require": {
-            "doctrine/orm": "^2.6.2",
-            "symfony/yaml": "2.*"
+            "doctrine/orm": "^2.11.0",
+            "doctrine/dbal": "^3.2",
+            "doctrine/annotations": "1.13.2",
+            "symfony/yaml": "^5.4",
+            "symfony/cache": "^5.4"
         },
         "autoload": {
             "psr-0": {"": "src/"}
@@ -111,6 +114,14 @@ Add the following directories:
 .. note::
     The YAML driver is deprecated and will be removed in version 3.0.
     It is strongly recommended to switch to one of the other mappings.
+.. note::
+    It is strongly recommended that you require ``doctrine/dbal`` in your
+    ``composer.json`` as well, because using the ORM means mapping objects
+    and their fields to database tables and their columns, and that
+    requires mentioning so-called types that are defined in ``doctrine/dbal``
+    in your application. Having an explicit requirement means you control
+    when the upgrade to the next major version happens, so that you can
+    do the necessary changes in your application beforehand.
 
 Obtaining the EntityManager
 ---------------------------
@@ -126,8 +137,8 @@ step:
 
     <?php
     // bootstrap.php
-    use Doctrine\ORM\Tools\Setup;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
 
     require_once "vendor/autoload.php";
 
@@ -136,10 +147,10 @@ step:
     $proxyDir = null;
     $cache = null;
     $useSimpleAnnotationReader = false;
-    $config = Setup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode, $proxyDir, $cache, $useSimpleAnnotationReader);
-    // or if you prefer yaml or XML
-    //$config = Setup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
-    //$config = Setup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
+    $config = ORMSetup::createAnnotationMetadataConfiguration(array(__DIR__."/src"), $isDevMode, $proxyDir, $cache, $useSimpleAnnotationReader);
+    // or if you prefer YAML or XML
+    // $config = ORMSetup::createXMLMetadataConfiguration(array(__DIR__."/config/xml"), $isDevMode);
+    // $config = ORMSetup::createYAMLMetadataConfiguration(array(__DIR__."/config/yaml"), $isDevMode);
 
     // database configuration parameters
     $conn = array(
@@ -162,7 +173,7 @@ The ``require_once`` statement sets up the class autoloading for Doctrine and
 its dependencies using Composer's autoloader.
 
 The second block consists of the instantiation of the ORM
-``Configuration`` object using the Setup helper. It assumes a bunch
+``Configuration`` object using the ``ORMSetup`` helper. It assumes a bunch
 of defaults that you don't have to bother about for now. You can
 read up on the configuration details in the
 :doc:`reference chapter on configuration <../reference/configuration>`.
@@ -180,22 +191,35 @@ Generating the Database Schema
 
 Doctrine has a command-line interface that allows you to access the SchemaTool,
 a component that can generate a relational database schema based entirely on the
-defined entity classes and their metadata. For this tool to work, a
-``cli-config.php`` file must exist in the project root directory:
+defined entity classes and their metadata. For this tool to work, you need to
+create an executable console script as described in the
+:doc:`tools chapter <../reference/tools>`.
+
+If you created the ``bootstrap.php`` file as described in the previous section,
+that script could look like this:
 
 .. code-block:: php
 
+    #!/usr/bin/env php
     <?php
-    // cli-config.php
-    require_once "bootstrap.php";
+    // bin/doctrine
 
-    return \Doctrine\ORM\Tools\Console\ConsoleRunner::createHelperSet($entityManager);
+    use Doctrine\ORM\Tools\Console\ConsoleRunner;
+    use Doctrine\ORM\Tools\Console\EntityManagerProvider\SingleManagerProvider;
 
-Now call the Doctrine command-line tool:
+    // Adjust this path to your actual bootstrap.php
+    require __DIR__ . 'path/to/your/bootstrap.php';
+
+    ConsoleRunner::run(
+        new SingleManagerProvider($entityManager)
+    );
+
+In the following examples, we will assume that this script has been created as
+``bin/doctrine``.
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:create
 
 Since we haven't added any entity metadata in ``src`` yet, you'll see a message
 stating "No Metadata Classes to process." In the next section, we'll create a
@@ -207,14 +231,14 @@ You can easily recreate the database using the following commands:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:drop --force
-    $ vendor/bin/doctrine orm:schema-tool:create
+    $ php bin/doctrine orm:schema-tool:drop --force
+    $ php bin/doctrine orm:schema-tool:create
 
 Or you can use the update functionality:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force
+    $ php bin/doctrine orm:schema-tool:update --force
 
 The updating of databases uses a diff algorithm for a given
 database schema. This is a cornerstone of the ``Doctrine\DBAL`` package,
@@ -235,44 +259,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 +525,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 +537,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">
@@ -358,7 +584,7 @@ let's update the database schema:
 
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force --dump-sql
+    $ php bin/doctrine orm:schema-tool:update --force --dump-sql
 
 Specifying both flags ``--force`` and ``--dump-sql`` will cause the DDL
 statements to be executed and then printed to the screen.
@@ -439,7 +665,7 @@ Let's continue by creating a script to display the name of a product based on it
     echo sprintf("-%s\n", $product->getName());
 
 Next we'll update a product's name, given its id. This simple example will
-help demonstrate Doctrine's implementation of the UnitOfWork pattern. Doctrine
+help demonstrate Doctrine's implementation of the :ref:`UnitOfWork pattern <unit-of-work>`. Doctrine
 keeps track of all the entities that were retrieved from the Entity Manager,
 and can detect when any of those entities' properties have been modified.
 As a result, rather than needing to call ``persist($entity)`` for each individual
@@ -494,25 +720,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 +795,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 +848,7 @@ domain model to match the requirements:
     {
         // ... (previous code)
 
-        protected $products;
+        private $products;
 
         public function __construct()
         {
@@ -640,8 +866,8 @@ domain model to match the requirements:
     {
         // ... (previous code)
 
-        protected $reportedBugs;
-        protected $assignedBugs;
+        private $reportedBugs;
+        private $assignedBugs;
 
         public function __construct()
         {
@@ -716,8 +942,8 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        protected $engineer;
-        protected $reporter;
+        private $engineer;
+        private $reporter;
 
         public function setEngineer(User $engineer)
         {
@@ -750,8 +976,8 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        protected $reportedBugs;
-        protected $assignedBugs;
+        private $reportedBugs;
+        private $assignedBugs;
 
         public function addReportedBug(Bug $bug)
         {
@@ -802,7 +1028,7 @@ the database that points from Bugs to Products.
     {
         // ... (previous code)
 
-        protected $products;
+        private $products;
 
         public function assignToProduct(Product $product)
         {
@@ -838,37 +1064,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 +1102,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 +1202,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 +1228,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">
@@ -1055,7 +1281,7 @@ class that holds the owning sides.
 Update your database schema by running:
 ::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force
+    $ php bin/doctrine orm:schema-tool:update --force
 
 
 Implementing more Requirements
@@ -1131,7 +1357,7 @@ call this script as follows:
     php create_bug.php 1 1 1
 
 See how simple it is to relate a Bug, Reporter, Engineer and Products?
-Also recall that thanks to the UnitOfWork pattern, Doctrine will detect
+Also recall that thanks to the :ref:`UnitOfWork pattern <unit-of-work>`, Doctrine will detect
 these relations and update all of the modified entities in the database
 automatically when ``flush()`` is called.
 
@@ -1188,9 +1414,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 +1670,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 +1766,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

@@ -14,25 +14,25 @@
 
   <xs:element name="doctrine-mapping">
     <xs:complexType>
-      <xs:sequence>
+      <xs:choice minOccurs="0" maxOccurs="unbounded">
         <xs:element name="mapped-superclass" type="orm:mapped-superclass" minOccurs="0" maxOccurs="unbounded" />
         <xs:element name="entity" type="orm:entity" minOccurs="0" maxOccurs="unbounded" />
         <xs:element name="embeddable" type="orm:embeddable" minOccurs="0" maxOccurs="unbounded" />
         <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-      </xs:sequence>
+      </xs:choice>
       <xs:anyAttribute namespace="##other"/>
     </xs:complexType>
   </xs:element>
 
   <xs:complexType name="emptyType">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="cascade-type">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="cascade-all" type="orm:emptyType" minOccurs="0"/>
       <xs:element name="cascade-persist" type="orm:emptyType" minOccurs="0"/>
       <xs:element name="cascade-merge" type="orm:emptyType" minOccurs="0"/>
@@ -40,7 +40,7 @@
       <xs:element name="cascade-refresh" type="orm:emptyType" minOccurs="0"/>
       <xs:element name="cascade-detach" type="orm:emptyType" minOccurs="0"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
@@ -66,19 +66,19 @@
   </xs:simpleType>
 
   <xs:complexType name="lifecycle-callback">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="type" type="orm:lifecycle-callback-type" use="required" />
     <xs:attribute name="method" type="xs:NMTOKEN" use="required" />
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="lifecycle-callbacks">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="lifecycle-callback" type="orm:lifecycle-callback" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
@@ -96,34 +96,34 @@
   </xs:complexType>
 
   <xs:complexType name="named-native-query">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="query" type="xs:string" minOccurs="1" maxOccurs="1"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:string" use="required" />
     <xs:attribute name="result-class" type="orm:fqcn" />
     <xs:attribute name="result-set-mapping" type="xs:string" />
   </xs:complexType>
 
   <xs:complexType name="named-native-queries">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="named-native-query" type="orm:named-native-query" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
   </xs:complexType>
 
   <xs:complexType name="entity-listener">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="lifecycle-callback" type="orm:lifecycle-callback" minOccurs="0" maxOccurs="unbounded"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="class" type="orm:fqcn"/>
   </xs:complexType>
 
   <xs:complexType name="entity-listeners">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="entity-listener" type="orm:entity-listener" minOccurs="1" maxOccurs="unbounded" />
-    </xs:sequence>
+    </xs:choice>
   </xs:complexType>
 
   <xs:complexType name="column-result">
@@ -136,29 +136,29 @@
   </xs:complexType>
 
   <xs:complexType name="entity-result">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="field-result" type="orm:field-result" minOccurs="0" maxOccurs="unbounded" />
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="entity-class" type="orm:fqcn" use="required" />
     <xs:attribute name="discriminator-column" type="xs:string" use="optional" />
   </xs:complexType>
 
   <xs:complexType name="sql-result-set-mapping">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
         <xs:choice minOccurs="0" maxOccurs="unbounded">
             <xs:element name="entity-result" type="orm:entity-result"/>
             <xs:element name="column-result" type="orm:column-result"/>
             <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
         </xs:choice>
         <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:string" use="required" />
   </xs:complexType>
 
   <xs:complexType name="sql-result-set-mappings">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="sql-result-set-mapping" type="orm:sql-result-set-mapping" minOccurs="1" maxOccurs="unbounded" />
-    </xs:sequence>
+    </xs:choice>
   </xs:complexType>
 
   <xs:complexType name="cache">
@@ -208,28 +208,28 @@
   </xs:simpleType>
 
   <xs:complexType name="option" mixed="true">
-    <xs:sequence minOccurs="0" maxOccurs="unbounded">
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="option" type="orm:option"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="options">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="option" type="orm:option" minOccurs="0" maxOccurs="unbounded"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="mapped-superclass" >
     <xs:complexContent>
       <xs:extension base="orm:entity">
-        <xs:sequence>
+        <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-        </xs:sequence>
+        </xs:choice>
         <xs:anyAttribute namespace="##other"/>
       </xs:extension>
     </xs:complexContent>
@@ -238,9 +238,9 @@
   <xs:complexType name="embeddable">
     <xs:complexContent>
       <xs:extension base="orm:entity">
-        <xs:sequence>
+        <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-        </xs:sequence>
+        </xs:choice>
       </xs:extension>
     </xs:complexContent>
   </xs:complexType>
@@ -264,7 +264,6 @@
   <xs:simpleType name="generator-strategy">
     <xs:restriction base="xs:token">
       <xs:enumeration value="NONE"/>
-      <xs:enumeration value="TABLE"/>
       <xs:enumeration value="SEQUENCE"/>
       <xs:enumeration value="IDENTITY"/>
       <xs:enumeration value="AUTO"/>
@@ -289,17 +288,29 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="generated-type">
+    <xs:restriction base="xs:token">
+      <xs:enumeration value="NEVER"/>
+      <xs:enumeration value="INSERT"/>
+      <xs:enumeration value="ALWAYS"/>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="field">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
-    <xs:attribute name="column" type="xs:NMTOKEN" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updatable" type="xs:boolean" default="true" />
+    <xs:attribute name="generated" type="orm:generated-type" default="NEVER" />
+    <xs:attribute name="enum-type" type="xs:string" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />
@@ -308,6 +319,9 @@
   </xs:complexType>
 
   <xs:complexType name="embedded">
+    <xs:sequence>
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
+    </xs:sequence>
     <xs:attribute name="name" type="xs:string" use="required" />
     <xs:attribute name="class" type="orm:fqcn" use="optional" />
     <xs:attribute name="column-prefix" type="xs:string" use="optional" />
@@ -315,9 +329,9 @@
   </xs:complexType>
 
   <xs:complexType name="discriminator-column">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="type" type="xs:NMTOKEN"/>
     <xs:attribute name="field-name" type="xs:NMTOKEN" />
@@ -327,10 +341,10 @@
   </xs:complexType>
 
   <xs:complexType name="unique-constraint">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional"/>
     <xs:attribute name="columns" type="xs:string" use="optional"/>
     <xs:attribute name="fields" type="xs:string" use="optional"/>
@@ -338,69 +352,69 @@
   </xs:complexType>
 
   <xs:complexType name="unique-constraints">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="unique-constraint" type="orm:unique-constraint" minOccurs="1" maxOccurs="unbounded"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="index">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <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:attribute name="flags" type="xs:string" use="optional"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="indexes">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="index" type="orm:index" minOccurs="1" maxOccurs="unbounded"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="discriminator-mapping">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="value" type="xs:NMTOKEN" use="required"/>
     <xs:attribute name="class" type="orm:fqcn" use="required"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="discriminator-map">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="discriminator-mapping" type="orm:discriminator-mapping" minOccurs="1" maxOccurs="unbounded"/>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="generator">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="strategy" type="orm:generator-strategy" use="optional" default="AUTO" />
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="id">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="generator" type="orm:generator" minOccurs="0" />
       <xs:element name="sequence-generator" type="orm:sequence-generator" minOccurs="0" maxOccurs="1" />
       <xs:element name="custom-id-generator" type="orm:custom-id-generator" minOccurs="0" maxOccurs="1" />
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="type" type="xs:NMTOKEN" />
-    <xs:attribute name="column" type="xs:NMTOKEN" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="association-key" type="xs:boolean" default="false" />
     <xs:attribute name="column-definition" type="xs:string" />
@@ -408,9 +422,9 @@
   </xs:complexType>
 
   <xs:complexType name="sequence-generator">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
       <xs:attribute name="sequence-name" type="xs:NMTOKEN" use="required" />
       <xs:attribute name="allocation-size" type="xs:integer" use="optional" default="1" />
       <xs:attribute name="initial-value" type="xs:integer" use="optional" default="1" />
@@ -418,9 +432,9 @@
   </xs:complexType>
 
   <xs:complexType name="custom-id-generator">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="class" type="orm:fqcn" use="required" />
   </xs:complexType>
 
@@ -432,17 +446,17 @@
   </xs:simpleType>
 
   <xs:complexType name="inverse-join-columns">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-column" type="orm:join-column" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="join-column">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional" />
     <xs:attribute name="referenced-column-name" type="xs:NMTOKEN" use="optional" default="id" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
@@ -453,36 +467,36 @@
   </xs:complexType>
 
   <xs:complexType name="join-columns">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-column" type="orm:join-column" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="join-table">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-columns" type="orm:join-columns" />
       <xs:element name="inverse-join-columns" type="orm:join-columns" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="schema" type="xs:NMTOKEN" />
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="order-by">
-      <xs:sequence>
+      <xs:choice minOccurs="0" maxOccurs="unbounded">
           <xs:element name="order-by-field" type="orm:order-by-field" minOccurs="1" maxOccurs="unbounded" />
           <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-      </xs:sequence>
+      </xs:choice>
       <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="order-by-field">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="direction" type="orm:order-by-direction" default="ASC" />
     <xs:anyAttribute namespace="##other"/>
@@ -495,14 +509,20 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="columntoken" id="columntoken">
+    <xs:restriction base="xs:token">
+      <xs:pattern value="[-._:A-Za-z0-9`]+" id="columntoken.pattern"/>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="many-to-many">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="cache" type="orm:cache" minOccurs="0" maxOccurs="1"/>
       <xs:element name="cascade" type="orm:cascade-type" minOccurs="0" />
       <xs:element name="join-table" type="orm:join-table" minOccurs="0" />
       <xs:element name="order-by" type="orm:order-by" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" use="required" />
     <xs:attribute name="mapped-by" type="xs:NMTOKEN" />
@@ -514,12 +534,12 @@
   </xs:complexType>
 
   <xs:complexType name="one-to-many">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="cache" type="orm:cache" minOccurs="0" maxOccurs="1"/>
       <xs:element name="cascade" type="orm:cascade-type" minOccurs="0" />
       <xs:element name="order-by" type="orm:order-by" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" use="required" />
     <xs:attribute name="mapped-by" type="xs:NMTOKEN" use="required" />
@@ -530,7 +550,7 @@
   </xs:complexType>
 
   <xs:complexType name="many-to-one">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="cache" type="orm:cache" minOccurs="0" maxOccurs="1"/>
       <xs:element name="cascade" type="orm:cascade-type" minOccurs="0" />
       <xs:choice minOccurs="0" maxOccurs="1">
@@ -539,7 +559,7 @@
         <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
       </xs:choice>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" />
     <xs:attribute name="inversed-by" type="xs:NMTOKEN" />
@@ -548,7 +568,7 @@
   </xs:complexType>
 
   <xs:complexType name="one-to-one">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:element name="cache" type="orm:cache" minOccurs="0" maxOccurs="1"/>
       <xs:element name="cascade" type="orm:cascade-type" minOccurs="0" />
       <xs:choice minOccurs="0" maxOccurs="1">
@@ -557,7 +577,7 @@
         <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
       </xs:choice>
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" />
     <xs:attribute name="mapped-by" type="xs:NMTOKEN" />
@@ -568,19 +588,19 @@
   </xs:complexType>
 
   <xs:complexType name="association-overrides">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="association-override" type="orm:association-override" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
   </xs:complexType>
 
   <xs:complexType name="association-override">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-table" type="orm:join-table" minOccurs="0" />
       <xs:element name="join-columns" type="orm:join-columns" minOccurs="0" />
       <xs:element name="inversed-by" type="orm:inversed-by-override" minOccurs="0" maxOccurs="1" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="fetch" type="orm:fetch-type" use="optional" />
   </xs:complexType>
@@ -590,30 +610,32 @@
   </xs:complexType>
 
   <xs:complexType name="attribute-overrides">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="attribute-override" type="orm:attribute-override" minOccurs="1" maxOccurs="unbounded" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
   </xs:complexType>
 
   <xs:complexType name="attribute-override">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="field" type="orm:attribute-override-field" minOccurs="1" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
   </xs:complexType>
 
   <xs:complexType name="attribute-override-field">
-    <xs:sequence>
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-    </xs:sequence>
+    </xs:choice>
     <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
-    <xs:attribute name="column" type="xs:NMTOKEN" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <xs:attribute name="nullable" type="xs:boolean" default="false" />
+    <xs:attribute name="insertable" type="xs:boolean" default="true" />
+    <xs:attribute name="updateable" type="xs:boolean" default="true" />
     <xs:attribute name="version" type="xs:boolean" />
     <xs:attribute name="column-definition" type="xs:string" />
     <xs:attribute name="precision" type="xs:integer" use="optional" />

lib/Doctrine/ORM/AbstractQuery.php

@@ -1,31 +1,20 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM;
 
+use BackedEnum;
 use Countable;
+use Doctrine\Common\Cache\Psr6\CacheAdapter;
+use Doctrine\Common\Cache\Psr6\DoctrineProvider;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
+use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Cache\QueryCacheProfile;
-use Doctrine\DBAL\Driver\ResultStatement;
+use Doctrine\DBAL\Result;
 use Doctrine\Deprecations\Deprecation;
+use Doctrine\ORM\Cache\Exception\InvalidResultCacheDriver;
 use Doctrine\ORM\Cache\Logging\CacheLogger;
 use Doctrine\ORM\Cache\QueryCacheKey;
 use Doctrine\ORM\Cache\TimestampCacheKey;
@@ -35,10 +24,13 @@ use Doctrine\ORM\Query\Parameter;
 use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\Mapping\MappingException;
+use LogicException;
+use Psr\Cache\CacheItemPoolInterface;
 use Traversable;
 
 use function array_map;
 use function array_shift;
+use function assert;
 use function count;
 use function is_array;
 use function is_numeric;
@@ -47,6 +39,7 @@ use function is_scalar;
 use function iterator_count;
 use function iterator_to_array;
 use function ksort;
+use function method_exists;
 use function reset;
 use function serialize;
 use function sha1;
@@ -85,6 +78,11 @@ abstract class AbstractQuery
      */
     public const HYDRATE_SIMPLEOBJECT = 5;
 
+    /**
+     * Hydrates scalar column value.
+     */
+    public const HYDRATE_SCALAR_COLUMN = 6;
+
     /**
      * The parameter map of this query.
      *
@@ -96,7 +94,7 @@ abstract class AbstractQuery
     /**
      * The user-specified ResultSetMapping to use.
      *
-     * @var ResultSetMapping
+     * @var ResultSetMapping|null
      */
     protected $_resultSetMapping;
 
@@ -118,6 +116,7 @@ abstract class AbstractQuery
      * The hydration mode.
      *
      * @var string|int
+     * @psalm-var string|AbstractQuery::HYDRATE_*
      */
     protected $_hydrationMode = self::HYDRATE_OBJECT;
 
@@ -131,7 +130,7 @@ abstract class AbstractQuery
      */
     protected $_expireResultCache = false;
 
-    /** @var QueryCacheProfile */
+    /** @var QueryCacheProfile|null */
     protected $_hydrationCacheProfile;
 
     /**
@@ -155,6 +154,7 @@ abstract class AbstractQuery
      * Second level query cache mode.
      *
      * @var int|null
+     * @psalm-var Cache::MODE_*|null
      */
     protected $cacheMode;
 
@@ -186,7 +186,7 @@ abstract class AbstractQuery
      *
      * @param bool $cacheable
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setCacheable($cacheable)
     {
@@ -206,7 +206,7 @@ abstract class AbstractQuery
     /**
      * @param string $cacheRegion
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setCacheRegion($cacheRegion)
     {
@@ -246,7 +246,7 @@ abstract class AbstractQuery
      *
      * @param int $lifetime
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setLifetime($lifetime)
     {
@@ -256,7 +256,8 @@ abstract class AbstractQuery
     }
 
     /**
-     * @return int
+     * @return int|null
+     * @psalm-return Cache::MODE_*|null
      */
     public function getCacheMode()
     {
@@ -265,8 +266,9 @@ abstract class AbstractQuery
 
     /**
      * @param int $cacheMode
+     * @psalm-param Cache::MODE_* $cacheMode
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setCacheMode($cacheMode)
     {
@@ -347,7 +349,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[] $parameters
      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setParameters($parameters)
     {
@@ -371,13 +373,13 @@ abstract class AbstractQuery
     /**
      * Sets a query parameter.
      *
-     * @param string|int  $key   The parameter position or name.
-     * @param mixed       $value The parameter value.
-     * @param string|null $type  The parameter type. If specified, the given value will be run through
-     *                           the type conversion of this type. This is usually not needed for
-     *                           strings and numeric types.
+     * @param string|int      $key   The parameter position or name.
+     * @param mixed           $value The parameter value.
+     * @param string|int|null $type  The parameter type. If specified, the given value will be run through
+     *                               the type conversion of this type. This is usually not needed for
+     *                               strings and numeric types.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setParameter($key, $value, $type = null)
     {
@@ -424,15 +426,20 @@ abstract class AbstractQuery
             return $value->name;
         }
 
+        if ($value instanceof BackedEnum) {
+            return $value->value;
+        }
+
         if (! is_object($value)) {
             return $value;
         }
 
         try {
+            $class = ClassUtils::getClass($value);
             $value = $this->_em->getUnitOfWork()->getSingleIdentifierValue($value);
 
             if ($value === null) {
-                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
+                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
             }
         } catch (MappingException | ORMMappingException $e) {
             /* Silence any mapping exceptions. These can occur if the object in
@@ -484,7 +491,7 @@ abstract class AbstractQuery
     /**
      * Sets the ResultSetMapping that should be used for hydration.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setResultSetMapping(Query\ResultSetMapping $rsm)
     {
@@ -497,7 +504,7 @@ abstract class AbstractQuery
     /**
      * Gets the ResultSetMapping used for hydration.
      *
-     * @return ResultSetMapping
+     * @return ResultSetMapping|null
      */
     protected function getResultSetMapping()
     {
@@ -529,7 +536,7 @@ abstract class AbstractQuery
      * some form of caching with UnitOfWork registration you should use
      * {@see AbstractQuery::setResultCacheProfile()}.
      *
-     * @return static This query instance.
+     * @return $this
      *
      * @example
      * $lifetime = 100;
@@ -539,9 +546,25 @@ abstract class AbstractQuery
      */
     public function setHydrationCacheProfile(?QueryCacheProfile $profile = null)
     {
-        if ($profile !== null && ! $profile->getResultCacheDriver()) {
-            $resultCacheDriver = $this->_em->getConfiguration()->getHydrationCacheImpl();
-            $profile           = $profile->setResultCacheDriver($resultCacheDriver);
+        if ($profile === null) {
+            $this->_hydrationCacheProfile = null;
+
+            return $this;
+        }
+
+        // DBAL 2
+        if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
+            if (! $profile->getResultCacheDriver()) {
+                $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
+                if ($defaultHydrationCacheImpl) {
+                    $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultHydrationCacheImpl));
+                }
+            }
+        } elseif (! $profile->getResultCache()) {
+            $defaultHydrationCacheImpl = $this->_em->getConfiguration()->getHydrationCache();
+            if ($defaultHydrationCacheImpl) {
+                $profile = $profile->setResultCache($defaultHydrationCacheImpl);
+            }
         }
 
         $this->_hydrationCacheProfile = $profile;
@@ -550,7 +573,7 @@ abstract class AbstractQuery
     }
 
     /**
-     * @return QueryCacheProfile
+     * @return QueryCacheProfile|null
      */
     public function getHydrationCacheProfile()
     {
@@ -563,13 +586,29 @@ abstract class AbstractQuery
      * If no result cache driver is set in the QueryCacheProfile, the default
      * result cache driver is used from the configuration.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setResultCacheProfile(?QueryCacheProfile $profile = null)
     {
-        if ($profile !== null && ! $profile->getResultCacheDriver()) {
-            $resultCacheDriver = $this->_em->getConfiguration()->getResultCacheImpl();
-            $profile           = $profile->setResultCacheDriver($resultCacheDriver);
+        if ($profile === null) {
+            $this->_queryCacheProfile = null;
+
+            return $this;
+        }
+
+        // DBAL 2
+        if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
+            if (! $profile->getResultCacheDriver()) {
+                $defaultResultCacheDriver = $this->_em->getConfiguration()->getResultCache();
+                if ($defaultResultCacheDriver) {
+                    $profile = $profile->setResultCacheDriver(DoctrineProvider::wrap($defaultResultCacheDriver));
+                }
+            }
+        } elseif (! $profile->getResultCache()) {
+            $defaultResultCache = $this->_em->getConfiguration()->getResultCache();
+            if ($defaultResultCache) {
+                $profile = $profile->setResultCache($defaultResultCache);
+            }
         }
 
         $this->_queryCacheProfile = $profile;
@@ -580,22 +619,53 @@ abstract class AbstractQuery
     /**
      * Defines a cache driver to be used for caching result sets and implicitly enables caching.
      *
+     * @deprecated Use {@see setResultCache()} instead.
+     *
      * @param \Doctrine\Common\Cache\Cache|null $resultCacheDriver Cache driver
      *
-     * @return static This query instance.
+     * @return $this
      *
-     * @throws ORMException
+     * @throws InvalidResultCacheDriver
      */
     public function setResultCacheDriver($resultCacheDriver = null)
     {
         /** @phpstan-ignore-next-line */
         if ($resultCacheDriver !== null && ! ($resultCacheDriver instanceof \Doctrine\Common\Cache\Cache)) {
-            throw ORMException::invalidResultCacheDriver();
+            throw InvalidResultCacheDriver::create();
+        }
+
+        return $this->setResultCache($resultCacheDriver ? CacheAdapter::wrap($resultCacheDriver) : null);
+    }
+
+    /**
+     * Defines a cache driver to be used for caching result sets and implicitly enables caching.
+     *
+     * @return $this
+     */
+    public function setResultCache(?CacheItemPoolInterface $resultCache = null)
+    {
+        if ($resultCache === null) {
+            if ($this->_queryCacheProfile) {
+                $this->_queryCacheProfile = new QueryCacheProfile($this->_queryCacheProfile->getLifetime(), $this->_queryCacheProfile->getCacheKey());
+            }
+
+            return $this;
+        }
+
+        // DBAL 2
+        if (! method_exists(QueryCacheProfile::class, 'setResultCache')) {
+            $resultCacheDriver = DoctrineProvider::wrap($resultCache);
+
+            $this->_queryCacheProfile = $this->_queryCacheProfile
+                ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
+                : new QueryCacheProfile(0, null, $resultCacheDriver);
+
+            return $this;
         }
 
         $this->_queryCacheProfile = $this->_queryCacheProfile
-            ? $this->_queryCacheProfile->setResultCacheDriver($resultCacheDriver)
-            : new QueryCacheProfile(0, null, $resultCacheDriver);
+            ? $this->_queryCacheProfile->setResultCache($resultCache)
+            : new QueryCacheProfile(0, null, $resultCache);
 
         return $this;
     }
@@ -622,11 +692,11 @@ 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.
+     * @return $this
      */
     public function useResultCache($useCache, $lifetime = null, $resultCacheId = null)
     {
@@ -642,7 +712,7 @@ abstract class AbstractQuery
      * @param int|null    $lifetime      How long the cache entry is valid, in seconds.
      * @param string|null $resultCacheId ID to use for the cache entry.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function enableResultCache(?int $lifetime = null, ?string $resultCacheId = null): self
     {
@@ -655,7 +725,7 @@ abstract class AbstractQuery
     /**
      * Disables caching of the results of this query.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function disableResultCache(): self
     {
@@ -667,17 +737,35 @@ 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.
+     * @return $this
      */
     public function setResultCacheLifetime($lifetime)
     {
-        $lifetime = $lifetime !== null ? (int) $lifetime : 0;
+        $lifetime = (int) $lifetime;
 
-        $this->_queryCacheProfile = $this->_queryCacheProfile
-            ? $this->_queryCacheProfile->setLifetime($lifetime)
-            : new QueryCacheProfile($lifetime, null, $this->_em->getConfiguration()->getResultCacheImpl());
+        if ($this->_queryCacheProfile) {
+            $this->_queryCacheProfile = $this->_queryCacheProfile->setLifetime($lifetime);
+
+            return $this;
+        }
+
+        $this->_queryCacheProfile = new QueryCacheProfile($lifetime);
+
+        $cache = $this->_em->getConfiguration()->getResultCache();
+        if (! $cache) {
+            return $this;
+        }
+
+        // Compatibility for DBAL 2
+        if (! method_exists($this->_queryCacheProfile, 'setResultCache')) {
+            $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCacheDriver(DoctrineProvider::wrap($cache));
+
+            return $this;
+        }
+
+        $this->_queryCacheProfile = $this->_queryCacheProfile->setResultCache($cache);
 
         return $this;
     }
@@ -699,7 +787,7 @@ abstract class AbstractQuery
      *
      * @param bool $expire Whether or not to force resultset cache expiration.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function expireResultCache($expire = true)
     {
@@ -735,7 +823,7 @@ abstract class AbstractQuery
      * @param string $assocName
      * @param int    $fetchMode
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setFetchMode($class, $assocName, $fetchMode)
     {
@@ -753,8 +841,9 @@ abstract class AbstractQuery
      *
      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
      *                                  One of the Query::HYDRATE_* constants.
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setHydrationMode($hydrationMode)
     {
@@ -767,6 +856,7 @@ abstract class AbstractQuery
      * Gets the hydration mode currently used by the query.
      *
      * @return string|int
+     * @psalm-return string|AbstractQuery::HYDRATE_*
      */
     public function getHydrationMode()
     {
@@ -779,6 +869,7 @@ abstract class AbstractQuery
      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
      *
      * @param string|int $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return mixed
      */
@@ -799,6 +890,18 @@ abstract class AbstractQuery
         return $this->execute(null, self::HYDRATE_ARRAY);
     }
 
+    /**
+     * Gets one-dimensional array of results for the query.
+     *
+     * Alias for execute(null, HYDRATE_SCALAR_COLUMN).
+     *
+     * @return mixed[]
+     */
+    public function getSingleColumnResult()
+    {
+        return $this->execute(null, self::HYDRATE_SCALAR_COLUMN);
+    }
+
     /**
      * Gets the scalar results for the query.
      *
@@ -814,7 +917,8 @@ abstract class AbstractQuery
     /**
      * Get exactly one result or null.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
@@ -851,12 +955,13 @@ abstract class AbstractQuery
      * If the result is not unique, a NonUniqueResultException is thrown.
      * If there is no result, a NoResultException is thrown.
      *
-     * @param string|int $hydrationMode
+     * @param string|int|null $hydrationMode
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @return mixed
      *
      * @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)
     {
@@ -898,7 +1003,7 @@ abstract class AbstractQuery
      * @param string $name  The name of the hint.
      * @param mixed  $value The value of the hint.
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setHint($name, $value)
     {
@@ -949,6 +1054,7 @@ abstract class AbstractQuery
      *
      * @param ArrayCollection|mixed[]|null $parameters    The query parameters.
      * @param string|int|null              $hydrationMode The hydration mode to use.
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode The hydration mode to use.
      *
      * @return IterableResult
      */
@@ -969,7 +1075,11 @@ abstract class AbstractQuery
             $this->setParameters($parameters);
         }
 
-        $rsm  = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $stmt = $this->_doExecute();
 
         return $this->_em->newHydrator($this->_hydrationMode)->iterate($stmt, $rsm, $this->_hints);
@@ -982,6 +1092,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|array|mixed[] $parameters    The query parameters.
      * @param string|int|null               $hydrationMode The hydration mode to use.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
      *
      * @return iterable<mixed>
      */
@@ -999,6 +1110,9 @@ abstract class AbstractQuery
         }
 
         $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
 
         if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
             throw QueryException::iterateWithMixedResultNotAllowed();
@@ -1015,6 +1129,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[]|null $parameters    Query parameters.
      * @param string|int|null              $hydrationMode Processing mode to be used during the hydration process.
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1033,6 +1148,7 @@ abstract class AbstractQuery
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
@@ -1052,9 +1168,9 @@ abstract class AbstractQuery
         if ($this->_hydrationCacheProfile !== null) {
             [$cacheKey, $realCacheKey] = $this->getHydrationCacheId();
 
-            $queryCacheProfile = $this->getHydrationCacheProfile();
-            $cache             = $queryCacheProfile->getResultCacheDriver();
-            $result            = $cache->fetch($cacheKey);
+            $cache     = $this->getHydrationCache();
+            $cacheItem = $cache->getItem($cacheKey);
+            $result    = $cacheItem->isHit() ? $cacheItem->get() : [];
 
             if (isset($result[$realCacheKey])) {
                 return $result[$realCacheKey];
@@ -1064,10 +1180,8 @@ abstract class AbstractQuery
                 $result = [];
             }
 
-            $setCacheEntry = static function ($data) use ($cache, $result, $cacheKey, $realCacheKey, $queryCacheProfile): void {
-                $result[$realCacheKey] = $data;
-
-                $cache->save($cacheKey, $result, $queryCacheProfile->getLifetime());
+            $setCacheEntry = static function ($data) use ($cache, $result, $cacheItem, $realCacheKey): void {
+                $cache->save($cacheItem->set($result + [$realCacheKey => $data]));
             };
         }
 
@@ -1079,7 +1193,11 @@ abstract class AbstractQuery
             return $stmt;
         }
 
-        $rsm  = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $data = $this->_em->newHydrator($this->_hydrationMode)->hydrateAll($stmt, $rsm, $this->_hints);
 
         $setCacheEntry($data);
@@ -1087,18 +1205,41 @@ abstract class AbstractQuery
         return $data;
     }
 
+    private function getHydrationCache(): CacheItemPoolInterface
+    {
+        assert($this->_hydrationCacheProfile !== null);
+
+        // Support for DBAL 2
+        if (! method_exists($this->_hydrationCacheProfile, 'getResultCache')) {
+            $cacheDriver = $this->_hydrationCacheProfile->getResultCacheDriver();
+            assert($cacheDriver !== null);
+
+            return CacheAdapter::wrap($cacheDriver);
+        }
+
+        $cache = $this->_hydrationCacheProfile->getResultCache();
+        assert($cache !== null);
+
+        return $cache;
+    }
+
     /**
      * Load from second level cache or executes the query and put into cache.
      *
      * @param ArrayCollection|mixed[]|null $parameters
      * @param string|int|null              $hydrationMode
      * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      *
      * @return mixed
      */
     private function executeUsingQueryCache($parameters = null, $hydrationMode = null)
     {
-        $rsm        = $this->getResultSetMapping();
+        $rsm = $this->getResultSetMapping();
+        if ($rsm === null) {
+            throw new LogicException('Uninitialized result set mapping.');
+        }
+
         $queryCache = $this->_em->getCache()->getQueryCache($this->cacheRegion);
         $queryKey   = new QueryCacheKey(
             $this->getHash(),
@@ -1133,6 +1274,7 @@ abstract class AbstractQuery
 
     private function getTimestampKey(): ?TimestampCacheKey
     {
+        assert($this->_resultSetMapping !== null);
         $entityName = reset($this->_resultSetMapping->aliasMap);
 
         if (empty($entityName)) {
@@ -1149,7 +1291,8 @@ abstract class AbstractQuery
      * Will return the configured id if it exists otherwise a hash will be
      * automatically generated for you.
      *
-     * @return array<string, string> ($key, $hash)
+     * @return string[] ($key, $hash)
+     * @psalm-return array{string, string} ($key, $hash)
      */
     protected function getHydrationCacheId()
     {
@@ -1165,6 +1308,7 @@ abstract class AbstractQuery
         $hints['hydrationMode'] = $this->getHydrationMode();
 
         ksort($hints);
+        assert($queryCacheProfile !== null);
 
         return $queryCacheProfile->generateCacheKeys($sql, $parameters, $hints);
     }
@@ -1174,15 +1318,17 @@ abstract class AbstractQuery
      * If this is not explicitly set by the developer then a hash is automatically
      * generated for you.
      *
-     * @param string $id
+     * @param string|null $id
      *
-     * @return static This query instance.
+     * @return $this
      */
     public function setResultCacheId($id)
     {
-        $this->_queryCacheProfile = $this->_queryCacheProfile
-            ? $this->_queryCacheProfile->setCacheKey($id)
-            : new QueryCacheProfile(0, $id, $this->_em->getConfiguration()->getResultCacheImpl());
+        if (! $this->_queryCacheProfile) {
+            return $this->setResultCacheProfile(new QueryCacheProfile(0, $id));
+        }
+
+        $this->_queryCacheProfile = $this->_queryCacheProfile->setCacheKey($id);
 
         return $this;
     }
@@ -1192,7 +1338,7 @@ abstract class AbstractQuery
      *
      * @deprecated
      *
-     * @return string
+     * @return string|null
      */
     public function getResultCacheId()
     {
@@ -1202,9 +1348,9 @@ abstract class AbstractQuery
     /**
      * Executes the query and returns a the resulting Statement object.
      *
-     * @return ResultStatement|int The executed database statement that holds
-     *                             the results, or an integer indicating how
-     *                             many rows were affected.
+     * @return Result|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.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM;
 
@@ -157,6 +141,8 @@ interface Cache
      * Evicts all cached query results under the given name, or default query cache if the region name is NULL.
      *
      * @param string|null $regionName The cache name associated to the queries being cached.
+     *
+     * @return void
      */
     public function evictQueryRegion($regionName = null);
 

lib/Doctrine/ORM/Cache/AssociationCacheEntry.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -26,22 +10,26 @@ namespace Doctrine\ORM\Cache;
 class AssociationCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity identifier
      *
-     * @var array<string, mixed> The entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $identifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $class;
 
     /**
      * @param string               $class      The entity class.
      * @param array<string, mixed> $identifier The entity identifier.
+     * @psalm-param class-string $class
      */
     public function __construct($class, array $identifier)
     {

lib/Doctrine/ORM/Cache/CacheConfiguration.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 

lib/Doctrine/ORM/Cache/CacheEntry.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 

lib/Doctrine/ORM/Cache/CacheException.php

@@ -1,26 +1,10 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
-use Doctrine\ORM\ORMException;
+use Doctrine\ORM\Exception\ORMException;
 
 use function sprintf;
 
@@ -41,6 +25,8 @@ class CacheException extends ORMException
     }
 
     /**
+     * @deprecated This method is not used anymore.
+     *
      * @param string $entityName
      *
      * @return CacheException
@@ -61,6 +47,8 @@ class CacheException extends ORMException
     }
 
     /**
+     * @deprecated This method is not used anymore.
+     *
      * @param string $entityName
      * @param string $field
      *

lib/Doctrine/ORM/Cache/CacheFactory.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -47,9 +31,7 @@ interface CacheFactory
     /**
      * Build a collection persister for the given relation mapping.
      *
-     * @param EntityManagerInterface $em        The entity manager.
-     * @param CollectionPersister    $persister The collection persister that will be cached.
-     * @param mixed[]                $mapping   The association mapping.
+     * @param mixed[] $mapping The association mapping.
      *
      * @return CachedCollectionPersister
      */
@@ -58,8 +40,7 @@ interface CacheFactory
     /**
      * Build a query cache based on the given region name
      *
-     * @param EntityManagerInterface $em         The Entity manager.
-     * @param string                 $regionName The region name.
+     * @param string|null $regionName The region name.
      *
      * @return QueryCache The built query cache.
      */
@@ -68,9 +49,6 @@ interface CacheFactory
     /**
      * Build an entity hydrator
      *
-     * @param EntityManagerInterface $em       The Entity manager.
-     * @param ClassMetadata          $metadata The entity metadata.
-     *
      * @return EntityHydrator The built entity hydrator.
      */
     public function buildEntityHydrator(EntityManagerInterface $em, ClassMetadata $metadata);
@@ -78,8 +56,7 @@ interface CacheFactory
     /**
      * Build a collection hydrator
      *
-     * @param EntityManagerInterface $em      The Entity manager.
-     * @param mixed[]                $mapping The association mapping.
+     * @param mixed[] $mapping The association mapping.
      *
      * @return CollectionHydrator The built collection hydrator.
      */

lib/Doctrine/ORM/Cache/CacheKey.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -27,9 +11,10 @@ namespace Doctrine\ORM\Cache;
 abstract class CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * Unique identifier
      *
-     * @var string Unique identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      */
     public $hash;
 }

lib/Doctrine/ORM/Cache/CollectionCacheEntry.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -26,9 +10,10 @@ namespace Doctrine\ORM\Cache;
 class CollectionCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The list of entity identifiers hold by the collection
      *
-     * @var CacheKey[] The list of entity identifiers hold by the collection
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var CacheKey[]
      */
     public $identifiers;
 

lib/Doctrine/ORM/Cache/CollectionCacheKey.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -31,23 +15,27 @@ use function strtolower;
 class CollectionCacheKey extends CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The owner entity identifier
      *
-     * @var array<string, mixed> The owner entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $ownerIdentifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The owner entity class
      *
-     * @var string The owner entity class
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $entityClass;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The association name
      *
-     * @var string The association name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      */
     public $association;
 
@@ -55,6 +43,7 @@ class CollectionCacheKey extends CacheKey
      * @param string               $entityClass     The entity class.
      * @param string               $association     The field name that represents the association.
      * @param array<string, mixed> $ownerIdentifier The identifier of the owning entity.
+     * @psalm-param class-string $entityClass
      */
     public function __construct($entityClass, $association, array $ownerIdentifier)
     {

lib/Doctrine/ORM/Cache/CollectionHydrator.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -30,8 +14,6 @@ use Doctrine\ORM\PersistentCollection;
 interface CollectionHydrator
 {
     /**
-     * @param ClassMetadata            $metadata   The entity metadata.
-     * @param CollectionCacheKey       $key        The cached collection key.
      * @param array|mixed[]|Collection $collection The collection.
      *
      * @return CollectionCacheEntry
@@ -39,12 +21,7 @@ interface CollectionHydrator
     public function buildCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, $collection);
 
     /**
-     * @param ClassMetadata        $metadata   The owning entity metadata.
-     * @param CollectionCacheKey   $key        The cached collection key.
-     * @param CollectionCacheEntry $entry      The cached collection entry.
-     * @param PersistentCollection $collection The collection to load the cache into.
-     *
-     * @return mixed[]
+     * @return mixed[]|null
      */
     public function loadCacheEntry(ClassMetadata $metadata, CollectionCacheKey $key, CollectionCacheEntry $entry, PersistentCollection $collection);
 }

lib/Doctrine/ORM/Cache/ConcurrentRegion.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -34,7 +18,7 @@ interface ConcurrentRegion extends Region
      *
      * @param CacheKey $key The key of the item to lock.
      *
-     * @return Lock A lock instance or NULL if the lock already exists.
+     * @return Lock|null A lock instance or NULL if the lock already exists.
      *
      * @throws LockException Indicates a problem accessing the region.
      */
@@ -46,7 +30,7 @@ interface ConcurrentRegion extends Region
      * @param CacheKey $key  The key of the item to unlock.
      * @param Lock     $lock The lock previously obtained from {@link readLock}
      *
-     * @return void
+     * @return bool
      *
      * @throws LockException Indicates a problem accessing the region.
      */

lib/Doctrine/ORM/Cache/DefaultCache.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -45,7 +29,10 @@ class DefaultCache implements Cache
      /** @var CacheFactory */
     private $cacheFactory;
 
-    /** @var QueryCache[] */
+    /**
+     * @var QueryCache[]
+     * @psalm-var array<string, QueryCache>
+     */
     private $queryCaches = [];
 
     /** @var QueryCache|null */
@@ -275,10 +262,9 @@ class DefaultCache implements Cache
         return $this->queryCaches[$regionName];
     }
 
-     /**
-      * @param ClassMetadata $metadata   The entity metadata.
-      * @param mixed         $identifier The entity identifier.
-      */
+    /**
+     * @param mixed $identifier The entity identifier.
+     */
     private function buildEntityCacheKey(ClassMetadata $metadata, $identifier): EntityCacheKey
     {
         if (! is_array($identifier)) {
@@ -289,9 +275,7 @@ class DefaultCache implements Cache
     }
 
     /**
-     * @param ClassMetadata $metadata        The entity metadata.
-     * @param string        $association     The field name that represents the association.
-     * @param mixed         $ownerIdentifier The identifier of the owning entity.
+     * @param mixed $ownerIdentifier The identifier of the owning entity.
      */
     private function buildCollectionCacheKey(
         ClassMetadata $metadata,
@@ -306,18 +290,20 @@ class DefaultCache implements Cache
     }
 
     /**
-     * @param ClassMetadata $metadata   The entity metadata.
-     * @param mixed         $identifier The entity identifier.
+     * @param mixed $identifier The entity identifier.
      *
      * @return array<string, mixed>
      */
     private function toIdentifierArray(ClassMetadata $metadata, $identifier): array
     {
-        if (is_object($identifier) && $this->em->getMetadataFactory()->hasMetadataFor(ClassUtils::getClass($identifier))) {
-            $identifier = $this->uow->getSingleIdentifierValue($identifier);
+        if (is_object($identifier)) {
+            $class = ClassUtils::getClass($identifier);
+            if ($this->em->getMetadataFactory()->hasMetadataFor($class)) {
+                $identifier = $this->uow->getSingleIdentifierValue($identifier);
 
-            if ($identifier === null) {
-                throw ORMInvalidArgumentException::invalidIdentifierBindingEntity();
+                if ($identifier === null) {
+                    throw ORMInvalidArgumentException::invalidIdentifierBindingEntity($class);
+                }
             }
         }
 

lib/Doctrine/ORM/Cache/DefaultCacheFactory.php

@@ -1,28 +1,12 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
-use Doctrine\Common\Cache\Cache as CacheAdapter;
-use Doctrine\Common\Cache\CacheProvider;
-use Doctrine\Common\Cache\MultiGetCache;
+use Doctrine\Common\Cache\Cache as LegacyCache;
+use Doctrine\Common\Cache\Psr6\CacheAdapter;
+use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Cache;
 use Doctrine\ORM\Cache\Persister\Collection\NonStrictReadWriteCachedCollectionPersister;
 use Doctrine\ORM\Cache\Persister\Collection\ReadOnlyCachedCollectionPersister;
@@ -30,7 +14,6 @@ use Doctrine\ORM\Cache\Persister\Collection\ReadWriteCachedCollectionPersister;
 use Doctrine\ORM\Cache\Persister\Entity\NonStrictReadWriteCachedEntityPersister;
 use Doctrine\ORM\Cache\Persister\Entity\ReadOnlyCachedEntityPersister;
 use Doctrine\ORM\Cache\Persister\Entity\ReadWriteCachedEntityPersister;
-use Doctrine\ORM\Cache\Region\DefaultMultiGetRegion;
 use Doctrine\ORM\Cache\Region\DefaultRegion;
 use Doctrine\ORM\Cache\Region\FileLockRegion;
 use Doctrine\ORM\Cache\Region\UpdateTimestampCache;
@@ -40,15 +23,19 @@ use Doctrine\ORM\Persisters\Collection\CollectionPersister;
 use Doctrine\ORM\Persisters\Entity\EntityPersister;
 use InvalidArgumentException;
 use LogicException;
+use Psr\Cache\CacheItemPoolInterface;
+use TypeError;
 
+use function assert;
+use function get_debug_type;
 use function sprintf;
 
 use const DIRECTORY_SEPARATOR;
 
 class DefaultCacheFactory implements CacheFactory
 {
-    /** @var CacheAdapter */
-    private $cache;
+    /** @var CacheItemPoolInterface */
+    private $cacheItemPool;
 
     /** @var RegionsConfiguration */
     private $regionsConfig;
@@ -62,9 +49,33 @@ class DefaultCacheFactory implements CacheFactory
     /** @var string|null */
     private $fileLockRegionDirectory;
 
-    public function __construct(RegionsConfiguration $cacheConfig, CacheAdapter $cache)
+    /**
+     * @param CacheItemPoolInterface $cacheItemPool
+     */
+    public function __construct(RegionsConfiguration $cacheConfig, $cacheItemPool)
     {
-        $this->cache         = $cache;
+        if ($cacheItemPool instanceof LegacyCache) {
+            Deprecation::trigger(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/pull/9322',
+                'Passing an instance of %s to %s is deprecated, pass a %s instead.',
+                get_debug_type($cacheItemPool),
+                __METHOD__,
+                CacheItemPoolInterface::class
+            );
+
+            $this->cacheItemPool = CacheAdapter::wrap($cacheItemPool);
+        } elseif (! $cacheItemPool instanceof CacheItemPoolInterface) {
+            throw new TypeError(sprintf(
+                '%s: Parameter #2 is expected to be an instance of %s, got %s.',
+                __METHOD__,
+                CacheItemPoolInterface::class,
+                get_debug_type($cacheItemPool)
+            ));
+        } else {
+            $this->cacheItemPool = $cacheItemPool;
+        }
+
         $this->regionsConfig = $cacheConfig;
     }
 
@@ -107,6 +118,7 @@ class DefaultCacheFactory implements CacheFactory
      */
     public function buildCachedEntityPersister(EntityManagerInterface $em, EntityPersister $persister, ClassMetadata $metadata)
     {
+        assert($metadata->cache !== null);
         $region = $this->getRegion($metadata->cache);
         $usage  = $metadata->cache['usage'];
 
@@ -197,13 +209,9 @@ class DefaultCacheFactory implements CacheFactory
             return $this->regions[$cache['region']];
         }
 
-        $name         = $cache['region'];
-        $cacheAdapter = $this->createRegionCache($name);
-        $lifetime     = $this->regionsConfig->getLifetime($cache['region']);
-
-        $region = $cacheAdapter instanceof MultiGetCache
-            ? new DefaultMultiGetRegion($name, $cacheAdapter, $lifetime)
-            : new DefaultRegion($name, $cacheAdapter, $lifetime);
+        $name     = $cache['region'];
+        $lifetime = $this->regionsConfig->getLifetime($cache['region']);
+        $region   = new DefaultRegion($name, $this->cacheItemPool, $lifetime);
 
         if ($cache['usage'] === ClassMetadata::CACHE_USAGE_READ_WRITE) {
             if (
@@ -223,25 +231,6 @@ class DefaultCacheFactory implements CacheFactory
         return $this->regions[$cache['region']] = $region;
     }
 
-    private function createRegionCache(string $name): CacheAdapter
-    {
-        $cacheAdapter = clone $this->cache;
-
-        if (! $cacheAdapter instanceof CacheProvider) {
-            return $cacheAdapter;
-        }
-
-        $namespace = $cacheAdapter->getNamespace();
-
-        if ($namespace !== '') {
-            $namespace .= ':';
-        }
-
-        $cacheAdapter->setNamespace($namespace . $name);
-
-        return $cacheAdapter;
-    }
-
     /**
      * {@inheritdoc}
      */
@@ -251,7 +240,7 @@ class DefaultCacheFactory implements CacheFactory
             $name     = Cache::DEFAULT_TIMESTAMP_REGION_NAME;
             $lifetime = $this->regionsConfig->getLifetime($name);
 
-            $this->timestampRegion = new UpdateTimestampCache($name, clone $this->cache, $lifetime);
+            $this->timestampRegion = new UpdateTimestampCache($name, $this->cacheItemPool, $lifetime);
         }
 
         return $this->timestampRegion;
@@ -260,8 +249,8 @@ class DefaultCacheFactory implements CacheFactory
     /**
      * {@inheritdoc}
      */
-    public function createCache(EntityManagerInterface $em)
+    public function createCache(EntityManagerInterface $entityManager)
     {
-        return new DefaultCache($em);
+        return new DefaultCache($entityManager);
     }
 }

lib/Doctrine/ORM/Cache/DefaultCollectionHydrator.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -27,7 +11,6 @@ use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\UnitOfWork;
 
-use function array_walk;
 use function assert;
 
 /**
@@ -86,12 +69,16 @@ class DefaultCollectionHydrator implements CollectionHydrator
         }
 
         foreach ($entityEntries as $index => $entityEntry) {
-            $list[$index] = $this->uow->createEntity($entityEntry->class, $entityEntry->resolveAssociationEntries($this->em), self::$hints);
-        }
+            $entity = $this->uow->createEntity(
+                $entityEntry->class,
+                $entityEntry->resolveAssociationEntries($this->em),
+                self::$hints
+            );
 
-        array_walk($list, static function ($entity, $index) use ($collection) {
             $collection->hydrateSet($index, $entity);
-        });
+
+            $list[$index] = $entity;
+        }
 
         $this->uow->hydrationComplete();
 

lib/Doctrine/ORM/Cache/DefaultEntityHydrator.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -71,8 +55,16 @@ class DefaultEntityHydrator implements EntityHydrator
         $data = $this->uow->getOriginalEntityData($entity);
         $data = array_merge($data, $metadata->getIdentifierValues($entity)); // why update has no identifier values ?
 
-        if ($metadata->isVersioned) {
-            $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+        if ($metadata->requiresFetchAfterChange) {
+            if ($metadata->isVersioned) {
+                $data[$metadata->versionField] = $metadata->getFieldValue($entity, $metadata->versionField);
+            }
+
+            foreach ($metadata->fieldMappings as $name => $fieldMapping) {
+                if (isset($fieldMapping['generated'])) {
+                    $data[$name] = $metadata->getFieldValue($entity, $name);
+                }
+            }
         }
 
         foreach ($metadata->associationMappings as $name => $assoc) {

lib/Doctrine/ORM/Cache/DefaultQueryCache.php

@@ -1,28 +1,14 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Proxy\Proxy;
 use Doctrine\ORM\Cache;
+use Doctrine\ORM\Cache\Exception\FeatureNotImplemented;
+use Doctrine\ORM\Cache\Exception\NonCacheableEntity;
 use Doctrine\ORM\Cache\Logging\CacheLogger;
 use Doctrine\ORM\Cache\Persister\Entity\CachedEntityPersister;
 use Doctrine\ORM\EntityManagerInterface;
@@ -32,7 +18,6 @@ use Doctrine\ORM\Query;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\ORM\UnitOfWork;
 
-use function array_key_exists;
 use function array_map;
 use function array_shift;
 use function array_unshift;
@@ -47,7 +32,7 @@ use function reset;
  */
 class DefaultQueryCache implements QueryCache
 {
-     /** @var EntityManagerInterface */
+    /** @var EntityManagerInterface */
     private $em;
 
     /** @var UnitOfWork */
@@ -59,7 +44,7 @@ class DefaultQueryCache implements QueryCache
     /** @var QueryCacheValidator */
     private $validator;
 
-    /** @var CacheLogger */
+    /** @var CacheLogger|null */
     protected $cacheLogger;
 
     /** @var array<string,mixed> */
@@ -186,7 +171,7 @@ class DefaultQueryCache implements QueryCache
                 $assocEntries = $assocRegion->getMultiple($assocKeys);
 
                 foreach ($assoc['list'] as $assocIndex => $assocId) {
-                    $assocEntry = is_array($assocEntries) && array_key_exists($assocIndex, $assocEntries) ? $assocEntries[$assocIndex] : null;
+                    $assocEntry = is_array($assocEntries) ? ($assocEntries[$assocIndex] ?? null) : null;
 
                     if ($assocEntry === null) {
                         if ($this->cacheLogger !== null) {
@@ -245,19 +230,19 @@ class DefaultQueryCache implements QueryCache
     public function put(QueryCacheKey $key, ResultSetMapping $rsm, $result, array $hints = [])
     {
         if ($rsm->scalarMappings) {
-            throw new CacheException('Second level cache does not support scalar results.');
+            throw FeatureNotImplemented::scalarResults();
         }
 
         if (count($rsm->entityMappings) > 1) {
-            throw new CacheException('Second level cache does not support multiple root entities.');
+            throw FeatureNotImplemented::multipleRootEntities();
         }
 
         if (! $rsm->isSelect) {
-            throw new CacheException('Second-level cache query supports only select statements.');
+            throw FeatureNotImplemented::nonSelectStatements();
         }
 
         if (($hints[Query\SqlWalker::HINT_PARTIAL] ?? false) === true || ($hints[Query::HINT_FORCE_PARTIAL_LOAD] ?? false) === true) {
-            throw new CacheException('Second level cache does not support partial entities.');
+            throw FeatureNotImplemented::partialEntities();
         }
 
         if (! ($key->cacheMode & Cache::MODE_PUT)) {
@@ -270,7 +255,7 @@ class DefaultQueryCache implements QueryCache
         $persister  = $this->uow->getEntityPersister($entityName);
 
         if (! $persister instanceof CachedEntityPersister) {
-            throw CacheException::nonCacheableEntity($entityName);
+            throw NonCacheableEntity::fromEntity($entityName);
         }
 
         $region = $persister->getCacheRegion();
@@ -399,7 +384,8 @@ class DefaultQueryCache implements QueryCache
     /**
      * @param object $entity
      *
-     * @return array<object>|object
+     * @return mixed[]|object|null
+     * @psalm-return list<mixed>|object|null
      */
     private function getAssociationValue(
         ResultSetMapping $rsm,
@@ -426,10 +412,11 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * @param mixed        $value
-     * @param array<mixed> $path
+     * @param mixed $value
+     * @psalm-param array<array-key, array{field: string, class: string}> $path
      *
-     * @return mixed
+     * @return mixed[]|object|null
+     * @psalm-return list<mixed>|object|null
      */
     private function getAssociationPathValue($value, array $path)
     {

lib/Doctrine/ORM/Cache/EntityCacheEntry.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -30,16 +14,18 @@ use function array_map;
 class EntityCacheEntry implements CacheEntry
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity map data
      *
-     * @var array<string,mixed> The entity map data
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string,mixed>
      */
     public $data;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
      * @psalm-var class-string
      */
     public $class;

lib/Doctrine/ORM/Cache/EntityCacheKey.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -31,22 +15,26 @@ use function strtolower;
 class EntityCacheKey extends CacheKey
 {
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity identifier
      *
-     * @var array<string, mixed> The entity identifier
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
     public $identifier;
 
     /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
+     * The entity class name
      *
-     * @var string The entity class name
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var string
+     * @psalm-var class-string
      */
     public $entityClass;
 
     /**
      * @param string               $entityClass The entity class name. In a inheritance hierarchy it should always be the root entity class.
      * @param array<string, mixed> $identifier  The entity identifier
+     * @psalm-param class-string $entityClass
      */
     public function __construct($entityClass, array $identifier)
     {

lib/Doctrine/ORM/Cache/EntityHydrator.php

@@ -1,22 +1,6 @@
 <?php
 
-/*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- *
- * This software consists of voluntary contributions made by many individuals
- * and is licensed under the MIT license. For more information, see
- * <http://www.doctrine-project.org>.
- */
+declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
@@ -40,7 +24,9 @@ interface EntityHydrator
      * @param ClassMetadata    $metadata The entity metadata.
      * @param EntityCacheKey   $key      The entity cache key.
      * @param EntityCacheEntry $entry    The entity cache entry.
-     * @param object           $entity   The entity to load the cache into. If not specified, a new entity is created.
+     * @param object|null      $entity   The entity to load the cache into. If not specified, a new entity is created.
+     *
+     * @return object|null
      */
     public function loadCacheEntry(ClassMetadata $metadata, EntityCacheKey $key, EntityCacheEntry $entry, $entity = null);
 }

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

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+use Doctrine\ORM\Cache\CacheException as BaseCacheException;
+
+/**
+ * Exception for cache.
+ */
+class CacheException extends BaseCacheException
+{
+}

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

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+use function sprintf;
+
+class CannotUpdateReadOnlyCollection extends CacheException
+{
+    public static function fromEntityAndField(string $sourceEntity, string $fieldName): self
+    {
+        return new self(sprintf(
+            'Cannot update a readonly collection "%s#%s"',
+            $sourceEntity,
+            $fieldName
+        ));
+    }
+}

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

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+use function sprintf;
+
+class CannotUpdateReadOnlyEntity extends CacheException
+{
+    public static function fromEntity(string $entityName): self
+    {
+        return new self(sprintf('Cannot update a readonly entity "%s"', $entityName));
+    }
+}

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

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+class FeatureNotImplemented extends CacheException
+{
+    public static function scalarResults(): self
+    {
+        return new self('Second level cache does not support scalar results.');
+    }
+
+    public static function multipleRootEntities(): self
+    {
+        return new self('Second level cache does not support multiple root entities.');
+    }
+
+    public static function nonSelectStatements(): self
+    {
+        return new self('Second-level cache query supports only select statements.');
+    }
+
+    public static function partialEntities(): self
+    {
+        return new self('Second level cache does not support partial entities.');
+    }
+}

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

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+/**
+ * @deprecated
+ */
+final class InvalidResultCacheDriver extends CacheException
+{
+    public static function create(): self
+    {
+        return new self(
+            'Invalid result cache driver; it must implement Doctrine\\Common\\Cache\\Cache.'
+        );
+    }
+}

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

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\ORM\Cache\Exception;
+
+final class MetadataCacheNotConfigured extends CacheException
+{
+    public static function create(): self
+    {
+        return new self('Class Metadata Cache is not configured.');
+    }
+}