Merge pull request #11820 from doctrine/dependabot/github_actions/2.20.x/doctrine/dot-github-7.2.1

Bump doctrine/.github from 7.1.0 to 7.2.1

.doctrine-project.json

@@ -6,26 +6,100 @@
     "docsSlug": "doctrine-orm",
     "versions": [
         {
-            "name": "3.0",
-            "branchName": "3.0.x",
+            "name": "4.0",
+            "branchName": "4.0.x",
             "slug": "latest",
             "upcoming": true
         },
+        {
+            "name": "3.2",
+            "branchName": "3.2.x",
+            "slug": "3.2",
+            "upcoming": true
+        },
+        {
+            "name": "3.1",
+            "branchName": "3.1.x",
+            "slug": "3.1",
+            "current": true
+        },
+        {
+            "name": "3.0",
+            "branchName": "3.0.x",
+            "slug": "3.0",
+            "maintained": false
+        },
+        {
+            "name": "2.20",
+            "branchName": "2.20.x",
+            "slug": "2.20",
+            "upcoming": true
+        },
+        {
+            "name": "2.19",
+            "branchName": "2.19.x",
+            "slug": "2.19",
+            "maintained": true
+        },
+        {
+            "name": "2.18",
+            "branchName": "2.18.x",
+            "slug": "2.18",
+            "maintained": false
+        },
+        {
+            "name": "2.17",
+            "branchName": "2.17.x",
+            "slug": "2.17",
+            "maintained": false
+        },
+        {
+            "name": "2.16",
+            "branchName": "2.16.x",
+            "slug": "2.16",
+            "maintained": false
+        },
+        {
+            "name": "2.15",
+            "branchName": "2.15.x",
+            "slug": "2.15",
+            "maintained": false
+        },
+        {
+            "name": "2.14",
+            "branchName": "2.14.x",
+            "slug": "2.14",
+            "maintained": false
+        },
+        {
+            "name": "2.13",
+            "branchName": "2.13.x",
+            "slug": "2.13",
+            "maintained": false
+        },
+        {
+            "name": "2.12",
+            "branchName": "2.12.x",
+            "slug": "2.12",
+            "maintained": false
+        },
+        {
+            "name": "2.11",
+            "branchName": "2.11.x",
+            "slug": "2.11",
+            "maintained": false
+        },
         {
             "name": "2.10",
             "branchName": "2.10.x",
             "slug": "2.10",
-            "upcoming": true
+            "maintained": false
         },
         {
             "name": "2.9",
             "branchName": "2.9.x",
             "slug": "2.9",
-            "current": true,
-            "aliases": [
-                "current",
-                "stable"
-            ]
+            "maintained": false
         },
         {
             "name": "2.8",

.gitattributes

@@ -1,7 +1,8 @@
+/.github export-ignore
+/ci export-ignore
+/docs export-ignore
 /tests export-ignore
 /tools export-ignore
-/docs export-ignore
-/.github export-ignore
 .doctrine-project.json export-ignore
 .gitattributes export-ignore
 .gitignore export-ignore
@@ -15,5 +16,6 @@ phpcs.xml.dist export-ignore
 phpbench.json export-ignore
 phpstan.neon export-ignore
 phpstan-baseline.neon export-ignore
-psalm.xml export-ignore
-psalm-baseline.xml export-ignore
+phpstan-dbal2.neon export-ignore
+phpstan-params.neon export-ignore
+phpstan-persistence2.neon export-ignore

.github/workflows/coding-standard.yml

@@ -1,39 +0,0 @@
-name: "Coding Standards"
-
-on:
-  pull_request:
-    branches:
-      - "*.x"
-  push:
-    branches:
-      - "*.x"
-
-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"

.github/workflows/coding-standards.yml

@@ -0,0 +1,27 @@
+name: "Coding Standards"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/coding-standards.yml
+      - bin/**
+      - composer.*
+      - src/**
+      - phpcs.xml.dist
+      - tests/**
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - .github/workflows/coding-standards.yml
+      - bin/**
+      - composer.*
+      - src/**
+      - phpcs.xml.dist
+      - tests/**
+
+jobs:
+  coding-standards:
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@7.2.1"

.github/workflows/continuous-integration.yml

@@ -4,13 +4,23 @@ on:
   pull_request:
     branches:
       - "*.x"
-    tag-ignore:
-      - "*"
+    paths:
+      - .github/workflows/continuous-integration.yml
+      - ci/**
+      - composer.*
+      - src/**
+      - phpunit.xml.dist
+      - tests/**
   push:
     branches:
       - "*.x"
-    tag-ignore:
-      - "*"
+    paths:
+      - .github/workflows/continuous-integration.yml
+      - ci/**
+      - composer.*
+      - src/**
+      - phpunit.xml.dist
+      - tests/**
 
 env:
   fail-fast: true
@@ -18,7 +28,7 @@ env:
 jobs:
   phpunit-smoke-check:
     name: "PHPUnit with SQLite"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:
@@ -28,17 +38,33 @@ jobs:
           - "7.4"
           - "8.0"
           - "8.1"
+          - "8.2"
+          - "8.3"
+          - "8.4"
         dbal-version:
           - "default"
+        extension:
+          - "pdo_sqlite"
+        proxy:
+          - "common"
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
+            extension: "pdo_sqlite"
+          - php-version: "8.2"
+            dbal-version: "3@dev"
+            extension: "pdo_sqlite"
+          - php-version: "8.2"
+            dbal-version: "default"
+            extension: "sqlite3"
           - php-version: "8.1"
-            dbal-version: "3.2@dev"
+            dbal-version: "default"
+            proxy: "lazy-ghost"
+            extension: "pdo_sqlite"
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -46,52 +72,66 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          extensions: "pdo, pdo_sqlite"
+          extensions: "apcu, pdo, ${{ matrix.extension }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
-        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --coverage-clover=coverage-no-cache.xml"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
       - name: "Run PHPUnit with Second Level Cache"
-        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v2"
+        uses: "actions/upload-artifact@v4"
         with:
-          name: "phpunit-sqlite-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
+          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.proxy }}-coverage"
           path: "coverage*.xml"
 
 
   phpunit-postgres:
     name: "PHPUnit with PostgreSQL"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.2"
+          - "8.3"
+          - "8.4"
         dbal-version:
           - "default"
+          - "3@dev"
         postgres-version:
-          - "9.6"
-          - "13"
+          - "17"
+        extension:
+          - pdo_pgsql
+          - pgsql
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
-            postgres-version: "13"
+            postgres-version: "14"
+            extension: pdo_pgsql
+          - php-version: "8.2"
+            dbal-version: "default"
+            postgres-version: "9.6"
+            extension: pdo_pgsql
 
     services:
       postgres:
@@ -107,7 +147,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -115,64 +155,70 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
+          extensions: "pgsql pdo_pgsql"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v2"
+        uses: "actions/upload-artifact@v4"
         with:
-          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
+          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.extension }}-coverage"
           path: "coverage.xml"
 
 
   phpunit-mariadb:
     name: "PHPUnit with MariaDB"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.2"
+          - "8.3"
+          - "8.4"
         dbal-version:
           - "default"
+          - "3@dev"
         mariadb-version:
-          - "10.5"
+          - "11.4"
         extension:
           - "mysqli"
           - "pdo_mysql"
         include:
           - php-version: "8.0"
             dbal-version: "2.13"
-            mariadb-version: "10.5"
+            mariadb-version: "10.6"
             extension: "pdo_mysql"
 
     services:
       mariadb:
         image: "mariadb:${{ matrix.mariadb-version }}"
         env:
-          MYSQL_ALLOW_EMPTY_PASSWORD: yes
-          MYSQL_DATABASE: "doctrine_tests"
+          MARIADB_ALLOW_EMPTY_ROOT_PASSWORD: yes
+          MARIADB_DATABASE: "doctrine_tests"
 
         options: >-
-          --health-cmd "mysqladmin ping --silent"
+          --health-cmd "healthcheck.sh --connect --innodb_initialized"
 
         ports:
           - "3306:3306"
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -185,17 +231,19 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
           extensions: "${{ matrix.extension }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v2"
+        uses: "actions/upload-artifact@v4"
         with:
           name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage.xml"
@@ -203,15 +251,18 @@ jobs:
 
   phpunit-mysql:
     name: "PHPUnit with MySQL"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
     strategy:
       matrix:
         php-version:
-          - "7.4"
+          - "8.2"
+          - "8.3"
+          - "8.4"
         dbal-version:
           - "default"
+          - "3@dev"
         mysql-version:
           - "5.7"
           - "8.0"
@@ -238,7 +289,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -247,7 +298,7 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
           extensions: "${{ matrix.extension }}"
 
       - name: "Require specific DBAL version"
@@ -255,7 +306,9 @@ jobs:
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
+        with:
+          composer-options: "--ignore-platform-req=php+"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
@@ -268,7 +321,7 @@ jobs:
             ENABLE_SECOND_LEVEL_CACHE: 1
 
       - name: "Upload coverage files"
-        uses: "actions/upload-artifact@v2"
+        uses: "actions/upload-artifact@v4"
         with:
           name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage*.xml"
@@ -276,7 +329,7 @@ jobs:
 
   phpunit-lower-php-versions:
     name: "PHPUnit with SQLite"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:
@@ -288,7 +341,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -296,20 +349,22 @@ jobs:
         uses: "shivammathur/setup-php@v2"
         with:
           php-version: "${{ matrix.php-version }}"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
         with:
           dependency-versions: "${{ matrix.deps }}"
 
       - name: "Run PHPUnit"
-        run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite.xml"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_sqlite.xml"
 
 
   upload_coverage:
     name: "Upload coverage to Codecov"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
+    # Only run on PRs from forks
+    if: "github.event.pull_request.head.repo.full_name != github.repository"
     needs:
       - "phpunit-smoke-check"
       - "phpunit-postgres"
@@ -318,16 +373,18 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
       - name: "Download coverage files"
-        uses: "actions/download-artifact@v2"
+        uses: "actions/download-artifact@v4"
         with:
           path: "reports"
 
       - name: "Upload to Codecov"
-        uses: "codecov/codecov-action@v1"
+        uses: "codecov/codecov-action@v5"
         with:
           directory: reports
+        env:
+          CODECOV_TOKEN: "${{ secrets.CODECOV_TOKEN }}"

.github/workflows/documentation.yml

@@ -0,0 +1,20 @@
+name: "Documentation"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - ".github/workflows/documentation.yml"
+      - "docs/**"
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - ".github/workflows/documentation.yml"
+      - "docs/**"
+
+jobs:
+  documentation:
+    name: "Documentation"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@7.2.1"

.github/workflows/phpbench.yml

@@ -5,9 +5,21 @@ on:
   pull_request:
     branches:
       - "*.x"
+    paths:
+      - .github/workflows/phpbench.yml
+      - composer.*
+      - src/**
+      - phpbench.json
+      - tests/**
   push:
     branches:
       - "*.x"
+    paths:
+      - .github/workflows/phpbench.yml
+      - composer.*
+      - src/**
+      - phpbench.json
+      - tests/**
 
 env:
   fail-fast: true
@@ -15,7 +27,7 @@ env:
 jobs:
   phpbench:
     name: "PHPBench"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       matrix:
@@ -24,7 +36,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
         with:
           fetch-depth: 2
 
@@ -33,17 +45,10 @@ jobs:
         with:
           php-version: "${{ matrix.php-version }}"
           coverage: "pcov"
-          ini-values: "zend.assertions=1"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
 
-      - name: "Cache dependencies installed with composer"
-        uses: "actions/cache@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: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v3"
 
       - name: "Run PHPBench"
         run: "vendor/bin/phpbench run --report=default"

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

@@ -7,46 +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"
-        # revert to v1 when
-        # https://github.com/laminas/automatic-releases/issues/166 is fixed
-        uses: "docker://ghcr.io/laminas/automatic-releases:1.11.1"
-        with:
-          args: "laminas:automatic-releases:release"
-        env:
-          "GITHUB_TOKEN": ${{ secrets.ORGANIZATION_ADMIN_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"
-        # revert to v1 when
-        # https://github.com/laminas/automatic-releases/issues/166 is fixed
-        uses: "docker://ghcr.io/laminas/automatic-releases:1.11.1"
-        with:
-          args: "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"
-        # revert to v1 when
-        # https://github.com/laminas/automatic-releases/issues/166 is fixed
-        uses: "docker://ghcr.io/laminas/automatic-releases:1.11.1"
-        with:
-          args: "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@7.2.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

@@ -1,86 +1,73 @@
-
 name: "Static Analysis"
 
 on:
   pull_request:
     branches:
       - "*.x"
+    paths:
+      - .github/workflows/static-analysis.yml
+      - composer.*
+      - src/**
+      - phpstan*
+      - tests/StaticAnalysis/**
   push:
     branches:
       - "*.x"
+    paths:
+      - .github/workflows/static-analysis.yml
+      - composer.*
+      - src/**
+      - phpstan*
+      - tests/StaticAnalysis/**
 
 jobs:
   static-analysis-phpstan:
     name: "Static Analysis with PHPStan"
-    runs-on: "ubuntu-20.04"
+    runs-on: "ubuntu-22.04"
 
     strategy:
       fail-fast: false
       matrix:
-        php-version:
-          - "8.0"
         dbal-version:
           - "default"
-          - "2.13"
+        persistence-version:
+          - "default"
+        include:
+          - dbal-version: "2.13"
+            persistence-version: "default"
+          - dbal-version: "default"
+            persistence-version: "2.5"
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v2"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"
         with:
           coverage: "none"
-          php-version: "${{ matrix.php-version }}"
+          php-version: "8.4"
 
       - 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 }} = default ] && echo '3.1' || echo ${{ matrix.persistence-version }}) --no-update"
+
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
+        uses: "ramsey/composer-install@v3"
         with:
           dependency-versions: "highest"
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse"
-        if: "${{ matrix.dbal-version == 'default' }}"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version == 'default'}}"
 
       - name: "Run a static analysis with phpstan/phpstan"
         run: "vendor/bin/phpstan analyse -c phpstan-dbal2.neon"
         if: "${{ matrix.dbal-version == '2.13' }}"
 
-  static-analysis-psalm:
-    name: "Static Analysis with Psalm"
-    runs-on: "ubuntu-20.04"
-
-    strategy:
-      fail-fast: false
-      matrix:
-        php-version:
-          - "8.0"
-        dbal-version:
-          - "default"
-          - "2.13"
-
-    steps:
-      - name: "Checkout code"
-        uses: "actions/checkout@v2"
-
-      - name: "Install PHP"
-        uses: "shivammathur/setup-php@v2"
-        with:
-          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: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v1"
-        with:
-          dependency-versions: "highest"
-
-      - name: "Run a static analysis with vimeo/psalm"
-        run: "vendor/bin/psalm --show-info=false --stats --output-format=github --threads=$(nproc)"
+      - 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'}}"

.gitignore

@@ -3,9 +3,6 @@ logs/
 reports/
 dist/
 download/
-lib/api/
-lib/Doctrine/Common
-lib/Doctrine/DBAL
 /.settings/
 .buildpath
 .project
@@ -15,5 +12,6 @@ vendor/
 /tests/Doctrine/Performance/history.db
 /.phpcs-cache
 composer.lock
-/.phpunit.result.cache
+.phpunit.cache
+.phpunit.result.cache
 /*.phpunit.xml

.gitmodules

@@ -1,6 +0,0 @@
-[submodule "docs/en/_theme"]
-    path = docs/en/_theme
-    url = git://github.com/doctrine/doctrine-sphinx-theme.git
-[submodule "lib/vendor/doctrine-build-common"]
-    path = lib/vendor/doctrine-build-common
-    url = git://github.com/doctrine/doctrine-build-common.git

CONTRIBUTING.md

@@ -23,7 +23,7 @@ You may fix many some of the issues with `vendor/bin/phpcbf`.
 Please try to add a test for your pull-request.
 
 * If you want to fix a bug or provide a reproduce case, create a test file in
-  ``tests/Doctrine/Tests/ORM/Functional/Ticket`` with the name of the ticket,
+  ``tests/Tests/ORM/Functional/Ticket`` with the name of the ticket,
   ``DDC1234Test.php`` for example.
 * If you want to contribute new functionality add unit- or functional tests
   depending on the scope of the feature.
@@ -37,10 +37,14 @@ 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
 ```
 
+You will also need to enable the PHP extension that provides the SQLite driver
+for PDO: `pdo_sqlite`. How to do so depends on your system, but checking that it
+is enabled can universally be done with `php -m`: that command should list the
+extension.
+
 To run the testsuite against another database, copy the ``phpunit.xml.dist``
 to for example ``mysql.phpunit.xml`` and edit the parameters. You can
 take a look at the ``ci/github/phpunit`` directory for some examples. Then run:
@@ -53,7 +57,7 @@ sqlite database.
 Tips for creating unit tests:
 
 1. If you put a test into the `Ticket` namespace as described above, put the testcase and all entities into the same class.
-   See `https://github.com/doctrine/orm/tree/2.8.x/tests/Doctrine/Tests/ORM/Functional/Ticket/DDC2306Test.php` for an
+   See `https://github.com/doctrine/orm/tree/2.8.x/tests/Tests/ORM/Functional/Ticket/DDC2306Test.php` for an
    example.
 
 ## Getting merged

README.md

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

SECURITY.md

@@ -10,9 +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
-developers and you only.
+If you find a Security bug in Doctrine, please follow our
+[Security reporting guidelines](https://www.doctrine-project.org/policies/security.html#reporting).

UPGRADE.md

@@ -1,5 +1,646 @@
+# Upgrade to 2.20
+
+## Add `Doctrine\ORM\Query\OutputWalker` interface, deprecate `Doctrine\ORM\Query\SqlWalker::getExecutor()`
+
+Output walkers should implement the new `\Doctrine\ORM\Query\OutputWalker` interface and create
+`Doctrine\ORM\Query\Exec\SqlFinalizer` instances instead of `Doctrine\ORM\Query\Exec\AbstractSqlExecutor`s.
+The output walker must not base its workings on the query `firstResult`/`maxResult` values, so that the 
+`SqlFinalizer` can be kept in the query cache and used regardless of the actual `firstResult`/`maxResult` values.
+Any operation dependent on `firstResult`/`maxResult` should take place within the `SqlFinalizer::createExecutor()`
+method. Details can be found at https://github.com/doctrine/orm/pull/11188.
+
+## Explictly forbid property hooks
+
+Property hooks are not supported yet by Doctrine ORM. Until support is added,
+they are explicitly forbidden because the support would result in a breaking
+change in behavior.
+
+Progress on this is tracked at https://github.com/doctrine/orm/issues/11624 .
+
+## PARTIAL DQL syntax is undeprecated 
+
+Use of the PARTIAL keyword is not deprecated anymore in DQL, because we will be
+able to support PARTIAL objects with PHP 8.4 Lazy Objects and
+Symfony/VarExporter in a better way. When we decided to remove this feature
+these two abstractions did not exist yet.
+
+WARNING: If you want to upgrade to 3.x and still use PARTIAL keyword in DQL
+with array or object hydrators, then you have to directly migrate to ORM 3.3.x or higher.
+PARTIAL keyword in DQL is not available in 3.0, 3.1 and 3.2 of ORM.
+
+## Deprecate `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()`
+
+Use the `\Doctrine\ORM\Query::HINT_CUSTOM_OUTPUT_WALKER` query hint to set the output walker
+class instead of setting it through the `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()` method
+on the parser instance.
+
+# Upgrade to 2.19
+
+## Deprecate calling `ClassMetadata::getAssociationMappedByTargetField()` with the owning side of an association
+
+Calling
+`Doctrine\ORM\Mapping\ClassMetadata::getAssociationMappedByTargetField()` with
+the owning side of an association returns `null`, which is undocumented, and
+wrong according to the phpdoc of the parent method.
+
+If you do not know whether you are on the owning or inverse side of an association,
+you can use  `Doctrine\ORM\Mapping\ClassMetadata::isAssociationInverseSide()`
+to find out.
+
+## Deprecate `Doctrine\ORM\Query\Lexer::T_*` constants
+
+Use `Doctrine\ORM\Query\TokenType::T_*` instead.
+
+# Upgrade to 2.17
+
+## Deprecate annotations classes for named queries
+
+The following classes have been deprecated:
+
+* `Doctrine\ORM\Mapping\NamedNativeQueries`
+* `Doctrine\ORM\Mapping\NamedNativeQuery`
+* `Doctrine\ORM\Mapping\NamedQueries`
+* `Doctrine\ORM\Mapping\NamedQuery`
+
+## Deprecate `Doctrine\ORM\Query\Exec\AbstractSqlExecutor::_sqlStatements`
+
+Use `Doctrine\ORM\Query\Exec\AbstractSqlExecutor::sqlStatements` instead.
+
+## Undeprecate `Doctrine\ORM\Proxy\Autoloader`
+
+It will be a full-fledged class, no longer extending
+`Doctrine\Common\Proxy\Autoloader` in 3.0.x.
+
+## Deprecated: reliance on the non-optimal defaults that come with the `AUTO` identifier generation strategy
+
+When the `AUTO` identifier generation strategy was introduced, the best
+strategy at the time was selected for each database platform.
+A lot of time has passed since then, and with ORM 3.0.0 and DBAL 4.0.0, support
+for better strategies will be added.
+
+Because of that, it is now deprecated to rely on the historical defaults when
+they differ from what we will be recommended in the future.
+
+Instead, you should pick a strategy for each database platform you use, and it
+will be used when using `AUTO`. As of now, only PostgreSQL is affected by this.
+
+It is recommended that PostgreSQL users configure their existing and new
+applications to use `SEQUENCE` until `doctrine/dbal` 4.0.0 is released:
+
+```php
+use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
+use Doctrine\ORM\Configuration;
+
+assert($configuration instanceof Configuration);
+$configuration->setIdentityGenerationPreferences([
+    PostgreSQLPlatform::CLASS => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
+]);
+```
+
+When DBAL 4 is released, `AUTO` will result in `IDENTITY`, and the above
+configuration should be removed to migrate to it.
+
+## Deprecate `EntityManagerInterface::getPartialReference()`
+
+This method does not have a replacement and will be removed in 3.0.
+
+## Deprecate not-enabling lazy-ghosts
+
+Not enabling lazy ghost objects is deprecated. In ORM 3.0, they will be always enabled.
+Ensure `Doctrine\ORM\Configuration::setLazyGhostObjectEnabled(true)` is called to enable them.
+
+# Upgrade to 2.16
+
+## Deprecated accepting duplicate IDs in the identity map
+
+For any given entity class and ID value, there should be only one object instance
+representing the entity.
+
+In https://github.com/doctrine/orm/pull/10785, a check was added that will guard this
+in the identity map. The most probable cause for violations of this rule are collisions
+of application-provided IDs.
+
+In ORM 2.16.0, the check was added by throwing an exception. In ORM 2.16.1, this will be
+changed to a deprecation notice. ORM 3.0 will make it an exception again. Use
+`\Doctrine\ORM\Configuration::setRejectIdCollisionInIdentityMap()` if you want to opt-in
+to the new mode.
+
+## Potential changes to the order in which `INSERT`s are executed
+
+In https://github.com/doctrine/orm/pull/10547, the commit order computation was improved
+to fix a series of bugs where a correct (working) commit order was previously not found.
+Also, the new computation may get away with fewer queries being executed: By inserting
+referred-to entities first and using their ID values for foreign key fields in subsequent
+`INSERT` statements, additional `UPDATE` statements that were previously necessary can be
+avoided.
+
+When using database-provided, auto-incrementing IDs, this may lead to IDs being assigned
+to entities in a different order than it was previously the case.
+
+## Deprecated returning post insert IDs from `EntityPersister::executeInserts()`
+
+Persisters implementing `\Doctrine\ORM\Persisters\Entity\EntityPersister` should no longer
+return an array of post insert IDs from their `::executeInserts()` method. Make the
+persister call `Doctrine\ORM\UnitOfWork::assignPostInsertId()` instead.
+
+## Changing the way how reflection-based mapping drivers report fields, deprecated the "old" mode
+
+In ORM 3.0, a change will be made regarding how the `AttributeDriver` reports field mappings.
+This change is necessary to be able to detect (and reject) some invalid mapping configurations.
+
+To avoid surprises during 2.x upgrades, the new mode is opt-in. It can be activated on the
+`AttributeDriver` and `AnnotationDriver` by setting the `$reportFieldsWhereDeclared`
+constructor parameter to `true`. It will cause `MappingException`s to be thrown when invalid
+configurations are detected.
+
+Not enabling the new mode will cause a deprecation notice to be raised. In ORM 3.0,
+only the new mode will be available.
+
+# Upgrade to 2.15
+
+## Deprecated configuring `JoinColumn` on the inverse side of one-to-one associations
+
+For one-to-one associations, the side using the `mappedBy` attribute is the inverse side.
+The owning side is the entity with the table containing the foreign key. Using `JoinColumn`
+configuration on the _inverse_ side now triggers a deprecation notice and will be an error
+in 3.0.
+
+## Deprecated overriding fields or associations not declared in mapped superclasses
+
+As stated in the documentation, fields and associations may only be overridden when being inherited
+from mapped superclasses. Overriding them for parent entity classes now triggers a deprecation notice
+and will be an error in 3.0.
+
+## Deprecated undeclared entity inheritance
+
+As soon as an entity class inherits from another entity class, inheritance has to
+be declared by adding the appropriate configuration for the root entity.
+
+## Deprecated stubs for "concrete table inheritance"
+
+This third way of mapping class inheritance was never implemented. Code stubs are
+now deprecated and will be removed in 3.0.
+
+* `\Doctrine\ORM\Mapping\ClassMetadataInfo::INHERITANCE_TYPE_TABLE_PER_CLASS` constant
+* `\Doctrine\ORM\Mapping\ClassMetadataInfo::isInheritanceTypeTablePerClass()` method
+* Using `TABLE_PER_CLASS` as the value for the `InheritanceType` attribute or annotation
+  or in XML configuration files.
+
+# Upgrade to 2.14
+
+## Deprecated `Doctrine\ORM\Persisters\Exception\UnrecognizedField::byName($field)` method.
+
+Use `Doctrine\ORM\Persisters\Exception\UnrecognizedField::byFullyQualifiedName($className, $field)` instead.
+
+## Deprecated constants of `Doctrine\ORM\Internal\CommitOrderCalculator`
+
+The following public constants have been deprecated:
+
+* `CommitOrderCalculator::NOT_VISITED`
+* `CommitOrderCalculator::IN_PROGRESS`
+* `CommitOrderCalculator::VISITED`
+
+These constants were used for internal purposes. Relying on them is discouraged.
+
+## Deprecated `Doctrine\ORM\Query\AST\InExpression`
+
+The AST parser will create a `InListExpression` or a `InSubselectExpression` when
+encountering an `IN ()` DQL expression instead of a generic `InExpression`.
+
+As a consequence, `SqlWalker::walkInExpression()` has been deprecated in favor of
+`SqlWalker::walkInListExpression()` and `SqlWalker::walkInSubselectExpression()`.
+
+## Deprecated constructing a `CacheKey` without `$hash`
+
+The `Doctrine\ORM\Cache\CacheKey` class has an explicit constructor now with
+an optional parameter `$hash`. That parameter will become mandatory in 3.0.
+
+## Deprecated `AttributeDriver::$entityAnnotationClasses`
+
+If you need to change the behavior of `AttributeDriver::isTransient()`,
+override that method instead.
+
+## Deprecated incomplete schema updates
+
+Using `orm:schema-tool:update` without passing the `--complete` flag is
+deprecated. Use schema asset filtering if you need to preserve assets not
+managed by DBAL.
+
+Likewise, calling `SchemaTool::updateSchema()` or
+`SchemaTool::getUpdateSchemaSql()` with a second argument is deprecated.
+
+## Deprecated annotation mapping driver.
+
+Please switch to one of the other mapping drivers. Native attributes which PHP
+supports since version 8.0 are probably your best option.
+
+As a consequence, the following methods are deprecated:
+- `ORMSetup::createAnnotationMetadataConfiguration`
+- `ORMSetup::createDefaultAnnotationDriver`
+
+The marker interface `Doctrine\ORM\Mapping\Annotation` is deprecated as well.
+All annotation/attribute classes implement
+`Doctrine\ORM\Mapping\MappingAttribute` now.
+
+## Deprecated `Doctrine\ORM\Proxy\Proxy` interface.
+
+Use `Doctrine\Persistence\Proxy` instead to check whether proxies are initialized.
+
+## Deprecated `Doctrine\ORM\Event\LifecycleEventArgs` class.
+
+It will be removed in 3.0. Use one of the dedicated event classes instead:
+
+* `Doctrine\ORM\Event\PrePersistEventArgs`
+* `Doctrine\ORM\Event\PreUpdateEventArgs`
+* `Doctrine\ORM\Event\PreRemoveEventArgs`
+* `Doctrine\ORM\Event\PostPersistEventArgs`
+* `Doctrine\ORM\Event\PostUpdateEventArgs`
+* `Doctrine\ORM\Event\PostRemoveEventArgs`
+* `Doctrine\ORM\Event\PostLoadEventArgs`
+
+# Upgrade to 2.13
+
+## Deprecated `EntityManager::create()`
+
+The constructor of `EntityManager` is now public and should be used instead of the `create()` method.
+However, the constructor expects a `Connection` while `create()` accepted an array with connection parameters.
+You can pass that array to DBAL's `Doctrine\DBAL\DriverManager::getConnection()` method to bootstrap the
+connection.
+
+## Deprecated `QueryBuilder` methods and constants.
+
+1. The `QueryBuilder::getState()` method has been deprecated as the builder state is an internal concern.
+2. Relying on the type of the query being built by using `QueryBuilder::getType()` has been deprecated.
+   If necessary, track the type of the query being built outside of the builder.
+
+The following `QueryBuilder` constants related to the above methods have been deprecated:
+
+1. `SELECT`,
+2. `DELETE`,
+3. `UPDATE`,
+4. `STATE_DIRTY`,
+5. `STATE_CLEAN`.
+
+## Deprecated omitting only the alias argument for `QueryBuilder::update` and `QueryBuilder::delete`
+
+When building an UPDATE or DELETE query and when passing a class/type to the function, the alias argument must not be omitted.
+
+### Before
+
+```php
+$qb = $em->createQueryBuilder()
+    ->delete('User u')
+    ->where('u.id = :user_id')
+    ->setParameter('user_id', 1);
+```
+
+### After
+
+```php
+$qb = $em->createQueryBuilder()
+    ->delete('User', 'u')
+    ->where('u.id = :user_id')
+    ->setParameter('user_id', 1);
+```
+
+## Deprecated using the `IDENTITY` identifier strategy on platform that do not support identity columns
+
+If identity columns are emulated with sequences on the platform you are using,
+you should switch to the `SEQUENCE` strategy.
+
+## Deprecated passing `null` to `Doctrine\ORM\Query::setFirstResult()`
+
+`$query->setFirstResult(null);` is equivalent to `$query->setFirstResult(0)`.
+
+## Deprecated calling setters without arguments
+
+The following methods will require an argument in 3.0. Pass `null` instead of
+omitting the argument.
+
+* `Doctrine\ORM\Event\OnClassMetadataNotFoundEventArgs::setFoundMetadata()`
+* `Doctrine\ORM\AbstractQuery::setHydrationCacheProfile()`
+* `Doctrine\ORM\AbstractQuery::setResultCache()`
+* `Doctrine\ORM\AbstractQuery::setResultCacheProfile()`
+
+## Deprecated passing invalid fetch modes to `AbstractQuery::setFetchMode()`
+
+Calling `AbstractQuery::setFetchMode()` with anything else than
+`Doctrine\ORM\Mapping::FETCH_EAGER` results in
+`Doctrine\ORM\Mapping::FETCH_LAZY` being used. Relying on that behavior is
+deprecated and will result in an exception in 3.0.
+
+## Deprecated `getEntityManager()` in `Doctrine\ORM\Event\OnClearEventArgs` and `Doctrine\ORM\Event\*FlushEventArgs`
+
+This method has been deprecated in:
+
+* `Doctrine\ORM\Event\OnClearEventArgs`
+* `Doctrine\ORM\Event\OnFlushEventArgs`
+* `Doctrine\ORM\Event\PostFlushEventArgs`
+* `Doctrine\ORM\Event\PreFlushEventArgs`
+
+It will be removed in 3.0. Use `getObjectManager()` instead.
+
+## Prepare split of output walkers and tree walkers
+
+In 3.0, `SqlWalker` and its child classes won't implement the `TreeWalker`
+interface anymore. Relying on that inheritance is deprecated.
+
+The following methods of the `TreeWalker` interface have been deprecated:
+
+* `setQueryComponent()`
+* `walkSelectClause()`
+* `walkFromClause()`
+* `walkFunction()`
+* `walkOrderByClause()`
+* `walkOrderByItem()`
+* `walkHavingClause()`
+* `walkJoin()`
+* `walkSelectExpression()`
+* `walkQuantifiedExpression()`
+* `walkSubselect()`
+* `walkSubselectFromClause()`
+* `walkSimpleSelectClause()`
+* `walkSimpleSelectExpression()`
+* `walkAggregateExpression()`
+* `walkGroupByClause()`
+* `walkGroupByItem()`
+* `walkDeleteClause()`
+* `walkUpdateClause()`
+* `walkUpdateItem()`
+* `walkWhereClause()`
+* `walkConditionalExpression()`
+* `walkConditionalTerm()`
+* `walkConditionalFactor()`
+* `walkConditionalPrimary()`
+* `walkExistsExpression()`
+* `walkCollectionMemberExpression()`
+* `walkEmptyCollectionComparisonExpression()`
+* `walkNullComparisonExpression()`
+* `walkInExpression()`
+* `walkInstanceOfExpression()`
+* `walkLiteral()`
+* `walkBetweenExpression()`
+* `walkLikeExpression()`
+* `walkStateFieldPathExpression()`
+* `walkComparisonExpression()`
+* `walkInputParameter()`
+* `walkArithmeticExpression()`
+* `walkArithmeticTerm()`
+* `walkStringPrimary()`
+* `walkArithmeticFactor()`
+* `walkSimpleArithmeticExpression()`
+* `walkPathExpression()`
+* `walkResultVariable()`
+* `getExecutor()`
+
+The following changes have been made to the abstract `TreeWalkerAdapter` class:
+
+* All implementations of now-deprecated `TreeWalker` methods have been
+  deprecated as well.
+* The method `setQueryComponent()` will become protected in 3.0. Calling it
+  publicly is deprecated.
+* The method `_getQueryComponents()` is deprecated, call `getQueryComponents()`
+  instead.
+
+On the `TreeWalkerChain` class, all implementations of now-deprecated
+`TreeWalker` methods have been deprecated as well.  However, `SqlWalker` is
+unaffected by those deprecations and will continue to implement all of those
+methods.
+
+## Deprecated passing `null` to `Doctrine\ORM\Query::setDQL()`
+
+Doing `$query->setDQL(null);` achieves nothing.
+
+## Deprecated omitting second argument to `NamingStrategy::joinColumnName`
+
+When implementing `NamingStrategy`, it is deprecated to implement
+`joinColumnName()` with only one argument.
+
+### Before
+
+```php
+<?php
+class MyStrategy implements NamingStrategy
+{
+    /**
+     * @param string $propertyName A property name.
+     */
+    public function joinColumnName($propertyName): string
+    {
+        // …
+    }
+}
+```
+
+### After
+
+For backward-compatibility reasons, the parameter has to be optional, but can
+be documented as guaranteed to be a `class-string`.
+
+```php
+<?php
+class MyStrategy implements NamingStrategy
+{
+    /**
+     * @param string       $propertyName A property name.
+     * @param class-string $className
+     */
+    public function joinColumnName($propertyName, $className = null): string
+    {
+        // …
+    }
+}
+```
+
+## Deprecated methods related to named queries
+
+The following methods have been deprecated:
+
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryMapping()`
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryResultClassMapping()`
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryResultSetMapping()`
+- `Doctrine\ORM\Query\ResultSetMappingBuilder::addNamedNativeQueryEntityResultMapping()`
+
+## Deprecated classes related to Doctrine 1 and reverse engineering
+
+The following classes have been deprecated:
+
+- `Doctrine\ORM\Tools\ConvertDoctrine1Schema`
+- `Doctrine\ORM\Tools\DisconnectedClassMetadataFactory`
+
+## Deprecate `ClassMetadataInfo` usage
+
+It is deprecated to pass `Doctrine\ORM\Mapping\ClassMetadataInfo` instances
+that are not also instances of `Doctrine\ORM\ClassMetadata` to the following
+methods:
+
+- `Doctrine\ORM\Mapping\Builder\ClassMetadataBuilder::__construct()`
+- `Doctrine\ORM\Mapping\Driver\DatabaseDriver::loadMetadataForClass()`
+- `Doctrine\ORM\Tools\SchemaValidator::validateClass()`
+
+# Upgrade to 2.12
+
+## Deprecated the `doctrine` binary.
+
+The documentation explains how the console tools can be bootstrapped for
+standalone usage.
+
+The method `ConsoleRunner::printCliConfigTemplate()` is deprecated because it
+was only useful in the context of the `doctrine` binary.
+
+## Deprecate omitting `$class` argument to `ORMInvalidArgumentException::invalidIdentifierBindingEntity()`
+
+To make it easier to identify understand the cause for that exception, it is
+deprecated to omit the class name when calling
+`ORMInvalidArgumentException::invalidIdentifierBindingEntity()`.
+
+## Deprecate `Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper`
+
+Using a console helper to provide the ORM's console commands with one or
+multiple entity managers had been deprecated with 2.9 already. This leaves
+The `EntityManagerHelper` class with no purpose which is why it is now
+deprecated too. Applications that still rely on the `em` console helper, can
+easily recreate that class in their own codebase.
+
+## Deprecate custom repository classes that don't extend `EntityRepository`
+
+Although undocumented, it is currently possible to configure a custom repository
+class that implements `ObjectRepository` but does not extend the
+`EntityRepository` base class.
+
+This is now deprecated. Please extend `EntityRepository` instead.
+
+## Deprecated more APIs related to entity namespace aliases
+
+```diff
+-$config = $entityManager->getConfiguration();
+-$config->addEntityNamespace('CMS', 'My\App\Cms');
++use My\App\Cms\CmsUser;
+
+-$entityManager->getRepository('CMS:CmsUser');
++$entityManager->getRepository(CmsUser::class);
+```
+
+## Deprecate `AttributeDriver::getReader()` and `AnnotationDriver::getReader()`
+
+That method was inherited from the abstract `AnnotationDriver` class of
+`doctrine/persistence`, and does not seem to serve any purpose.
+
+## Un-deprecate `Doctrine\ORM\Proxy\Proxy`
+
+Because no forward-compatible new proxy solution had been implemented yet, the
+current proxy mechanism is not considered deprecated anymore for the time
+being. This applies to the following interfaces/classes:
+
+* `Doctrine\ORM\Proxy\Proxy`
+* `Doctrine\ORM\Proxy\ProxyFactory`
+
+These methods have been un-deprecated:
+
+* `Doctrine\ORM\Configuration::getAutoGenerateProxyClasses()`
+* `Doctrine\ORM\Configuration::getProxyDir()`
+* `Doctrine\ORM\Configuration::getProxyNamespace()`
+
+Note that the `Doctrine\ORM\Proxy\Autoloader` remains deprecated and will be removed in 3.0.
+
+## Deprecate helper methods from `AbstractCollectionPersister`
+
+The following protected methods of
+`Doctrine\ORM\Cache\Persister\Collection\AbstractCollectionPersister`
+are not in use anymore and will be removed.
+
+* `evictCollectionCache()`
+* `evictElementCache()`
+
+## Deprecate `Doctrine\ORM\Query\TreeWalkerChainIterator`
+
+This class won't have a replacement.
+
+## Deprecate `OnClearEventArgs::getEntityClass()` and `OnClearEventArgs::clearsAllEntities()`
+
+These methods will be removed in 3.0 along with the ability to partially clear
+the entity manager.
+
+## Deprecate `Doctrine\ORM\Configuration::newDefaultAnnotationDriver`
+
+This functionality has been moved to the new `ORMSetup` class. Call
+`Doctrine\ORM\ORMSetup::createDefaultAnnotationDriver()` to create
+a new annotation driver.
+
+## Deprecate `Doctrine\ORM\Tools\Setup`
+
+In our effort to migrate from Doctrine Cache to PSR-6, the `Setup` class which
+accepted a Doctrine Cache instance in each method has been deprecated.
+
+The replacement is `Doctrine\ORM\ORMSetup` which accepts a PSR-6
+cache instead.
+
+## Deprecate `Doctrine\ORM\Cache\MultiGetRegion`
+
+The interface will be merged with `Doctrine\ORM\Cache\Region` in 3.0.
+
+# Upgrade to 2.11
+
+## Rename `AbstractIdGenerator::generate()` to `generateId()`
+
+Implementations of `AbstractIdGenerator` have to override the method
+`generateId()` without calling the parent implementation. Not doing so is
+deprecated. Calling `generate()` on any `AbstractIdGenerator` implementation
+is deprecated.
+
+## PSR-6-based second level cache
+
+The second level cache has been reworked to consume a PSR-6 cache. Using a
+Doctrine Cache instance is deprecated.
+
+* `DefaultCacheFactory`: The constructor expects a PSR-6 cache item pool as
+  second argument now.
+* `DefaultMultiGetRegion`: This class is deprecated in favor of `DefaultRegion`.
+* `DefaultRegion`:
+  * The constructor expects a PSR-6 cache item pool as second argument now.
+  * The protected `$cache` property is deprecated.
+  * The properties `$name` and `$lifetime` as well as the constant
+   `REGION_KEY_SEPARATOR` and the method `getCacheEntryKey()` are flagged as
+   `@internal` now. They all will become `private` in 3.0.
+  * The method `getCache()` is deprecated without replacement.
+
+## Deprecated: `Doctrine\ORM\Mapping\Driver\PHPDriver`
+
+Use `StaticPHPDriver` instead when you want to programmatically configure
+entity metadata.
+
+You can convert mappings with the `orm:convert-mapping` command or more simply
+in this case, `include` the metadata file from the `loadMetadata` static method
+used by the `StaticPHPDriver`.
+
+## Deprecated: `Setup::registerAutoloadDirectory()`
+
+Use Composer's autoloader instead.
+
+## Deprecated: `AbstractHydrator::hydrateRow()`
+
+Following the deprecation of the method `AbstractHydrator::iterate()`, the
+method `hydrateRow()` has been deprecated as well.
+
+## Deprecate cache settings inspection
+
+Doctrine does not provide its own cache implementation anymore and relies on
+the PSR-6 standard instead. As a consequence, we cannot determine anymore
+whether a given cache adapter is suitable for a production environment.
+Because of that, functionality that aims to do so has been deprecated:
+
+* `Configuration::ensureProductionSettings()`
+* the `orm:ensure-production-settings` console command
+
 # Upgrade to 2.10
 
+## BC Break: `UnitOfWork` now relies on SPL object IDs, not hashes
+
+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.
@@ -9,10 +650,6 @@ It is now deprecated to rely on:
 - `Doctrine\ORM\Mapping\ClassMetadata::$tableGeneratorDefinition`;
 - or `Doctrine\ORM\Mapping\ClassMetadata::isIdGeneratorTable()`.
 
-## BC Break: Removed possibility to extend the doctrine mapping xml schema with anything
-
-If you want to extend it now you have to provide your own validation schema.
-
 ## 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_.
@@ -24,7 +661,7 @@ function foo(EntityManagerInterface $entityManager, callable $func) {
     if (method_exists($entityManager, 'wrapInTransaction')) {
         return $entityManager->wrapInTransaction($func);
     }
-    
+
     return $entityManager->transactional($func);
 }
 ```
@@ -90,7 +727,7 @@ implementation. To work around this:
 * As a quick workaround, you can lock the doctrine/cache dependency to work around this: `composer require doctrine/cache ^1.11`.
   Note that this is only recommended as a bandaid fix, as future versions of ORM will no longer work with doctrine/cache
   1.11.
-  
+
 ## Deprecated: doctrine/cache for metadata caching
 
 The `Doctrine\ORM\Configuration#setMetadataCacheImpl()` method is deprecated and should no longer be used. Please use
@@ -108,19 +745,19 @@ 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
 
-## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods	
+## Added `Doctrine\ORM\AbstractQuery#enableResultCache()` and `Doctrine\ORM\AbstractQuery#disableResultCache()` methods
 
 Method `Doctrine\ORM\AbstractQuery#useResultCache()` which could be used for both enabling and disabling the cache
-(depending on passed flag) was split into two.	
+(depending on passed flag) was split into two.
 
-## Minor BC BREAK: paginator output walkers aren't be called anymore on sub-queries for queries without max results  
+## Minor BC BREAK: paginator output walkers aren't be called anymore on sub-queries for queries without max results
 
 To optimize DB interaction, `Doctrine\ORM\Tools\Pagination\Paginator` no longer fetches identifiers to be able to
 perform the pagination with join collections when max results isn't set in the query.
@@ -139,7 +776,7 @@ In the last patch of the `v2.6.x` series, we fixed a bug that was not converting
 In order to not break BC we've introduced a way to enable the fixed behavior using a boolean constructor argument. This
 argument will be removed in 3.0 and the default behavior will be the fixed one.
 
-## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`	
+## Deprecated: `Doctrine\ORM\AbstractQuery#useResultCache()`
 
 Method `Doctrine\ORM\AbstractQuery#useResultCache()` is deprecated because it is split into `enableResultCache()`
 and `disableResultCache()`. It will be removed in 3.0.
@@ -169,7 +806,7 @@ These related classes have been deprecated:
 
  * `Doctrine\ORM\Proxy\ProxyFactory`
  * `Doctrine\ORM\Proxy\Autoloader` - we suggest using the composer autoloader instead
- 
+
 These methods have been deprecated:
 
  * `Doctrine\ORM\Configuration#getAutoGenerateProxyClasses()`
@@ -179,8 +816,7 @@ These methods have been deprecated:
 ## Deprecated `Doctrine\ORM\Version`
 
 The `Doctrine\ORM\Version` class is now deprecated and will be removed in Doctrine ORM 3.0:
-please refrain from checking the ORM version at runtime or use
-[ocramius/package-versions](https://github.com/Ocramius/PackageVersions/).
+please refrain from checking the ORM version at runtime or use Composer's [runtime API](https://getcomposer.org/doc/07-runtime.md#knowing-whether-package-x-is-installed-in-version-y).
 
 ## Deprecated `EntityManager#merge()` method
 
@@ -219,7 +855,7 @@ If your code relies on single entity flushing optimisations via
 
 Said API was affected by multiple data integrity bugs due to the fact
 that change tracking was being restricted upon a subset of the managed
-entities. The ORM cannot support committing subsets of the managed 
+entities. The ORM cannot support committing subsets of the managed
 entities while also guaranteeing data integrity, therefore this
 utility was removed.
 
@@ -234,8 +870,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.
 
@@ -320,8 +956,8 @@ either:
  - map those classes as `MappedSuperclass`
 
 ## Minor BC BREAK: ``EntityManagerInterface`` instead of ``EntityManager`` in type-hints
- 
-As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require 
+
+As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require
 an ``EntityManagerInterface`` instead.
 If you are extending any of the following classes, then you need to check following
 signatures:
@@ -414,7 +1050,7 @@ the `Doctrine\ORM\Repository\DefaultRepositoryFactory`.
 When executing DQL queries with new object expressions, instead of returning DTOs numerically indexes, it will now respect user provided aliases. Consider the following query:
 
     SELECT new UserDTO(u.id,u.name) as user,new AddressDTO(a.street,a.postalCode) as address, a.id as addressId FROM User u INNER JOIN u.addresses a WITH a.isPrimary = true
-    
+
 Previously, your result would be similar to this:
 
     array(
@@ -652,7 +1288,7 @@ The EntityRepository now has an interface Doctrine\Persistence\ObjectRepository.
 The annotation reader was heavily refactored between 2.0 and 2.1-RC1. In theory the operation of the new reader should be backwards compatible, but it has to be setup differently to work that way:
 
     // new call to the AnnotationRegistry
-    \Doctrine\Common\Annotations\AnnotationRegistry::registerFile('/doctrine-src/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php');
+    \Doctrine\Common\Annotations\AnnotationRegistry::registerFile('/doctrine-src/src/Mapping/Driver/DoctrineAnnotations.php');
 
     $reader = new \Doctrine\Common\Annotations\AnnotationReader();
     $reader->setDefaultAnnotationNamespace('Doctrine\ORM\Mapping\\');

bin/doctrine-pear.php

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

bin/doctrine.php

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

ci/github/phpunit/mysqli.xml

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

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"/>
@@ -25,7 +27,7 @@
 
     <filter>
         <whitelist>
-            <directory suffix=".php">../../../lib/Doctrine</directory>
+            <directory suffix=".php">../../../src</directory>
         </whitelist>
     </filter>
 

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" />
@@ -25,7 +27,7 @@
 
     <filter>
         <whitelist>
-            <directory suffix=".php">../../../lib/Doctrine</directory>
+            <directory suffix=".php">../../../src</directory>
         </whitelist>
     </filter>
 

ci/github/phpunit/pdo_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"/>
@@ -23,7 +25,7 @@
 
     <filter>
         <whitelist>
-            <directory suffix=".php">../../../lib/Doctrine</directory>
+            <directory suffix=".php">../../../src</directory>
         </whitelist>
     </filter>
 

ci/github/phpunit/pgsql.xml

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

ci/github/phpunit/sqlite3.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
+         colors="true"
+         beStrictAboutOutputDuringTests="true"
+         beStrictAboutTodoAnnotatedTests="true"
+         failOnRisky="true"
+         convertDeprecationsToExceptions="true"
+>
+    <php>
+        <ini name="error_reporting" value="-1" />
+        <!-- use an in-memory sqlite database -->
+        <var name="db_driver" value="sqlite3"/>
+        <var name="db_memory" value="true"/>
+
+        <!-- necessary change for some CLI/console output test assertions -->
+        <env name="COLUMNS" value="120"/>
+    </php>
+
+    <testsuites>
+        <testsuite name="Doctrine DBAL Test Suite">
+            <directory>../../../tests</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist>
+            <directory suffix=".php">../../../src</directory>
+        </whitelist>
+    </filter>
+
+    <groups>
+        <exclude>
+            <group>performance</group>
+            <group>locking_functional</group>
+        </exclude>
+    </groups>
+</phpunit>

composer.json

@@ -13,54 +13,62 @@
         {"name": "Marco Pivetta", "email": "ocramius@gmail.com"}
     ],
     "config": {
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true,
+            "dealerdirect/phpcodesniffer-composer-installer": true,
+            "phpstan/extension-installer": true
+        },
         "sort-packages": true
     },
     "require": {
-        "php": "^7.1 ||^8.0",
+        "php": "^7.1 || ^8.0",
+        "composer-runtime-api": "^2",
         "ext-ctype": "*",
-        "ext-pdo": "*",
-        "composer/package-versions-deprecated": "^1.8",
         "doctrine/cache": "^1.12.1 || ^2.1.1",
-        "doctrine/collections": "^1.5",
+        "doctrine/collections": "^1.5 || ^2.1",
         "doctrine/common": "^3.0.3",
-        "doctrine/dbal": "^2.13.1 || ^3.1.1",
-        "doctrine/deprecations": "^0.5.3",
-        "doctrine/event-manager": "^1.1",
+        "doctrine/dbal": "^2.13.1 || ^3.2",
+        "doctrine/deprecations": "^0.5.3 || ^1",
+        "doctrine/event-manager": "^1.2 || ^2",
         "doctrine/inflector": "^1.4 || ^2.0",
-        "doctrine/instantiator": "^1.3",
-        "doctrine/lexer": "^1.0",
-        "doctrine/persistence": "^2.2",
+        "doctrine/instantiator": "^1.3 || ^2",
+        "doctrine/lexer": "^2 || ^3",
+        "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^3.0 || ^4.0 || ^5.0 || ^6.0",
+        "symfony/console": "^4.2 || ^5.0 || ^6.0 || ^7.0",
         "symfony/polyfill-php72": "^1.23",
-        "symfony/polyfill-php80": "^1.15"
+        "symfony/polyfill-php80": "^1.16"
     },
     "require-dev": {
-        "doctrine/annotations": "^1.13",
-        "doctrine/coding-standard": "^9.0",
+        "doctrine/annotations": "^1.13 || ^2",
+        "doctrine/coding-standard": "^9.0.2 || ^12.0",
         "phpbench/phpbench": "^0.16.10 || ^1.0",
-        "phpstan/phpstan": "0.12.99",
-        "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.10.0"
+        "phpstan/extension-installer": "~1.1.0 || ^1.4",
+        "phpstan/phpstan": "~1.4.10 || 2.0.3",
+        "phpstan/phpstan-deprecation-rules": "^1 || ^2",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6",
+        "psr/log": "^1 || ^2 || ^3",
+        "squizlabs/php_codesniffer": "3.7.2",
+        "symfony/cache": "^4.4 || ^5.4 || ^6.4 || ^7.0",
+        "symfony/var-exporter": "^4.4 || ^5.4 || ^6.2 || ^7.0",
+        "symfony/yaml": "^3.4 || ^4.0 || ^5.0 || ^6.0 || ^7.0"
     },
     "conflict": {
-        "doctrine/annotations": "<1.13 || >= 2.0"
+        "doctrine/annotations": "<1.13 || >= 3.0"
     },
     "suggest": {
+        "ext-dom": "Provides support for XSD validation for XML mapping files",
         "symfony/cache": "Provides cache support for Setup Tool with doctrine/cache 2.0",
         "symfony/yaml": "If you want to use YAML Metadata Mapping Driver"
     },
     "autoload": {
-        "psr-4": { "Doctrine\\ORM\\": "lib/Doctrine/ORM" }
+        "psr-4": { "Doctrine\\ORM\\": "src" }
     },
     "autoload-dev": {
         "psr-4": {
-            "Doctrine\\Tests\\": "tests/Doctrine/Tests",
-            "Doctrine\\StaticAnalysis\\": "tests/Doctrine/StaticAnalysis",
-            "Doctrine\\Performance\\": "tests/Doctrine/Performance"
+            "Doctrine\\Tests\\": "tests/Tests",
+            "Doctrine\\StaticAnalysis\\": "tests/StaticAnalysis",
+            "Doctrine\\Performance\\": "tests/Performance"
         }
     },
     "bin": ["bin/doctrine"],

docs/.gitignore

@@ -1,4 +0,0 @@
-en/_exts/configurationblock.pyc
-build
-en/_build
-.idea

docs/.gitmodules

@@ -1,3 +0,0 @@
-[submodule "en/_theme"]
-	path = en/_theme
-	url = https://github.com/doctrine/doctrine-sphinx-theme.git

docs/en/_exts/configurationblock.py

@@ -1,93 +0,0 @@
-#Copyright (c) 2010 Fabien Potencier
-#
-#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 the Software without restriction, including without limitation the rights
-#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-#copies of the Software, and to permit persons to whom the Software is furnished
-#to do so, subject to the following conditions:
-#
-#The above copyright notice and this permission notice shall be included in all
-#copies or substantial portions of the Software.
-#
-#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-#THE SOFTWARE.
-
-from docutils.parsers.rst import Directive, directives
-from docutils import nodes
-from string import upper
-
-class configurationblock(nodes.General, nodes.Element):
-    pass
-
-class ConfigurationBlock(Directive):
-    has_content = True
-    required_arguments = 0
-    optional_arguments = 0
-    final_argument_whitespace = True
-    option_spec = {}
-    formats = {
-        'html':            'HTML',
-        'xml':             'XML',
-        'php':             'PHP',
-        'yaml':            'YAML',
-        'jinja':           'Twig',
-        'html+jinja':      'Twig',
-        'jinja+html':      'Twig',
-        'php+html':        'PHP',
-        'html+php':        'PHP',
-        'ini':             'INI',
-        'php-annotations': 'Annotations',
-    }
-
-    def run(self):
-        env = self.state.document.settings.env
-
-        node = nodes.Element()
-        node.document = self.state.document
-        self.state.nested_parse(self.content, self.content_offset, node)
-
-        entries = []
-        for i, child in enumerate(node):
-            if isinstance(child, nodes.literal_block):
-                # add a title (the language name) before each block
-                #targetid = "configuration-block-%d" % env.new_serialno('configuration-block')
-                #targetnode = nodes.target('', '', ids=[targetid])
-                #targetnode.append(child)
-
-                innernode = nodes.emphasis(self.formats[child['language']], self.formats[child['language']])
-
-                para = nodes.paragraph()
-                para += [innernode, child]
-
-                entry = nodes.list_item('')
-                entry.append(para)
-                entries.append(entry)
-
-        resultnode = configurationblock()
-        resultnode.append(nodes.bullet_list('', *entries))
-
-        return [resultnode]
-
-def visit_configurationblock_html(self, node):
-    self.body.append(self.starttag(node, 'div', CLASS='configuration-block'))
-
-def depart_configurationblock_html(self, node):
-    self.body.append('</div>\n')
-
-def visit_configurationblock_latex(self, node):
-    pass
-
-def depart_configurationblock_latex(self, node):
-    pass
-
-def setup(app):
-    app.add_node(configurationblock,
-                 html=(visit_configurationblock_html, depart_configurationblock_html),
-                 latex=(visit_configurationblock_latex, depart_configurationblock_latex))
-    app.add_directive('configuration-block', ConfigurationBlock)

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/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,62 +29,42 @@ The entity class:
 .. code-block:: php
 
     <?php
-    
+
     namespace Geo\Entity;
- 
-    /**
-     * @Entity
-     */
+
+    use Geo\ValueObject\Point;
+
+    #[Entity]
     class Location
     {
-        /**
-         * @Column(type="point")
-         *
-         * @var \Geo\ValueObject\Point
-         */
-        private $point;
+        #[Column(type: 'point')]
+        private Point $point;
 
-        /**
-         * @Column(type="string")
-         *
-         * @var string
-         */
-        private $address;
+        #[Column]
+        private string $address;
 
-        /**
-         * @param \Geo\ValueObject\Point $point
-         */
-        public function setPoint(\Geo\ValueObject\Point $point)
+        public function setPoint(Point $point): void
         {
             $this->point = $point;
         }
 
-        /**
-         * @return \Geo\ValueObject\Point
-         */
-        public function getPoint()
+        public function getPoint(): Point
         {
             return $this->point;
         }
 
-        /**
-         * @param string $address
-         */
-        public function setAddress($address)
+        public function setAddress(string $address): void
         {
             $this->address = $address;
         }
 
-        /**
-         * @return string
-         */
-        public function getAddress()
+        public function getAddress(): string
         {
             return $this->address;
         }
     }
 
-We use the custom type ``point`` in the ``@Column``  docblock annotation of the 
+We use the custom type ``point`` in the ``#[Column]``  attribute of the
 ``$point`` field. We will create this custom mapping type in the next chapter.
 
 The point class:
@@ -92,34 +72,23 @@ The point class:
 .. code-block:: php
 
     <?php
-    
+
     namespace Geo\ValueObject;
 
     class Point
     {
-
-        /**
-         * @param float $latitude
-         * @param float $longitude
-         */
-        public function __construct($latitude, $longitude)
-        {
-            $this->latitude  = $latitude;
-            $this->longitude = $longitude;
+        public function __construct(
+            private float $latitude,
+            private float $longitude,
+        ) {
         }
 
-        /**
-         * @return float
-         */
-        public function getLatitude()
+        public function getLatitude(): float
         {
             return $this->latitude;
         }
 
-        /**
-         * @return float
-         */
-        public function getLongitude()
+        public function getLongitude(): float
         {
             return $this->longitude;
         }
@@ -196,7 +165,7 @@ The format of the string representation format is called
 `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 +179,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
@@ -227,7 +196,7 @@ Example usage
     <?php
 
     // Bootstrapping stuff...
-    // $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config);
+    // $em = new \Doctrine\ORM\EntityManager($connection, $config);
 
     // Setup custom mapping type
     use Doctrine\DBAL\Types\Type;
@@ -252,5 +221,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/aggregate-fields.rst

@@ -36,71 +36,50 @@ Our entities look like:
     namespace Bank\Entities;
 
     use Doctrine\ORM\Mapping as ORM;
-    
-    /**
-     * @ORM\Entity
-     */
+    use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\Common\Collections\Collection;
+
+    #[ORM\Entity]
     class Account
     {
-        /**
-         * @ORM\Id
-         * @ORM\GeneratedValue
-         * @ORM\Column(type="integer")
-         */
+        #[ORM\Id]
+        #[ORM\GeneratedValue]
+        #[ORM\Column(type: 'integer')]
         private ?int $id;
-    
-        /**
-         * @ORM\Column(type="string", unique=true)
-         */
-        private string $no;
-    
-        /**
-         * @ORM\OneToMany(targetEntity="Entry", mappedBy="account", cascade={"persist"})
-         */
-        private array $entries;
-    
-        /**
-         * @ORM\Column(type="integer")
-         */
-        private int $maxCredit = 0;
-    
-        public function __construct(string $no, int $maxCredit = 0)
-        {
-            $this->no = $no;
-            $this->maxCredit = $maxCredit;
-            $this->entries = new \Doctrine\Common\Collections\ArrayCollection();
+
+        #[ORM\OneToMany(targetEntity: Entry::class, mappedBy: 'account', cascade: ['persist'])]
+        private Collection $entries;
+
+
+        public function __construct(
+            #[ORM\Column(type: 'string', unique: true)]
+            private string $no,
+
+            #[ORM\Column(type: 'integer')]
+            private int $maxCredit = 0,
+        ) {
+            $this->entries = new ArrayCollection();
         }
     }
-    
-    /**
-     * @ORM\Entity
-     */
+
+    #[ORM\Entity]
     class Entry
     {
-        /**
-         * @ORM\Id
-         * @ORM\GeneratedValue
-         * @ORM\Column(type="integer")
-         */
+        #[ORM\Id]
+        #[ORM\GeneratedValue]
+        #[ORM\Column(type: 'integer')]
         private ?int $id;
-    
-        /**
-         * @ORM\ManyToOne(targetEntity="Account", inversedBy="entries")
-         */
-        private Account $account;
-    
-        /**
-         * @ORM\Column(type="integer")
-         */
-        private int $amount;
-    
-        public function __construct(Account $account, int $amount)
-        {
-            $this->account = $account;
-            $this->amount = $amount;
+
+        public function __construct(
+            #[ORM\ManyToOne(targetEntity: Account::class, inversedBy: 'entries')]
+            private Account $account,
+
+            #[ORM\Column(type: 'integer')]
+            private int $amount,
+        ) {
             // more stuff here, from/to whom, stated reason, execution date and such
         }
-    
+
         public function getAmount(): Amount
         {
             return $this->amount;
@@ -193,9 +172,8 @@ relation with this method:
         public function addEntry(int $amount): void
         {
             $this->assertAcceptEntryAllowed($amount);
-    
-            $e = new Entry($this, $amount);
-            $this->entries[] = $e;
+
+            $this->entries[] = new Entry($this, $amount);
         }
     }
 
@@ -211,20 +189,20 @@ Now look at the following test-code for our entities:
     {
         public function testAddEntry()
         {
-            $account = new Account("123456", $maxCredit = 200);
+            $account = new Account("123456", maxCredit: 200);
             $this->assertEquals(0, $account->getBalance());
-    
+
             $account->addEntry(500);
             $this->assertEquals(500, $account->getBalance());
-    
+
             $account->addEntry(-700);
             $this->assertEquals(-200, $account->getBalance());
         }
-    
+
         public function testExceedMaxLimit()
         {
-            $account = new Account("123456", $maxCredit = 200);
-    
+            $account = new Account("123456", maxCredit: 200);
+
             $this->expectException(Exception::class);
             $account->addEntry(-1000);
         }
@@ -285,22 +263,19 @@ entries collection) we want to add an aggregate field called
     <?php
     class Account
     {
-        /**
-         * @ORM\Column(type="integer")
-         */
+        #[ORM\Column(type: 'integer')]
         private int $balance = 0;
-    
+
         public function getBalance(): int
         {
             return $this->balance;
         }
-    
+
         public function addEntry(int $amount): void
         {
             $this->assertAcceptEntryAllowed($amount);
-    
-            $e = new Entry($this, $amount);
-            $this->entries[] = $e;
+
+            $this->entries[] = new Entry($this, $amount);
             $this->balance += $amount;
         }
     }
@@ -331,13 +306,13 @@ potentially lead to inconsistent state. See this example:
     // The Account $accId has a balance of 0 and a max credit limit of 200:
     // request 1 account
     $account1 = $em->find(Account::class, $accId);
-    
+
     // request 2 account
     $account2 = $em->find(Account::class, $accId);
-    
+
     $account1->addEntry(-200);
     $account2->addEntry(-200);
-    
+
     // now request 1 and 2 both flush the changes.
 
 The aggregate field ``Account::$balance`` is now -200, however the
@@ -357,10 +332,8 @@ Optimistic locking is as easy as adding a version column:
 
     class Account
     {
-        /**
-         * @ORM\Column(type="integer")
-         * @ORM\Version
-         */
+        #[ORM\Column(type: 'integer')]
+        #[ORM\Version]
         private int $version;
     }
 

docs/en/cookbook/decorator-pattern.rst

@@ -23,48 +23,32 @@ concrete subclasses, ``ConcreteComponent`` and ``ConcreteDecorator``.
 
     namespace Test;
 
-    /**
-     * @Entity
-     * @InheritanceType("SINGLE_TABLE")
-     * @DiscriminatorColumn(name="discr", type="string")
-     * @DiscriminatorMap({"cc" = "Test\Component\ConcreteComponent",
-        "cd" = "Test\Decorator\ConcreteDecorator"})
-     */
+    #[Entity]
+    #[InheritanceType('SINGLE_TABLE')]
+    #[DiscriminatorColumn(name: 'discr', type: 'string')]
+    #[DiscriminatorMap(['cc' => Component\ConcreteComponent::class,
+        'cd' => Decorator\ConcreteDecorator::class])]
     abstract class Component
     {
 
-        /**
-         * @Id @Column(type="integer")
-         * @GeneratedValue(strategy="AUTO")
-         */
-        protected $id;
+        #[Id, Column]
+        #[GeneratedValue(strategy: 'AUTO')]
+        protected int|null $id = null;
 
-        /** @Column(type="string", nullable=true) */
+        #[Column(type: 'string', nullable: true)]
         protected $name;
 
-        /**
-         * Get id
-         * @return integer $id
-         */
-        public function getId()
+        public function getId(): int|null
         {
             return $this->id;
         }
 
-        /**
-         * Set name
-         * @param string $name
-         */
-        public function setName($name)
+        public function setName(string $name): void
         {
             $this->name = $name;
         }
 
-        /**
-         * Get name
-         * @return string $name
-         */
-        public function getName()
+        public function getName(): string
         {
             return $this->name;
         }
@@ -86,7 +70,7 @@ purpose of keeping this example simple).
 
     use Test\Component;
 
-    /** @Entity */
+    #[Entity]
     class ConcreteComponent extends Component
     {}
 
@@ -103,14 +87,11 @@ use a ``MappedSuperclass`` for this.
 
     namespace Test;
 
-    /** @MappedSuperclass */
+    #[MappedSuperclass]
     abstract class Decorator extends Component
     {
-
-        /**
-         * @OneToOne(targetEntity="Test\Component", cascade={"all"})
-         * @JoinColumn(name="decorates", referencedColumnName="id")
-         */
+        #[OneToOne(targetEntity: Component::class, cascade: ['all'])]
+        #[JoinColumn(name: 'decorates', referencedColumnName: 'id')]
         protected $decorates;
 
         /**
@@ -126,25 +107,19 @@ use a ``MappedSuperclass`` for this.
          * (non-PHPdoc)
          * @see Test.Component::getName()
          */
-        public function getName()
+        public function getName(): string
         {
     	    return 'Decorated ' . $this->getDecorates()->getName();
         }
 
-        /**
-         * the component being decorated
-         * @return Component
-         */
-        protected function getDecorates()
+        /** the component being decorated */
+        protected function getDecorates(): Component
         {
     	    return $this->decorates;
         }
 
-        /**
-         * sets the component being decorated
-         * @param Component $c
-         */
-        protected function setDecorates(Component $c)
+        /** sets the component being decorated */
+        protected function setDecorates(Component $c): void
         {
     	    $this->decorates = $c;
         }
@@ -187,27 +162,19 @@ of the getSpecial() method to its return value.
 
     use Test\Decorator;
 
-    /** @Entity */
+    #[Entity]
     class ConcreteDecorator extends Decorator
     {
 
-        /** @Column(type="string", nullable=true) */
-        protected $special;
+        #[Column(type: 'string', nullable: true)]
+        protected string|null $special = null;
 
-        /**
-         * Set special
-         * @param string $special
-         */
-        public function setSpecial($special)
+        public function setSpecial(string|null $special): void
         {
             $this->special = $special;
         }
 
-        /**
-         * Get special
-         * @return string $special
-         */
-        public function getSpecial()
+        public function getSpecial(): string|null
         {
             return $this->special;
         }
@@ -216,7 +183,7 @@ of the getSpecial() method to its return value.
          * (non-PHPdoc)
          * @see Test.Component::getName()
          */
-        public function getName()
+        public function getName(): string
         {
             return '[' . $this->getSpecial()
                 . '] ' . parent::getName();
@@ -270,4 +237,3 @@ objects
 
     echo $d->getName();
     // prints: [Really] Decorated Test Component 2
-

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

@@ -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,8 +45,8 @@ configuration:
     $config->addCustomStringFunction($name, $class);
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
-    
-    $em = EntityManager::create($dbParams, $config);
+
+    $em = new EntityManager($connection, $config);
 
 The ``$name`` is the name the function will be referred to in the
 DQL query. ``$class`` is a string of a class-name which has to
@@ -96,17 +96,17 @@ 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)
-            $parser->match(Lexer::T_OPEN_PARENTHESIS); // (3)
+            $parser->match(TokenType::T_IDENTIFIER); // (2)
+            $parser->match(TokenType::T_OPEN_PARENTHESIS); // (3)
             $this->firstDateExpression = $parser->ArithmeticPrimary(); // (4)
-            $parser->match(Lexer::T_COMMA); // (5)
+            $parser->match(TokenType::T_COMMA); // (5)
             $this->secondDateExpression = $parser->ArithmeticPrimary(); // (6)
-            $parser->match(Lexer::T_CLOSE_PARENTHESIS); // (3)
+            $parser->match(TokenType::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 <https://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/dql-doctrine-query-language.html#ebnf>`_
+denominator of valid EBNF tokens taken from the :ref:`DQL EBNF grammar
+<dql_ebnf_grammar>`
 that matches our requirements for valid input into the DateDiff Dql
 function. Picking the right tokens for your methods is a tricky
 business, but the EBNF grammar is pretty helpful finding it, as is
@@ -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);
-    
+            $parser->match(TokenType::T_IDENTIFIER);
+            $parser->match(TokenType::T_OPEN_PARENTHESIS);
+
             $this->firstDateExpression = $parser->ArithmeticPrimary();
-    
-            $parser->match(Lexer::T_COMMA);
-            $parser->match(Lexer::T_IDENTIFIER);
-    
+
+            $parser->match(TokenType::T_COMMA);
+            $parser->match(TokenType::T_IDENTIFIER);
+
             $this->intervalExpression = $parser->ArithmeticPrimary();
-    
-            $parser->match(Lexer::T_IDENTIFIER);
-    
-            /* @var $lexer Lexer */
+
+            $parser->match(TokenType::T_IDENTIFIER);
+
+            /** @var Lexer $lexer */
             $lexer = $parser->getLexer();
             $this->unit = $lexer->token['value'];
-    
-            $parser->match(Lexer::T_CLOSE_PARENTHESIS);
+
+            $parser->match(TokenType::T_CLOSE_PARENTHESIS);
         }
-    
+
         public function getSql(\Doctrine\ORM\Query\SqlWalker $sqlWalker)
         {
             return 'DATE_ADD(' .
@@ -247,5 +247,3 @@ vendor sql functions and extend the DQL languages scope.
 Code for this Extension to DQL and other Doctrine Extensions can be
 found
 `in the GitHub DoctrineExtensions repository <https://github.com/beberlei/DoctrineExtensions>`_.
-
-

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

@@ -1,7 +1,7 @@
 Implementing ArrayAccess for Domain Objects
 ===========================================
 
-.. sectionauthor:: Roman Borschel (roman@code-factory.org)
+.. sectionauthor:: Roman Borschel <roman@code-factory.org>
 
 This recipe will show you how to implement ArrayAccess for your
 domain objects in order to allow more uniform access, for example

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

@@ -1,7 +1,7 @@
 Implementing the Notify ChangeTracking Policy
 =============================================
 
-.. sectionauthor:: Roman Borschel (roman@code-factory.org)
+.. sectionauthor:: Roman Borschel <roman@code-factory.org>
 
 The NOTIFY change-tracking policy is the most effective
 change-tracking policy provided by Doctrine but it requires some
@@ -13,7 +13,7 @@ for all our domain objects.
 .. note::
 
     The notify change tracking policy is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
 
 Implementing NotifyPropertyChanged
 ----------------------------------
@@ -29,15 +29,15 @@ implement the ``NotifyPropertyChanged`` interface from the
     <?php
     use Doctrine\Persistence\NotifyPropertyChanged;
     use Doctrine\Persistence\PropertyChangedListener;
-    
+
     abstract class DomainObject implements NotifyPropertyChanged
     {
         private $listeners = array();
-    
+
         public function addPropertyChangedListener(PropertyChangedListener $listener) {
             $this->listeners[] = $listener;
         }
-    
+
         /** Notifies listeners of a change. */
         protected function onPropertyChanged($propName, $oldValue, $newValue) {
             if ($this->listeners) {
@@ -55,12 +55,12 @@ listeners:
 .. code-block:: php
 
     <?php
-    // Mapping not shown, either in annotations, xml or yaml as usual
+    // Mapping not shown, either in attributes, annotations, xml or yaml as usual
     class MyEntity extends DomainObject
     {
         private $data;
         // ... other fields as usual
-    
+
         public function setData($data) {
             if ($data != $this->data) { // check: is it actually modified?
                 $this->onPropertyChanged('data', $this->data, $data);
@@ -73,5 +73,3 @@ The check whether the new value is different from the old one is
 not mandatory but recommended. That way you can avoid unnecessary
 updates and also have full control over when you consider a
 property changed.
-
-

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

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

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

@@ -47,10 +47,8 @@ A Customer entity
     use Acme\CustomerModule\Entity\Customer as BaseCustomer;
     use Acme\InvoiceModule\Model\InvoiceSubjectInterface;
 
-    /**
-     * @ORM\Entity
-     * @ORM\Table(name="customer")
-     */
+    #[ORM\Entity]
+    #[ORM\Table(name: 'customer')]
     class Customer extends BaseCustomer implements InvoiceSubjectInterface
     {
         // In our example, any methods defined in the InvoiceSubjectInterface
@@ -69,19 +67,12 @@ An Invoice entity
     use Doctrine\ORM\Mapping AS ORM;
     use Acme\InvoiceModule\Model\InvoiceSubjectInterface;
 
-    /**
-     * Represents an Invoice.
-     *
-     * @ORM\Entity
-     * @ORM\Table(name="invoice")
-     */
+    #[ORM\Entity]
+    #[ORM\Table(name: 'invoice')]
     class Invoice
     {
-        /**
-         * @ORM\ManyToOne(targetEntity="Acme\InvoiceModule\Model\InvoiceSubjectInterface")
-         * @var InvoiceSubjectInterface
-         */
-        protected $subject;
+        #[ORM\ManyToOne(targetEntity: InvoiceSubjectInterface::class)]
+        protected InvoiceSubjectInterface $subject;
     }
 
 An InvoiceSubjectInterface
@@ -127,7 +118,8 @@ the targetEntity resolution will occur reliably:
     // Add the ResolveTargetEntityListener
     $evm->addEventListener(Doctrine\ORM\Events::loadClassMetadata, $rtel);
 
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
+    $connection = \Doctrine\DBAL\DriverManager::getConnection($connectionOptions, $config, $evm);
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);
 
 Final Thoughts
 --------------
@@ -136,5 +128,3 @@ With the ``ResolveTargetEntityListener``, we are able to decouple our
 bundles, keeping them usable by themselves, but still being able to
 define relationships between different objects. By using this method,
 I've found my bundles end up being easier to maintain independently.
-
-

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

@@ -47,7 +47,7 @@ appropriate autoloaders.
             }
 
             foreach ($classMetadata->getAssociationMappings() as $fieldName => $mapping) {
-                if ($mapping['type'] == \Doctrine\ORM\Mapping\ClassMetadataInfo::MANY_TO_MANY && $mapping['isOwningSide']) {
+                if ($mapping['type'] == \Doctrine\ORM\Mapping\ClassMetadata::MANY_TO_MANY && $mapping['isOwningSide']) {
                     $mappedTableName = $mapping['joinTable']['name'];
                     $classMetadata->associationMappings[$fieldName]['joinTable']['name'] = $this->prefix . $mappedTableName;
                 }
@@ -81,6 +81,4 @@ before the prefix has been set.
     $tablePrefix = new \DoctrineExtensions\TablePrefix('prefix_');
     $evm->addEventListener(\Doctrine\ORM\Events::loadClassMetadata, $tablePrefix);
     
-    $em = \Doctrine\ORM\EntityManager::create($connectionOptions, $config, $evm);
-
-
+    $em = new \Doctrine\ORM\EntityManager($connection, $config, $evm);

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

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

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

@@ -11,7 +11,7 @@ What we offer are hooks to execute any kind of validation.
 .. note::
 
     You don't need to validate your entities in the lifecycle
-    events. Its only one of many options. Of course you can also
+    events. It is only one of many options. Of course you can also
     perform validations in value setters or any other method of your
     entities that are used in your code.
 
@@ -36,12 +36,12 @@ are allowed to:
         public function assertCustomerAllowedBuying()
         {
             $orderLimit = $this->customer->getOrderLimit();
-    
+
             $amount = 0;
             foreach ($this->orderLines as $line) {
                 $amount += $line->getAmount();
             }
-    
+
             if ($amount > $orderLimit) {
                 throw new CustomerOrderLimitExceededException();
             }
@@ -53,7 +53,25 @@ code, enforcing it at any time is important so that customers with
 a unknown reputation don't owe your business too much money.
 
 We can enforce this constraint in any of the metadata drivers.
-First Annotations:
+First Attributes:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\Entity;
+    use Doctrine\ORM\Mapping\HasLifecycleCallbacks;
+    use Doctrine\ORM\Mapping\PrePersist;
+    use Doctrine\ORM\Mapping\PreUpdate;
+
+    #[Entity]
+    #[HasLifecycleCallbacks]
+    class Order
+    {
+        #[PrePersist, PreUpdate]
+        public function assertCustomerAllowedBuying() {}
+    }
+
+As Annotations:
 
 .. code-block:: php
 
@@ -83,9 +101,6 @@ In XML Mappings:
         </entity>
     </doctrine-mapping>
 
-YAML needs some little change yet, to allow multiple lifecycle
-events for one method, this will happen before Beta 1 though.
-
 Now validation is performed whenever you call
 ``EntityManager#persist($order)`` or when you call
 ``EntityManager#flush()`` and an order is about to be updated. Any
@@ -101,19 +116,17 @@ validation callbacks.
     <?php
     class Order
     {
-        /**
-         * @PrePersist @PreUpdate
-         */
+        #[PrePersist, PreUpdate]
         public function validate()
         {
             if (!($this->plannedShipDate instanceof DateTime)) {
                 throw new ValidateException();
             }
-    
+
             if ($this->plannedShipDate->format('U') < time()) {
                 throw new ValidateException();
             }
-    
+
             if ($this->customer == null) {
                 throw new OrderRequiresCustomerException();
             }

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

@@ -15,13 +15,16 @@ these comparisons are always made **BY REFERENCE**. That means the following cha
 .. code-block:: php
 
     <?php
-    /** @Entity */
+
+    use DateTime;
+
+    #[Entity]
     class Article
     {
-        /** @Column(type="datetime") */
-        private $updated;
+        #[Column(type: 'datetime')]
+        private DateTime $updated;
 
-        public function setUpdated()
+        public function setUpdated(): void
         {
             // will NOT be saved in the database
             $this->updated->modify("now");
@@ -33,12 +36,14 @@ The way to go would be:
 .. code-block:: php
 
     <?php
+    use DateTime;
+
     class Article
     {
-        public function setUpdated()
+        public function setUpdated(): void
         {
             // WILL be saved in the database
-            $this->updated = new \DateTime("now");
+            $this->updated = new DateTime("now");
         }
     }
 
@@ -84,16 +89,14 @@ the UTC time at the time of the booking and the timezone the event happened in.
 
     namespace DoctrineExtensions\DBAL\Types;
 
+    use DateTimeZone;
     use Doctrine\DBAL\Platforms\AbstractPlatform;
     use Doctrine\DBAL\Types\ConversionException;
     use Doctrine\DBAL\Types\DateTimeType;
 
     class UTCDateTimeType extends DateTimeType
     {
-        /**
-         * @var \DateTimeZone
-         */
-        private static $utc;
+        private static DateTimeZone $utc;
 
         public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
@@ -126,10 +129,10 @@ the UTC time at the time of the booking and the timezone the event happened in.
 
             return $converted;
         }
-        
-        private static function getUtc(): \DateTimeZone
+
+        private static function getUtc(): DateTimeZone
         {
-            return self::$utc ?: self::$utc = new \DateTimeZone('UTC');
+            return self::$utc ??= new DateTimeZone('UTC');
         }
     }
 

docs/en/index.rst

@@ -16,11 +16,10 @@ 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
-of contents <toc>`.
+If you need more structure over the different topics you can browse the table
+of contents.
 
 Getting Started
 ---------------
@@ -35,32 +34,32 @@ Mapping Objects onto a Database
 -------------------------------
 
 * **Mapping**:
-  :doc:`Objects <reference/basic-mapping>` |
-  :doc:`Associations <reference/association-mapping>` |
+  :doc:`Objects <reference/basic-mapping>` \|
+  :doc:`Associations <reference/association-mapping>` \|
   :doc:`Inheritance <reference/inheritance-mapping>`
 
 * **Drivers**:
-  :doc:`Docblock Annotations <reference/annotations-reference>` |
-  :doc:`Attributes <reference/attributes-reference>` |
-  :doc:`XML <reference/xml-mapping>` |
-  :doc:`YAML <reference/yaml-mapping>` |
+  :doc:`Docblock Annotations <reference/annotations-reference>` \|
+  :doc:`Attributes <reference/attributes-reference>` \|
+  :doc:`XML <reference/xml-mapping>` \|
+  :doc:`YAML <reference/yaml-mapping>` \|
   :doc:`PHP <reference/php-mapping>`
 
 Working with Objects
 --------------------
 
 * **Basic Reference**:
-  :doc:`Entities <reference/working-with-objects>` |
-  :doc:`Associations <reference/working-with-associations>` |
+  :doc:`Entities <reference/working-with-objects>` \|
+  :doc:`Associations <reference/working-with-associations>` \|
   :doc:`Events <reference/events>`
 
 * **Query Reference**:
-  :doc:`DQL <reference/dql-doctrine-query-language>` |
-  :doc:`QueryBuilder <reference/query-builder>` |
+  :doc:`DQL <reference/dql-doctrine-query-language>` \|
+  :doc:`QueryBuilder <reference/query-builder>` \|
   :doc:`Native SQL <reference/native-sql>`
 
 * **Internals**:
-  :doc:`Internals explained <reference/unitofwork>` |
+  :doc:`Internals explained <reference/unitofwork>` \|
   :doc:`Associations <reference/unitofwork-associations>`
 
 Advanced Topics
@@ -73,6 +72,7 @@ Advanced Topics
 * :doc:`Transactions and Concurrency <reference/transactions-and-concurrency>`
 * :doc:`Filters <reference/filters>`
 * :doc:`NamingStrategy <reference/namingstrategy>`
+* :doc:`TypedFieldMapper <reference/typedfieldmapper>`
 * :doc:`Improving Performance <reference/improving-performance>`
 * :doc:`Caching <reference/caching>`
 * :doc:`Partial Objects <reference/partial-objects>`
@@ -96,27 +96,26 @@ Tutorials
 Changelogs
 ----------
 
-* `Upgrade <https://github.com/doctrine/doctrine2/blob/master/UPGRADE.md>`_
+* `Upgrade <https://github.com/doctrine/orm/blob/HEAD/UPGRADE.md>`_
 
 Cookbook
 --------
 
 * **Patterns**:
-  :doc:`Aggregate Fields <cookbook/aggregate-fields>` |
-  :doc:`Decorator Pattern <cookbook/decorator-pattern>` |
+  :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
 * **DQL Extension Points**:
-  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` |
+  :doc:`DQL Custom Walkers <cookbook/dql-custom-walkers>` \|
   :doc:`DQL User-Defined-Functions <cookbook/dql-user-defined-functions>`
 
 * **Implementation**:
-  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` |
-  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` |
-  :doc:`Using Wakeup Or Clone <cookbook/implementing-wakeup-or-clone>` |
-  :doc:`Working with DateTime <cookbook/working-with-datetime>` |
-  :doc:`Validation <cookbook/validation-of-entities>` |
-  :doc:`Entities in the Session <cookbook/entities-in-session>` |
+  :doc:`Array Access <cookbook/implementing-arrayaccess-for-domain-objects>` \|
+  :doc:`Notify ChangeTracking Example <cookbook/implementing-the-notify-changetracking-policy>` \|
+  :doc:`Working with DateTime <cookbook/working-with-datetime>` \|
+  :doc:`Validation <cookbook/validation-of-entities>` \|
+  :doc:`Entities in the Session <cookbook/entities-in-session>` \|
   :doc:`Keeping your Modules independent <cookbook/resolve-target-entity-listener>`
 
 * **Hidden Gems**
@@ -125,5 +124,3 @@ Cookbook
 * **Custom Datatypes**
   :doc:`MySQL Enums <cookbook/mysql-enums>`
   :doc:`Advanced Field Value Conversion <cookbook/advanced-field-value-conversion-using-custom-mapping-types>`
-
-.. include:: toc.rst

docs/en/make.bat

@@ -1,113 +0,0 @@
-@ECHO OFF
-
-REM Command file for Sphinx documentation
-
-set SPHINXBUILD=sphinx-build
-set BUILDDIR=_build
-set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
-if NOT "%PAPER%" == "" (
-	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
-)
-
-if "%1" == "" goto help
-
-if "%1" == "help" (
-	:help
-	echo.Please use `make ^<target^>` where ^<target^> is one of
-	echo.  html      to make standalone HTML files
-	echo.  dirhtml   to make HTML files named index.html in directories
-	echo.  pickle    to make pickle files
-	echo.  json      to make JSON files
-	echo.  htmlhelp  to make HTML files and a HTML help project
-	echo.  qthelp    to make HTML files and a qthelp project
-	echo.  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter
-	echo.  changes   to make an overview over all changed/added/deprecated items
-	echo.  linkcheck to check all external links for integrity
-	echo.  doctest   to run all doctests embedded in the documentation if enabled
-	goto end
-)
-
-if "%1" == "clean" (
-	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
-	del /q /s %BUILDDIR%\*
-	goto end
-)
-
-if "%1" == "html" (
-	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
-	goto end
-)
-
-if "%1" == "dirhtml" (
-	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
-	echo.
-	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
-	goto end
-)
-
-if "%1" == "pickle" (
-	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
-	echo.
-	echo.Build finished; now you can process the pickle files.
-	goto end
-)
-
-if "%1" == "json" (
-	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
-	echo.
-	echo.Build finished; now you can process the JSON files.
-	goto end
-)
-
-if "%1" == "htmlhelp" (
-	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
-	echo.
-	echo.Build finished; now you can run HTML Help Workshop with the ^
-.hhp project file in %BUILDDIR%/htmlhelp.
-	goto end
-)
-
-if "%1" == "qthelp" (
-	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
-	echo.
-	echo.Build finished; now you can run "qcollectiongenerator" with the ^
-.qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Doctrine2ORM.qhcp
-	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Doctrine2ORM.ghc
-	goto end
-)
-
-if "%1" == "latex" (
-	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
-	echo.
-	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
-	goto end
-)
-
-if "%1" == "changes" (
-	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
-	echo.
-	echo.The overview file is in %BUILDDIR%/changes.
-	goto end
-)
-
-if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
-	echo.
-	echo.Link check complete; look for any errors in the above output ^
-or in %BUILDDIR%/linkcheck/output.txt.
-	goto end
-)
-
-if "%1" == "doctest" (
-	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
-	echo.
-	echo.Testing of doctests in the sources finished, look at the ^
-results in %BUILDDIR%/doctest/output.txt.
-	goto end
-)
-
-:end

docs/en/reference/advanced-configuration.rst

@@ -12,6 +12,8 @@ steps of configuration.
 
     use Doctrine\ORM\Configuration;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\Mapping\Driver\AttributeDriver;
+    use Doctrine\ORM\ORMSetup;
     use Symfony\Component\Cache\Adapter\ArrayAdapter;
     use Symfony\Component\Cache\Adapter\PhpFilesAdapter;
 
@@ -27,7 +29,7 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
     $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
@@ -39,12 +41,12 @@ steps of configuration.
         $config->setAutoGenerateProxyClasses(false);
     }
 
-    $connectionOptions = array(
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
-        'path' => 'database.sqlite'
-    );
+        'path' => 'database.sqlite',
+    ], $config);
 
-    $em = EntityManager::create($connectionOptions, $config);
+    $em = new EntityManager($connection, $config);
 
 Doctrine and Caching
 --------------------
@@ -112,27 +114,30 @@ classes.
 There are currently 5 available implementations:
 
 
--  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver``
 -  ``Doctrine\ORM\Mapping\Driver\AttributeDriver``
 -  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
--  ``Doctrine\ORM\Mapping\Driver\YamlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\DriverChain``
+-  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver`` (deprecated and will
+  be removed in ``doctrine/orm`` 3.0)
+-  ``Doctrine\ORM\Mapping\Driver\YamlDriver`` (deprecated and will be
+   removed in ``doctrine/orm`` 3.0)
 
-Throughout the most part of this manual the AnnotationDriver is
-used in the examples. For information on the usage of the XmlDriver
-or YamlDriver please refer to the dedicated chapters
-``XML Mapping`` and ``YAML Mapping``.
+Throughout the most part of this manual the AttributeDriver is
+used in the examples. For information on the usage of the
+AnnotationDriver, XmlDriver or YamlDriver please refer to the dedicated
+chapters ``Annotation Reference``, ``XML Mapping`` and ``YAML Mapping``.
 
-The annotation driver can be configured with a factory method on
-the ``Doctrine\ORM\Configuration``:
+The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
 
 .. code-block:: php
 
     <?php
-    $driverImpl = $config->newDefaultAnnotationDriver('/path/to/lib/MyProject/Entities');
+    use Doctrine\ORM\Mapping\Driver\AttributeDriver;
+
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
 
-The path information to the entities is required for the annotation
+The path information to the entities is required for the attribute
 driver, because otherwise mass-operations on all entities through
 the console could not work correctly. All of metadata drivers
 accept either a single directory as a string or an array of
@@ -149,7 +154,7 @@ Metadata Cache (***RECOMMENDED***)
     $config->getMetadataCache();
 
 Gets or sets the cache adapter to use for caching metadata
-information, that is, all the information you supply via
+information, that is, all the information you supply via attributes,
 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 PSR-6
@@ -195,10 +200,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***)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -214,7 +216,7 @@ option that controls this behavior is:
 
 Possible values for ``$mode`` are:
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_NEVER``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_NEVER``
 
 Never autogenerate a proxy. You will need to generate the proxies
 manually, for this use the Doctrine Console like so:
@@ -230,17 +232,17 @@ methods were added to the entity class that are not yet in the proxy class.
 In such a case, simply use the Doctrine Console to (re)generate the
 proxy classes.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_ALWAYS``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_ALWAYS``
 
 Always generates a new proxy in every request and writes it to disk.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_FILE_NOT_EXISTS``
 
 Generate the proxy class when the proxy file does not exist.
 This strategy causes a file exists call whenever any proxy is
 used the first time in a request.
 
--  ``Doctrine\Common\Proxy\AbstractProxyFactory::AUTOGENERATE_EVAL``
+-  ``Doctrine\ORM\Proxy\ProxyFactory::AUTOGENERATE_EVAL``
 
 Generate the proxy classes and evaluate them on the fly via eval(),
 avoiding writing the proxies to disk.
@@ -274,15 +276,13 @@ proxy sets an exclusive file lock which can cause serious
 performance bottlenecks in systems with regular concurrent
 requests.
 
-Connection Options
-------------------
+Connection
+----------
 
-The ``$connectionOptions`` passed as the first argument to
-``EntityManager::create()`` has to be either an array or an
-instance of ``Doctrine\DBAL\Connection``. If an array is passed it
-is directly passed along to the DBAL Factory
-``Doctrine\DBAL\DriverManager::getConnection()``. The DBAL
-configuration is explained in the
+The ``$connection`` passed as the first argument to he constructor of
+``EntityManager`` has to be an instance of ``Doctrine\DBAL\Connection``.
+You can use the factory ``Doctrine\DBAL\DriverManager::getConnection()``
+to create such a connection. The DBAL configuration is explained in the
 `DBAL section <https://www.doctrine-project.org/projects/doctrine-dbal/en/current/reference/configuration.html>`_.
 
 Proxy Objects
@@ -311,10 +311,12 @@ Reference Proxies
 
 The method ``EntityManager#getReference($entityName, $identifier)``
 lets you obtain a reference to an entity for which the identifier
-is known, without loading that entity from the database. This is
-useful, for example, as a performance enhancement, when you want to
-establish an association to an entity for which you have the
-identifier. You could simply do this:
+is known, without necessarily loading that entity from the database.
+This is useful, for example, as a performance enhancement, when you
+want to establish an association to an entity for which you have the
+identifier.
+
+Consider the following example:
 
 .. code-block:: php
 
@@ -324,14 +326,33 @@ identifier. You could simply do this:
     $item = $em->getReference('MyProject\Model\Item', $itemId);
     $cart->addItem($item);
 
-Here, we added an Item to a Cart without loading the Item from the
-database. If you invoke any method on the Item instance, it would
-fully initialize its state transparently from the database. Here
-$item is actually an instance of the proxy class that was generated
-for the Item class but your code does not need to care. In fact it
-**should not care**. Proxy objects should be transparent to your
+Whether the object being returned from ``EntityManager#getReference()``
+is a proxy or a direct instance of the entity class may depend on different
+factors, including whether the entity has already been loaded into memory
+or entity inheritance being used. But your code does not need to care
+and in fact it **should not care**. Proxy objects should be transparent to your
 code.
 
+When using the ``EntityManager#getReference()`` method, you need to be aware
+of a few peculiarities.
+
+At the best case, the ORM can avoid querying the database at all. But, that
+also means that this method will not throw an exception when an invalid value
+for the ``$identifier`` parameter is passed. ``$identifier`` values are
+not checked and there is no guarantee that the requested entity instance even
+exists – the method will still return a proxy object.
+
+Its only when the proxy has to be fully initialized or associations cannot
+be written to the database that invalid ``$identifier`` values may lead to
+exceptions.
+
+The ``EntityManager#getReference()`` is mostly useful when you only
+need a reference to some entity to make an association, like in the example
+above. In that case, it can save you from loading data from the database
+that you don't need. But remember – as soon as you read any property values
+besides those making up the ID, a database request will be made to initialize
+all fields.
+
 Association proxies
 ~~~~~~~~~~~~~~~~~~~
 
@@ -387,7 +408,7 @@ means that you have to register a special autoloader for these classes:
 .. code-block:: php
 
     <?php
-    use Doctrine\Common\Proxy\Autoloader;
+    use Doctrine\ORM\Proxy\Autoloader;
 
     $proxyDir = "/path/to/proxies";
     $proxyNamespace = "MyProxies";
@@ -404,15 +425,15 @@ Multiple Metadata Sources
 
 When using different components using Doctrine ORM you may end up
 with them using two different metadata drivers, for example XML and
-YAML. You can use the DriverChain Metadata implementations to
+YAML. You can use the MappingDriverChain Metadata implementations to
 aggregate these drivers based on namespaces:
 
 .. code-block:: php
 
     <?php
-    use Doctrine\ORM\Mapping\Driver\DriverChain;
+    use Doctrine\Persistence\Mapping\Driver\MappingDriverChain;
 
-    $chain = new DriverChain();
+    $chain = new MappingDriverChain();
     $chain->addDriver($xmlDriver, 'Doctrine\Tests\Models\Company');
     $chain->addDriver($yamlDriver, 'Doctrine\Tests\ORM\Mapping');
 
@@ -440,22 +461,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
 =====================
 
+.. warning::
+    The annotation driver is deprecated and will be removed in version
+    3.0. It is strongly recommended to switch to one of the other
+    mapping drivers.
+
 .. note::
 
     To be able to use annotations, you will have to install an extra
@@ -123,6 +128,18 @@ Optional attributes:
 
 -  **nullable**: Determines if NULL values allowed for this column. If not specified, default value is false.
 
+-  **insertable**: Boolean value to determine if the column should be
+   included when inserting a new row into the underlying entities table.
+   If not specified, default value is true.
+
+-  **updatable**: Boolean value to determine if the column should be
+   included when updating the row of the underlying entities table.
+   If not specified, default value is true.
+
+-  **generated**: An enum with the possible values ALWAYS, INSERT, NEVER.  Is
+   used after an INSERT or UPDATE statement to determine if the database
+   generated this value and it needs to be fetched using a SELECT statement.
+
 -  **options**: Array of additional options:
 
    -  ``default``: The default value to set for the column if no value
@@ -193,6 +210,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
@@ -521,12 +545,12 @@ has meaning in the SchemaTool schema generation context.
 Required attributes:
 
 
--  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will
@@ -1292,12 +1316,12 @@ context.
 Required attributes:
 
 
--  **name**: Name of the Index
 -  **fields**: Array of fields. Exactly one of **fields**, **columns** is required.
 -  **columns**: Array of columns. Exactly one of **fields**, **columns** is required.
 
 Optional attributes:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will
@@ -1363,4 +1387,3 @@ Example:
      * @Version
      */
     protected $version;
-

docs/en/reference/architecture.rst

@@ -24,28 +24,34 @@ performance it is also recommended that you use APC with PHP.
 Doctrine ORM Packages
 -------------------
 
-Doctrine ORM is divided into three main packages.
+Doctrine ORM is divided into four main packages.
 
--  Common
--  DBAL (includes Common)
--  ORM (includes DBAL+Common)
+-  `Collections <https://www.doctrine-project.org/projects/doctrine-collections/en/stable/index.html>`_
+-  `Event Manager <https://www.doctrine-project.org/projects/doctrine-event-manager/en/stable/index.html>`_
+-  `Persistence <https://www.doctrine-project.org/projects/doctrine-persistence/en/stable/index.html>`_
+-  `DBAL <https://www.doctrine-project.org/projects/doctrine-dbal/en/stable/index.html>`_
+-  ORM (depends on DBAL+Persistence+Collections)
 
 This manual mainly covers the ORM package, sometimes touching parts
-of the underlying DBAL and Common packages. The Doctrine code base
+of the underlying DBAL and Persistence packages. The Doctrine code base
 is split in to these packages for a few reasons and they are to...
 
 
 -  ...make things more maintainable and decoupled
--  ...allow you to use the code in Doctrine Common without the ORM
-   or DBAL
+-  ...allow you to use the code in Doctrine Persistence and Collections
+  without the ORM or DBAL
 -  ...allow you to use the DBAL without the ORM
 
-The Common Package
-~~~~~~~~~~~~~~~~~~
+Collection, Event Manager and Persistence
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The Common package contains highly reusable components that have no
-dependencies beyond the package itself (and PHP, of course). The
-root namespace of the Common package is ``Doctrine\Common``.
+The Collection, Event Manager and Persistence packages contain highly
+reusable components that have no dependencies beyond the packages
+themselves (and PHP, of course). The root namespace of the Persistence
+package is ``Doctrine\Persistence``. The root namespace of the
+Collection package is ``Doctrine\Common\Collections``, for historical
+reasons. The root namespace of the Event Manager package is just
+``Doctrine\Common``, also for historical reasons.
 
 The DBAL Package
 ~~~~~~~~~~~~~~~~
@@ -66,33 +72,21 @@ The root namespace of the ORM package is ``Doctrine\ORM``.
 Terminology
 -----------
 
+.. _terminology_entities:
+
 Entities
 ~~~~~~~~
 
 An entity is a lightweight, persistent domain object. An entity can
 be any regular PHP class observing the following restrictions:
 
-
--  An entity class must not be final or contain final methods.
--  All persistent properties/field of any entity class should
-   always be private or protected, otherwise lazy-loading might not
-   work as expected. In case you serialize entities (for example Session)
-   properties should be protected (See Serialize section below).
--  An entity class must not implement ``__clone`` or
-   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
--  An entity class must not implement ``__wakeup`` or
-   :doc:`do so safely <../cookbook/implementing-wakeup-or-clone>`.
-   Also consider implementing
-   `Serializable <https://php.net/manual/en/class.serializable.php>`_
-   instead.
+-  An entity class must not be final nor read-only but
+   it may contain final methods or read-only properties.
 -  Any two entity classes in a class hierarchy that inherit
    directly or indirectly from one another must not have a mapped
    property with the same name. That is, if B inherits from A then B
    must not have a mapped field with the same name as an already
    mapped field that is inherited from A.
--  An entity cannot make use of func_get_args() to implement variable parameters.
-   Generated proxies do not support this for performance reasons and your code might
-   actually fail to work when violating this restriction.
 
 Entities support inheritance, polymorphic associations, and
 polymorphic queries. Both abstract and concrete classes can be
@@ -106,6 +100,25 @@ classes, and non-entity classes may extend entity classes.
     never calls entity constructors, thus you are free to use them as
     you wish and even have it require arguments of any type.
 
+Mapped Superclasses
+~~~~~~~~~~~~~~~~~~~
+
+A mapped superclass is an abstract or concrete class that provides
+persistent entity state and mapping information for its subclasses,
+but which is not itself an entity.
+
+Mapped superclasses are explained in greater detail in the chapter
+on :doc:`inheritance mapping </reference/inheritance-mapping>`.
+
+Transient Classes
+~~~~~~~~~~~~~~~~~
+
+The term "transient class" appears in some places in the mapping
+drivers as well as the code dealing with metadata handling.
+
+A transient class is a class that is neither an entity nor a mapped
+superclass. From the ORM's point of view, these classes can be
+completely ignored, and no class metadata is loaded for them at all.
 
 Entity states
 ~~~~~~~~~~~~~
@@ -152,16 +165,13 @@ Serializing entities
 
 Serializing entities can be problematic and is not really
 recommended, at least not as long as an entity instance still holds
-references to proxy objects or is still managed by an
-EntityManager. If you intend to serialize (and unserialize) entity
-instances that still hold references to proxy objects you may run
-into problems with private properties because of technical
-limitations. Proxy objects implement ``__sleep`` and it is not
-possible for ``__sleep`` to return names of private properties in
-parent classes. On the other hand it is not a solution for proxy
-objects to implement ``Serializable`` because Serializable does not
-work well with any potential cyclic object references (at least we
-did not find a way yet, if you did, please contact us).
+references to proxy objects or is still managed by an EntityManager.
+By default, serializing proxy objects does not initialize them. On
+unserialization, resulting objects are detached from the entity
+manager and cannot be initialiazed anymore. You can implement the
+``__serialize()`` method if you want to change that behavior, but
+then you need to ensure that you won't generate large serialized
+object graphs and take care of circular associations.
 
 The EntityManager
 ~~~~~~~~~~~~~~~~~
@@ -184,6 +194,8 @@ 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
 ~~~~~~~~~~~~~~~~
 
@@ -193,5 +205,3 @@ typical implementation of the
 to keep track of all the things that need to be done the next time
 ``flush`` is invoked. You usually do not directly interact with a
 ``UnitOfWork`` but with the ``EntityManager`` instead.
-
-

docs/en/reference/association-mapping.rst

@@ -37,7 +37,26 @@ A many-to-one association is the most common association between objects. Exampl
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class User
+        {
+            // ...
+
+            #[ManyToOne(targetEntity: Address::class)]
+            #[JoinColumn(name: 'address_id', referencedColumnName: 'id')]
+            private Address|null $address = null;
+        }
+
+        #[Entity]
+        class Address
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -49,7 +68,7 @@ A many-to-one association is the most common association between objects. Exampl
              * @ManyToOne(targetEntity="Address")
              * @JoinColumn(name="address_id", referencedColumnName="id")
              */
-            private $address;
+            private Address|null $address = null;
         }
 
         /** @Entity */
@@ -82,9 +101,11 @@ A many-to-one association is the most common association between objects. Exampl
 
 .. note::
 
-    The above ``@JoinColumn`` is optional as it would default
+    The above ``#[JoinColumn]`` is optional as it would default
     to ``address_id`` and ``id`` anyways. You can omit it and let it
     use the defaults.
+    Likewise, inside the ``#[ManyToOne]`` attribute you can omit the
+    ``targetEntity`` argument and it will default to ``Address``.
 
 Generated MySQL Schema:
 
@@ -111,7 +132,29 @@ references one ``Shipment`` entity.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class Product
+        {
+            // ...
+
+            /** One Product has One Shipment. */
+            #[OneToOne(targetEntity: Shipment::class)]
+            #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
+            private Shipment|null $shipment = null;
+
+            // ...
+        }
+
+        #[Entity]
+        class Shipment
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -124,7 +167,7 @@ references one ``Shipment`` entity.
              * @OneToOne(targetEntity="Shipment")
              * @JoinColumn(name="shipment_id", referencedColumnName="id")
              */
-            private $shipment;
+            private Shipment|null $shipment = null;
 
             // ...
         }
@@ -156,7 +199,7 @@ references one ``Shipment`` entity.
                 name: shipment_id
                 referencedColumnName: id
 
-Note that the @JoinColumn is not really necessary in this example,
+Note that the ``#[JoinColumn]`` is not really necessary in this example,
 as the defaults would be the same.
 
 Generated MySQL Schema:
@@ -188,7 +231,35 @@ object.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class Customer
+        {
+            // ...
+
+            /** One Customer has One Cart. */
+            #[OneToOne(targetEntity: Cart::class, mappedBy: 'customer')]
+            private Cart|null $cart = null;
+
+            // ...
+        }
+
+        #[Entity]
+        class Cart
+        {
+            // ...
+
+            /** One Cart has One Customer. */
+            #[OneToOne(targetEntity: Customer::class, inversedBy: 'cart')]
+            #[JoinColumn(name: 'customer_id', referencedColumnName: 'id')]
+            private Customer|null $customer = null;
+
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -200,7 +271,7 @@ object.
              * One Customer has One Cart.
              * @OneToOne(targetEntity="Cart", mappedBy="customer")
              */
-            private $cart;
+            private Cart|null $cart = null;
 
             // ...
         }
@@ -215,7 +286,7 @@ object.
              * @OneToOne(targetEntity="Customer", inversedBy="cart")
              * @JoinColumn(name="customer_id", referencedColumnName="id")
              */
-            private $customer;
+            private Customer|null $customer = null;
 
             // ...
         }
@@ -281,17 +352,15 @@ below.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Student
     {
         // ...
 
-        /**
-         * One Student has One Mentor.
-         * @OneToOne(targetEntity="Student")
-         * @JoinColumn(name="mentor_id", referencedColumnName="id")
-         */
-        private $mentor;
+        /** One Student has One Mentor. */
+        #[OneToOne(targetEntity: Student::class)]
+        #[JoinColumn(name: 'mentor_id', referencedColumnName: 'id')]
+        private Student|null $mentor = null;
 
         // ...
     }
@@ -326,7 +395,40 @@ bidirectional many-to-one.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        #[Entity]
+        class Product
+        {
+            // ...
+            /**
+             * One product has many features. This is the inverse side.
+             * @var Collection<int, Feature>
+             */
+            #[OneToMany(targetEntity: Feature::class, mappedBy: 'product')]
+            private Collection $features;
+            // ...
+
+            public function __construct() {
+                $this->features = new ArrayCollection();
+            }
+        }
+
+        #[Entity]
+        class Feature
+        {
+            // ...
+            /** Many features have one product. This is the owning side. */
+            #[ManyToOne(targetEntity: Product::class, inversedBy: 'features')]
+            #[JoinColumn(name: 'product_id', referencedColumnName: 'id')]
+            private Product|null $product = null;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         use Doctrine\Common\Collections\ArrayCollection;
@@ -337,9 +439,10 @@ bidirectional many-to-one.
             // ...
             /**
              * One product has many features. This is the inverse side.
+             * @var Collection<int, Feature>
              * @OneToMany(targetEntity="Feature", mappedBy="product")
              */
-            private $features;
+            private Collection $features;
             // ...
 
             public function __construct() {
@@ -356,7 +459,7 @@ bidirectional many-to-one.
              * @ManyToOne(targetEntity="Product", inversedBy="features")
              * @JoinColumn(name="product_id", referencedColumnName="id")
              */
-            private $product;
+            private Product|null $product = null;
             // ...
         }
 
@@ -421,7 +524,39 @@ The following example sets up such a unidirectional one-to-many association:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Phonenumbers.
+             * @var Collection<int, Phonenumber>
+             */
+            #[JoinTable(name: 'users_phonenumbers')]
+            #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[InverseJoinColumn(name: 'phonenumber_id', referencedColumnName: 'id', unique: true)]
+            #[ManyToMany(targetEntity: 'Phonenumber')]
+            private Collection $phonenumbers;
+
+            public function __construct()
+            {
+                $this->phonenumbers = new ArrayCollection();
+            }
+
+            // ...
+        }
+
+        #[Entity]
+        class Phonenumber
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -430,14 +565,15 @@ 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")},
              *      inverseJoinColumns={@JoinColumn(name="phonenumber_id", referencedColumnName="id", unique=true)}
              *      )
+             * @var Collection<int, Phonenumber>
              */
-            private $phonenumbers;
+            private Collection $phonenumbers;
 
             public function __construct()
             {
@@ -523,7 +659,32 @@ database perspective is known as an adjacency list approach.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class Category
+        {
+            // ...
+            /**
+             * One Category has Many Categories.
+             * @var Collection<int, Category>
+             */
+            #[OneToMany(targetEntity: Category::class, mappedBy: 'parent')]
+            private Collection $children;
+
+            /** Many Categories have One Category. */
+            #[ManyToOne(targetEntity: Category::class, inversedBy: 'children')]
+            #[JoinColumn(name: 'parent_id', referencedColumnName: 'id')]
+            private Category|null $parent = null;
+            // ...
+
+            public function __construct() {
+                $this->children = new ArrayCollection();
+            }
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -533,15 +694,16 @@ database perspective is known as an adjacency list approach.
             /**
              * One Category has Many Categories.
              * @OneToMany(targetEntity="Category", mappedBy="parent")
+             * @var Collection<int, Category>
              */
-            private $children;
+            private Collection $children;
 
             /**
              * Many Categories have One Category.
              * @ManyToOne(targetEntity="Category", inversedBy="children")
              * @JoinColumn(name="parent_id", referencedColumnName="id")
              */
-            private $parent;
+            private Category|null $parent = null;
             // ...
 
             public function __construct() {
@@ -594,7 +756,38 @@ entities:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Groups.
+             * @var Collection<int, Group>
+             */
+            #[JoinTable(name: 'users_groups')]
+            #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
+            #[ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
+
+            // ...
+
+            public function __construct() {
+                $this->groups = new ArrayCollection();
+            }
+        }
+
+        #[Entity]
+        class Group
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -609,8 +802,9 @@ entities:
              *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
              *      inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
              *      )
+             * @var Collection<int, Group>
              */
-            private $groups;
+            private Collection $groups;
 
             // ...
 
@@ -687,6 +881,15 @@ Generated MySQL Schema:
     replaced by one-to-many/many-to-one associations between the 3
     participating classes.
 
+.. note::
+
+    For many-to-many associations, the ORM takes care of managing rows
+    in the join table connecting both sides. Due to the way it deals
+    with entity removals, database-level constraints may not work the
+    way one might intuitively assume. Thus, be sure not to miss the section
+    on :ref:`join table management <remove_object_many_to_many_join_tables>`.
+
+
 Many-To-Many, Bidirectional
 ---------------------------
 
@@ -695,7 +898,48 @@ one is bidirectional.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Groups.
+             * @var Collection<int, Group>
+             */
+            #[ManyToMany(targetEntity: Group::class, inversedBy: 'users')]
+            #[JoinTable(name: 'users_groups')]
+            private Collection $groups;
+
+            public function __construct() {
+                $this->groups = new ArrayCollection();
+            }
+
+            // ...
+        }
+
+        #[Entity]
+        class Group
+        {
+            // ...
+            /**
+             * Many Groups have Many Users.
+             * @var Collection<int, User>
+             */
+            #[ManyToMany(targetEntity: User::class, mappedBy: 'groups')]
+            private Collection $users;
+
+            public function __construct() {
+                $this->users = new ArrayCollection();
+            }
+
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity */
@@ -707,8 +951,9 @@ one is bidirectional.
              * Many Users have Many Groups.
              * @ManyToMany(targetEntity="Group", inversedBy="users")
              * @JoinTable(name="users_groups")
+             * @var Collection<int, Group>
              */
-            private $groups;
+            private Collection $groups;
 
             public function __construct() {
                 $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
@@ -724,8 +969,9 @@ one is bidirectional.
             /**
              * Many Groups have Many Users.
              * @ManyToMany(targetEntity="User", mappedBy="groups")
+             * @var Collection<int, User>
              */
-            private $users;
+            private Collection $users;
 
             public function __construct() {
                 $this->users = new \Doctrine\Common\Collections\ArrayCollection();
@@ -782,6 +1028,15 @@ one is bidirectional.
 The MySQL schema is exactly the same as for the Many-To-Many
 uni-directional case above.
 
+.. note::
+
+    For many-to-many associations, the ORM takes care of managing rows
+    in the join table connecting both sides. Due to the way it deals
+    with entity removals, database-level constraints may not work the
+    way one might intuitively assume. Thus, be sure not to miss the section
+    on :ref:`join table management <remove_object_many_to_many_join_tables>`.
+
+
 Owning and Inverse Side on a ManyToMany Association
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -806,9 +1061,9 @@ understandable:
     <?php
     class Article
     {
-        private $tags;
+        private Collection $tags;
 
-        public function addTag(Tag $tag)
+        public function addTag(Tag $tag): void
         {
             $tag->addArticle($this); // synchronously updating inverse side
             $this->tags[] = $tag;
@@ -817,9 +1072,9 @@ understandable:
 
     class Tag
     {
-        private $articles;
+        private Collection $articles;
 
-        public function addArticle(Article $article)
+        public function addArticle(Article $article): void
         {
             $this->articles[] = $article;
         }
@@ -847,30 +1102,31 @@ field named ``$friendsWithMe`` and ``$myFriends``.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class User
     {
         // ...
 
         /**
          * Many Users have Many Users.
-         * @ManyToMany(targetEntity="User", mappedBy="myFriends")
+         * @var Collection<int, User>
          */
-        private $friendsWithMe;
+        #[ManyToMany(targetEntity: User::class, mappedBy: 'myFriends')]
+        private Collection $friendsWithMe;
 
         /**
          * Many Users have many Users.
-         * @ManyToMany(targetEntity="User", inversedBy="friendsWithMe")
-         * @JoinTable(name="friends",
-         *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
-         *      inverseJoinColumns={@JoinColumn(name="friend_user_id", referencedColumnName="id")}
-         *      )
+         * @var Collection<int, User>
          */
-        private $myFriends;
+        #[JoinTable(name: 'friends')]
+        #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+        #[InverseJoinColumn(name: 'friend_user_id', referencedColumnName: 'id')]
+        #[ManyToMany(targetEntity: 'User', inversedBy: 'friendsWithMe')]
+        private Collection $myFriends;
 
         public function __construct() {
-            $this->friendsWithMe = new \Doctrine\Common\Collections\ArrayCollection();
-            $this->myFriends = new \Doctrine\Common\Collections\ArrayCollection();
+            $this->friendsWithMe = new ArrayCollection();
+            $this->myFriends = new ArrayCollection();
         }
 
         // ...
@@ -910,11 +1166,17 @@ As an example, consider this mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[OneToOne(targetEntity: Shipment::class)]
+        private Shipment|null $shipment = null;
+
+    .. code-block:: annotation
 
         <?php
         /** @OneToOne(targetEntity="Shipment") */
-        private $shipment;
+        private Shipment|null $shipment = null;
 
     .. code-block:: xml
 
@@ -937,7 +1199,15 @@ mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        /** One Product has One Shipment. */
+        #[OneToOne(targetEntity: Shipment::class)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
+        private Shipment|null $shipment = null;
+
+    .. code-block:: annotation
 
         <?php
         /**
@@ -945,7 +1215,7 @@ mapping:
          * @OneToOne(targetEntity="Shipment")
          * @JoinColumn(name="shipment_id", referencedColumnName="id")
          */
-        private $shipment;
+        private Shipment|null $shipment = null;
 
     .. code-block:: xml
 
@@ -973,14 +1243,29 @@ similar defaults. As an example, consider this mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
         class User
         {
             // ...
-            /** @ManyToMany(targetEntity="Group") */
-            private $groups;
+            /** @var Collection<int, Group> */
+            #[ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /**
+             * @ManyToMany(targetEntity="Group")
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
             // ...
         }
 
@@ -1004,7 +1289,25 @@ This is essentially the same as the following, more verbose, mapping:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        class User
+        {
+            // ...
+            /**
+             * Many Users have Many Groups.
+             * @var Collection<int, Group>
+             */
+            #[JoinTable(name: 'User_Group')]
+            #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
+            #[ManyToMany(targetEntity: Group::class)]
+            private Collection $groups;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         class User
@@ -1017,8 +1320,9 @@ This is essentially the same as the following, more verbose, mapping:
              *      joinColumns={@JoinColumn(name="User_id", referencedColumnName="id")},
              *      inverseJoinColumns={@JoinColumn(name="Group_id", referencedColumnName="id")}
              *      )
+             * @var Collection<int, Group>
              */
-            private $groups;
+            private Collection $groups;
             // ...
         }
 
@@ -1029,10 +1333,10 @@ This is essentially the same as the following, more verbose, mapping:
                 <many-to-many field="groups" target-entity="Group">
                     <join-table name="User_Group">
                         <join-columns>
-                            <join-column id="User_id" referenced-column-name="id" />
+                            <join-column id="user_id" referenced-column-name="id" />
                         </join-columns>
                         <inverse-join-columns>
-                            <join-column id="Group_id" referenced-column-name="id" />
+                            <join-column id="group_id" referenced-column-name="id" />
                         </inverse-join-columns>
                     </join-table>
                 </many-to-many>
@@ -1064,12 +1368,17 @@ defaults to "id", just as in one-to-one or many-to-one mappings.
 
 Additionally, when using typed properties with Doctrine 2.9 or newer
 you can skip ``targetEntity`` in ``ManyToOne`` and ``OneToOne``
-associations as they will be set based on type. Also ``nullable``
-attribute on ``JoinColumn`` will be inherited from PHP type. So that:
+associations as they will be set based on type. So that:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[OneToOne]
+        private Shipment $shipment;
+
+    .. code-block:: annotation
 
         <?php
         /** @OneToOne */
@@ -1094,13 +1403,21 @@ Is essentially the same as following:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        /** One Product has One Shipment. */
+        #[OneToOne(targetEntity: Shipment::class)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
+        private Shipment $shipment;
+
+    .. code-block:: annotation
 
         <?php
         /**
          * One Product has One Shipment.
          * @OneToOne(targetEntity="Shipment")
-         * @JoinColumn(name="shipment_id", referencedColumnName="id", nullable=false)
+         * @JoinColumn(name="shipment_id", referencedColumnName="id")
          */
         private Shipment $shipment;
 
@@ -1124,7 +1441,6 @@ Is essentially the same as following:
               joinColumn:
                 name: shipment_id
                 referencedColumnName: id
-                nullable: false
 
 If you accept these defaults, you can reduce the mapping code to a
 minimum.
@@ -1163,22 +1479,19 @@ and ``@ManyToMany`` associations in the constructor of your entities:
     use Doctrine\Common\Collections\Collection;
     use Doctrine\Common\Collections\ArrayCollection;
 
-    /** @Entity */
+    #[Entity]
     class User
     {
-        /**
-         * Many Users have Many Groups.
-         * @var Collection
-         * @ManyToMany(targetEntity="Group")
-         */
-        private $groups;
+        /** Many Users have Many Groups. */
+        #[ManyToMany(targetEntity: Group::class)]
+        private Collection $groups;
 
         public function __construct()
         {
             $this->groups = new ArrayCollection();
         }
 
-        public function getGroups()
+        public function getGroups(): Collection
         {
             return $this->groups;
         }

docs/en/reference/attributes-reference.rst

@@ -10,9 +10,11 @@ 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>`
+-  :ref:`#[ChangeTrackingPolicy] <attrref_changetrackingpolicy>`
 -  :ref:`#[CustomIdGenerator] <attrref_customidgenerator>`
 -  :ref:`#[DiscriminatorColumn] <attrref_discriminatorcolumn>`
 -  :ref:`#[DiscriminatorMap] <attrref_discriminatormap>`
@@ -25,7 +27,6 @@ Index
 -  :ref:`#[Id] <attrref_id>`
 -  :ref:`#[InheritanceType] <attrref_inheritancetype>`
 -  :ref:`#[JoinColumn] <attrref_joincolumn>`
--  :ref:`#[JoinColumns] <attrref_joincolumns>`
 -  :ref:`#[JoinTable] <attrref_jointable>`
 -  :ref:`#[ManyToOne] <attrref_manytoone>`
 -  :ref:`#[ManyToMany] <attrref_manytomany>`
@@ -49,6 +50,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 +147,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 +177,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
@@ -106,6 +206,8 @@ Optional attributes:
    -  ``comment``: The comment of the column in the schema (might not
       be supported by all vendors).
 
+   -  ``charset``: The charset of the column (only supported by Mysql, PostgreSQL, Sqlite and SQLServer).
+
    -  ``collation``: The collation of the column (only supported by Mysql, PostgreSQL, Sqlite and SQLServer).
 
    -  ``check``: Adds a check constraint type to the column (might not
@@ -159,13 +261,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 +321,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,17 +355,20 @@ 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.
 -  **length**: By default this is 255.
+-  **columnDefinition**: By default this is null the definition according to the type will be used. This option allows to override it.
+-  **enumType**: By default this is `null`. Allows to map discriminatorColumn value to PHP enum
+-  **options**: See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
 .. _attrref_discriminatormap:
 
@@ -319,7 +433,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 +445,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
@@ -368,7 +482,7 @@ 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``, ``IDENTITY``, ``UUID``
@@ -424,15 +538,15 @@ 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
 -  **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:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will
@@ -460,9 +574,9 @@ 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))"
+            "where" => "((category IS NOT NULL))"
         ]
     )]
     class ECommerceProduct
@@ -518,7 +632,7 @@ Examples:
     #[Entity]
     #[InheritanceType("SINGLE_TABLE")]
     #[DiscriminatorColumn(name: "discr", type: "string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -527,7 +641,7 @@ Examples:
     #[Entity]
     #[InheritanceType("JOINED")]
     #[DiscriminatorColumn(name: "discr", type: "string")]
-    #[DiscriminatorMap({"person" = "Person", "employee" = "Employee"})]
+    #[DiscriminatorMap(["person" => "Person", "employee" => "Employee"])]
     class Person
     {
         // ...
@@ -546,9 +660,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
@@ -570,6 +685,8 @@ Optional attributes:
    "columnDefinition" attribute on :ref:`#[Column] <attrref_column>` also sets
    the related ``#[JoinColumn]``'s columnDefinition. This is necessary to
    make foreign keys work.
+-  **options**:
+   See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
 Example:
 
@@ -596,7 +713,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:
@@ -623,14 +740,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
@@ -659,14 +776,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
@@ -720,7 +837,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.
@@ -756,13 +873,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
@@ -786,13 +903,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
@@ -916,11 +1033,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
@@ -954,11 +1071,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.
 
@@ -985,13 +1102,14 @@ 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.
+-  **fields**: Array of fields (the names of the properties, used in the entity class).
+-  **columns**: Array of columns (the names of the columns, used in the schema).
 
-Optional attributes:
+Optional parameters:
 
+-  **name**: Name of the Index. If not provided, a generated name will be assigned.
 -  **options**: Array of platform specific options:
 
    -  ``where``: SQL WHERE condition to be used for partial indexes. It will

docs/en/reference/basic-mapping.rst

@@ -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,20 +44,21 @@ that describes your entity.
 Doctrine provides several different ways to specify object-relational
 mapping metadata:
 
--  :doc:`Docblock Annotations <annotations-reference>`
 -  :doc:`Attributes <attributes-reference>`
 -  :doc:`XML <xml-mapping>`
--  :doc:`YAML <yaml-mapping>`
 -  :doc:`PHP code <php-mapping>`
+-  :doc:`Docblock Annotations <annotations-reference>` (deprecated and will be removed in ``doctrine/orm`` 3.0)
+-  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
-This manual will usually show mapping metadata via docblock annotations, though
-many examples also show the equivalent configuration in YAML and XML.
+This manual will usually show mapping metadata via attributes, though
+many examples also show the equivalent configuration in annotations,
+YAML and XML.
 
 .. note::
 
     All metadata drivers perform equally. Once the metadata of a class has been
-    read from the source (annotations, xml or yaml) it is stored in an instance
-    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class and these instances are
+    read from the source (attributes, annotations, XML, etc.) it is stored in an instance
+    of the ``Doctrine\ORM\Mapping\ClassMetadata`` class which are
     stored in the metadata cache.  If you're not using a metadata cache (not
     recommended!) then the XML driver is the fastest.
 
@@ -71,9 +66,22 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+
+        #[Entity]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+
         /** @Entity */
         class Message
         {
@@ -100,9 +108,25 @@ You can change this by configuring information about the table:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
+        #[Entity]
+        #[Table(name: 'message')]
+        class Message
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
         /**
          * @Entity
          * @Table(name="message")
@@ -132,19 +156,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``
-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.
+To configure a property use the ``Column`` attribute. The ``type``
+argument specifies the :ref:`Doctrine Mapping Type
+<reference-mapping-types>` to use for the field. If the type is not
+specified, ``string`` is used as the default.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
+        use Doctrine\ORM\Mapping\Column;
+        use Doctrine\DBAL\Types\Types;
+
+        #[Entity]
+        class Message
+        {
+            #[Column(type: Types::INTEGER)]
+            private $id;
+            #[Column(length: 140)]
+            private $text;
+            #[Column(name: 'posted_at', type: Types::DATETIME)]
+            private $postedAt;
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Column;
+
         /** @Entity */
         class Message
         {
@@ -180,36 +223,35 @@ 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.
+- ``generated`` (default: ``null``): Whether the generated strategy should be ``'NEVER'``, ``'INSERT'`` and ``ALWAYS``.
+- ``enumType`` (requires PHP 8.1 and ``doctrine/orm`` 2.11): The PHP enum class name to convert the database value into.
+- ``precision`` (default: 0): The precision for a decimal (exact numeric) column
+  (applies only for decimal column),
   which is the maximum number of digits that are stored for the values.
-- ``scale``: (optional, default 0) The scale for a decimal (exact
+- ``scale`` (default: 0): The scale for a decimal (exact
   numeric) column (applies only for decimal column), which represents
   the number of digits to the right of the decimal point and must
-  not be greater than *precision*.
-- ``columnDefinition``: (optional) Allows to define a custom
+  not be greater than ``precision``.
+- ``columnDefinition``: Allows to define a custom
   DDL snippet that is used to create the column. Warning: This normally
-  confuses the SchemaTool to always detect the column as changed.
-- ``options``: (optional) Key-value pairs of options that get passed
+  confuses the :doc:`SchemaTool <tools>` to always detect the column as changed.
+- ``options``: Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
 .. _reference-php-mapping-types:
@@ -217,71 +259,54 @@ list:
 PHP Types Mapping
 _________________
 
-Since version 2.9 Doctrine can determine usable defaults from property types
-on entity classes. When property type is nullable this has no effect on
-``nullable`` Column attribute at the moment for backwards compatibility
-reasons.
+.. versionadded:: 2.9
 
-Additionally, Doctrine will map PHP types to ``type`` attribute as follows:
+The column types can be inferred automatically from PHP's property types.
+However, when the property type is nullable this has no effect on the ``nullable`` Column attribute.
 
-- ``DateInterval``: ``dateinterval``
-- ``DateTime``: ``datetime``
-- ``DateTimeImmutable``: ``datetime_immutable``
-- ``array``: ``json``
-- ``bool``: ``boolean``
-- ``float``: ``float``
-- ``int``: ``integer``
-- ``string`` or any other type: ``string``
+These are the "automatic" mapping rules:
+
++-----------------------+-------------------------------+
+| PHP property type     | Doctrine column type          |
++=======================+===============================+
+| ``DateInterval``      | ``Types::DATEINTERVAL``       |
++-----------------------+-------------------------------+
+| ``DateTime``          | ``Types::DATETIME_MUTABLE``   |
++-----------------------+-------------------------------+
+| ``DateTimeImmutable`` | ``Types::DATETIME_IMMUTABLE`` |
++-----------------------+-------------------------------+
+| ``array``             | ``Types::JSON``               |
++-----------------------+-------------------------------+
+| ``bool``              | ``Types::BOOLEAN``            |
++-----------------------+-------------------------------+
+| ``float``             | ``Types::FLOAT``              |
++-----------------------+-------------------------------+
+| ``int``               | ``Types::INTEGER``            |
++-----------------------+-------------------------------+
+| Any other type        | ``Types::STRING``             |
++-----------------------+-------------------------------+
+
+As of version 2.11 Doctrine can also automatically map typed properties using a
+PHP 8.1 enum to set the right ``type`` and ``enumType``.
+
+.. versionadded:: 2.14
+
+Since version 2.14 you can specify custom typed field mapping between PHP type and DBAL type using ``Configuration``
+and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
+
+:doc:`Read more about TypedFieldMapper <typedfieldmapper>`.
 
 .. _reference-mapping-types:
 
 Doctrine Mapping Types
 ----------------------
 
-The ``type`` option used in the ``@Column`` accepts any of the existing
-Doctrine types or even your own custom types. A Doctrine type defines
+The ``type`` option used in the ``@Column`` accepts any of the
+`existing Doctrine DBAL types <https://docs.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/types.html#reference>`_
+or :doc:`your own custom mapping types
+<../cookbook/custom-mapping-types>`. A Doctrine type defines
 the conversion between PHP and SQL types, independent from the database vendor
-you are using. All Mapping Types that ship with Doctrine are fully portable
-between the supported database systems.
-
-As an example, the Doctrine Mapping Type ``string`` defines the
-mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
-depending on the RDBMS brand). Here is a quick overview of the
-built-in mapping types:
-
--  ``string``: Type that maps a SQL VARCHAR to a PHP string.
--  ``integer``: Type that maps a SQL INT to a PHP integer.
--  ``smallint``: Type that maps a database SMALLINT to a PHP
-   integer.
--  ``bigint``: Type that maps a database BIGINT to a PHP string.
--  ``boolean``: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.
--  ``decimal``: Type that maps a SQL DECIMAL to a PHP string.
--  ``date``: Type that maps a SQL DATETIME to a PHP DateTime
-   object.
--  ``time``: Type that maps a SQL TIME to a PHP DateTime object.
--  ``datetime``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
-   DateTime object.
--  ``datetimetz``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
-   DateTime object with timezone.
--  ``text``: Type that maps a SQL CLOB to a PHP string.
--  ``object``: Type that maps a SQL CLOB to a PHP object using
-   ``serialize()`` and ``unserialize()``
--  ``array``: Type that maps a SQL CLOB to a PHP array using
-   ``serialize()`` and ``unserialize()``
--  ``simple_array``: Type that maps a SQL CLOB to a PHP array using
-   ``implode()`` and ``explode()``, with a comma as delimiter. *IMPORTANT*
-   Only use this type if you are sure that your values cannot contain a ",".
--  ``json_array``: Type that maps a SQL CLOB to a PHP array using
-   ``json_encode()`` and ``json_decode()``
--  ``float``: Type that maps a SQL Float (Double Precision) to a
-   PHP double. *IMPORTANT*: Works only with locale settings that use
-   decimal points as separator.
--  ``guid``: Type that maps a database GUID/UUID to a PHP string. Defaults to
-   varchar but uses a specific type if the platform supports it.
--  ``blob``: Type that maps a SQL BLOB to a PHP resource stream
-
-A cookbook article shows how to define :doc:`your own custom mapping types
-<../cookbook/custom-mapping-types>`.
+you are using.
 
 .. note::
 
@@ -306,12 +331,23 @@ Identifiers / Primary Keys
 --------------------------
 
 Every entity class must have an identifier/primary key. You can select
-the field that serves as the identifier with the ``@Id``
-annotation.
+the field that serves as the identifier with the ``#[Id]`` attribute.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        class Message
+        {
+            #[Id]
+            #[Column(type: 'integer')]
+            #[GeneratedValue]
+            private int|null $id = null;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         class Message
@@ -321,7 +357,7 @@ annotation.
              * @Column(type="integer")
              * @GeneratedValue
              */
-            private $id;
+            private int|null $id = null;
             // ...
         }
 
@@ -348,10 +384,12 @@ annotation.
           fields:
             # fields here
 
-In most cases using the automatic generator strategy (``@GeneratedValue``) is
-what you want. It defaults to the identifier generation mechanism your current
-database vendor prefers: AUTO_INCREMENT with MySQL, sequences with PostgreSQL
-and Oracle and so on.
+In most cases using the automatic generator strategy (``#[GeneratedValue]``) is
+what you want, but for backwards-compatibility reasons it might not. It
+defaults to the identifier generation mechanism your current database
+vendor preferred at the time that strategy was introduced:
+``AUTO_INCREMENT`` with MySQL, sequences with PostgreSQL and Oracle and
+so on.
 
 .. _identifier-generation-strategies:
 
@@ -368,25 +406,26 @@ Here is the list of possible generation strategies:
 
 -  ``AUTO`` (default): Tells Doctrine to pick the strategy that is
    preferred by the used database platform. The preferred strategies
-   are IDENTITY for MySQL, SQLite, MsSQL and SQL Anywhere and SEQUENCE
-   for Oracle and PostgreSQL. This strategy provides full portability.
--  ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
-   generation. This strategy does currently not provide full
-   portability. Sequences are supported by Oracle, PostgreSql and
-   SQL Anywhere.
+   are ``IDENTITY`` for MySQL, SQLite, MsSQL and SQL Anywhere and, for
+   historical reasons, ``SEQUENCE`` for Oracle and PostgreSQL. This
+   strategy provides full portability.
 -  ``IDENTITY``: Tells Doctrine to use special identity columns in
    the database that generate a value on insertion of a row. This
    strategy does currently not provide full portability and is
    supported by the following platforms: MySQL/SQLite/SQL Anywhere
-   (AUTO\_INCREMENT), MSSQL (IDENTITY) and PostgreSQL (SERIAL).
+   (``AUTO_INCREMENT``), MSSQL (``IDENTITY``) and PostgreSQL (``SERIAL``).
+-  ``SEQUENCE``: Tells Doctrine to use a database sequence for ID
+   generation. This strategy does currently not provide full
+   portability. Sequences are supported by Oracle, PostgreSql and
+   SQL Anywhere.
 -  ``UUID`` (deprecated): Tells Doctrine to use the built-in Universally
    Unique Identifier generator. This strategy provides full portability.
 -  ``NONE``: Tells Doctrine that the identifiers are assigned (and
    thus generated) by your code. The assignment must take place before
    a new entity is passed to ``EntityManager#persist``. NONE is the
-   same as leaving off the @GeneratedValue entirely.
--  ``CUSTOM``: With this option, you can use the ``@CustomIdGenerator`` annotation.
-   It will allow you to pass a :doc:`class of your own to generate the identifiers.<_annref_customidgenerator>`
+   same as leaving off the ``#[GeneratedValue]`` entirely.
+-  ``CUSTOM``: With this option, you can use the ``#[CustomIdGenerator]`` attribute.
+   It will allow you to pass a :ref:`class of your own to generate the identifiers. <annref_customidgenerator>`
 
 Sequence Generator
 ^^^^^^^^^^^^^^^^^^
@@ -397,7 +436,19 @@ besides specifying the sequence's name:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        class Message
+        {
+            #[Id]
+            #[GeneratedValue(strategy: 'SEQUENCE')]
+            #[SequenceGenerator(sequenceName: 'message_seq', initialValue: 1, allocationSize: 100)]
+            protected int|null $id = null;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         class Message
@@ -407,7 +458,7 @@ besides specifying the sequence's name:
              * @GeneratedValue(strategy="SEQUENCE")
              * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
              */
-            protected $id = null;
+            protected int|null $id = null;
             // ...
         }
 
@@ -448,8 +499,6 @@ the above example with ``allocationSize=100`` Doctrine ORM would only
 need to access the sequence once to generate the identifiers for
 100 new entities.
 
-*The default allocationSize for a @SequenceGenerator is currently 10.*
-
 .. caution::
 
     The allocationSize is detected by SchemaTool and
@@ -472,11 +521,12 @@ need to access the sequence once to generate the identifiers for
 Composite Keys
 ~~~~~~~~~~~~~~
 
-With Doctrine ORM you can use composite primary keys, using ``@Id`` on more then
-one column. Some restrictions exist opposed to using a single identifier in
-this case: The use of the ``@GeneratedValue`` annotation is not supported,
-which means you can only use composite keys if you generate the primary key
-values yourself before calling ``EntityManager#persist()`` on the entity.
+With Doctrine ORM you can use composite primary keys, using ``#[Id]`` on
+more than one column. Some restrictions exist opposed to using a single
+identifier in this case: The use of the ``#[GeneratedValue]`` attribute
+is not supported, which means you can only use composite keys if you
+generate the primary key values yourself before calling
+``EntityManager#persist()`` on the entity.
 
 More details on composite primary keys are discussed in a :doc:`dedicated tutorial
 <../tutorials/composite-primary-keys>`.
@@ -492,7 +542,8 @@ needs to be done explicitly using ticks in the definition.
 .. code-block:: php
 
     <?php
-    /** @Column(name="`number`", type="integer") */
+
+    #[Column(name: '`number`', type: 'integer')]
     private $number;
 
 Doctrine will then quote this column name in all SQL statements

docs/en/reference/batch-processing.rst

@@ -18,8 +18,16 @@ especially what the strategies presented here provide help with.
 
 .. note::
 
-    Having an SQL logger enabled when processing batches can have a serious impact on performance and resource usage.
-    To avoid that you should disable it in the DBAL configuration:
+    Having an SQL logger enabled when processing batches can have a
+    serious impact on performance and resource usage.
+    To avoid that, you should use a PSR logger implementation that can be
+    disabled at runtime.
+    For example, with Monolog, you can use ``Logger::pushHandler()``
+    to push a ``NullHandler`` to the logger instance, and then pop it
+    when you need to enable logging again.
+
+    With DBAL 2, you can disable the SQL logger like below:
+
 .. code-block:: php
 
     <?php
@@ -84,7 +92,7 @@ with the batching strategy that was already used for bulk inserts:
 
     <?php
     $batchSize = 20;
-    $i = 1;
+    $i = 0;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     foreach ($q->toIterable() as $user) {
         $user->increaseCredit();
@@ -143,7 +151,7 @@ The following example shows how to do this:
 
     <?php
     $batchSize = 20;
-    $i = 1;
+    $i = 0;
     $q = $em->createQuery('select u from MyProject\Model\User u');
     foreach($q->toIterable() as $row) {
         $em->remove($row);
@@ -186,6 +194,3 @@ problems using the following approach:
     Iterating results is not possible with queries that
     fetch-join a collection-valued association. The nature of such SQL
     result sets is not suitable for incremental hydration.
-
-
-

docs/en/reference/best-practices.rst

@@ -74,11 +74,13 @@ collections in entities in the constructor. Example:
     <?php
     namespace MyProject\Model;
     use Doctrine\Common\Collections\ArrayCollection;
-    
+
     class User {
-        private $addresses;
-        private $articles;
-    
+        /** @var Collection<int, Address> */
+        private Collection $addresses;
+        /** @var Collection<int, Article> */
+        private Collection $articles;
+
         public function __construct() {
             $this->addresses = new ArrayCollection;
             $this->articles = new ArrayCollection;

docs/en/reference/caching.rst

@@ -109,8 +109,9 @@ Metadata Cache
 ~~~~~~~~~~~~~~
 
 Your class metadata can be parsed from a few different sources like
-YAML, XML, Annotations, etc. Instead of parsing this information on
-each request we should cache it using one of the cache drivers.
+YAML, XML, Attributes, Annotations etc. Instead of parsing this
+information on each request we should cache it using one of the cache
+drivers.
 
 Just like the query and result cache we need to configure it
 first.
@@ -199,5 +200,3 @@ not letting your users' requests populate the cache.
 
 You can read more about cache slams
 `in this blog post <http://notmysock.org/blog/php/user-cache-timebomb.html>`_.
-
-

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

@@ -49,10 +49,9 @@ This policy can be configured as follows:
 .. code-block:: php
 
     <?php
-    /**
-     * @Entity
-     * @ChangeTrackingPolicy("DEFERRED_EXPLICIT")
-     */
+
+    #[Entity]
+    #[ChangeTrackingPolicy('DEFERRED_EXPLICIT')]
     class User
     {
         // ...
@@ -64,7 +63,7 @@ Notify
 .. note::
 
     The notify change tracking policy is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8383>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
 
 This policy is based on the assumption that the entities notify
 interested listeners of changes to their properties. For that
@@ -78,18 +77,16 @@ follows:
     <?php
     use Doctrine\Persistence\NotifyPropertyChanged,
         Doctrine\Persistence\PropertyChangedListener;
-    
-    /**
-     * @Entity
-     * @ChangeTrackingPolicy("NOTIFY")
-     */
+
+    #[Entity]
+    #[ChangeTrackingPolicy('NOTIFY')]
     class MyEntity implements NotifyPropertyChanged
     {
         // ...
-    
-        private $_listeners = array();
-    
-        public function addPropertyChangedListener(PropertyChangedListener $listener)
+
+        private array $_listeners = array();
+
+        public function addPropertyChangedListener(PropertyChangedListener $listener): void
         {
             $this->_listeners[] = $listener;
         }
@@ -104,12 +101,12 @@ behaviour:
 
     <?php
     // ...
-    
+
     class MyEntity implements NotifyPropertyChanged
     {
         // ...
-    
-        protected function _onPropertyChanged($propName, $oldValue, $newValue)
+
+        protected function _onPropertyChanged($propName, $oldValue, $newValue): void
         {
             if ($this->_listeners) {
                 foreach ($this->_listeners as $listener) {
@@ -117,8 +114,8 @@ behaviour:
                 }
             }
         }
-    
-        public function setData($data)
+
+        public function setData($data): void
         {
             if ($data != $this->data) {
                 $this->_onPropertyChanged('data', $this->data, $data);
@@ -134,18 +131,18 @@ 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 
+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)
+        public function setEmbeddable(MyValueObject $embeddable): void
         {
             if (!$embeddable->equals($this->embeddable)) {
                 // notice the entityField.embeddableField notation for referencing the property
@@ -178,5 +175,3 @@ The positive point and main advantage of this policy is its
 effectiveness. It has the best performance characteristics of the 3
 policies with larger units of work and a flush() operation is very
 cheap when nothing has changed.
-
-

docs/en/reference/configuration.rst

@@ -41,86 +41,80 @@ access point to ORM functionality provided by Doctrine.
     // bootstrap.php
     require_once "vendor/autoload.php";
 
-    use Doctrine\ORM\Tools\Setup;
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
 
-    $paths = array("/path/to/entity-files");
+    $paths = ['/path/to/entity-files'];
     $isDevMode = false;
 
     // the connection configuration
-    $dbParams = array(
+    $dbParams = [
         'driver'   => 'pdo_mysql',
         'user'     => 'root',
         'password' => '',
         'dbname'   => 'foo',
-    );
+    ];
 
-    $config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $config = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $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);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $paths = ['/path/to/xml-mappings'];
+    $config = ORMSetup::createXMLMetadataConfiguration($paths, $isDevMode);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 Or if you prefer YAML:
 
 .. code-block:: php
 
     <?php
-    $paths = array("/path/to/yml-mappings");
-    $config = Setup::createYAMLMetadataConfiguration($paths, $isDevMode);
-    $entityManager = EntityManager::create($dbParams, $config);
+    $paths = ['/path/to/yml-mappings'];
+    $config = ORMSetup::createYAMLMetadataConfiguration($paths, $isDevMode);
+    $connection = DriverManager::getConnection($dbParams, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     If you want to use yml mapping you should add yaml dependency to your `composer.json`:
-    
+
     ::
-    
+
         "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.
 
-If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration <reference/advanced-configuration>` section.
+.. note::
+
+    In order to have ``ORMSetup`` configure the cache automatically, the library ``symfony/cache``
+    has to be installed as a dependency.
+
+If you want to configure Doctrine in more detail, take a look at the :doc:`Advanced Configuration </reference/advanced-configuration>` section.
 
 .. note::
 
     You can learn more about the database connection configuration in the
-    `Doctrine DBAL connection configuration reference <https://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html>`_.
+    `Doctrine DBAL connection configuration reference <https://docs.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/configuration.html>`_.
 
 Setting up the Commandline Tool
 -------------------------------
 
 Doctrine ships with a number of command line tools that are very helpful
-during development. You can call this command from the Composer binary
-directory:
-
-.. code-block:: sh
-
-    $ php vendor/bin/doctrine
-
-You need to register your applications EntityManager to the console tool
-to make use of the tasks by creating a ``cli-config.php`` file with the
-following content:
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Tools\Console\ConsoleRunner;
-
-    // replace with file to your own project bootstrap
-    require_once 'bootstrap.php';
-
-    // replace with mechanism to retrieve EntityManager in your app
-    $entityManager = GetEntityManager();
-
-    return ConsoleRunner::createHelperSet($entityManager);
+during development. In order to make use of them, create an executable PHP
+script in your project as described in the
+:doc:`tools chapter <../reference/tools>`.

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

@@ -180,10 +180,10 @@ not need to lazy load the association with another query.
 
     Doctrine allows you to walk all the associations between
     all the objects in your domain model. Objects that were not already
-    loaded from the database are replaced with lazy load proxy
-    instances. Non-loaded Collections are also replaced by lazy-load
+    loaded from the database are replaced with lazy-loading proxy
+    instances. Non-loaded Collections are also replaced by lazy-loading
     instances that fetch all the contained objects upon first access.
-    However relying on the lazy-load mechanism leads to many small
+    However relying on the lazy-loading mechanism leads to many small
     queries executed against the database, which can significantly
     affect the performance of your application. **Fetch Joins** are the
     solution to hydrate most or all of the entities that you need in a
@@ -319,11 +319,11 @@ With Nested Conditions in WHERE Clause:
 
     <?php
     $query = $em->createQuery('SELECT u FROM ForumUser u WHERE (u.username = :name OR u.username = :name2) AND u.id = :id');
-    $query->setParameters(array(
+    $query->setParameters([
         'name' => 'Bob',
         'name2' => 'Alice',
         'id' => 321,
-    ));
+    ]);
     $users = $query->getResult(); // array of ForumUser objects
 
 With COUNT DISTINCT:
@@ -464,6 +464,11 @@ hierarchies:
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF Doctrine\Tests\Models\Company\CompanyEmployee');
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u INSTANCE OF ?1');
     $query = $em->createQuery('SELECT u FROM Doctrine\Tests\Models\Company\CompanyPerson u WHERE u NOT INSTANCE OF ?1');
+    $query->setParameter(0, $em->getClassMetadata(CompanyEmployee::class));
+
+.. note::
+    To use a class as parameter, you have to bind its class metadata:
+    ``$query->setParameter(0, $em->getClassMetadata(CompanyEmployee::class);``.
 
 Get all users visible on a given website that have chosen certain gender:
 
@@ -670,11 +675,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
 -------------------
@@ -718,7 +735,7 @@ clauses:
 -  ``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.
@@ -782,7 +799,7 @@ You can register custom DQL functions in your ORM Configuration:
     $config->addCustomNumericFunction($name, $class);
     $config->addCustomDatetimeFunction($name, $class);
 
-    $em = EntityManager::create($dbParams, $config);
+    $em = new EntityManager($connection, $config);
 
 The functions have to return either a string, numeric or datetime
 value depending on the registered function type. As an example we
@@ -794,8 +811,8 @@ classes have to implement the base class :
     <?php
     namespace MyProject\Query\AST;
 
-    use \Doctrine\ORM\Query\AST\Functions\FunctionNode;
-    use \Doctrine\ORM\Query\Lexer;
+    use Doctrine\ORM\Query\AST\Functions\FunctionNode;
+    use Doctrine\ORM\Query\TokenType;
 
     class MysqlFloor extends FunctionNode
     {
@@ -810,12 +827,12 @@ classes have to implement the base class :
 
         public function parse(\Doctrine\ORM\Query\Parser $parser)
         {
-            $parser->match(Lexer::T_IDENTIFIER);
-            $parser->match(Lexer::T_OPEN_PARENTHESIS);
+            $parser->match(TokenType::T_IDENTIFIER);
+            $parser->match(TokenType::T_OPEN_PARENTHESIS);
 
             $this->simpleArithmeticExpression = $parser->SimpleArithmeticExpression();
 
-            $parser->match(Lexer::T_CLOSE_PARENTHESIS);
+            $parser->match(TokenType::T_CLOSE_PARENTHESIS);
         }
     }
 
@@ -852,36 +869,26 @@ scenario it is a generic Person and Employee example:
     <?php
     namespace Entities;
 
-    /**
-     * @Entity
-     * @InheritanceType("SINGLE_TABLE")
-     * @DiscriminatorColumn(name="discr", type="string")
-     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
-     */
+    #[Entity]
+    #[InheritanceType('SINGLE_TABLE')]
+    #[DiscriminatorColumn(name: 'discr', type: 'string')]
+    #[DiscriminatorMap(['person' => 'Person', 'employee' => 'Employee'])]
     class Person
     {
-        /**
-         * @Id @Column(type="integer")
-         * @GeneratedValue
-         */
-        protected $id;
+        #[Id, Column(type: 'integer')]
+        #[GeneratedValue]
+        protected int|null $id = null;
 
-        /**
-         * @Column(type="string", length=50)
-         */
-        protected $name;
+        #[Column(type: 'string', length: 50)]
+        protected string $name;
 
         // ...
     }
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class Employee extends Person
     {
-        /**
-         * @Column(type="string", length=50)
-         */
+        #[Column(type: 'string', length: 50)]
         private $department;
 
         // ...
@@ -947,12 +954,11 @@ table, you just need to change the inheritance type from
 .. code-block:: php
 
     <?php
-    /**
-     * @Entity
-     * @InheritanceType("JOINED")
-     * @DiscriminatorColumn(name="discr", type="string")
-     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
-     */
+
+    #[Entity]
+    #[InheritanceType('JOINED')]
+    #[DiscriminatorColumn(name: 'discr', type: 'string')]
+    #[DiscriminatorMap(['person' => 'Person', 'employee' => 'Employee'])]
     class Person
     {
         // ...
@@ -997,7 +1003,7 @@ The Query class
 ---------------
 
 An instance of the ``Doctrine\ORM\Query`` class represents a DQL
-query. You create a Query instance be calling
+query. You create a Query instance by calling
 ``EntityManager#createQuery($dql)``, passing the DQL query string.
 Alternatively you can create an empty ``Query`` instance and invoke
 ``Query#setDQL($dql)`` afterwards. Here are some examples:
@@ -1014,58 +1020,146 @@ Alternatively you can create an empty ``Query`` instance and invoke
     $q = $em->createQuery();
     $q->setDQL('select u from MyProject\Model\User u');
 
-Query Result Formats
-~~~~~~~~~~~~~~~~~~~~
+Query Result Formats (Hydration Modes)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The format in which the result of a DQL SELECT query is returned
-can be influenced by a so-called ``hydration mode``. A hydration
-mode specifies a particular way in which a SQL result set is
-transformed. Each hydration mode has its own dedicated method on
-the Query class. Here they are:
+The way in which the SQL result set of a DQL SELECT query is transformed
+to PHP is determined by the so-called "hydration mode".
 
+``getResult()``
+^^^^^^^^^^^^^^^
 
--  ``Query#getResult()``: Retrieves a collection of objects. The
-   result is either a plain collection of objects (pure) or an array
-   where the objects are nested in the result rows (mixed).
--  ``Query#getSingleResult()``: Retrieves a single object. If the
-   result contains more than one object, an ``NonUniqueResultException``
-   is thrown. If the result contains no objects, an ``NoResultException``
-   is thrown. The pure/mixed distinction does not apply.
--  ``Query#getOneOrNullResult()``: Retrieve a single object. If the
-   result contains more than one object, a ``NonUniqueResultException``
-   is thrown. If no object is found null will be returned.
--  ``Query#getArrayResult()``: Retrieves an array graph (a nested
-   array) that is largely interchangeable with the object graph
-   generated by ``Query#getResult()`` for read-only purposes.
+Retrieves a collection of objects. The result is either a plain collection of objects (pure) or an array
+where the objects are nested in the result rows (mixed):
 
-    .. note::
+.. code-block:: php
 
-        An array graph can differ from the corresponding object
-        graph in certain scenarios due to the difference of the identity
-        semantics between arrays and objects.
+    <?php
+    use Doctrine\ORM\AbstractQuery;
 
+    $query = $em->createQuery('SELECT u FROM User u');
+    $users = $query->getResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_OBJECT);
 
+- Objects fetched in a FROM clause are returned as a Set, that means every
+  object is only ever included in the resulting array once. This is the case
+  even when using JOIN or GROUP BY in ways that return the same row for an
+  object multiple times. If the hydrator sees the same object multiple times,
+  then it makes sure it is only returned once.
 
--  ``Query#getScalarResult()``: Retrieves a flat/rectangular result
-   set of scalar values that can contain duplicate data. The
-   pure/mixed distinction does not apply.
--  ``Query#getSingleScalarResult()``: Retrieves a single scalar
-   value from the result returned by the dbms. If the result contains
-   more than a single scalar value, an exception is thrown. The
-   pure/mixed distinction does not apply.
+- If an object is already in memory from a previous query of any kind, then
+  then the previous object is used, even if the database may contain more
+  recent data. This even happens if the previous object is still an unloaded proxy.
 
-Instead of using these methods, you can alternatively use the
-general-purpose method
-``Query#execute(array $params = array(), $hydrationMode = Query::HYDRATE_OBJECT)``.
-Using this method you can directly supply the hydration mode as the
-second parameter via one of the Query constants. In fact, the
-methods mentioned earlier are just convenient shortcuts for the
-execute method. For example, the method ``Query#getResult()``
-internally invokes execute, passing in ``Query::HYDRATE_OBJECT`` as
-the hydration mode.
+``getArrayResult()``
+^^^^^^^^^^^^^^^^^^^^
 
-The use of the methods mentioned earlier is generally preferred as
-it leads to more concise code.
+Retrieves an array graph (a nested array) for read-only purposes.
+
+.. note::
+
+    An array graph can differ from the corresponding object
+    graph in certain scenarios due to the difference of the identity
+    semantics between arrays and objects.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getArrayResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_ARRAY);
+
+``getScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a flat/rectangular result set of scalar values that can contain duplicate data. The
+pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getScalarResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_SCALAR);
+
+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 the result rows.
+
+``getSingleScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single scalar value from the result returned by the database. If the result contains
+more than a single scalar value, a ``NonUniqueResultException`` is thrown. The pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT COUNT(u.id) FROM User u');
+    $numUsers = $query->getSingleScalarResult();
+    // same as:
+    $numUsers = $query->getResult(AbstractQuery::HYDRATE_SINGLE_SCALAR);
+
+``getSingleColumnResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves an array from a one-dimensional array of scalar values:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT a.id FROM User u');
+    $ids = $query->getSingleColumnResult();
+    // same as:
+    $ids = $query->getResult(AbstractQuery::HYDRATE_SCALAR_COLUMN);
+
+``getSingleResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If the result contains no objects, a ``NoResultException`` is thrown. The pure/mixed distinction does not apply.
+
+``getOneOrNullResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If no object is found, ``null`` will be returned.
+
+Custom Hydration Modes
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can easily add your own custom hydration modes by first
+creating a class which extends ``AbstractHydrator``:
+
+.. code-block:: php
+
+    <?php
+    namespace MyProject\Hydrators;
+
+    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
+
+    class CustomHydrator extends AbstractHydrator
+    {
+        protected function _hydrateAll()
+        {
+            return $this->_stmt->fetchAllAssociative();
+        }
+    }
+
+Next you just need to add the class to the ORM configuration:
+
+.. code-block:: php
+
+    <?php
+    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
+
+Now the hydrator is ready to be used in your queries:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT u FROM CmsUser u');
+    $results = $query->getResult('CustomHydrator');
 
 Pure and Mixed Results
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -1169,166 +1263,6 @@ will return the rows iterating the different top-level entities.
         [2] => Object (User)
         [3] => Object (Group)
 
-
-Hydration Modes
-~~~~~~~~~~~~~~~
-
-Each of the Hydration Modes makes assumptions about how the result
-is returned to user land. You should know about all the details to
-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_SCALAR_COLUMN``
-
-Object Hydration
-^^^^^^^^^^^^^^^^
-
-Object hydration hydrates the result set into the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_OBJECT);
-
-Sometimes the behavior in the object hydrator can be confusing, which is
-why we are listing as many of the assumptions here for reference:
-
-- Objects fetched in a FROM clause are returned as a Set, that means every
-  object is only ever included in the resulting array once. This is the case
-  even when using JOIN or GROUP BY in ways that return the same row for an
-  object multiple times. If the hydrator sees the same object multiple times,
-  then it makes sure it is only returned once.
-
-- If an object is already in memory from a previous query of any kind, then
-  then the previous object is used, even if the database may contain more
-  recent data. Data from the database is discarded. This even happens if the
-  previous object is still an unloaded proxy.
-
-This list might be incomplete.
-
-Array Hydration
-^^^^^^^^^^^^^^^
-
-You can run the same query with array hydration and the result set
-is hydrated into an array that represents the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_ARRAY);
-
-You can use the ``getArrayResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $users = $query->getArrayResult();
-
-Scalar Hydration
-^^^^^^^^^^^^^^^^
-
-If you want to return a flat rectangular result set instead of an
-object graph you can use scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_SCALAR);
-    echo $users[0]['u_id'];
-
-The following assumptions are made about selected fields using
-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
-   the result rows.
-
-Single Scalar Hydration
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a query which returns just a single scalar value you can use
-single scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT COUNT(a.id) FROM CmsUser u LEFT JOIN u.articles a WHERE u.username = ?1 GROUP BY u.id');
-    $query->setParameter(1, 'jwage');
-    $numArticles = $query->getResult(Query::HYDRATE_SINGLE_SCALAR);
-
-You can use the ``getSingleScalarResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?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
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can easily add your own custom hydration modes by first
-creating a class which extends ``AbstractHydrator``:
-
-.. code-block:: php
-
-    <?php
-    namespace MyProject\Hydrators;
-
-    use Doctrine\DBAL\FetchMode;
-    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
-
-    class CustomHydrator extends AbstractHydrator
-    {
-        protected function _hydrateAll()
-        {
-            return $this->_stmt->fetchAll(FetchMode::FETCH_ASSOC);
-        }
-    }
-
-Next you just need to add the class to the ORM configuration:
-
-.. code-block:: php
-
-    <?php
-    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
-
-Now the hydrator is ready to be used in your queries:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $results = $query->getResult('CustomHydrator');
-
 Iterating Large Result Sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1336,8 +1270,8 @@ There are situations when a query you want to execute returns a
 very large result-set that needs to be processed. All the
 previously described hydration modes completely load a result-set
 into memory which might not be feasible with large result sets. See
-the `Batch Processing <batch-processing.html>`_ section on details how
-to iterate large result sets.
+the :doc:`Batch Processing </reference/batch-processing>` section on
+details how to iterate large result sets.
 
 Functions
 ~~~~~~~~~
@@ -1381,7 +1315,7 @@ Result Cache API:
     $query->setResultCacheDriver(new ApcCache());
 
     $query->useResultCache(true)
-          ->setResultCacheLifeTime($seconds = 3600);
+          ->setResultCacheLifeTime(3600);
 
     $result = $query->getResult(); // cache miss
 
@@ -1392,7 +1326,7 @@ Result Cache API:
     $result = $query->getResult(); // saved in given result cache id.
 
     // or call useResultCache() with all parameters:
-    $query->useResultCache(true, $seconds = 3600, 'my_query_result');
+    $query->useResultCache(true, 3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
@@ -1425,7 +1359,7 @@ userland:
    reloading this data. Partially loaded objects have to be passed to
    ``EntityManager::refresh()`` if they are to be reloaded fully from
    the database. This query hint is deprecated and will be removed
-   in the future (`Details <https://github.com/doctrine/orm/issues/8471>`_)
+   in the future (\ `Details <https://github.com/doctrine/orm/issues/8471>`_)
 -  ``Query::HINT_REFRESH`` - This query is used internally by
    ``EntityManager::refresh()`` and can be used in userland as well.
    If you specify this hint and a query returns the data for an entity
@@ -1457,7 +1391,7 @@ several methods to interact with it:
 
 -  ``Query::setQueryCacheDriver($driver)`` - Allows to set a Cache
    instance
--  ``Query::setQueryCacheLifeTime($seconds = 3600)`` - Set lifetime
+-  ``Query::setQueryCacheLifeTime($seconds)`` - Set lifetime
    of the query caching.
 -  ``Query::expireQueryCache($bool)`` - Enforce the expiring of the
    query cache if set to true.
@@ -1519,6 +1453,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
 ----
 
@@ -1712,7 +1648,7 @@ Literal Values
 .. code-block:: php
 
     Literal     ::= string | char | integer | float | boolean
-    InParameter ::= Literal | InputParameter
+    InParameter ::= ArithmeticExpression | InputParameter
 
 Input Parameter
 ~~~~~~~~~~~~~~~
@@ -1827,5 +1763,3 @@ Functions
             "LOWER" "(" StringPrimary ")" |
             "UPPER" "(" StringPrimary ")" |
             "IDENTITY" "(" SingleValuedAssociationPathExpression {"," string} ")"
-
-

docs/en/reference/faq.rst

@@ -13,10 +13,10 @@ Database Schema
 How do I set the charset and collation for MySQL tables?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can't set these values inside the annotations, yml or xml mapping files. To make a database
-work with the default charset and collation you should configure MySQL to use it as default charset,
-or create the database with charset and collation details. This way they get inherited to all newly
-created database tables and columns.
+In your mapping configuration, the column definition (for example, the
+``#[Column]`` attribute) has an ``options`` parameter where you can specify
+the ``charset`` and ``collation``. The default values are ``utf8`` and
+``utf8_unicode_ci``, respectively.
 
 Entity Classes
 --------------
@@ -32,11 +32,12 @@ upon insert:
 
     class User
     {
-        const STATUS_DISABLED = 0;
-        const STATUS_ENABLED = 1;
+        private const STATUS_DISABLED = 0;
+        private const STATUS_ENABLED = 1;
 
-        private $algorithm = "sha1";
-        private $status = self:STATUS_DISABLED;
+        private string $algorithm = "sha1";
+        /** @var self::STATUS_* */
+        private int $status = self::STATUS_DISABLED;
     }
 
 .
@@ -100,7 +101,7 @@ The many-to-many association is only supporting foreign keys in the table defini
 To work with many-to-many tables containing extra columns you have to use the
 foreign keys as primary keys feature of Doctrine ORM.
 
-See :doc:`the tutorial on composite primary keys for more information<../tutorials/composite-primary-keys>`.
+See :doc:`the tutorial on composite primary keys for more information <../tutorials/composite-primary-keys>`.
 
 
 How can i paginate fetch-joined collections?

docs/en/reference/filters.rst

@@ -28,10 +28,11 @@ table alias of the SQL table of the entity.
     In the case of joined or single table inheritance, you always get passed the ClassMetadata of the
     inheritance root. This is necessary to avoid edge cases that would break the SQL when applying the filters.
 
-Parameters for the query should be set on the filter object by
-``SQLFilter#setParameter()``. Only parameters set via this function can be used
-in filters.  The ``SQLFilter#getParameter()`` function takes care of the
-proper quoting of parameters.
+For the filter to correctly function, the following rules must be followed. Failure to do so will lead to unexpected results from the query cache.
+  1. Parameters for the query should be set on the filter object by ``SQLFilter#setParameter()`` before the filter is used by the ORM ( i.e. do not set parameters inside ``SQLFilter#addFilterConstraint()`` function ).
+  2. The filter must be deterministic. Don't change the values base on external inputs.
+
+The ``SQLFilter#getParameter()`` function takes care of the proper quoting of parameters.
 
 .. code-block:: php
 
@@ -42,7 +43,7 @@ proper quoting of parameters.
 
     class MyLocaleFilter extends SQLFilter
     {
-        public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias)
+        public function addFilterConstraint(ClassMetadata $targetEntity, $targetTableAlias): string
         {
             // Check if the entity implements the LocalAware interface
             if (!$targetEntity->reflClass->implementsInterface('LocaleAware')) {
@@ -92,3 +93,34 @@ object.
     want to refresh or reload an object after having modified a filter or the
     FilterCollection, then you should clear the EntityManager and re-fetch your
     entities, having the new rules for filtering applied.
+
+
+Suspending/Restoring Filters
+----------------------------
+When a filter is disabled, the instance is fully deleted and all the filter
+parameters previously set are lost. Then, if you enable it again, a new filter
+is created without the previous filter parameters. If you want to keep a filter
+(in order to use it later) but temporary disable it, you'll need to use the
+``FilterCollection#suspend($name)`` and ``FilterCollection#restore($name)``
+methods instead.
+
+.. code-block:: php
+
+    <?php
+    $filter = $em->getFilters()->enable("locale");
+    $filter->setParameter('locale', 'en');
+
+    // Temporary suspend the filter
+    $filter = $em->getFilters()->suspend("locale");
+
+    // Do things
+
+    // Then restore it, the locale parameter will still be set
+    $filter = $em->getFilters()->restore("locale");
+
+.. warning::
+    If you enable a previously disabled filter, doctrine will create a new
+    one without keeping any of the previously parameter set with
+    ``SQLFilter#setParameter()`` or ``SQLFilter#getParameterList()``. If you
+    want to restore the previously disabled filter instead, you must use the
+    ``FilterCollection#restore($name)`` method.

docs/en/reference/improving-performance.rst

@@ -45,8 +45,7 @@ in scenarios where data is loaded for read-only purposes.
 Read-Only Entities
 ------------------
 
-You can mark entities as read only (See metadata mapping
-references for details).
+You can mark entities as read only. For details, see :ref:`attrref_entity`
 
 This means that the entity marked as read only is never considered for updates.
 During flush on the EntityManager these entities are skipped even if properties
@@ -55,8 +54,6 @@ changed.
 Read-Only allows to persist new entities of a kind and remove existing ones,
 they are just not considered for updates.
 
-See :ref:`annref_entity`
-
 You can also explicitly mark individual entities read only directly on the
 UnitOfWork via a call to ``markReadOnly()``:
 
@@ -94,7 +91,7 @@ Apply Best Practices
 A lot of the points mentioned in the Best Practices chapter will
 also positively affect the performance of Doctrine.
 
-See :doc:`Best Practices <reference/best-practices>`
+See :doc:`Best Practices </reference/best-practices>`
 
 Change Tracking policies
 ------------------------

docs/en/reference/inheritance-mapping.rst

@@ -1,6 +1,9 @@
 Inheritance Mapping
 ===================
 
+This chapter explains the available options for mapping class
+hierarchies.
+
 Mapped Superclasses
 -------------------
 
@@ -12,19 +15,52 @@ is common to multiple entity classes.
 
 Mapped superclasses, just as regular, non-mapped classes, can
 appear in the middle of an otherwise mapped inheritance hierarchy
-(through Single Table Inheritance or Class Table Inheritance).
+(through Single Table Inheritance or Class Table Inheritance). They
+are not query-able, and need not have an ``#[Id]`` property.
+
+No database table will be created for a mapped superclass itself,
+only for entity classes inheriting from it. That  implies that a
+mapped superclass cannot be the ``targetEntity`` in associations.
+
+In other words, a mapped superclass can use unidirectional One-To-One
+and Many-To-One associations where it is the owning side.
+Many-To-Many associations are only possible if the mapped
+superclass is only used in exactly one entity at the moment. For further
+support of inheritance, the single or joined table inheritance features
+have to be used.
 
 .. note::
 
-    A mapped superclass cannot be an entity, it is not query-able and
-    persistent relationships defined by a mapped superclass must be
-    unidirectional (with an owning side only). This means that One-To-Many
-    associations are not possible on a mapped superclass at all.
-    Furthermore Many-To-Many associations are only possible if the
-    mapped superclass is only used in exactly one entity at the moment.
-    For further support of inheritance, the single or
-    joined table inheritance features have to be used.
+    One-To-Many associations are not generally possible on a mapped
+    superclass, since they require the "many" side to hold the foreign
+    key.
 
+    It is, however, possible to use the :doc:`ResolveTargetEntityListener </cookbook/resolve-target-entity-listener>`
+    to replace references to a mapped superclass with an entity class at runtime.
+    As long as there is only one entity subclass inheriting from the mapped
+    superclass and all references to the mapped superclass are resolved to that
+    entity class at runtime, the mapped superclass *can* use One-To-Many associations
+    and be named as the ``targetEntity`` on the owning sides.
+
+.. warning::
+
+    At least when using attributes or annotations to specify your mapping,
+    it *seems* as if you could inherit from a base class that is neither
+    an entity nor a mapped superclass, but has properties with mapping configuration
+    on them that would also be used in the inheriting class.
+
+    This, however, is due to how the corresponding mapping
+    drivers work and what the PHP reflection API reports for inherited fields.
+
+    Such a configuration is explicitly not supported. To give just one example,
+    it will break for ``private`` properties.
+
+.. note::
+
+    You may be tempted to use traits to mix mapped fields or relationships
+    into your entity classes to circumvent some of the limitations of
+    mapped superclasses. Before doing that, please read the section on traits
+    in the :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
 
 Example:
 
@@ -38,38 +74,36 @@ Example:
     use Doctrine\ORM\Mapping\MappedSuperclass;
     use Doctrine\ORM\Mapping\Entity;
 
-    /** @MappedSuperclass */
+    #[MappedSuperclass]
     class Person
     {
-        /** @Column(type="integer") */
-        protected $mapped1;
-        /** @Column(type="string") */
-        protected $mapped2;
-        /**
-         * @OneToOne(targetEntity="Toothbrush")
-         * @JoinColumn(name="toothbrush_id", referencedColumnName="id")
-         */
-        protected $toothbrush;
+        #[Column(type: 'integer')]
+        protected int $mapped1;
+        #[Column(type: 'string')]
+        protected string $mapped2;
+        #[OneToOne(targetEntity: Toothbrush::class)]
+        #[JoinColumn(name: 'toothbrush_id', referencedColumnName: 'id')]
+        protected Toothbrush|null $toothbrush = null;
 
         // ... more fields and methods
     }
-    
-    /** @Entity */
+
+    #[Entity]
     class Employee extends Person
     {
-        /** @Id @Column(type="integer") */
-        private $id;
-        /** @Column(type="string") */
-        private $name;
-    
+        #[Id, Column(type: 'integer')]
+        private int|null $id = null;
+        #[Column(type: 'string')]
+        private string $name;
+
         // ... more fields and methods
     }
 
-    /** @Entity */
+    #[Entity]
     class Toothbrush
     {
-        /** @Id @Column(type="integer") */
-        private $id;
+        #[Id, Column(type: 'integer')]
+        private int|null $id = null;
 
         // ... more fields and methods
     }
@@ -79,31 +113,106 @@ like this (this is for SQLite):
 
 .. code-block:: sql
 
-    CREATE TABLE EntitySubClass (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, related1_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
+    CREATE TABLE Employee (mapped1 INTEGER NOT NULL, mapped2 TEXT NOT NULL, id INTEGER NOT NULL, name TEXT NOT NULL, toothbrush_id INTEGER DEFAULT NULL, PRIMARY KEY(id))
 
 As you can see from this DDL snippet, there is only a single table
 for the entity subclass. All the mappings from the mapped
 superclass were inherited to the subclass as if they had been
 defined on that class directly.
 
+Entity Inheritance
+------------------
+
+As soon as one entity class inherits from another entity class, either
+directly, with a mapped superclass or other unmapped (also called
+"transient") classes in between, these entities form an inheritance
+hierarchy. The topmost entity class in this hierarchy is called the
+root entity, and the hierarchy includes all entities that are
+descendants of this root entity.
+
+On the root entity class, ``#[InheritanceType]``,
+``#[DiscriminatorColumn]`` and ``#[DiscriminatorMap]`` must be specified.
+
+``#[InheritanceType]`` specifies one of the two available inheritance
+mapping strategies that are explained in the following sections.
+
+``#[DiscriminatorColumn]`` designates the so-called discriminator column.
+This is an extra column in the table that keeps information about which
+type from the hierarchy applies for a particular database row.
+
+``#[DiscriminatorMap]`` declares the possible values for the discriminator
+column and maps them to class names in the hierarchy. This discriminator map
+has to declare all non-abstract entity classes that exist in that particular
+inheritance hierarchy. That includes the root as well as any intermediate
+entity classes, given they are not abstract.
+
+The names of the classes in the discriminator map do not need to be fully
+qualified if the classes are contained in the same namespace as the entity
+class on which the discriminator map is applied.
+
+If no discriminator map is provided, then the map is generated
+automatically. The automatically generated discriminator map contains the
+lowercase short name of each class as key.
+
+.. note::
+
+    Automatically generating the discriminator map is very expensive
+    computation-wise. The mapping driver has to provide all classes
+    for which mapping configuration exists, and those have to be
+    loaded and checked against  the current inheritance hierarchy
+    to see if they are part of it. The resulting map, however, can be kept
+    in the metadata cache.
+
+Performance impact on to-one associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is a general performance consideration when using entity inheritance:
+If the target-entity of a many-to-one or one-to-one association is part of
+an inheritance hierarchy, it is preferable for performance reasons that it
+be a leaf entity (ie. have no subclasses).
+
+Otherwise, the ORM is currently unable to tell beforehand which entity class
+will have to be used, and so no appropriate proxy instance can be created.
+That means the referred-to entities will *always* be loaded eagerly, which
+might even propagate to relationships of these entities (in the case of
+self-referencing associations).
+
 Single Table Inheritance
 ------------------------
 
 `Single Table Inheritance <https://martinfowler.com/eaaCatalog/singleTableInheritance.html>`_
-is an inheritance mapping strategy where all classes of a hierarchy
-are mapped to a single database table. In order to distinguish
-which row represents which type in the hierarchy a so-called
-discriminator column is used.
+is an inheritance mapping strategy where all classes of a hierarchy are
+mapped to a single database table.
 
 Example:
 
 .. configuration-block::
 
-    .. code-block:: php
-    
+    .. code-block:: attribute
+
         <?php
         namespace MyProject\Model;
-        
+
+        #[Entity]
+        #[InheritanceType('SINGLE_TABLE')]
+        #[DiscriminatorColumn(name: 'discr', type: 'string')]
+        #[DiscriminatorMap(['person' => Person::class, 'employee' => Employee::class])]
+        class Person
+        {
+            // ...
+        }
+
+        #[Entity]
+        class Employee extends Person
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
+
+        <?php
+        namespace MyProject\Model;
+
         /**
          * @Entity
          * @InheritanceType("SINGLE_TABLE")
@@ -114,7 +223,7 @@ Example:
         {
             // ...
         }
-        
+
         /**
          * @Entity
          */
@@ -124,7 +233,7 @@ Example:
         }
 
     .. code-block:: yaml
-    
+
         MyProject\Model\Person:
           type: entity
           inheritanceType: SINGLE_TABLE
@@ -134,30 +243,13 @@ Example:
           discriminatorMap:
             person: Person
             employee: Employee
-                
+
         MyProject\Model\Employee:
           type: entity
-            
-Things to note:
 
-
--  The @InheritanceType and @DiscriminatorColumn must be specified 
-   on the topmost class that is part of the mapped entity hierarchy.
--  The @DiscriminatorMap specifies which values of the
-   discriminator column identify a row as being of a certain type. In
-   the case above a value of "person" identifies a row as being of
-   type ``Person`` and "employee" identifies a row as being of type
-   ``Employee``.
--  All entity classes that is part of the mapped entity hierarchy
-   (including the topmost class) should be specified in the
-   @DiscriminatorMap. In the case above Person class included.
--  The names of the classes in the discriminator map do not need to
-   be fully qualified if the classes are contained in the same
-   namespace as the entity class on which the discriminator map is
-   applied.
--  If no discriminator map is provided, then the map is generated
-   automatically. The automatically generated discriminator map 
-   contains the lowercase short name of each class as key.
+In this example, the ``#[DiscriminatorMap]`` specifies that in the
+discriminator column, a value of "person" identifies a row as being of type
+``Person`` and employee" identifies a row as being of type ``Employee``.
 
 Design-time considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -173,17 +265,10 @@ Performance impact
 
 This strategy is very efficient for querying across all types in
 the hierarchy or for specific types. No table joins are required,
-only a WHERE clause listing the type identifiers. In particular,
+only a ``WHERE`` clause listing the type identifiers. In particular,
 relationships involving types that employ this mapping strategy are
 very performing.
 
-There is a general performance consideration with Single Table
-Inheritance: If the target-entity of a many-to-one or one-to-one 
-association is an STI entity, it is preferable for performance reasons that it 
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
-Otherwise Doctrine *CANNOT* create proxy instances
-of this entity and will *ALWAYS* load the entity eagerly.
-
 SQL Schema considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -191,7 +276,7 @@ For Single-Table-Inheritance to work in scenarios where you are
 using either a legacy database schema or a self-written database
 schema you have to make sure that all columns that are not in the
 root entity but in any of the different sub-entities has to allow
-null values. Columns that have NOT NULL constraints have to be on
+null values. Columns that have ``NOT NULL`` constraints have to be on
 the root entity of the single-table inheritance hierarchy.
 
 Class Table Inheritance
@@ -201,10 +286,11 @@ Class Table Inheritance
 is an inheritance mapping strategy where each class in a hierarchy
 is mapped to several tables: its own table and the tables of all
 parent classes. The table of a child class is linked to the table
-of a parent class through a foreign key constraint. Doctrine ORM
-implements this strategy through the use of a discriminator column
-in the topmost table of the hierarchy because this is the easiest
-way to achieve polymorphic queries with Class Table Inheritance.
+of a parent class through a foreign key constraint.
+
+The discriminator column is placed in the topmost table of the hierarchy,
+because this is the easiest way to achieve polymorphic queries with Class
+Table Inheritance.
 
 Example:
 
@@ -212,42 +298,25 @@ Example:
 
     <?php
     namespace MyProject\Model;
-    
-    /**
-     * @Entity
-     * @InheritanceType("JOINED")
-     * @DiscriminatorColumn(name="discr", type="string")
-     * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
-     */
+
+    #[Entity]
+    #[InheritanceType('JOINED')]
+    #[DiscriminatorColumn(name: 'discr', type: 'string')]
+    #[DiscriminatorMap(['person' => Person::class, 'employee' => Employee::class])]
     class Person
     {
         // ...
     }
-    
-    /** @Entity */
+
+    #[Entity]
     class Employee extends Person
     {
         // ...
     }
 
-Things to note:
-
-
--  The @InheritanceType, @DiscriminatorColumn and @DiscriminatorMap
-   must be specified on the topmost class that is part of the mapped
-   entity hierarchy.
--  The @DiscriminatorMap specifies which values of the
-   discriminator column identify a row as being of which type. In the
-   case above a value of "person" identifies a row as being of type
-   ``Person`` and "employee" identifies a row as being of type
-   ``Employee``.
--  The names of the classes in the discriminator map do not need to
-   be fully qualified if the classes are contained in the same
-   namespace as the entity class on which the discriminator map is
-   applied.
--  If no discriminator map is provided, then the map is generated
-   automatically. The automatically generated discriminator map 
-   contains the lowercase short name of each class as key.
+As before, the ``#[DiscriminatorMap]`` specifies that in the
+discriminator column, a value of "person" identifies a row as being of type
+``Person`` and "employee" identifies a row as being of type ``Employee``.
 
 .. note::
 
@@ -278,20 +347,13 @@ perform just about any query which can have a negative impact on
 performance, especially with large tables and/or large hierarchies.
 When partial objects are allowed, either globally or on the
 specific query, then querying for any type will not cause the
-tables of subtypes to be OUTER JOINed which can increase
+tables of subtypes to be ``OUTER JOIN``ed which can increase
 performance but the resulting partial objects will not fully load
 themselves on access of any subtype fields, so accessing fields of
 subtypes after such a query is not safe.
 
-There is a general performance consideration with Class Table
-Inheritance: If the target-entity of a many-to-one or one-to-one 
-association is a CTI entity, it is preferable for performance reasons that it 
-be a leaf entity in the inheritance hierarchy, (ie. have no subclasses). 
-Otherwise Doctrine *CANNOT* create proxy instances
-of this entity and will *ALWAYS* load the entity eagerly.
-
-There is also another important performance consideration that it is *NOT POSSIBLE* 
-to query for the base entity without any LEFT JOINs to the sub-types.
+There is also another important performance consideration that it is *not possible*
+to query for the base entity without any ``LEFT JOIN``s to the sub-types.
 
 SQL Schema considerations
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -309,14 +371,16 @@ column and cascading on delete.
 Overrides
 ---------
 
-Used to override a mapping for an entity field or relationship.  Can only be
-applied to an entity that extends a mapped superclass or uses a trait to
-override a relationship or field mapping defined by the mapped superclass or
-trait.
+Overrides can only be applied to entities that extend a mapped superclass or
+use traits. They are used to override a mapping for an entity field or
+relationship defined in that mapped superclass or trait.
 
-It is not possible to override attributes or associations in entity to entity
-inheritance scenarios, because this can cause unforseen edge case behavior and
-increases complexity in ORM internal classes.
+It is not supported to use overrides in entity inheritance scenarios.
+
+.. note::
+
+    When using traits, make sure not to miss the warnings given in the
+    :doc:`Limitations and Known Issues </reference/limitations-and-known-issues>` chapter.
 
 
 Association Override
@@ -330,7 +394,52 @@ Example:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+
+        #[MappedSuperclass]
+        class User
+        {
+            // other fields mapping
+
+            /** @var Collection<int, Group> */
+            #[JoinTable(name: 'users_groups')]
+            #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
+            #[ManyToMany(targetEntity: 'Group', inversedBy: 'users')]
+            protected Collection $groups;
+
+            #[ManyToOne(targetEntity: 'Address')]
+            #[JoinColumn(name: 'address_id', referencedColumnName: 'id')]
+            protected Address|null $address = null;
+        }
+
+        // admin mapping
+        namespace MyProject\Model;
+
+        #[Entity]
+        #[AssociationOverrides([
+            new AssociationOverride(
+                name: 'groups',
+                joinTable: new JoinTable(
+                    name: '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 Admin extends User
+        {
+        }
+
+    .. code-block:: annotation
 
         <?php
         // user mapping
@@ -348,14 +457,15 @@ Example:
              *  joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
              *  inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
              * )
+             * @var Collection<int, Group>
              */
-            protected $groups;
+            protected Collection $groups;
 
             /**
              * @ManyToOne(targetEntity="Address")
              * @JoinColumn(name="address_id", referencedColumnName="id")
              */
-            protected $address;
+            protected Address|null $address = null;
         }
 
         // admin mapping
@@ -475,10 +585,11 @@ Example:
 
 Things to note:
 
--  The "association override" specifies the overrides base on the property name.
--  This feature is available for all kind of associations. (OneToOne, OneToMany, ManyToOne, ManyToMany)
--  The association type *CANNOT* be changed.
--  The override could redefine the joinTables or joinColumns depending on the association type.
+-  The "association override" specifies the overrides based on the property
+ name.
+-  This feature is available for all kind of associations (OneToOne, OneToMany, ManyToOne, ManyToMany).
+-  The association type *cannot* be changed.
+-  The override could redefine the ``joinTables`` or ``joinColumns`` depending on the association type.
 -  The override could redefine ``inversedBy`` to reference more than one extended entity.
 -  The override could redefine fetch to modify the fetch strategy of the extended entity.
 
@@ -490,7 +601,51 @@ Could be used by an entity that extends a mapped superclass to override a field
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+
+        #[MappedSuperclass]
+        class User
+        {
+            #[Id, GeneratedValue, Column(type: 'integer', name: 'user_id', length: 150)]
+            protected int|null $id = null;
+
+            #[Column(name: 'user_name', nullable: true, unique: false, length: 250)]
+            protected string $name;
+
+            // other fields mapping
+        }
+
+        // guest mapping
+        namespace MyProject\Model;
+        #[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 Guest extends User
+        {
+        }
+
+    .. code-block:: annotation
 
         <?php
         // user mapping
@@ -501,10 +656,10 @@ Could be used by an entity that extends a mapped superclass to override a field
         class User
         {
             /** @Id @GeneratedValue @Column(type="integer", name="user_id", length=150) */
-            protected $id;
+            protected int|null $id = null;
 
             /** @Column(name="user_name", nullable=true, unique=false, length=250) */
-            protected $name;
+            protected string $name;
 
             // other fields mapping
         }
@@ -607,8 +762,8 @@ Could be used by an entity that extends a mapped superclass to override a field
 
 Things to note:
 
--  The "attribute override" specifies the overrides base on the property name.
--  The column type *CANNOT* be changed. If the column type is not equal you get a ``MappingException``
+-  The "attribute override" specifies the overrides based on the property name.
+-  The column type *cannot* be changed. If the column type is not equal, you get a ``MappingException``.
 -  The override can redefine all the attributes except the type.
 
 Query the Type

docs/en/reference/installation.rst

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

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

@@ -1,10 +1,10 @@
 Limitations and Known Issues
 ============================
 
-We try to make using Doctrine2 a very pleasant experience.
+We try to make using Doctrine ORM a very pleasant experience.
 Therefore we think it is very important to be honest about the
 current limitations to our users. Much like every other piece of
-software Doctrine2 is not perfect and far from feature complete.
+software the ORM is not perfect and far from feature complete.
 This section should give you an overview of current limitations of
 Doctrine ORM as well as critical known issues that you should know
 about.
@@ -130,10 +130,63 @@ included in the core of Doctrine ORM. However there are already two
 extensions out there that offer support for Nested Set with
 ORM:
 
-
 -  `Doctrine2 Hierarchical-Structural Behavior <https://github.com/guilhermeblanco/Doctrine2-Hierarchical-Structural-Behavior>`_
 -  `Doctrine2 NestedSet <https://github.com/blt04/doctrine2-nestedset>`_
 
+Using Traits in Entity Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The use of traits in entity or mapped superclasses, at least when they
+include mapping configuration or mapped fields, is currently not
+endorsed by the Doctrine project. The reasons for this are as follows.
+
+Traits were added in PHP 5.4 more than 10 years ago, but at the same time
+more than two years after the initial Doctrine 2 release and the time where
+core components were designed.
+
+In fact, this documentation mentions traits only in the context of
+:doc:`overriding field association mappings in subclasses </tutorials/override-field-association-mappings-in-subclasses>`.
+Coverage of traits in test cases is practically nonexistent.
+
+Thus, you should at least be aware that when using traits in your entity and
+mapped superclasses, you will be in uncharted terrain.
+
+.. warning::
+
+    There be dragons.
+
+From a more technical point of view, traits basically work at the language level
+as if the code contained in them had been copied into the class where the trait
+is used, and even private fields are accessible by the using class. In addition to
+that, some precedence and conflict resolution rules apply.
+
+When it comes to loading mapping configuration, the annotation and attribute drivers
+rely on PHP reflection to inspect class properties including their docblocks.
+As long as the results are consistent with what a solution *without* traits would
+have produced, this is probably fine.
+
+However, to mention known limitations, it is currently not possible to use "class"
+level `annotations <https://github.com/doctrine/orm/pull/1517>`_ or
+`attributes <https://github.com/doctrine/orm/issues/8868>`_ on traits, and attempts to
+improve parser support for traits as `here <https://github.com/doctrine/annotations/pull/102>`_
+or `there <https://github.com/doctrine/annotations/pull/63>`_ have been abandoned
+due to complexity.
+
+XML mapping configuration probably needs to completely re-configure or otherwise
+copy-and-paste configuration for fields used from traits.
+
+Mapping multiple private fields of the same name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When two classes, say a mapped superclass and an entity inheriting from it,
+both contain a ``private`` field of the same name, this will lead to a ``MappingException``.
+
+Since the fields are ``private``, both are technically separate and can contain
+different values at the same time. However, the ``ClassMetadata`` configuration used
+internally by the ORM currently refers to fields by their name only, without taking the
+class containing the field into consideration. This makes it impossible to keep separate
+mapping configuration for both fields.
+
 Known Issues
 ------------
 
@@ -177,27 +230,3 @@ MySQL with MyISAM tables
 Doctrine cannot provide atomic operations when calling ``EntityManager#flush()`` if one
 of the tables involved uses the storage engine MyISAM. You must use InnoDB or
 other storage engines that support transactions if you need integrity.
-
-Entities, Proxies and Reflection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using methods for Reflection on entities can be prone to error, when the entity
-is actually a proxy the following methods will not work correctly:
-
-- ``new ReflectionClass``
-- ``new ReflectionObject``
-- ``get_class()``
-- ``get_parent_class()``
-
-This is why ``Doctrine\Common\Util\ClassUtils`` class exists that has similar
-methods, which resolve the proxy problem beforehand.
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\Common\Util\ClassUtils;
-
-    $bookProxy = $entityManager->getReference('Acme\Book');
-
-    $reflection = ClassUtils::newReflectionClass($bookProxy);
-    $class = ClassUtils::getClass($bookProxy)¸

docs/en/reference/metadata-drivers.rst

@@ -13,11 +13,16 @@ metadata:
 
 
 -  **XML files** (XmlDriver)
--  **Class DocBlock Annotations** (AnnotationDriver)
 -  **Attributes** (AttributeDriver)
--  **YAML files** (YamlDriver)
 -  **PHP Code in files or static functions** (PhpDriver)
 
+There are also two deprecated ways to do this:
+
+-  **Class DocBlock Annotations** (AnnotationDriver)
+-  **YAML files** (YamlDriver)
+
+They will be removed in 3.0, make sure to avoid them.
+
 Something important to note about the above drivers is they are all
 an intermediate step to the same end result. The mapping
 information is populated to ``Doctrine\ORM\Mapping\ClassMetadata``
@@ -40,8 +45,9 @@ an entity.
 
 
 If you want to use one of the included core metadata drivers you need to
-configure it. If you pick the annotation driver, you will additionally
-need to install ``doctrine/annotations``. All the drivers are in the
+configure it. If you pick the annotation driver despite it being
+deprecated, you will additionally need to install
+``doctrine/annotations``. All the drivers are in the
 ``Doctrine\ORM\Mapping\Driver`` namespace:
 
 .. code-block:: php
@@ -55,69 +61,83 @@ Implementing Metadata Drivers
 
 In addition to the included metadata drivers you can very easily
 implement your own. All you need to do is define a class which
-implements the ``Driver`` interface:
+implements the ``MappingDriver`` interface:
 
 .. code-block:: php
 
     <?php
-    namespace Doctrine\ORM\Mapping\Driver;
-    
-    use Doctrine\ORM\Mapping\ClassMetadataInfo;
-    
-    interface Driver
+
+    declare(strict_types=1);
+
+    namespace Doctrine\Persistence\Mapping\Driver;
+
+    use Doctrine\Persistence\Mapping\ClassMetadata;
+
+    /**
+     * Contract for metadata drivers.
+     */
+    interface MappingDriver
     {
         /**
          * Loads the metadata for the specified class into the provided container.
-         * 
-         * @param string $className
-         * @param ClassMetadataInfo $metadata
+         *
+         * @param class-string<T> $className
+         * @param ClassMetadata<T> $metadata
+         *
+         * @return void
+         *
+         * @template T of object
          */
-        function loadMetadataForClass($className, ClassMetadataInfo $metadata);
-    
+        public function loadMetadataForClass(string $className, ClassMetadata $metadata);
+
         /**
          * Gets the names of all mapped classes known to this driver.
-         * 
-         * @return array The names of all mapped classes known to this driver.
-         */
-        function getAllClassNames(); 
-    
-        /**
-         * Whether the class with the specified name should have its metadata loaded.
-         * This is only the case if it is either mapped as an Entity or a
-         * MappedSuperclass.
          *
-         * @param string $className
-         * @return boolean
+         * @return list<class-string> The names of all mapped classes known to this driver.
          */
-        function isTransient($className);
+        public function getAllClassNames();
+
+        /**
+         * Returns whether the class with the specified name should have its metadata loaded.
+         * This is only the case if it is either mapped as an Entity or a MappedSuperclass.
+         *
+         * @param class-string $className
+         *
+         * @return bool
+         */
+        public function isTransient(string $className);
     }
 
 If you want to write a metadata driver to parse information from
 some file format we've made your life a little easier by providing
-the ``AbstractFileDriver`` implementation for you to extend from:
+the ``FileDriver`` implementation for you to extend from:
 
 .. code-block:: php
 
     <?php
-    class MyMetadataDriver extends AbstractFileDriver
+
+    use Doctrine\Persistence\Mapping\ClassMetadata;
+    use Doctrine\Persistence\Mapping\Driver\FileDriver;
+
+    class MyMetadataDriver extends FileDriver
     {
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
         protected $_fileExtension = '.dcm.ext';
-    
+
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
-        public function loadMetadataForClass($className, ClassMetadataInfo $metadata)
+        public function loadMetadataForClass($className, ClassMetadata $metadata)
         {
             $data = $this->_loadMappingFile($file);
-    
-            // populate ClassMetadataInfo instance from $data
+
+            // populate ClassMetadata instance from $data
         }
-    
+
         /**
-         * {@inheritdoc}
+         * {@inheritDoc}
          */
         protected function _loadMappingFile($file)
         {
@@ -127,13 +147,12 @@ the ``AbstractFileDriver`` implementation for you to extend from:
 
 .. note::
 
-    When using the ``AbstractFileDriver`` it requires that you
-    only have one entity defined per file and the file named after the
-    class described inside where namespace separators are replaced by
-    periods. So if you have an entity named ``Entities\User`` and you
-    wanted to write a mapping file for your driver above you would need
-    to name the file ``Entities.User.dcm.ext`` for it to be
-    recognized.
+    When using the ``FileDriver`` it requires that you only have one
+    entity defined per file and the file named after the class described
+    inside where namespace separators are replaced by periods. So if you
+    have an entity named ``Entities\User`` and you wanted to write a
+    mapping file for your driver above you would need to name the file
+    ``Entities.User.dcm.ext`` for it to be recognized.
 
 
 Now you can use your ``MyMetadataDriver`` implementation by setting
@@ -156,14 +175,6 @@ entity when needed.
 
 You have all the methods you need to manually specify the mapping
 information instead of using some mapping file to populate it from.
-The base ``ClassMetadataInfo`` class is responsible for only data
-storage and is not meant for runtime use. It does not require that
-the class actually exists yet so it is useful for describing some
-entity before it exists and using that information to generate for
-example the entities themselves. The class ``ClassMetadata``
-extends ``ClassMetadataInfo`` and adds some functionality required
-for runtime usage and requires that the PHP class is present and
-can be autoloaded.
 
 You can read more about the API of the ``ClassMetadata`` classes in
 the PHP Mapping chapter.
@@ -192,5 +203,3 @@ iterate over them:
     foreach ($class->fieldMappings as $fieldMapping) {
         echo $fieldMapping['fieldName'] . "\n";
     }
-
-

docs/en/reference/namingstrategy.rst

@@ -7,7 +7,7 @@ reduce the verbosity of the mapping document, eliminating repetitive noise (eg:
 
 .. warning
 
-    The naming strategy is always overridden by entity mapping such as the `Table` annotation.
+    The naming strategy is always overridden by entity mapping such as the `Table` attribute.
 
 Configuring a naming strategy
 -----------------------------

docs/en/reference/native-sql.rst

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

docs/en/reference/partial-objects.rst

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

docs/en/reference/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``:
@@ -85,12 +90,14 @@ Static Function
 In addition to the PHP files you can also specify your mapping
 information inside of a static function defined on the entity class
 itself. This is useful for cases where you want to keep your entity
-and mapping information together but don't want to use annotations.
-For this you just need to use the ``StaticPHPDriver``:
+and mapping information together but don't want to use attributes or
+annotations. For this you just need to use the ``StaticPHPDriver``:
 
 .. code-block:: php
 
     <?php
+    use Doctrine\Persistence\Mapping\Driver\StaticPHPDriver;
+
     $driver = new StaticPHPDriver('/path/to/entities');
     $em->getConfiguration()->setMetadataDriverImpl($driver);
 
@@ -160,7 +167,7 @@ The API of the ClassMetadataBuilder has the following methods with a fluent inte
 -   ``addNamedQuery($name, $dqlQuery)``
 -   ``setJoinedTableInheritance()``
 -   ``setSingleTableInheritance()``
--   ``setDiscriminatorColumn($name, $type = 'string', $length = 255)``
+-   ``setDiscriminatorColumn($name, $type = 'string', $length = 255, $columnDefinition = null, $enumType = null, $options = [])``
 -   ``addDiscriminatorMapClass($name, $class)``
 -   ``setChangeTrackingPolicyDeferredExplicit()``
 -   ``setChangeTrackingPolicyNotify()``
@@ -180,13 +187,12 @@ It also has several methods that create builders (which are necessary for advanc
 -   ``createManyToMany($name, $targetEntity)`` returns an ``ManyToManyAssociationBuilder`` instance
 -   ``createOneToMany($name, $targetEntity)`` returns an ``OneToManyAssociationBuilder`` instance
 
-ClassMetadataInfo API
----------------------
+ClassMetadata API
+-----------------
 
-The ``ClassMetadataInfo`` class is the base data object for storing
-the mapping metadata for a single entity. It contains all the
-getters and setters you need populate and retrieve information for
-an entity.
+The ``ClassMetadata`` class is the data object for storing the mapping
+metadata for a single entity. It contains all the getters and setters
+you need populate and retrieve information for an entity.
 
 General Setters
 ~~~~~~~~~~~~~~~
@@ -304,13 +310,11 @@ Lifecycle Callback Getters
 -  ``hasLifecycleCallbacks($lifecycleEvent)``
 -  ``getLifecycleCallbacks($event)``
 
-ClassMetadata API
------------------
+Runtime reflection methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``ClassMetadata`` class extends ``ClassMetadataInfo`` and adds
-the runtime functionality required by Doctrine. It adds a few extra
-methods related to runtime reflection for working with the entities
-themselves.
+These are methods related to runtime reflection for working with the
+entities themselves.
 
 
 -  ``getReflectionClass()``
@@ -321,5 +325,3 @@ themselves.
 -  ``setIdentifierValues($entity, $id)``
 -  ``setFieldValue($entity, $field, $value)``
 -  ``getFieldValue($entity, $field)``
-
-

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -253,7 +253,7 @@ Calling ``setParameter()`` automatically infers which type you are setting as
 value. This works for integers, arrays of strings/integers, DateTime instances
 and for managed entities. If you want to set a type explicitly you can call
 the third argument to ``setParameter()`` explicitly. It accepts either a DBAL
-Doctrine\DBAL\ParameterType::* or a DBAL Type name for conversion.
+``Doctrine\DBAL\ParameterType::*`` or a DBAL Type name for conversion.
 
 .. note::
 
@@ -268,7 +268,7 @@ Doctrine\DBAL\ParameterType::* or a DBAL Type name for conversion.
     use Doctrine\DBAL\Types\Types;
     
     // prevents attempt to load metadata for date time class, improving performance
-    $qb->setParameter('date', new \DateTimeImmutable(), Types::DATE_IMMUTABLE)
+    $qb->setParameter('date', new \DateTimeImmutable(), Types::DATETIME_IMMUTABLE)
 
 If you've got several parameters to bind to your query, you can
 also use setParameters() instead of setParameter() with the
@@ -434,6 +434,12 @@ complete list of supported helper methods available:
         // Example - $qb->expr()->isNotNull('u.id') => u.id IS NOT NULL
         public function isNotNull($x); // Returns string
 
+        // Example - $qb->expr()->isMemberOf('?1', 'u.groups') => ?1 MEMBER OF u.groups
+        public function isMemberOf($x, $y); // Returns Expr\Comparison instance
+
+        // Example - $qb->expr()->isInstanceOf('u', Employee::class) => u INSTANCE OF Employee
+        public function isInstanceOf($x, $y); // Returns Expr\Comparison instance
+
 
         /** Arithmetic objects **/
 
@@ -572,8 +578,6 @@ of DQL. It takes 3 parameters: ``$dqlPartName``, ``$dqlPart`` and
    not (no effect on the ``where`` and ``having`` DQL query parts,
    which always override all previously defined items)
 
--
-
 .. code-block:: php
 
     <?php

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

@@ -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 <https://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,13 +166,13 @@ 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 \Doctrine\ORM\Cache\RegionsConfiguration $cacheConfig */
-    /** @var \Doctrine\Common\Cache\Cache $cache */
+    /** @var \Psr\Cache\CacheItemPoolInterface $cache */
     /** @var \Doctrine\ORM\Configuration $config */
 
     $factory = new \Doctrine\ORM\Cache\DefaultCacheFactory($cacheConfig, $cache);
@@ -196,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.
@@ -209,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 <https://www.doctrine-project.org/api/orm/current/Doctrine/ORM/Cache/DefaultCacheFactory.html>`_.
-
 Region Lifetime
 ~~~~~~~~~~~~~~~
 
@@ -234,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
@@ -269,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 <https://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.
@@ -288,26 +277,44 @@ level cache region.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        #[Cache(usage: 'READ_ONLY', region: 'my_entity_region')]
+        class Country
+        {
+            #[Id]
+            #[GeneratedValue]
+            #[Column]
+            protected int|null $id = null;
+
+            #[Column(unique: true)]
+            protected string $name;
+
+            // other properties and methods
+        }
+
+    .. code-block:: annotation
 
         <?php
         /**
          * @Entity
-         * @Cache(usage="READ_ONLY", region="my_entity_region")
+         * @Cache("NONSTRICT_READ_WRITE")
          */
-        class Country
+        class State
         {
             /**
              * @Id
              * @GeneratedValue
              * @Column(type="integer")
              */
-            protected $id;
+            protected int|null $id = null;
 
             /**
              * @Column(unique=true)
              */
-            protected $name;
+            protected string $name;
 
             // other properties and methods
         }
@@ -315,7 +322,10 @@ level cache region.
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="Country">
             <cache usage="READ_ONLY" region="my_entity_region" />
             <id name="id" type="integer" column="id">
@@ -330,8 +340,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
@@ -351,7 +361,35 @@ It caches the primary keys of association and cache each element will be cached
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        #[Cache(usage: 'NONSTRICT_READ_WRITE')]
+        class State
+        {
+            #[Id]
+            #[GeneratedValue]
+            #[Column]
+            protected int|null $id = null;
+
+            #[Column(unique: true)]
+            protected string $name;
+
+            #[Cache(usage: 'NONSTRICT_READ_WRITE')]
+            #[ManyToOne(targetEntity: Country::class)]
+            #[JoinColumn(name: 'country_id', referencedColumnName: 'id')]
+            protected Country|null $country = null;
+
+            /** @var Collection<int, City> */
+            #[Cache(usage: 'NONSTRICT_READ_WRITE')]
+            #[OneToMany(targetEntity: City::class, mappedBy: 'state')]
+            protected Collection $cities;
+
+            // other properties and methods
+        }
+
+    .. code-block:: annotation
 
         <?php
         /**
@@ -365,25 +403,26 @@ It caches the primary keys of association and cache each element will be cached
              * @GeneratedValue
              * @Column(type="integer")
              */
-            protected $id;
+            protected int|null $id = null;
 
             /**
              * @Column(unique=true)
              */
-            protected $name;
+            protected string $name;
 
             /**
              * @Cache("NONSTRICT_READ_WRITE")
              * @ManyToOne(targetEntity="Country")
              * @JoinColumn(name="country_id", referencedColumnName="id")
              */
-            protected $country;
+            protected Country|null $country;
 
             /**
              * @Cache("NONSTRICT_READ_WRITE")
              * @OneToMany(targetEntity="City", mappedBy="state")
+             * @var Collection<int, City>
              */
-            protected $cities;
+            protected Collection $cities;
 
             // other properties and methods
         }
@@ -391,7 +430,10 @@ It caches the primary keys of association and cache each element will be cached
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="State">
 
             <cache usage="NONSTRICT_READ_WRITE" />
@@ -401,7 +443,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" />
 
@@ -421,7 +463,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
@@ -439,17 +481,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
 ~~~~~~~~~~~
@@ -466,8 +509,8 @@ Basic entity cache
 
     $country1  = $em->find('Country', 1); // Retrieve item from cache
 
-    $country1->setName("New Name");
-    
+    $country1->setName('New Name');
+
     $em->flush();                         // Hit database to update the row and update cache
 
     $em->clear();                         // Clear entity manager
@@ -492,7 +535,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();
 
@@ -543,14 +586,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')
@@ -570,10 +613,10 @@ 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();
 
@@ -597,7 +640,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();
 
 
@@ -659,7 +702,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
@@ -683,40 +726,35 @@ For performance reasons the cache API does not extract from composite primary ke
 .. code-block:: php
 
     <?php
-    /**
-     * @Entity
-     */
+
+    #[Entity]
     class Reference
     {
-        /**
-         * @Id
-         * @ManyToOne(targetEntity="Article", inversedBy="references")
-         * @JoinColumn(name="source_id", referencedColumnName="article_id")
-         */
-        private $source;
+        #[Id]
+        #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')]
+        #[JoinColumn(name: 'source_id', referencedColumnName: 'article_id')]
+        private Article|null $source = null;
 
-        /**
-         * @Id
-         * @ManyToOne(targetEntity="Article")
-         * @JoinColumn(name="target_id", referencedColumnName="article_id")
-         */
+        #[Id]
+        #[ManyToOne(targetEntity: Article::class, inversedBy: 'references')]
+        #[JoinColumn(name: 'target_id', referencedColumnName: 'article_id')]
         private $target;
     }
 
     // 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

@@ -12,9 +12,8 @@ page only handles Security issues in the ORM.
 
 - `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
-developers and you only.
+If you find a Security bug in Doctrine, please follow our
+`Security reporting guidelines <https://www.doctrine-project.org/policies/security.html#reporting>`_.
 
 User input and Doctrine ORM
 ---------------------------
@@ -98,19 +97,20 @@ entity might look like this:
 
     <?php
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class InsecureEntity
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
-        /** @Column */
-        private $email;
-        /** @Column(type="boolean") */
-        private $isAdmin;
+        #[Id, Column, GeneratedValue]
+        private int|null $id = null;
 
-        public function fromArray(array $userInput)
+        #[Column]
+        private string $email;
+
+        #[Column]
+        private bool $isAdmin;
+
+        /** @param array<string, mixed> $userInput */
+        public function fromArray(array $userInput): void
         {
             foreach ($userInput as $key => $value) {
                 $this->$key = $value;
@@ -118,7 +118,7 @@ entity might look like this:
         }
     }
 
-Now the possiblity of mass-asignment exists on this entity and can
+Now the possiblity of mass-assignment exists on this entity and can
 be exploited by attackers to set the "isAdmin" flag to true on any
 object when you pass the whole request data to this method like:
 

docs/en/reference/tools.rst

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

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

@@ -88,7 +88,7 @@ requirement.
 
 A more convenient alternative for explicit transaction demarcation is the use
 of provided control abstractions in the form of
-``Connection#transactional($func)`` and ``EntityManager#transactional($func)``.
+``Connection#transactional($func)`` and ``EntityManager#wrapInTransaction($func)``.
 When used, these control abstractions ensure that you never forget to rollback
 the transaction, in addition to the obvious code reduction. An example that is
 functionally equivalent to the previously shown code looks as follows:
@@ -96,26 +96,28 @@ functionally equivalent to the previously shown code looks as follows:
 .. code-block:: php
 
     <?php
+    // transactional with Connection instance
+    // $conn instanceof Connection
+    $conn->transactional(function($conn) {
+        // ... do some work
+        $user = new User;
+        $user->setName('George');
+    });
+
+    // transactional with EntityManager instance
     // $em instanceof EntityManager
-    $em->transactional(function($em) {
+    $em->wrapInTransaction(function($em) {
         // ... do some work
         $user = new User;
         $user->setName('George');
         $em->persist($user);
     });
 
-.. warning::
-
-    For historical reasons, ``EntityManager#transactional($func)`` will return
-    ``true`` whenever the return value of ``$func`` is loosely false.
-    Some examples of this include ``array()``, ``"0"``, ``""``, ``0``, and
-    ``null``.
-
 The difference between ``Connection#transactional($func)`` and
 ``EntityManager#transactional($func)`` is that the latter
 abstraction flushes the ``EntityManager`` prior to transaction
-commit and rolls back the transaction when an
-exception occurs.
+commit and in case of an exception the ``EntityManager`` gets closed
+in addition to the transaction rollback.
 
 .. _transactions-and-concurrency_exception-handling:
 
@@ -189,14 +191,25 @@ example we'll use an integer.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        class User
+        {
+            // ...
+            #[Version, Column(type: 'integer')]
+            private int $version;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         class User
         {
             // ...
             /** @Version @Column(type="integer") */
-            private $version;
+            private int $version;
             // ...
         }
 
@@ -222,14 +235,25 @@ timestamp or datetime):
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        class User
+        {
+            // ...
+            #[Version, Column(type: 'datetime')]
+            private DateTime $version;
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
         class User
         {
             // ...
             /** @Version @Column(type="datetime") */
-            private $version;
+            private DateTime $version;
             // ...
         }
 
@@ -279,15 +303,15 @@ either when calling ``EntityManager#find()``:
     <?php
     use Doctrine\DBAL\LockMode;
     use Doctrine\ORM\OptimisticLockException;
-    
+
     $theEntityId = 1;
     $expectedVersion = 184;
-    
+
     try {
         $entity = $em->find('User', $theEntityId, LockMode::OPTIMISTIC, $expectedVersion);
-    
+
         // do the work
-    
+
         $em->flush();
     } catch(OptimisticLockException $e) {
         echo "Sorry, but someone else has already changed this entity. Please apply the changes again!";
@@ -300,16 +324,16 @@ Or you can use ``EntityManager#lock()`` to find out:
     <?php
     use Doctrine\DBAL\LockMode;
     use Doctrine\ORM\OptimisticLockException;
-    
+
     $theEntityId = 1;
     $expectedVersion = 184;
-    
+
     $entity = $em->find('User', $theEntityId);
-    
+
     try {
         // assert version
         $em->lock($entity, LockMode::OPTIMISTIC, $expectedVersion);
-    
+
     } catch(OptimisticLockException $e) {
         echo "Sorry, but someone else has already changed this entity. Please apply the changes again!";
     }
@@ -348,7 +372,7 @@ See the example code, The form (GET Request):
 
     <?php
     $post = $em->find('BlogPost', 123456);
-    
+
     echo '<input type="hidden" name="id" value="' . $post->getId() . '" />';
     echo '<input type="hidden" name="version" value="' . $post->getCurrentVersion() . '" />';
 
@@ -359,7 +383,7 @@ And the change headline action (POST Request):
     <?php
     $postId = (int)$_GET['id'];
     $postVersion = (int)$_GET['version'];
-    
+
     $post = $em->find('BlogPost', $postId, \Doctrine\DBAL\LockMode::OPTIMISTIC, $postVersion);
 
 .. _transactions-and-concurrency_pessimistic-locking:
@@ -390,7 +414,7 @@ Doctrine ORM currently supports two pessimistic lock modes:
    locks other concurrent requests that attempt to update or lock rows
    in write mode.
 
-You can use pessimistic locks in three different scenarios:
+You can use pessimistic locks in four different scenarios:
 
 
 1. Using
@@ -402,8 +426,10 @@ You can use pessimistic locks in three different scenarios:
    or
    ``EntityManager#lock($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
 3. Using
+   ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+   or
+   ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+4. Using
    ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
    or
    ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
-
-

docs/en/reference/typedfieldmapper.rst

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

docs/en/reference/unitofwork.rst

@@ -17,7 +17,7 @@ ask for an entity with a specific ID twice, it will return the same instance:
 
 .. code-block:: php
 
-    public function testIdentityMap()
+    public function testIdentityMap(): void
     {
         $objectA = $this->entityManager->find('EntityName', 1);
         $objectB = $this->entityManager->find('EntityName', 1);
@@ -34,11 +34,11 @@ will still end up with the same reference:
 
 .. code-block:: php
 
-    public function testIdentityMapReference()
+    public function testIdentityMapReference(): void
     {
         $objectA = $this->entityManager->getReference('EntityName', 1);
-        // check for proxyinterface
-        $this->assertInstanceOf('Doctrine\ORM\Proxy\Proxy', $objectA);
+        // check entity is not initialized
+        $this->assertTrue($this->entityManager->isUninitializedObject($objectA));
 
         $objectB = $this->entityManager->find('EntityName', 1);
 
@@ -102,9 +102,9 @@ How Doctrine Detects Changes
 ----------------------------
 
 Doctrine is a data-mapper that tries to achieve persistence-ignorance (PI).
-This means you map php objects into a relational database that don't
+This means you map PHP objects into a relational database that don't
 necessarily know about the database at all. A natural question would now be,
-"how does Doctrine even detect objects have changed?". 
+"how does Doctrine even detect objects have changed?".
 
 For this Doctrine keeps a second map inside the UnitOfWork. Whenever you fetch
 an object from the database Doctrine will keep a copy of all the properties and
@@ -137,7 +137,7 @@ optimize the performance of the Flush Operation:
 .. note::
 
     Flush only a single entity with ``$entityManager->flush($entity)`` is deprecated and will be removed in ORM 3.0.
-    (`Details <https://github.com/doctrine/orm/issues/8459>`_)
+    (\ `Details <https://github.com/doctrine/orm/issues/8459>`_)
 
 Query Internals
 ---------------
@@ -202,4 +202,3 @@ ClassMetadataFactory
 ~~~~~~~~~~~~~~~~~~~~
 
 tbr
-

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

@@ -32,62 +32,62 @@ information about its type and if it's the owning or inverse side.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class User
     {
-        /** @Id @GeneratedValue @Column(type="string") */
-        private $id;
-    
+        #[Id, GeneratedValue, Column]
+        private int|null $id = null;
+
         /**
          * Bidirectional - Many users have Many favorite comments (OWNING SIDE)
          *
-         * @ManyToMany(targetEntity="Comment", inversedBy="userFavorites")
-         * @JoinTable(name="user_favorite_comments")
+         * @var Collection<int, Comment>
          */
-        private $favorites;
-    
+        #[ManyToMany(targetEntity: Comment::class, inversedBy: 'userFavorites')]
+        #[JoinTable(name: 'user_favorite_comments')]
+        private Collection $favorites;
+
         /**
          * Unidirectional - Many users have marked many comments as read
          *
-         * @ManyToMany(targetEntity="Comment")
-         * @JoinTable(name="user_read_comments")
+         * @var Collection<int, Comment>
          */
-        private $commentsRead;
-    
+        #[ManyToMany(targetEntity: Comment::class)]
+        #[JoinTable(name: 'user_read_comments')]
+        private Collection $commentsRead;
+
         /**
          * Bidirectional - One-To-Many (INVERSE SIDE)
          *
-         * @OneToMany(targetEntity="Comment", mappedBy="author")
+         * @var Collection<int, Comment>
          */
-        private $commentsAuthored;
-    
-        /**
-         * Unidirectional - Many-To-One
-         *
-         * @ManyToOne(targetEntity="Comment")
-         */
-        private $firstComment;
+        #[OneToMany(targetEntity: Comment::class, mappedBy: 'author')]
+        private Collection $commentsAuthored;
+
+        /** Unidirectional - Many-To-One */
+        #[ManyToOne(targetEntity: Comment::class)]
+        private Comment|null $firstComment = null;
     }
-    
-    /** @Entity */
+
+    #[Entity]
     class Comment
     {
-        /** @Id @GeneratedValue @Column(type="string") */
-        private $id;
-    
+        #[Id, GeneratedValue, Column]
+        private string $id;
+
         /**
          * Bidirectional - Many comments are favorited by many users (INVERSE SIDE)
          *
-         * @ManyToMany(targetEntity="User", mappedBy="favorites")
+         * @var Collection<int, User>
          */
-        private $userFavorites;
-    
+        #[ManyToMany(targetEntity: User::class, mappedBy: 'favorites')]
+        private Collection $userFavorites;
+
         /**
          * Bidirectional - Many Comments are authored by one user (OWNING SIDE)
-         *
-         * @ManyToOne(targetEntity="User", inversedBy="commentsAuthored")
          */
-         private $author;
+        #[ManyToOne(targetEntity: User::class, inversedBy: 'commentsAuthored')]
+        private User|null $author = null;
     }
 
 This two entities generate the following MySQL Schema (Foreign Key
@@ -100,19 +100,19 @@ definitions omitted):
         firstComment_id VARCHAR(255) DEFAULT NULL,
         PRIMARY KEY(id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE Comment (
         id VARCHAR(255) NOT NULL,
         author_id VARCHAR(255) DEFAULT NULL,
         PRIMARY KEY(id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE user_favorite_comments (
         user_id VARCHAR(255) NOT NULL,
         favorite_comment_id VARCHAR(255) NOT NULL,
         PRIMARY KEY(user_id, favorite_comment_id)
     ) ENGINE = InnoDB;
-    
+
     CREATE TABLE user_read_comments (
         user_id VARCHAR(255) NOT NULL,
         comment_id VARCHAR(255) NOT NULL,
@@ -132,11 +132,12 @@ relations of the ``User``:
     class User
     {
         // ...
-        public function getReadComments() {
+        /** @return Collection<int, Comment> */
+        public function getReadComments(): Collection {
              return $this->commentsRead;
         }
-    
-        public function setFirstComment(Comment $c) {
+
+        public function setFirstComment(Comment $c): void {
             $this->firstComment = $c;
         }
     }
@@ -148,17 +149,17 @@ The interaction code would then look like in the following snippet
 
     <?php
     $user = $em->find('User', $userId);
-    
+
     // unidirectional many to many
     $comment = $em->find('Comment', $readCommentId);
     $user->getReadComments()->add($comment);
-    
+
     $em->flush();
-    
+
     // unidirectional many to one
     $myFirstComment = new Comment();
     $user->setFirstComment($myFirstComment);
-    
+
     $em->persist($myFirstComment);
     $em->flush();
 
@@ -171,40 +172,43 @@ fields on both sides:
     class User
     {
         // ..
-    
-        public function getAuthoredComments() {
+
+        /** @return Collection<int, Comment> */
+        public function getAuthoredComments(): Collection {
             return $this->commentsAuthored;
         }
-    
-        public function getFavoriteComments() {
+
+        /** @return Collection<int, Comment> */
+        public function getFavoriteComments(): Collection {
             return $this->favorites;
         }
     }
-    
+
     class Comment
     {
         // ...
-    
-        public function getUserFavorites() {
+
+        /** @return Collection<int, User> */
+        public function getUserFavorites(): Collection {
             return $this->userFavorites;
         }
-    
-        public function setAuthor(User $author = null) {
+
+        public function setAuthor(User|null $author = null): void {
             $this->author = $author;
         }
     }
-    
+
     // Many-to-Many
     $user->getFavorites()->add($favoriteComment);
     $favoriteComment->getUserFavorites()->add($user);
-    
+
     $em->flush();
-    
+
     // Many-To-One / One-To-Many Bidirectional
     $newComment = new Comment();
     $user->getAuthoredComments()->add($newComment);
     $newComment->setAuthor($user);
-    
+
     $em->persist($newComment);
     $em->flush();
 
@@ -225,10 +229,10 @@ element. Here are some examples:
     // Remove by Elements
     $user->getComments()->removeElement($comment);
     $comment->setAuthor(null);
-    
+
     $user->getFavorites()->removeElement($comment);
     $comment->getUserFavorites()->removeElement($user);
-    
+
     // Remove by Key
     $user->getComments()->remove($ithComment);
     $comment->setAuthor(null);
@@ -240,7 +244,7 @@ Notice how both sides of the bidirectional association are always
 updated. Unidirectional associations are consequently simpler to
 handle.
 
-Also note that if you use type-hinting in your methods, you will 
+Also note that if you use type-hinting in your methods, you will
 have to specify a nullable type, i.e. ``setAddress(?Address $address)``,
 otherwise ``setAddress(null)`` will fail to remove the association.
 Another way to deal with this is to provide a special method, like
@@ -271,8 +275,8 @@ entities that have been re-added to the collection.
 
 Say you clear a collection of tags by calling
 ``$post->getTags()->clear();`` and then call
-``$post->getTags()->add($tag)``. This will not recognize the tag having 
-already been added previously and will consequently issue two separate database 
+``$post->getTags()->add($tag)``. This will not recognize the tag having
+already been added previously and will consequently issue two separate database
 calls.
 
 Association Management Methods
@@ -292,43 +296,43 @@ example that encapsulate much of the association management code:
     class User
     {
         // ...
-        public function markCommentRead(Comment $comment) {
+        public function markCommentRead(Comment $comment): void {
             // Collections implement ArrayAccess
             $this->commentsRead[] = $comment;
         }
-    
-        public function addComment(Comment $comment) {
+
+        public function addComment(Comment $comment): void {
             if (count($this->commentsAuthored) == 0) {
                 $this->setFirstComment($comment);
             }
             $this->comments[] = $comment;
             $comment->setAuthor($this);
         }
-    
-        private function setFirstComment(Comment $c) {
+
+        private function setFirstComment(Comment $c): void {
             $this->firstComment = $c;
         }
-    
-        public function addFavorite(Comment $comment) {
+
+        public function addFavorite(Comment $comment): void {
             $this->favorites->add($comment);
             $comment->addUserFavorite($this);
         }
-    
-        public function removeFavorite(Comment $comment) {
+
+        public function removeFavorite(Comment $comment): void {
             $this->favorites->removeElement($comment);
             $comment->removeUserFavorite($this);
         }
     }
-    
+
     class Comment
     {
         // ..
-    
-        public function addUserFavorite(User $user) {
+
+        public function addUserFavorite(User $user): void {
             $this->userFavorites[] = $user;
         }
-    
-        public function removeUserFavorite(User $user) {
+
+        public function removeUserFavorite(User $user): void {
             $this->userFavorites->removeElement($user);
         }
     }
@@ -356,7 +360,8 @@ the details inside the classes can be challenging.
 
     <?php
     class User {
-        public function getReadComments() {
+        /** @return array<int, Comment> */
+        public function getReadComments(): array {
             return $this->commentsRead->toArray();
         }
     }
@@ -373,7 +378,7 @@ as your preferences.
 Synchronizing Bidirectional Collections
 ---------------------------------------
 
-In the case of Many-To-Many associations you as the developer have the 
+In the case of Many-To-Many associations you as the developer have the
 responsibility of keeping the collections on the owning and inverse side
 in sync when you apply changes to them. Doctrine can only
 guarantee a consistent state for the hydration, not for your client
@@ -387,7 +392,7 @@ can show the possible caveats you can encounter:
     <?php
     $user->getFavorites()->add($favoriteComment);
     // not calling $favoriteComment->getUserFavorites()->add($user);
-    
+
     $user->getFavorites()->contains($favoriteComment); // TRUE
     $favoriteComment->getUserFavorites()->contains($user); // FALSE
 
@@ -422,7 +427,7 @@ comment might look like in your controller (without ``cascade: persist``):
     $user = new User();
     $myFirstComment = new Comment();
     $user->addComment($myFirstComment);
-    
+
     $em->persist($user);
     $em->persist($myFirstComment); // required, if `cascade: persist` is not set
     $em->flush();
@@ -437,8 +442,10 @@ only accessing it through the User entity:
     // User entity
     class User
     {
-        private $id;
-        private $comments;
+        private int $id;
+
+        /** @var Collection<int, Comment> */
+        private Collection $comments;
 
         public function __construct()
         {
@@ -464,11 +471,8 @@ If you then set up the cascading to the ``User#commentsAuthored`` property...
     class User
     {
         // ...
-        /**
-         * Bidirectional - One-To-Many (INVERSE SIDE)
-         *
-         * @OneToMany(targetEntity="Comment", mappedBy="author", cascade={"persist", "remove"})
-         */
+        /** Bidirectional - One-To-Many (INVERSE SIDE) */
+        #[OneToMany(targetEntity: Comment::class, mappedBy: 'author', cascade: ['persist', 'remove'])]
         private $commentsAuthored;
         // ...
     }
@@ -480,7 +484,7 @@ If you then set up the cascading to the ``User#commentsAuthored`` property...
     <?php
     $user = new User();
     $user->comment('Lorem ipsum', new DateTime());
-    
+
     $em->persist($user);
     $em->flush();
 
@@ -521,6 +525,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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -557,6 +563,13 @@ OrphanRemoval works with one-to-one, one-to-many and many-to-many associations.
     If you neglect this assumption your entities will get deleted by Doctrine even if
     you assigned the orphaned entity to another one.
 
+.. note::
+
+    ``orphanRemoval=true`` option should be used in combination with ``cascade=["persist"]`` option
+    as the child entity, that is manually persisted, will not be deleted automatically by Doctrine
+    when a collection is still an instance of ArrayCollection (before first flush / hydration).
+    This is a Doctrine limitation since ArrayCollection does not have access to a UnitOfWork.
+
 As a better example consider an Addressbook application where you have Contacts, Addresses
 and StandingData:
 
@@ -568,31 +581,30 @@ and StandingData:
 
     use Doctrine\Common\Collections\ArrayCollection;
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class Contact
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
+        #[Id, Column(type: 'integer'), GeneratedValue]
+        private int|null $id = null;
 
-        /** @OneToOne(targetEntity="StandingData", orphanRemoval=true) */
-        private $standingData;
+        #[OneToOne(targetEntity: StandingData::class, cascade: ['persist'], orphanRemoval: true)]
+        private StandingData|null $standingData = null;
 
-        /** @OneToMany(targetEntity="Address", mappedBy="contact", orphanRemoval=true) */
-        private $addresses;
+        /** @var Collection<int, Address> */
+        #[OneToMany(targetEntity: Address::class, mappedBy: 'contact', cascade: ['persist'], orphanRemoval: true)]
+        private Collection $addresses;
 
         public function __construct()
         {
             $this->addresses = new ArrayCollection();
         }
 
-        public function newStandingData(StandingData $sd)
+        public function newStandingData(StandingData $sd): void
         {
             $this->standingData = $sd;
         }
 
-        public function removeAddress($pos)
+        public function removeAddress(int $pos): void
         {
             unset($this->addresses[$pos]);
         }
@@ -610,10 +622,10 @@ Now two examples of what happens when you remove the references:
 
     $em->flush();
 
-In this case you have not only changed the ``Contact`` entity itself but 
-you have also removed the references for standing data and as well as one 
-address reference. When flush is called not only are the references removed 
-but both the old standing data and the one address entity are also deleted 
+In this case you have not only changed the ``Contact`` entity itself but
+you have also removed the references for standing data and as well as one
+address reference. When flush is called not only are the references removed
+but both the old standing data and the one address entity are also deleted
 from the database.
 
 .. _filtering-collections:
@@ -706,6 +718,7 @@ methods:
 
 * ``andX($arg1, $arg2, ...)``
 * ``orX($arg1, $arg2, ...)``
+* ``not($expression)``
 * ``eq($field, $value)``
 * ``gt($field, $value)``
 * ``lt($field, $value)``

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

@@ -95,28 +95,29 @@ from newly opened EntityManager.
 .. code-block:: php
 
     <?php
-    /** @Entity */
+    #[Entity]
     class Article
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
+        #[Id, Column(type: 'integer'), GeneratedValue]
+        private int|null $id = null;
 
-        /** @Column(type="string") */
-        private $headline;
+        #[Column(type: 'string')]
+        private string $headline;
 
-        /** @ManyToOne(targetEntity="User") */
-        private $author;
+        #[ManyToOne(targetEntity: User::class)]
+        private User|null $author = null;
 
-        /** @OneToMany(targetEntity="Comment", mappedBy="article") */
-        private $comments;
+        /** @var Collection<int, Comment> */
+        #[OneToMany(targetEntity: Comment::class, mappedBy: 'article')]
+        private Collection $comments;
 
         public function __construct()
         {
             $this->comments = new ArrayCollection();
         }
 
-        public function getAuthor() { return $this->author; }
-        public function getComments() { return $this->comments; }
+        public function getAuthor(): User|null { return $this->author; }
+        public function getComments(): Collection { return $this->comments; }
     }
 
     $article = $em->find('Article', 1);
@@ -161,28 +162,6 @@ your code. See the following code:
         echo "This will always be true!";
     }
 
-A slice of the generated proxy classes code looks like the
-following piece of code. A real proxy class override ALL public
-methods along the lines of the ``getName()`` method shown below:
-
-.. code-block:: php
-
-    <?php
-    class UserProxy extends User implements Proxy
-    {
-        private function _load()
-        {
-            // lazy loading code
-        }
-
-        public function getName()
-        {
-            $this->_load();
-            return parent::getName();
-        }
-        // .. other public methods of User
-    }
-
 .. warning::
 
     Traversing the object graph for parts that are lazy-loaded will
@@ -213,6 +192,11 @@ be properly synchronized with the database when
     database in the most efficient way and a single, short transaction,
     taking care of maintaining referential integrity.
 
+.. note::
+
+    Do not make any assumptions in your code about the number of queries
+    it takes to flush changes, about the ordering of ``INSERT``, ``UPDATE``
+    and ``DELETE`` queries or the order in which entities will be processed.
 
 Example:
 
@@ -304,24 +288,61 @@ as follows:
 -  A removed entity X will be removed from the database as a result
    of the flush operation.
 
-After an entity has been removed its in-memory state is the same as
+After an entity has been removed, its in-memory state is the same as
 before the removal, except for generated identifiers.
 
-Removing an entity will also automatically delete any existing
-records in many-to-many join tables that link this entity. The
-action taken depends on the value of the ``@joinColumn`` mapping
-attribute "onDelete". Either Doctrine issues a dedicated ``DELETE``
-statement for records of each join table or it depends on the
-foreign key semantics of onDelete="CASCADE".
+During the ``EntityManager#flush()`` operation, the removed entity
+will also be removed from all collections in entities currently
+loaded into memory.
+
+.. _remove_object_many_to_many_join_tables:
+
+Join-table management when removing from many-to-many collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Regarding existing rows in many-to-many join tables that refer to
+an entity being removed, the following applies.
+
+When the entity being removed does not declare the many-to-many association
+itself (that is, the many-to-many association is unidirectional and
+the entity is on the inverse side), the ORM has no reasonable way to
+detect associations targeting the entity's class. Thus, no ORM-level handling
+of join-table rows is attempted and database-level constraints apply.
+In case of database-level ``ON DELETE RESTRICT`` constraints, the
+``EntityManager#flush()`` operation may abort and a ``ConstraintViolationException``
+may be thrown. No in-memory collections will be modified in this case.
+With ``ON DELETE CASCADE``, the RDBMS will take care of removing rows
+from join tables.
+
+When the entity being removed is part of bi-directional many-to-many
+association, either as the owning or inverse side, the ORM will
+delete rows from join tables before removing the entity itself. That means
+database-level ``ON DELETE RESTRICT`` constraints on join tables are not
+effective, since the join table rows are removed first. Removal of join table
+rows happens through specialized methods in entity and collection persister
+classes and take one query per entity and join table. In case the association
+uses a ``@JoinColumn`` configuration with ``onDelete="CASCADE"``, instead
+of using a dedicated ``DELETE`` query the database-level operation will be
+relied upon.
+
+.. note::
+
+    In case you rely on database-level ``ON DELETE RESTRICT`` constraints,
+    be aware that by making many-to-many associations bidirectional the
+    assumed protection may be lost.
+
+
+Performance of different deletion strategies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Deleting an object with all its associated objects can be achieved
 in multiple ways with very different performance impacts.
 
-
-1. If an association is marked as ``CASCADE=REMOVE`` Doctrine ORM
-   will fetch this association. If its a Single association it will
-   pass this entity to
-   ``EntityManager#remove()``. If the association is a collection, Doctrine will loop over all    its elements and pass them to``EntityManager#remove()``.
+1. If an association is marked as ``CASCADE=REMOVE`` Doctrine ORM will
+   fetch this association. If it's a Single association it will pass
+   this entity to ``EntityManager#remove()``. If the association is a
+   collection, Doctrine will loop over all its elements and pass them to
+   ``EntityManager#remove()``.
    In both cases the cascade remove semantics are applied recursively.
    For large object graphs this removal strategy can be very costly.
 2. Using a DQL ``DELETE`` statement allows you to delete multiple
@@ -339,8 +360,8 @@ in multiple ways with very different performance impacts.
 .. note::
 
     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. 
+    map and therefore detach it. Querying the same entity again, for example
+    via a lazy loaded relation, will return a new object.
 
 
 Detaching entities
@@ -413,14 +434,6 @@ Example:
     // $entity now refers to the fully managed copy returned by the merge operation.
     // The EntityManager $em now manages the persistence of $entity as usual.
 
-.. note::
-
-    When you want to serialize/unserialize entities you
-    have to make all entity properties protected, never private. The
-    reason for this is, if you serialize a class that was a proxy
-    instance before, the private variables won't be serialized and a
-    PHP Notice is thrown.
-
 
 The semantics of the merge operation, applied to an entity X, are
 as follows:
@@ -770,6 +783,23 @@ and these associations are mapped as EAGER, they will automatically
 be loaded together with the entity being queried and is thus
 immediately available to your application.
 
+Eager Loading can also be configured at runtime through
+``AbstractQuery::setFetchMode`` in DQL or Native Queries.
+
+Eager loading for many-to-one and one-to-one associations is using either a
+LEFT JOIN or a second query for fetching the related entity eagerly.
+
+Eager loading for many-to-one associations uses a second query to load
+the collections for several entities at the same time.
+
+When many-to-many, one-to-one or one-to-many associations are eagerly loaded,
+then the global batch size configuration is used to avoid IN(?) queries with
+too many arguments. The default batch size is 100 and can be changed with
+``Configuration::setEagerFetchBatchSize()``.
+
+For eagerly loaded Many-To-Many associations one query has to be made for each
+collection.
+
 By Lazy Loading
 ~~~~~~~~~~~~~~~
 
@@ -833,7 +863,7 @@ By default the EntityManager returns a default implementation of
 ``Doctrine\ORM\EntityRepository`` when you call
 ``EntityManager#getRepository($entityClass)``. You can overwrite
 this behaviour by specifying the class name of your own Entity
-Repository in the Annotation, XML or YAML metadata. In large
+Repository in the Attribute, Annotation, XML or YAML metadata. In large
 applications that require lots of specialized DQL queries using a
 custom repository is one recommended way of grouping these queries
 in a central location.
@@ -843,12 +873,11 @@ in a central location.
     <?php
     namespace MyDomain\Model;
 
+    use MyDomain\Model\UserRepository;
     use Doctrine\ORM\EntityRepository;
     use Doctrine\ORM\Mapping as ORM;
 
-    /**
-     * @ORM\Entity(repositoryClass="MyDomain\Model\UserRepository")
-     */
+    #[ORM\Entity(repositoryClass: UserRepository::class)]
     class User
     {
 
@@ -856,7 +885,8 @@ in a central location.
 
     class UserRepository extends EntityRepository
     {
-        public function getAllAdminUsers()
+        /** @return Collection<User> */
+        public function getAllAdminUsers(): Collection
         {
             return $this->_em->createQuery('SELECT u FROM MyDomain\Model\User u WHERE u.status = "admin"')
                              ->getResult();
@@ -871,5 +901,3 @@ You can access your repository now by calling:
     // $em instanceof EntityManager
 
     $admins = $em->getRepository('MyDomain\Model\User')->getAllAdminUsers();
-
-

docs/en/reference/xml-mapping.rst

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

docs/en/reference/yaml-mapping.rst

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

docs/en/sidebar.rst

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

docs/en/toc.rst

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

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

@@ -23,7 +23,34 @@ and year of production as primary keys:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        namespace VehicleCatalogue\Model;
+
+        #[Entity]
+        class Car
+        {
+            public function __construct(
+                #[Id, Column]
+                private string $name,
+                #[Id, Column]
+                private int $year,
+            ) {
+            }
+
+            public function getModelName(): string
+            {
+                return $this->name;
+            }
+
+            public function getYearOfProduction(): int
+            {
+                return $this->year;
+            }
+        }
+
+    .. code-block:: annotation
 
         <?php
         namespace VehicleCatalogue\Model;
@@ -34,9 +61,9 @@ and year of production as primary keys:
         class Car
         {
             /** @Id @Column(type="string") */
-            private $name;
+            private string $name;
             /** @Id @Column(type="integer") */
-            private $year;
+            private int $year;
 
             public function __construct($name, $year)
             {
@@ -44,12 +71,12 @@ and year of production as primary keys:
                 $this->year = $year;
             }
 
-            public function getModelName()
+            public function getModelName(): string
             {
                 return $this->name;
             }
 
-            public function getYearOfProduction()
+            public function getYearOfProduction(): int
             {
                 return $this->year;
             }
@@ -58,9 +85,9 @@ and year of production as primary keys:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="VehicleCatalogue\Model\Car">
@@ -104,7 +131,7 @@ And for querying you can use arrays to both DQL and EntityRepositories:
 
     $dql = "SELECT c FROM VehicleCatalogue\Model\Car c WHERE c.id = ?1";
     $audi = $em->createQuery($dql)
-               ->setParameter(1, array("name" => "Audi A8", "year" => 2010))
+               ->setParameter(1, ["name" => "Audi A8", "year" => 2010])
                ->getSingleResult();
 
 You can also use this entity in associations. Doctrine will then generate two foreign keys one for ``name``
@@ -131,7 +158,7 @@ of one or many parent entities.
 The semantics of mapping identity through foreign entities are easy:
 
 -   Only allowed on Many-To-One or One-To-One associations.
--   Plug an ``@Id`` annotation onto every association.
+-   Plug an ``#[Id]`` attribute onto every association.
 -   Set an attribute ``association-key`` with the field name of the association in XML.
 -   Set a key ``associationKey:`` with the field name of the association in YAML.
 
@@ -142,7 +169,52 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        namespace Application\Model;
+
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        #[Entity]
+        class Article
+        {
+            #[Id, Column, GeneratedValue]
+            private int|null $id = null;
+            #[Column]
+            private string $title;
+
+            /** @var ArrayCollection<string, ArticleAttribute> */
+            #[OneToMany(targetEntity: ArticleAttribute::class, mappedBy: 'article', cascade: ['ALL'], indexBy: 'attribute')]
+            private Collection $attributes;
+
+            public function addAttribute(string $name, string $value): void
+            {
+                $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
+            }
+        }
+
+        #[Entity]
+        class ArticleAttribute
+        {
+            #[Id, ManyToOne(targetEntity: Article::class, inversedBy: 'attributes')]
+            private Article $article;
+
+            #[Id, Column]
+            private string $attribute;
+
+            #[Column]
+            private string $value;
+
+            public function __construct(string $name, string $value, Article $article)
+            {
+                $this->attribute = $name;
+                $this->value = $value;
+                $this->article = $article;
+            }
+        }
+
+    .. code-block:: annotation
 
         <?php
         namespace Application\Model;
@@ -155,16 +227,17 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
         class Article
         {
             /** @Id @Column(type="integer") @GeneratedValue */
-            private $id;
+            private int|null $id = null;
             /** @Column(type="string") */
-            private $title;
+            private string $title;
 
             /**
              * @OneToMany(targetEntity="ArticleAttribute", mappedBy="article", cascade={"ALL"}, indexBy="attribute")
+             * @var Collection<int, ArticleAttribute>
              */
-            private $attributes;
+            private Collection $attributes;
 
-            public function addAttribute($name, $value)
+            public function addAttribute($name, $value): void
             {
                 $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
             }
@@ -176,13 +249,13 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
         class ArticleAttribute
         {
             /** @Id @ManyToOne(targetEntity="Article", inversedBy="attributes") */
-            private $article;
+            private Article|null $article;
 
             /** @Id @Column(type="string") */
-            private $attribute;
+            private string $attribute;
 
             /** @Column(type="string") */
-            private $value;
+            private string $value;
 
             public function __construct($name, $value, $article)
             {
@@ -194,15 +267,15 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="Application\Model\ArticleAttribute">
                 <id name="article" association-key="true" />
                 <id name="attribute" type="string" />
-                
+
                 <field name="value" type="string" />
 
                 <many-to-one field="article" target-entity="Article" inversed-by="attributes" />
@@ -237,25 +310,22 @@ One good example for this is a user-address relationship:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
 
         <?php
-        /**
-         * @Entity
-         */
+
+        #[Entity]
         class User
         {
-            /** @Id @Column(type="integer") @GeneratedValue */
-            private $id;
+            #[Id, Column, GeneratedValue]
+            private int|null $id = null;
         }
 
-        /**
-         * @Entity
-         */
+        #[Entity]
         class Address
         {
-            /** @Id @OneToOne(targetEntity="User") */
-            private $user;
+            #[Id, OneToOne(targetEntity: User::class)]
+            private User|null $user = null;
         }
 
     .. code-block:: yaml
@@ -288,68 +358,70 @@ of products purchased and maybe even the current price.
 .. code-block:: php
 
     <?php
+
+    use DateTime;
     use Doctrine\Common\Collections\ArrayCollection;
 
-    /** @Entity */
+    #[Entity]
     class Order
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
+        #[Id, Column, GeneratedValue]
+        private int|null $id = null;
 
-        /** @ManyToOne(targetEntity="Customer") */
-        private $customer;
-        /** @OneToMany(targetEntity="OrderItem", mappedBy="order") */
-        private $items;
+        /** @var ArrayCollection<int, OrderItem> */
+        #[OneToMany(targetEntity: OrderItem::class, mappedBy: 'order')]
+        private Collection $items;
 
-        /** @Column(type="boolean") */
-        private $paid = false;
-        /** @Column(type="boolean") */
-        private $shipped = false;
-        /** @Column(type="datetime") */
-        private $created;
+        #[Column]
+        private bool $paid = false;
+        #[Column]
+        private bool $shipped = false;
+        #[Column]
+        private DateTime $created;
 
-        public function __construct(Customer $customer)
-        {
-            $this->customer = $customer;
+        public function __construct(
+            #[ManyToOne(targetEntity: Customer::class)]
+            private Customer $customer,
+        ) {
             $this->items = new ArrayCollection();
-            $this->created = new \DateTime("now");
+            $this->created = new DateTime("now");
         }
     }
 
-    /** @Entity */
+    #[Entity]
     class Product
     {
-        /** @Id @Column(type="integer") @GeneratedValue */
-        private $id;
+        #[Id, Column, GeneratedValue]
+        private int|null $id = null;
 
-        /** @Column(type="string") */
-        private $name;
+        #[Column]
+        private string $name;
 
-        /** @Column(type="decimal") */
-        private $currentPrice;
+        #[Column]
+        private int $currentPrice;
 
-        public function getCurrentPrice()
+        public function getCurrentPrice(): int
         {
             return $this->currentPrice;
         }
     }
 
-    /** @Entity */
+    #[Entity]
     class OrderItem
     {
-        /** @Id @ManyToOne(targetEntity="Order") */
-        private $order;
+        #[Id, ManyToOne(targetEntity: Order::class)]
+        private Order|null $order = null;
 
-        /** @Id @ManyToOne(targetEntity="Product") */
-        private $product;
+        #[Id, ManyToOne(targetEntity: Product::class)]
+        private Product|null $product = null;
 
-        /** @Column(type="integer") */
-        private $amount = 1;
+        #[Column]
+        private int $amount = 1;
 
-        /** @Column(type="decimal") */
-        private $offeredPrice;
+        #[Column]
+        private int $offeredPrice;
 
-        public function __construct(Order $order, Product $product, $amount = 1)
+        public function __construct(Order $order, Product $product, int $amount = 1)
         {
             $this->order = $order;
             $this->product = $product;

docs/en/tutorials/embeddables.rst

@@ -1,10 +1,10 @@
 Separating Concerns using Embeddables
--------------------------------------
+=====================================
 
 Embeddables are classes which are not entities themselves, but are embedded
 in entities and can also be queried in DQL. You'll mostly want to use them
 to reduce duplication or separating concerns. Value objects such as date range
-or address are the primary use case for this feature. 
+or address are the primary use case for this feature.
 
 .. note::
 
@@ -17,7 +17,34 @@ instead of simply adding the respective columns to the ``User`` class.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+
+        #[Entity]
+        class User
+        {
+            #[Embedded(class: Address::class)]
+            private Address $address;
+        }
+
+        #[Embeddable]
+        class Address
+        {
+            #[Column(type: "string")]
+            private string $street;
+
+            #[Column(type: "string")]
+            private string $postalCode;
+
+            #[Column(type: "string")]
+            private string $city;
+
+            #[Column(type: "string")]
+            private string $country;
+        }
+
+    .. code-block:: annotation
 
         <?php
 
@@ -25,23 +52,23 @@ instead of simply adding the respective columns to the ``User`` class.
         class User
         {
             /** @Embedded(class = "Address") */
-            private $address;
+            private Address $address;
         }
 
         /** @Embeddable */
         class Address
         {
             /** @Column(type = "string") */
-            private $street;
+            private string $street;
 
             /** @Column(type = "string") */
-            private $postalCode;
+            private string $postalCode;
 
             /** @Column(type = "string") */
-            private $city;
+            private string $city;
 
             /** @Column(type = "string") */
-            private $country;
+            private string $country;
         }
 
     .. code-block:: xml
@@ -109,7 +136,18 @@ The following example shows you how to set your prefix to ``myPrefix_``:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+
+        #[Entity]
+        class User
+        {
+            #[Embedded(class: Address::class, columnPrefix: "myPrefix_")]
+            private Address $address;
+        }
+
+    .. code-block:: annotation
 
         <?php
 
@@ -140,7 +178,18 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+
+        #[Entity]
+        class User
+        {
+            #[Embedded(class: Address::class, columnPrefix: false)]
+            private Address $address;
+        }
+
+    .. code-block:: annotation
 
         <?php
 
@@ -148,9 +197,15 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
         class User
         {
             /** @Embedded(class = "Address", columnPrefix = false) */
-            private $address;
+            private Address $address;
         }
 
+    .. code-block:: xml
+
+        <entity name="User">
+            <embedded name="address" class="Address" use-column-prefix="false" />
+        </entity>
+
     .. code-block:: yaml
 
         User:
@@ -160,12 +215,6 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
               class: Address
               columnPrefix: false
 
-    .. code-block:: xml
-
-        <entity name="User">
-            <embedded name="address" class="Address" use-column-prefix="false" />
-        </entity>
-
 
 DQL
 ---
@@ -176,4 +225,3 @@ as if they were declared in the ``User`` class:
 .. code-block:: sql
 
     SELECT u FROM User u WHERE u.address.city = :myCity
-

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

@@ -18,6 +18,7 @@ can be called without triggering a full load of the collection:
 -  ``Collection#containsKey($key)``
 -  ``Collection#count()``
 -  ``Collection#get($key)``
+-  ``Collection#isEmpty()``
 -  ``Collection#slice($offset, $length = null)``
 
 For each of the above methods the following semantics apply:
@@ -40,7 +41,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.
 
 
@@ -52,7 +53,20 @@ switch to extra lazy as shown in these examples:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        namespace Doctrine\Tests\Models\CMS;
+
+        #[Entity]
+        class CmsGroup
+        {
+            /** @var Collection<int, CmsUser> */
+            #[ManyToMany(targetEntity: CmsUser::class, mappedBy: 'groups', fetch: 'EXTRA_LAZY')]
+            public Collection $users;
+        }
+
+    .. code-block:: annotation
 
         <?php
         namespace Doctrine\Tests\Models\CMS;
@@ -64,16 +78,17 @@ switch to extra lazy as shown in these examples:
         {
             /**
              * @ManyToMany(targetEntity="CmsUser", mappedBy="groups", fetch="EXTRA_LAZY")
+             * @var Collection<int, CmsUser>
              */
-            public $users;
+            public Collection $users;
         }
 
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\CMS\CmsGroup">
@@ -92,4 +107,3 @@ switch to extra lazy as shown in these examples:
               targetEntity: CmsUser
               mappedBy: groups
               fetch: EXTRA_LAZY
-

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

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

docs/en/tutorials/getting-started.rst

@@ -18,7 +18,7 @@ before. There are some prerequisites for the tutorial that have to be
 installed:
 
 - PHP (latest stable version)
-- Composer Package Manager (`Install Composer
+- Composer Package Manager (\ `Install Composer
   <https://getcomposer.org/doc/00-intro.md>`_)
 
 The code of this tutorial is `available on Github <https://github.com/doctrine/doctrine2-orm-tutorial>`_.
@@ -43,14 +43,15 @@ What are Entities?
 
 Entities are PHP Objects that can be identified over many requests
 by a unique identifier or primary key. These classes don't need to extend any
-abstract base class or interface. An entity class must not be final
-or contain final methods. Additionally it must not implement
-**clone** nor **wakeup**, unless it :doc:`does so safely <../cookbook/implementing-wakeup-or-clone>`.
+abstract base class or interface.
 
 An entity contains persistable properties. A persistable property
 is an instance variable of the entity that is saved into and retrieved from the database
 by Doctrine's data mapping capabilities.
 
+An entity class must not be final nor read-only, although
+it can contain final methods or read-only properties.
+
 An Example Model: Bug Tracker
 -----------------------------
 
@@ -81,9 +82,10 @@ that directory with the following contents:
 
     {
         "require": {
-            "doctrine/orm": "^2.6.2",
-            "symfony/yaml": "2.*",
-            "symfony/cache": "^5.3"
+            "doctrine/orm": "^2.11.0",
+            "doctrine/dbal": "^3.2",
+            "symfony/yaml": "^5.4",
+            "symfony/cache": "^5.4"
         },
         "autoload": {
             "psr-0": {"": "src/"}
@@ -100,8 +102,7 @@ Install Doctrine using the Composer Dependency Management tool, by calling:
 This will install the packages Doctrine Common, Doctrine DBAL, Doctrine ORM,
 into the ``vendor`` directory.
 
-Add the following directories:
-::
+Add the following directories::
 
     doctrine2-tutorial
     |-- config
@@ -112,6 +113,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
 ---------------------------
@@ -127,43 +136,49 @@ step:
 
     <?php
     // bootstrap.php
-    use Doctrine\ORM\Tools\Setup;
+    use Doctrine\DBAL\DriverManager;
     use Doctrine\ORM\EntityManager;
+    use Doctrine\ORM\ORMSetup;
 
     require_once "vendor/autoload.php";
 
-    // Create a simple "default" Doctrine ORM configuration for Annotations
-    $isDevMode = true;
-    $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);
+    // Create a simple "default" Doctrine ORM configuration for Attributes
+    $config = ORMSetup::createAttributeMetadataConfiguration(
+        paths: [__DIR__ . '/src'],
+        isDevMode: true,
+    );
+    // or if you prefer annotation, YAML or XML
+    // $config = ORMSetup::createAnnotationMetadataConfiguration(
+    //    paths: array(__DIR__."/src"),
+    //    isDevMode: true,
+    // );
+    // $config = ORMSetup::createXMLMetadataConfiguration(
+    //    paths: [__DIR__ . '/config/xml'],
+    //    isDevMode: true,
+    //);
+    // $config = ORMSetup::createYAMLMetadataConfiguration(
+    //    paths: array(__DIR__."/config/yaml"),
+    //    isDevMode: true,
+    // );
 
-    // database configuration parameters
-    $conn = array(
+    // configuring the database connection
+    $connection = DriverManager::getConnection([
         'driver' => 'pdo_sqlite',
         'path' => __DIR__ . '/db.sqlite',
-    );
+    ], $config);
 
     // obtaining the entity manager
-    $entityManager = EntityManager::create($conn, $config);
+    $entityManager = new EntityManager($connection, $config);
 
 .. note::
     The YAML driver is deprecated and will be removed in version 3.0.
     It is strongly recommended to switch to one of the other mappings.
 
-.. note::
-    It is recommended not to use the SimpleAnnotationReader because its
-    usage will be removed for version 3.0.
-
 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>`.
@@ -181,22 +196,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
@@ -208,14 +236,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,
@@ -233,14 +261,8 @@ entity definition:
     // src/Product.php
     class Product
     {
-        /**
-         * @var int
-         */
-        private $id;
-        /**
-         * @var string
-         */
-        private $name;
+        private int|null $id = null;
+        private string $name;
     }
 
 When creating entity classes, all of the fields should be ``private``.
@@ -299,7 +321,7 @@ data in your storage, and later in your application when the data is loaded agai
 .. note::
 
     This method, although very common, is inappropriate for Domain Driven
-    Design (`DDD <https://en.wikipedia.org/wiki/Domain-driven_design>`)
+    Design (\ `DDD <https://en.wikipedia.org/wiki/Domain-driven_design>`_)
     where methods should represent real business operations and not simple
     property change, And business invariants should be maintained both in the
     application state (entities in this case) and in the database, with no
@@ -426,7 +448,7 @@ entity.
 
 .. note::
 
-    A `DTO <https://en.wikipedia.org/wiki/Data_transfer_object>` is an object
+    A `DTO <https://en.wikipedia.org/wiki/Data_transfer_object>`_ is an object
     that only carries data without any logic. Its only goal is to be transferred
     from one service to another.
     A ``DTO`` often represents data sent by a client and that has to be validated,
@@ -477,14 +499,35 @@ 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
-Started guide will demonstrate metadata mappings using all three methods,
-but you only need to choose one.
+Metadata for an Entity can be configured using attributes directly in
+the Entity class itself, or in an external XML or YAML file. This
+Getting Started guide will demonstrate metadata mappings using all three
+methods, but you only need to choose one.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        // src/Product.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        #[ORM\Entity]
+        #[ORM\Table(name: 'products')]
+        class Product
+        {
+            #[ORM\Id]
+            #[ORM\Column(type: 'integer')]
+            #[ORM\GeneratedValue]
+            private int|null $id = null;
+            #[ORM\Column(type: 'string')]
+            private string $name;
+
+            // .. (other code)
+        }
+
+    .. code-block:: annotation
 
         <?php
         // src/Product.php
@@ -502,11 +545,11 @@ but you only need to choose one.
              * @ORM\Column(type="integer")
              * @ORM\GeneratedValue
              */
-            private $id;
+            private int|null $id = null;
             /**
              * @ORM\Column(type="string")
              */
-            private $name;
+            private string $name;
 
             // .. (other code)
         }
@@ -514,10 +557,10 @@ but you only need to choose one.
     .. code-block:: xml
 
         <!-- config/xml/Product.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Product" table="products">
                   <id name="id" type="integer">
@@ -561,7 +604,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.
@@ -642,7 +685,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
@@ -685,49 +728,35 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
 
     use Doctrine\ORM\Mapping as ORM;
 
-    /**
-     * @ORM\Entity
-     * @ORM\Table(name="bugs")
-     */
+    #[ORM\Entity]
+    #[ORM\Table(name: 'bugs')]
     class Bug
     {
-        /**
-         * @ORM\Id
-         * @ORM\Column(type="integer")
-         * @ORM\GeneratedValue
-         * @var int
-         */
-        private $id;
+        #[ORM\Id]
+        #[ORM\Column(type: 'integer')]
+        #[ORM\GeneratedValue]
+        private int|null $id;
 
-        /**
-         * @ORM\Column(type="string")
-         * @var string
-         */
-        private $description;
+        #[ORM\Column(type: 'string')]
+        private string $description;
 
-        /**
-         * @ORM\Column(type="datetime")
-         * @var DateTime
-         */
-        private $created;
+        #[ORM\Column(type: 'datetime')]
+        private DateTime $created;
 
-        /**
-         * @ORM\Column(type="string")
-         * @var string
-         */
-        private $status;
+        #[ORM\Column(type: 'string')]
+        private string $status;
 
-        public function getId()
+        public function getId(): int|null
         {
             return $this->id;
         }
 
-        public function getDescription()
+        public function getDescription(): string
         {
             return $this->description;
         }
 
-        public function setDescription($description)
+        public function setDescription(string $description): void
         {
             $this->description = $description;
         }
@@ -737,17 +766,17 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
             $this->created = $created;
         }
 
-        public function getCreated()
+        public function getCreated(): DateTime
         {
             return $this->created;
         }
 
-        public function setStatus($status)
+        public function setStatus($status): void
         {
             $this->status = $status;
         }
 
-        public function getStatus()
+        public function getStatus():string
         {
             return $this->status;
         }
@@ -760,37 +789,31 @@ classes. We'll store them in ``src/Bug.php`` and ``src/User.php``, respectively.
 
     use Doctrine\ORM\Mapping as ORM;
 
-    /**
-     * @ORM\Entity
-     * @ORM\Table(name="users")
-     */
+    #[ORM\Entity]
+    #[ORM\Table(name: 'users')]
     class User
     {
-        /**
-         * @ORM\Id
-         * @ORM\GeneratedValue
-         * @ORM\Column(type="integer")
-         * @var int
-         */
-        private $id;
+        /** @var int */
+        #[ORM\Id]
+        #[ORM\GeneratedValue]
+        #[ORM\Column(type: 'integer')]
+        private int|null $id = null;
 
-        /**
-         * @ORM\Column(type="string")
-         * @var string
-         */
-        private $name;
+        /** @var string */
+        #[ORM\Column(type: 'string')]
+        private string $name;
 
-        public function getId()
+        public function getId(): int|null
         {
             return $this->id;
         }
 
-        public function getName()
+        public function getName(): string
         {
             return $this->name;
         }
 
-        public function setName($name)
+        public function setName(string $name): void
         {
             $this->name = $name;
         }
@@ -819,13 +842,16 @@ domain model to match the requirements:
 
     <?php
     // src/Bug.php
+
     use Doctrine\Common\Collections\ArrayCollection;
+    use Doctrine\Common\Collections\Collection;
 
     class Bug
     {
         // ... (previous code)
 
-        private $products;
+        /** @var Collection<int, Product> */
+        private Collection $products;
 
         public function __construct()
         {
@@ -843,8 +869,10 @@ domain model to match the requirements:
     {
         // ... (previous code)
 
-        private $reportedBugs;
-        private $assignedBugs;
+        /** @var Collection<int, Bug> */
+        private Collection $reportedBugs;
+        /** @var Collection<int, Bug> */
+        private Collection $assignedBugs;
 
         public function __construct()
         {
@@ -861,18 +889,6 @@ domain model to match the requirements:
     understand the changes that have happened to the collection that are
     noteworthy for persistence.
 
-.. warning::
-
-    Lazy load proxies always contain an instance of
-    Doctrine's EntityManager and all its dependencies. Therefore a
-    ``var_dump()`` will possibly dump a very large recursive structure
-    which is impossible to render and read. You have to use
-    ``Doctrine\Common\Util\Debug::dump()`` to restrict the dumping to a
-    human readable level. Additionally you should be aware that dumping
-    the EntityManager to a Browser may take several minutes, and the
-    ``Debug::dump()`` method just ignores any occurrences of it in Proxy
-    instances.
-
 Because we only work with collections for the references we must be
 careful to implement a bidirectional reference in the domain model.
 The concept of owning or inverse side of a relation is central to
@@ -919,27 +935,27 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        private $engineer;
-        private $reporter;
+        private User $engineer;
+        private User $reporter;
 
-        public function setEngineer(User $engineer)
+        public function setEngineer(User $engineer): void
         {
             $engineer->assignedToBug($this);
             $this->engineer = $engineer;
         }
 
-        public function setReporter(User $reporter)
+        public function setReporter(User $reporter): void
         {
             $reporter->addReportedBug($this);
             $this->reporter = $reporter;
         }
 
-        public function getEngineer()
+        public function getEngineer(): User
         {
             return $this->engineer;
         }
 
-        public function getReporter()
+        public function getReporter(): User
         {
             return $this->reporter;
         }
@@ -953,15 +969,17 @@ the bi-directional reference:
     {
         // ... (previous code)
 
-        private $reportedBugs;
-        private $assignedBugs;
+        /** @var Collection<int, Bug> */
+        private Collection $reportedBugs;
+        /** @var Collection<int, Bug> */
+        private Collection $assignedBugs;
 
-        public function addReportedBug(Bug $bug)
+        public function addReportedBug(Bug $bug): void
         {
             $this->reportedBugs[] = $bug;
         }
 
-        public function assignedToBug(Bug $bug)
+        public function assignedToBug(Bug $bug): void
         {
             $this->assignedBugs[] = $bug;
         }
@@ -1005,14 +1023,16 @@ the database that points from Bugs to Products.
     {
         // ... (previous code)
 
-        private $products;
+        /** @var Collection<int, Product> */
+        private Collection $products;
 
-        public function assignToProduct(Product $product)
+        public function assignToProduct(Product $product): void
         {
             $this->products[] = $product;
         }
 
-        public function getProducts()
+        /** @return Collection<int, Product> */
+        public function getProducts(): Collection
         {
             return $this->products;
         }
@@ -1023,7 +1043,46 @@ Lets add metadata mappings for the ``Bug`` entity, as we did for
 the ``Product`` before:
 
 .. configuration-block::
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        // src/Bug.php
+
+        use DateTime;
+        use Doctrine\ORM\Mapping as ORM;
+
+        #[ORM\Entity]
+        #[ORM\Table(name: 'bugs')]
+        class Bug
+        {
+            #[ORM\Id]
+            #[ORM\Column(type: 'integer')]
+            #[ORM\GeneratedValue]
+            private int|null $id = null;
+
+            #[ORM\Column(type: 'string')]
+            private string $description;
+
+            #[ORM\Column(type: 'datetime')]
+            private DateTime $created;
+
+            #[ORM\Column(type: 'string')]
+            private string $status;
+
+            #[ORM\ManyToOne(targetEntity: User::class, inversedBy: 'assignedBugs')]
+            private User|null $engineer = null;
+
+            #[ORM\ManyToOne(targetEntity: User::class, inversedBy: 'reportedBugs')]
+            private User|null $reporter;
+
+            /** @var Collection<int, Product> */
+            #[ORM\ManyToMany(targetEntity: Product::class)]
+            private Collection $products;
+
+            // ... (other code)
+        }
+
+    .. code-block:: annotation
 
         <?php
         // src/Bug.php
@@ -1041,37 +1100,37 @@ the ``Product`` before:
              * @ORM\Column(type="integer")
              * @ORM\GeneratedValue
              */
-            private $id;
+            private int|null $id = null;
 
             /**
              * @ORM\Column(type="string")
              */
-            private $description;
+            private string $description;
 
             /**
              * @ORM\Column(type="datetime")
              */
-            private $created;
+            private DateTime $created;
 
             /**
              * @ORM\Column(type="string")
              */
-            private $status;
+            private string $status;
 
             /**
              * @ORM\ManyToOne(targetEntity="User", inversedBy="assignedBugs")
              */
-            private $engineer;
+            private User|null $engineer;
 
             /**
              * @ORM\ManyToOne(targetEntity="User", inversedBy="reportedBugs")
              */
-            private $reporter;
+            private User|null $reporter;
 
             /**
              * @ORM\ManyToMany(targetEntity="Product")
              */
-            private $products;
+            private Collection $products;
 
             // ... (other code)
         }
@@ -1079,10 +1138,10 @@ the ``Product`` before:
     .. code-block:: xml
 
         <!-- config/xml/Bug.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Bug" table="bugs">
                 <id name="id" type="integer">
@@ -1140,27 +1199,57 @@ which translates the YYYY-mm-dd HH:mm:ss database format
 into a PHP DateTime instance and back.
 
 After the field definitions, the two qualified references to the
-user entity are defined. They are created by the ``many-to-one``
-tag. The class name of the related entity has to be specified with
-the ``target-entity`` attribute, which is enough information for
-the database mapper to access the foreign-table. Since
+user entity are defined. They are created by the ``ManyToOne``
+attribute. The class name of the related entity has to be specified with
+the ``targetEntity`` parameter, which is enough information for
+the database mapper to access the foreign table. Since
 ``reporter`` and ``engineer`` are on the owning side of a
-bi-directional relation, we also have to specify the ``inversed-by``
-attribute. They have to point to the field names on the inverse
-side of the relationship. We will see in the next example that the ``inversed-by``
-attribute has a counterpart ``mapped-by`` which makes that
+bi-directional relation, we also have to specify the ``inversedBy``
+parameter. They have to point to the field names on the inverse
+side of the relationship. We will see in the next example that the ``inversedBy``
+parameter has a counterpart ``mappedBy`` which makes that
 the inverse side.
 
 The last definition is for the ``Bug#products`` collection. It
 holds all products where the specific bug occurs. Again
-you have to define the ``target-entity`` and ``field`` attributes
-on the ``many-to-many`` tag.
+you have to define the ``targetEntity`` and ``field`` parameters
+on the ``ManyToMany`` attribute.
 
 Finally, we'll add metadata mappings for the ``User`` entity.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        // src/User.php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        #[ORM\Entity]
+        #[ORM\Table(name: 'users')]
+        class User
+        {
+            #[ORM\Id]
+            #[ORM\GeneratedValue]
+            #[ORM\Column(type: 'integer')]
+            private int|null $id = null;
+
+            #[ORM\Column(type: 'string')]
+            private string $name;
+
+            /** @var Collection<int, Bug> An ArrayCollection of Bug objects. */
+            #[ORM\OneToMany(targetEntity: Bug::class, mappedBy: 'reporter')]
+            private Collection $reportedBugs;
+
+            /** @var Collection<int,Bug> An ArrayCollection of Bug objects. */
+            #[ORM\OneToMany(targetEntity: Bug::class, mappedBy: 'engineer')]
+            private $assignedBugs;
+
+            // .. (other code)
+        }
+
+    .. code-block:: annotation
 
         <?php
         // src/User.php
@@ -1179,36 +1268,35 @@ Finally, we'll add metadata mappings for the ``User`` entity.
              * @ORM\Column(type="integer")
              * @var int
              */
-            private $id;
+            private int|null $id = null;
 
             /**
              * @ORM\Column(type="string")
              * @var string
              */
-            private $name;
+            private string $name;
 
             /**
              * @ORM\OneToMany(targetEntity="Bug", mappedBy="reporter")
-             * @var Bug[] An ArrayCollection of Bug objects.
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
              */
-            private $reportedBugs;
+            private Collection $reportedBugs;
 
             /**
              * @ORM\OneToMany(targetEntity="Bug", mappedBy="engineer")
-             * @var Bug[] An ArrayCollection of Bug objects.
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
              */
-            private $assignedBugs;
+            private Collection $assignedBugs;
 
             // .. (other code)
         }
-
     .. code-block:: xml
 
         <!-- config/xml/User.dcm.xml -->
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                                              https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
              <entity name="User" table="users">
                  <id name="id" type="integer">
@@ -1248,17 +1336,16 @@ Finally, we'll add metadata mappings for the ``User`` entity.
               targetEntity: Bug
               mappedBy: engineer
 
-Here are some new things to mention about the ``one-to-many`` tags.
+Here are some new things to mention about the ``OneToMany`` attribute.
 Remember that we discussed about the inverse and owning side. Now
 both reportedBugs and assignedBugs are inverse relations, which
 means the join details have already been defined on the owning
 side. Therefore we only have to specify the property on the Bug
 class that holds the owning sides.
 
-Update your database schema by running:
-::
+Update your database schema by running::
 
-    $ vendor/bin/doctrine orm:schema-tool:update --force
+    $ php bin/doctrine orm:schema-tool:update --force
 
 
 Implementing more Requirements
@@ -1334,7 +1421,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.
 
@@ -1489,39 +1576,8 @@ The output of the engineer’s name is fetched from the database! What is happen
 
 Since we only retrieved the bug by primary key both the engineer and reporter
 are not immediately loaded from the database but are replaced by LazyLoading
-proxies. These proxies will load behind the scenes, when the first method
-is called on them.
-
-Sample code of this proxy generated code can be found in the specified Proxy
-Directory, it looks like:
-
-.. code-block:: php
-
-    <?php
-    namespace MyProject\Proxies;
-
-    /**
-     * THIS CLASS WAS GENERATED BY THE DOCTRINE ORM. DO NOT EDIT THIS FILE.
-     **/
-    class UserProxy extends \User implements \Doctrine\ORM\Proxy\Proxy
-    {
-        // .. lazy load code here
-
-        public function addReportedBug($bug)
-        {
-            $this->_load();
-            return parent::addReportedBug($bug);
-        }
-
-        public function assignedToBug($bug)
-        {
-            $this->_load();
-            return parent::assignedToBug($bug);
-        }
-    }
-
-See how upon each method call the proxy is lazily loaded from the
-database?
+proxies. These proxies will load behind the scenes, when attempting to access
+any of their un-initialized state.
 
 The call prints:
 
@@ -1731,7 +1787,20 @@ we have to adjust the metadata slightly.
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        #[ORM\Entity(repositoryClass: BugRepository::class)]
+        #[ORM\Table(name: 'bugs')]
+        class Bug
+        {
+            // ...
+        }
+
+    .. code-block:: annotation
 
         <?php
 
@@ -1740,7 +1809,7 @@ we have to adjust the metadata slightly.
         /**
          * @ORM\Entity(repositoryClass="BugRepository")
          * @ORM\Table(name="bugs")
-         **/
+         */
         class Bug
         {
             // ...
@@ -1748,9 +1817,9 @@ we have to adjust the metadata slightly.
 
     .. code-block:: xml
 
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
               <entity name="Bug" table="bugs" repository-class="BugRepository">

docs/en/tutorials/ordered-associations.rst

@@ -5,28 +5,42 @@ There are use-cases when you'll want to sort collections when they are
 retrieved from the database. In userland you do this as long as you
 haven't initially saved an entity with its associations into the
 database. To retrieve a sorted collection from the database you can
-use the ``@OrderBy`` annotation with a collection that specifies
+use the ``#[OrderBy]`` attribute with a collection that specifies
 a DQL snippet that is appended to all queries with this
 collection.
 
-Additional to any ``@OneToMany`` or ``@ManyToMany`` annotation you
-can specify the ``@OrderBy`` in the following way:
+Additional to any ``#[OneToMany]`` or ``#[ManyToMany]`` attribute you
+can specify the ``#[OrderBy]`` in the following way:
 
 .. configuration-block::
 
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        #[Entity]
+        class User
+        {
+            // ...
+
+            #[ManyToMany(targetEntity: Group::class)]
+            #[OrderBy(["name" => "ASC"])]
+            private Collection $groups;
+        }
+
+    .. code-block:: annotation
 
         <?php
         /** @Entity **/
         class User
         {
             // ...
-        
+
             /**
              * @ManyToMany(targetEntity="Group")
              * @OrderBy({"name" = "ASC"})
-             **/
-            private $groups;
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
         }
 
     .. code-block:: xml
@@ -62,7 +76,7 @@ The DQL Snippet in OrderBy is only allowed to consist of
 unqualified, unquoted field names and of an optional ASC/DESC
 positional statement. Multiple Fields are separated by a comma (,).
 The referenced field names have to exist on the ``targetEntity``
-class of the ``@ManyToMany`` or ``@OneToMany`` annotation.
+class of the ``#[ManyToMany]`` or ``#[OneToMany]`` attribute.
 
 The semantics of this feature can be described as follows:
 
@@ -106,5 +120,3 @@ You can reverse the order with an explicit DQL ORDER BY:
 .. code-block:: sql
 
     SELECT u, g FROM User u JOIN u.groups g WHERE u.id = 10 ORDER BY g.name DESC, g.name ASC
-
-

docs/en/tutorials/override-field-association-mappings-in-subclasses.rst

@@ -9,52 +9,46 @@ i.e. attributes and associations metadata in particular. The example here shows
 the overriding of a class that uses a trait but is similar when extending a base
 class as shown at the end of this tutorial.
 
-Suppose we have a class ExampleEntityWithOverride. This class uses trait ExampleTrait:
+Suppose we have a class ``ExampleEntityWithOverride``. This class uses trait ``ExampleTrait``:
 
 .. code-block:: php
 
     <?php
-    /**
-     * @Entity
-     *
-     * @AttributeOverrides({
-     *      @AttributeOverride(name="foo",
-     *          column=@Column(
-     *              name     = "foo_overridden",
-     *              type     = "integer",
-     *              length   = 140,
-     *              nullable = false,
-     *              unique   = false
-     *          )
-     *      )
-     * })
-     *
-     * @AssociationOverrides({
-     *      @AssociationOverride(name="bar",
-     *          joinColumns=@JoinColumn(
-     *              name="example_entity_overridden_bar_id", referencedColumnName="id"
-     *          )
-     *      )
-     * })
-     */
+
+    #[Entity]
+    #[AttributeOverrides([
+        new AttributeOverride('foo', new Column(
+            name: 'foo_overridden',
+            type: 'integer',
+            length: 140,
+            nullable: false,
+            unique: false,
+        )),
+    ])]
+    #[AssociationOverrides([
+        new AssociationOverride('bar', [
+            new JoinColumn(
+                name: 'example_entity_overridden_bar_id',
+                referencedColumnName: 'id',
+            ),
+        ]),
+    ])]
     class ExampleEntityWithOverride
     {
         use ExampleTrait;
     }
 
-    /**
-     * @Entity
-     */
+    #[Entity]
     class Bar
     {
-        /** @Id @Column(type="string") */
+        #[Id, Column(type: 'string')]
         private $id;
     }
 
-The docblock is showing metadata override of the attribute and association type. It
+``#[AttributeOverrides]`` contains metadata override of the attribute and association type. It
 basically changes the names of the columns mapped for a property ``foo`` and for
 the association ``bar`` which relates to Bar class shown above. Here is the trait
-which has mapping metadata that is overridden by the annotation above:
+which has mapping metadata that is overridden by the attribute above:
 
 .. code-block:: php
 
@@ -64,19 +58,15 @@ which has mapping metadata that is overridden by the annotation above:
      */
     trait ExampleTrait
     {
-        /** @Id @Column(type="string") */
-        private $id;
+        #[Id, Column(type: 'integer')]
+        private int|null $id = null;
 
-        /**
-         * @Column(name="trait_foo", type="integer", length=100, nullable=true, unique=true)
-         */
-        protected $foo;
+        #[Column(name: 'trait_foo', type: 'integer', length: 100, nullable: true, unique: true)]
+        protected int $foo;
 
-        /**
-         * @OneToOne(targetEntity="Bar", cascade={"persist", "merge"})
-         * @JoinColumn(name="example_trait_bar_id", referencedColumnName="id")
-         */
-        protected $bar;
+        #[OneToOne(targetEntity: Bar::class, cascade: ['persist', 'merge'])]
+        #[JoinColumn(name: 'example_trait_bar_id', referencedColumnName: 'id')]
+        protected Bar|null $bar = null;
     }
 
 The case for just extending a class would be just the same but:

docs/en/tutorials/pagination.rst

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

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

@@ -23,6 +23,7 @@ Mapping Indexed Associations
 
 You can map indexed associations by adding:
 
+    * ``indexBy`` argument to any ``#[OneToMany]`` or ``#[ManyToMany]`` attribute.
     * ``indexBy`` attribute to any ``@OneToMany`` or ``@ManyToMany`` annotation.
     * ``index-by`` attribute to any ``<one-to-many />`` or ``<many-to-many />`` xml element.
     * ``indexBy:`` key-value pair to any association defined in ``manyToMany:`` or ``oneToMany:`` YAML mapping files.
@@ -30,109 +31,18 @@ You can map indexed associations by adding:
 The code and mappings for the Market entity looks like this:
 
 .. configuration-block::
-    .. code-block:: php
+    .. literalinclude:: working-with-indexed-associations/Market.php
+        :language: attribute
 
-        <?php
-        namespace Doctrine\Tests\Models\StockExchange;
+    .. literalinclude:: working-with-indexed-associations/Market-annotations.php
+        :language: annotation
 
-        use Doctrine\Common\Collections\ArrayCollection;
+    .. literalinclude:: working-with-indexed-associations/market.xml
+        :language: xml
 
-        /**
-         * @Entity
-         * @Table(name="exchange_markets")
-         */
-        class Market
-        {
-            /**
-             * @Id @Column(type="integer") @GeneratedValue
-             * @var int
-             */
-            private $id;
+    .. literalinclude:: working-with-indexed-associations/market.yaml
+        :language: yaml
 
-            /**
-             * @Column(type="string")
-             * @var string
-             */
-            private $name;
-
-            /**
-             * @OneToMany(targetEntity="Stock", mappedBy="market", indexBy="symbol")
-             * @var Stock[]
-             */
-            private $stocks;
-
-            public function __construct($name)
-            {
-                $this->name = $name;
-                $this->stocks = new ArrayCollection();
-            }
-
-            public function getId()
-            {
-                return $this->id;
-            }
-
-            public function getName()
-            {
-                return $this->name;
-            }
-
-            public function addStock(Stock $stock)
-            {
-                $this->stocks[$stock->getSymbol()] = $stock;
-            }
-
-            public function getStock($symbol)
-            {
-                if (!isset($this->stocks[$symbol])) {
-                    throw new \InvalidArgumentException("Symbol is not traded on this market.");
-                }
-
-                return $this->stocks[$symbol];
-            }
-
-            public function getStocks()
-            {
-                return $this->stocks->toArray();
-            }
-        }
-
-    .. 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="Doctrine\Tests\Models\StockExchange\Market">
-                <id name="id" type="integer">
-                    <generator strategy="AUTO" />
-                </id>
-
-                <field name="name" type="string"/>
-
-                <one-to-many target-entity="Stock" mapped-by="market" field="stocks" index-by="symbol" />
-            </entity>
-        </doctrine-mapping>
-
-    .. code-block:: yaml
-
-        Doctrine\Tests\Models\StockExchange\Market:
-          type: entity
-          id:
-            id:
-              type: integer
-              generator:
-                strategy: AUTO
-          fields:
-            name:
-              type:string
-          oneToMany:
-            stocks:
-              targetEntity: Stock
-              mappedBy: market
-              indexBy: symbol
 
 Inside the ``addStock()`` method you can see how we directly set the key of the association to the symbol,
 so that we can work with the indexed association directly after invoking ``addStock()``. Inside ``getStock($symbol)``
@@ -142,7 +52,38 @@ The ``Stock`` entity doesn't contain any special instructions that are new, but
 here are the code and mappings for it:
 
 .. configuration-block::
-    .. code-block:: php
+    .. code-block:: attribute
+
+        <?php
+        namespace Doctrine\Tests\Models\StockExchange;
+
+        #[Entity]
+        #[Table(name: 'exchange_stocks')]
+        class Stock
+        {
+            #[Id, Column(type: 'integer'), GeneratedValue]
+            private int|null $id = null;
+
+            #[Column(type: 'string', unique: true)]
+            private string $symbol;
+
+            #[ManyToOne(targetEntity: Market::class, inversedBy: 'stocks')]
+            private Market|null $market;
+
+            public function __construct(string $symbol, Market $market)
+            {
+                $this->symbol = $symbol;
+                $this->market = $market;
+                $market->addStock($this);
+            }
+
+            public function getSymbol(): string
+            {
+                return $this->symbol;
+            }
+        }
+
+    .. code-block:: annotation
 
         <?php
         namespace Doctrine\Tests\Models\StockExchange;
@@ -157,18 +98,18 @@ here are the code and mappings for it:
              * @Id @GeneratedValue @Column(type="integer")
              * @var int
              */
-            private $id;
+            private int|null $id = null;
 
             /**
              * @Column(type="string", unique=true)
              */
-            private $symbol;
+            private string $symbol;
 
             /**
              * @ManyToOne(targetEntity="Market", inversedBy="stocks")
              * @var Market
              */
-            private $market;
+            private Market|null $market = null;
 
             public function __construct($symbol, Market $market)
             {
@@ -177,7 +118,7 @@ here are the code and mappings for it:
                 $market->addStock($this);
             }
 
-            public function getSymbol()
+            public function getSymbol(): string
             {
                 return $this->symbol;
             }
@@ -186,9 +127,9 @@ here are the code and mappings for it:
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="https://doctrine-project.org/schemas/orm/doctrine-mapping"
+        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
               xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="https://doctrine-project.org/schemas/orm/doctrine-mapping
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
             <entity name="Doctrine\Tests\Models\StockExchange\Stock">
@@ -249,7 +190,7 @@ now query for the market:
     // $em is the EntityManager
     $marketId = 1;
     $symbol = "AAPL";
-    
+
     $market = $em->find("Doctrine\Tests\Models\StockExchange\Market", $marketId);
 
     // Access the stocks by symbol now:

docs/en/tutorials/working-with-indexed-associations/Market-annotations.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Doctrine\Tests\Models\StockExchange;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Entity;
+use Doctrine\ORM\Mapping\GeneratedValue;
+use Doctrine\ORM\Mapping\Id;
+use Doctrine\ORM\Mapping\OneToMany;
+use Doctrine\ORM\Mapping\Table;
+use InvalidArgumentException;
+
+/**
+ * @Entity
+ * @Table(name="exchange_markets")
+ */
+class Market
+{
+    /**
+     * @Id @Column(type="integer") @GeneratedValue
+     * @var int
+     */
+    private int|null $id = null;
+
+    /**
+     * @Column(type="string")
+     * @var string
+     */
+    private string $name;
+
+    /**
+     * @OneToMany(targetEntity="Stock", mappedBy="market", indexBy="symbol")
+     * @var Collection<int, Stock>
+     */
+    private Collection $stocks;
+
+    public function __construct($name)
+    {
+        $this->name = $name;
+        $this->stocks = new ArrayCollection();
+    }
+
+    public function getId(): int|null
+    {
+        return $this->id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function addStock(Stock $stock): void
+    {
+        $this->stocks[$stock->getSymbol()] = $stock;
+    }
+
+    public function getStock($symbol): Stock
+    {
+        if (!isset($this->stocks[$symbol])) {
+            throw new InvalidArgumentException("Symbol is not traded on this market.");
+        }
+
+        return $this->stocks[$symbol];
+    }
+
+    /** @return array<string, Stock> */
+    public function getStocks(): array
+    {
+        return $this->stocks->toArray();
+    }
+}

docs/en/tutorials/working-with-indexed-associations/Market.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\Models\StockExchange;
+
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping\Column;
+use Doctrine\ORM\Mapping\Entity;
+use Doctrine\ORM\Mapping\GeneratedValue;
+use Doctrine\ORM\Mapping\Id;
+use Doctrine\ORM\Mapping\OneToMany;
+use Doctrine\ORM\Mapping\Table;
+use InvalidArgumentException;
+
+#[Entity]
+#[Table(name: 'exchange_markets')]
+class Market
+{
+    #[Id]
+    #[Column(type: 'integer')]
+    #[GeneratedValue]
+    private int|null $id = null;
+
+    #[Column(type: 'string')]
+    private string $name;
+
+    /** @var Collection<string, Stock> */
+    #[OneToMany(targetEntity: Stock::class, mappedBy: 'market', indexBy: 'symbol')]
+    private Collection $stocks;
+
+    public function __construct(string $name)
+    {
+        $this->name   = $name;
+        $this->stocks = new ArrayCollection();
+    }
+
+    public function getId(): int|null
+    {
+        return $this->id;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function addStock(Stock $stock): void
+    {
+        $this->stocks[$stock->getSymbol()] = $stock;
+    }
+
+    public function getStock(string $symbol): Stock
+    {
+        if (! isset($this->stocks[$symbol])) {
+            throw new InvalidArgumentException('Symbol is not traded on this market.');
+        }
+
+        return $this->stocks[$symbol];
+    }
+
+    /** @return array<string, Stock> */
+    public function getStocks(): array
+    {
+        return $this->stocks->toArray();
+    }
+}

docs/en/tutorials/working-with-indexed-associations/market.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+      xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+			  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+    <entity name="Doctrine\Tests\Models\StockExchange\Market">
+	<id name="id" type="integer">
+	    <generator strategy="AUTO" />
+	</id>
+
+	<field name="name" type="string"/>
+
+	<one-to-many target-entity="Stock" mapped-by="market" field="stocks" index-by="symbol" />
+    </entity>
+</doctrine-mapping>

docs/en/tutorials/working-with-indexed-associations/market.yaml

@@ -0,0 +1,15 @@
+Doctrine\Tests\Models\StockExchange\Market:
+  type: entity
+  id:
+    id:
+      type: integer
+      generator:
+        strategy: AUTO
+  fields:
+    name:
+      type:string
+  oneToMany:
+    stocks:
+      targetEntity: Stock
+      mappedBy: market
+      indexBy: symbol

doctrine-mapping.xsd

@@ -18,13 +18,17 @@
         <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:choice>
+      <xs:anyAttribute namespace="##other"/>
     </xs:complexType>
   </xs:element>
 
   <xs:complexType name="emptyType">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="cascade-type">
@@ -35,7 +39,9 @@
       <xs:element name="cascade-remove" type="orm:emptyType" minOccurs="0"/>
       <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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:simpleType name="lifecycle-callback-type">
@@ -61,15 +67,19 @@
 
   <xs:complexType name="lifecycle-callback">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </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: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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="named-query">
@@ -88,6 +98,7 @@
   <xs:complexType name="named-native-query">
     <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:choice>
     <xs:attribute name="name" type="xs:string" use="required" />
     <xs:attribute name="result-class" type="orm:fqcn" />
@@ -97,12 +108,14 @@
   <xs:complexType name="named-native-queries">
     <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:choice>
   </xs:complexType>
 
   <xs:complexType name="entity-listener">
     <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:choice>
     <xs:attribute name="class" type="orm:fqcn"/>
   </xs:complexType>
@@ -136,6 +149,7 @@
             <xs:element name="entity-result" type="orm:entity-result"/>
             <xs:element name="column-result" type="orm:column-result"/>
         </xs:choice>
+        <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:string" use="required" />
   </xs:complexType>
@@ -173,6 +187,7 @@
       <xs:element name="many-to-many" type="orm:many-to-many" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="association-overrides" type="orm:association-overrides" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="attribute-overrides" type="orm:attribute-overrides" minOccurs="0" maxOccurs="unbounded" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:string" use="required" />
     <xs:attribute name="table" type="orm:tablename" />
@@ -181,6 +196,7 @@
     <xs:attribute name="inheritance-type" type="orm:inheritance-type"/>
     <xs:attribute name="change-tracking-policy" type="orm:change-tracking-policy" />
     <xs:attribute name="read-only" type="xs:boolean" default="false" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:simpleType name="tablename" id="tablename">
@@ -193,31 +209,29 @@
   <xs:complexType name="option" mixed="true">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="option" type="orm:option"/>
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required"/>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="options">
     <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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="mapped-superclass" >
     <xs:complexContent>
-      <xs:extension base="orm:entity">
-        <xs:choice minOccurs="0" maxOccurs="unbounded">
-        </xs:choice>
-      </xs:extension>
+      <xs:extension base="orm:entity"/>
     </xs:complexContent>
   </xs:complexType>
 
   <xs:complexType name="embeddable">
     <xs:complexContent>
-      <xs:extension base="orm:entity">
-        <xs:choice minOccurs="0" maxOccurs="unbounded">
-        </xs:choice>
-      </xs:extension>
+      <xs:extension base="orm:entity"/>
     </xs:complexContent>
   </xs:complexType>
 
@@ -264,20 +278,34 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="generated-type">
+    <xs:restriction base="xs:token">
+      <xs:enumeration value="NEVER"/>
+      <xs:enumeration value="INSERT"/>
+      <xs:enumeration value="ALWAYS"/>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="field">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
-    <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
-    <xs:attribute name="column" type="xs:NMTOKEN" />
+    <xs:attribute name="type" type="orm:type" default="string" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <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" />
     <xs:attribute name="scale" type="xs:integer" use="optional" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="embedded">
@@ -292,62 +320,80 @@
 
   <xs:complexType name="discriminator-column">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:element name="options" type="orm:options" minOccurs="0" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="type" type="xs:NMTOKEN"/>
     <xs:attribute name="field-name" type="xs:NMTOKEN" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="column-definition" type="xs:string" />
+    <xs:attribute name="enum-type" type="xs:string" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="unique-constraint">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional"/>
     <xs:attribute name="columns" type="xs:string" use="optional"/>
     <xs:attribute name="fields" type="xs:string" use="optional"/>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="unique-constraints">
     <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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="index">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="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: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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="discriminator-mapping">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
-    <xs:attribute name="value" type="xs:NMTOKEN" use="required"/>
+    <xs:attribute name="value" type="orm:type" use="required"/>
     <xs:attribute name="class" type="orm:fqcn" use="required"/>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="discriminator-map">
     <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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="generator">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="strategy" type="orm:generator-strategy" use="optional" default="AUTO" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="id">
@@ -356,25 +402,30 @@
       <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: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="type" type="orm:type" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="association-key" type="xs:boolean" default="false" />
     <xs:attribute name="column-definition" type="xs:string" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="sequence-generator">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </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" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="custom-id-generator">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="class" type="orm:fqcn" use="required" />
   </xs:complexType>
@@ -386,14 +437,24 @@
     </xs:restriction>
   </xs:simpleType>
 
+  <xs:simpleType name="type" id="type">
+    <xs:restriction base="xs:token">
+      <xs:pattern value="([a-zA-Z_u01-uff][a-zA-Z0-9_u01-uff]+)|(\c+)" id="type.class.pattern">
+      </xs:pattern>
+    </xs:restriction>
+  </xs:simpleType>
+
   <xs:complexType name="inverse-join-columns">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="join-column" type="orm:join-column" minOccurs="1" maxOccurs="unbounded" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="join-column">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="optional" />
     <xs:attribute name="referenced-column-name" type="xs:NMTOKEN" use="optional" default="id" />
@@ -401,34 +462,43 @@
     <xs:attribute name="nullable" type="xs:boolean" default="true" />
     <xs:attribute name="on-delete" type="orm:fk-action" />
     <xs:attribute name="column-definition" type="xs:string" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="join-columns">
     <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:choice>
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="join-table">
     <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: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: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:choice>
+      <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="order-by-field">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </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"/>
   </xs:complexType>
 
   <xs:simpleType name="order-by-direction">
@@ -438,12 +508,19 @@
     </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: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:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" use="required" />
@@ -452,6 +529,7 @@
     <xs:attribute name="index-by" type="xs:NMTOKEN" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />
     <xs:attribute name="orphan-removal" type="xs:boolean" default="false" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="one-to-many">
@@ -459,6 +537,7 @@
        <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:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" use="required" />
@@ -466,6 +545,7 @@
     <xs:attribute name="index-by" type="xs:NMTOKEN" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />
     <xs:attribute name="orphan-removal" type="xs:boolean" default="false" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="many-to-one">
@@ -476,11 +556,13 @@
         <xs:element name="join-column" type="orm:join-column"/>
         <xs:element name="join-columns" type="orm:join-columns"/>
       </xs:choice>
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </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" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="one-to-one">
@@ -491,6 +573,7 @@
         <xs:element name="join-column" type="orm:join-column"/>
         <xs:element name="join-columns" type="orm:join-columns"/>
       </xs:choice>
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
     <xs:attribute name="field" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="target-entity" type="xs:string" />
@@ -498,11 +581,13 @@
     <xs:attribute name="inversed-by" type="xs:NMTOKEN" />
     <xs:attribute name="fetch" type="orm:fetch-type" default="LAZY" />
     <xs:attribute name="orphan-removal" type="xs:boolean" default="false" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
   <xs:complexType name="association-overrides">
     <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:choice>
   </xs:complexType>
 
@@ -511,6 +596,7 @@
       <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:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
     <xs:attribute name="fetch" type="orm:fetch-type" use="optional" />
@@ -523,12 +609,14 @@
   <xs:complexType name="attribute-overrides">
     <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:choice>
   </xs:complexType>
 
   <xs:complexType name="attribute-override">
     <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:choice>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required" />
   </xs:complexType>
@@ -536,16 +624,20 @@
   <xs:complexType name="attribute-override-field">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="options" type="orm:options" minOccurs="0" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
-    <xs:attribute name="type" type="xs:NMTOKEN" default="string" />
-    <xs:attribute name="column" type="xs:NMTOKEN" />
+    <xs:attribute name="type" type="orm:type" default="string" />
+    <xs:attribute name="column" type="orm:columntoken" />
     <xs:attribute name="length" type="xs:NMTOKEN" />
     <xs:attribute name="unique" type="xs:boolean" default="false" />
     <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" />
     <xs:attribute name="scale" type="xs:integer" use="optional" />
+    <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
 </xs:schema>

lib/Doctrine/ORM/Cache/CacheKey.php

@@ -1,19 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Cache;
-
-/**
- * Defines entity / collection / query key to be stored in the cache region.
- * Allows multiple roles to be stored in the same cache region.
- */
-abstract class CacheKey
-{
-    /**
-     * READ-ONLY: Public only for performance reasons, it should be considered immutable.
-     *
-     * @var string Unique identifier
-     */
-    public $hash;
-}

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

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

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

@@ -1,150 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Cache\Region;
-
-use BadMethodCallException;
-use Doctrine\Common\Cache\Cache as CacheAdapter;
-use Doctrine\Common\Cache\CacheProvider;
-use Doctrine\Common\Cache\ClearableCache;
-use Doctrine\ORM\Cache\CacheEntry;
-use Doctrine\ORM\Cache\CacheKey;
-use Doctrine\ORM\Cache\CollectionCacheEntry;
-use Doctrine\ORM\Cache\Lock;
-use Doctrine\ORM\Cache\Region;
-
-use function get_class;
-use function sprintf;
-
-/**
- * The simplest cache region compatible with all doctrine-cache drivers.
- */
-class DefaultRegion implements Region
-{
-    public const REGION_KEY_SEPARATOR = '_';
-
-    /** @var CacheAdapter */
-    protected $cache;
-
-    /** @var string */
-    protected $name;
-
-    /** @var int */
-    protected $lifetime = 0;
-
-    /**
-     * @param string $name
-     * @param int    $lifetime
-     */
-    public function __construct($name, CacheAdapter $cache, $lifetime = 0)
-    {
-        $this->cache    = $cache;
-        $this->name     = (string) $name;
-        $this->lifetime = (int) $lifetime;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getName()
-    {
-        return $this->name;
-    }
-
-    /**
-     * @return CacheProvider
-     */
-    public function getCache()
-    {
-        return $this->cache;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function contains(CacheKey $key)
-    {
-        return $this->cache->contains($this->getCacheEntryKey($key));
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function get(CacheKey $key)
-    {
-        $entry = $this->cache->fetch($this->getCacheEntryKey($key));
-
-        if (! $entry instanceof CacheEntry) {
-            return null;
-        }
-
-        return $entry;
-    }
-
-    /**
-     * {@inheritdoc}
-     */
-    public function getMultiple(CollectionCacheEntry $collection)
-    {
-        $result = [];
-
-        foreach ($collection->identifiers as $key) {
-            $entryKey   = $this->getCacheEntryKey($key);
-            $entryValue = $this->cache->fetch($entryKey);
-
-            if (! $entryValue instanceof CacheEntry) {
-                return null;
-            }
-
-            $result[] = $entryValue;
-        }
-
-        return $result;
-    }
-
-    /**
-     * @return string
-     */
-    protected function getCacheEntryKey(CacheKey $key)
-    {
-        return $this->name . self::REGION_KEY_SEPARATOR . $key->hash;
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @return bool
-     */
-    public function put(CacheKey $key, CacheEntry $entry, ?Lock $lock = null)
-    {
-        return $this->cache->save($this->getCacheEntryKey($key), $entry, $this->lifetime);
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @return bool
-     */
-    public function evict(CacheKey $key)
-    {
-        return $this->cache->delete($this->getCacheEntryKey($key));
-    }
-
-    /**
-     * {@inheritdoc}
-     *
-     * @return bool
-     */
-    public function evictAll()
-    {
-        if (! $this->cache instanceof ClearableCache) {
-            throw new BadMethodCallException(sprintf(
-                'Clearing all cache entries is not supported by the supplied cache adapter of type %s',
-                get_class($this->cache)
-            ));
-        }
-
-        return $this->cache->deleteAll();
-    }
-}

lib/Doctrine/ORM/Event/LifecycleEventArgs.php

@@ -1,37 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Event;
-
-use Doctrine\ORM\EntityManager;
-use Doctrine\Persistence\Event\LifecycleEventArgs as BaseLifecycleEventArgs;
-
-/**
- * Lifecycle Events are triggered by the UnitOfWork during lifecycle transitions
- * of entities.
- *
- * @link   www.doctrine-project.org
- */
-class LifecycleEventArgs extends BaseLifecycleEventArgs
-{
-    /**
-     * Retrieves associated Entity.
-     *
-     * @return object
-     */
-    public function getEntity()
-    {
-        return $this->getObject();
-    }
-
-    /**
-     * Retrieves associated EntityManager.
-     *
-     * @return EntityManager
-     */
-    public function getEntityManager()
-    {
-        return $this->getObjectManager();
-    }
-}

lib/Doctrine/ORM/Event/OnFlushEventArgs.php

@@ -1,34 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Doctrine\ORM\Event;
-
-use Doctrine\Common\EventArgs;
-use Doctrine\ORM\EntityManagerInterface;
-
-/**
- * Provides event arguments for the preFlush event.
- *
- * @link        www.doctrine-project.org
- */
-class OnFlushEventArgs extends EventArgs
-{
-    /** @var EntityManagerInterface */
-    private $em;
-
-    public function __construct(EntityManagerInterface $em)
-    {
-        $this->em = $em;
-    }
-
-    /**
-     * Retrieve associated EntityManager.
-     *
-     * @return EntityManagerInterface
-     */
-    public function getEntityManager()
-    {
-        return $this->em;
-    }
-}