Merge pull request #12373 from tomme87/12225-fix-hydration-issue

12225 Fix hydration issue when using indexBy, SQL filter, and inheritance mapping

.doctrine-project.json

@@ -12,58 +12,124 @@
             "upcoming": true
         },
         {
-            "name": "3.7",
-            "branchName": "3.7.x",
-            "slug": "3.7",
+            "name": "3.2",
+            "branchName": "3.2.x",
+            "slug": "3.2",
             "upcoming": true
         },
         {
-            "name": "3.6",
-            "branchName": "3.6.x",
-            "slug": "3.6",
+            "name": "3.1",
+            "branchName": "3.1.x",
+            "slug": "3.1",
             "current": true
         },
         {
-            "name": "2.21",
-            "branchName": "2.21.x",
-            "slug": "2.21",
-            "upcoming": true
+            "name": "3.0",
+            "branchName": "3.0.x",
+            "slug": "3.0",
+            "maintained": false
         },
         {
             "name": "2.20",
             "branchName": "2.20.x",
             "slug": "2.20",
-            "maintained": true
+            "upcoming": true
         },
         {
             "name": "2.19",
+            "branchName": "2.19.x",
             "slug": "2.19",
-            "maintained": false
+            "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",
+            "maintained": false
+        },
+        {
+            "name": "2.9",
+            "branchName": "2.9.x",
+            "slug": "2.9",
+            "maintained": false
+        },
+        {
+            "name": "2.8",
+            "branchName": "2.8.x",
+            "slug": "2.8",
+            "maintained": false
+        },
+        {
+            "name": "2.7",
+            "branchName": "2.7",
+            "slug": "2.7",
+            "maintained": false
+        },
+        {
+            "name": "2.6",
+            "branchName": "2.6",
+            "slug": "2.6",
+            "maintained": false
+        },
+        {
+            "name": "2.5",
+            "branchName": "2.5",
+            "slug": "2.5",
+            "maintained": false
+        },
+        {
+            "name": "2.4",
+            "branchName": "2.4",
+            "slug": "2.4",
+            "maintained": false
         }
     ]
 }

.github/ISSUE_TEMPLATE/BC_Break.md

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

.github/ISSUE_TEMPLATE/Bug.md

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

.github/ISSUE_TEMPLATE/Feature_Request.md

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

.github/ISSUE_TEMPLATE/Support_Question.md

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

.github/dependabot.yml

@@ -1,9 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    labels:
-      - "CI"
-    target-branch: "2.20.x"

.github/workflows/coding-standards.yml

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

.github/workflows/composer-lint.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   composer-lint:
     name: "Composer Lint"
-    uses: "doctrine/.github/.github/workflows/composer-lint.yml@13.1.0"
+    uses: "doctrine/.github/.github/workflows/composer-lint.yml@14.0.0"

.github/workflows/continuous-integration.yml

@@ -9,6 +9,7 @@ on:
       - ci/**
       - composer.*
       - src/**
+      - phpunit.xml.dist
       - tests/**
   push:
     branches:
@@ -18,6 +19,7 @@ on:
       - ci/**
       - composer.*
       - src/**
+      - phpunit.xml.dist
       - tests/**
 
 env:
@@ -26,7 +28,7 @@ env:
 jobs:
   phpunit-smoke-check:
     name: >
-      SQLite -
+      SQLite - 
       ${{ format('PHP {0} - DBAL {1} - ext. {2} - proxy {3}',
         matrix.php-version || 'Ø',
         matrix.dbal-version || 'Ø',
@@ -38,6 +40,10 @@ jobs:
     strategy:
       matrix:
         php-version:
+          - "7.2"
+          - "7.3"
+          - "7.4"
+          - "8.0"
           - "8.1"
           - "8.2"
           - "8.3"
@@ -45,45 +51,24 @@ jobs:
           - "8.5"
         dbal-version:
           - "default"
-          - "3.7"
         extension:
-          - "sqlite3"
           - "pdo_sqlite"
-        deps:
-          - "highest"
-        stability:
-          - "stable"
-        native_lazy:
-          - "0"
+        proxy:
+          - "common"
         include:
-          - php-version: "8.2"
-            dbal-version: "4@dev"
+          - php-version: "8.0"
+            dbal-version: "2.13"
             extension: "pdo_sqlite"
-            stability: "stable"
-            native_lazy: "0"
           - php-version: "8.2"
-            dbal-version: "4@dev"
+            dbal-version: "3@dev"
+            extension: "pdo_sqlite"
+          - php-version: "8.2"
+            dbal-version: "default"
             extension: "sqlite3"
-            stability: "stable"
-            native_lazy: "0"
           - php-version: "8.1"
             dbal-version: "default"
-            deps: "lowest"
+            proxy: "lazy-ghost"
             extension: "pdo_sqlite"
-            stability: "stable"
-            native_lazy: "0"
-          - php-version: "8.4"
-            dbal-version: "default"
-            deps: "highest"
-            extension: "pdo_sqlite"
-            stability: "stable"
-            native_lazy: "1"
-          - php-version: "8.4"
-            dbal-version: "default"
-            deps: "highest"
-            extension: "sqlite3"
-            stability: "dev"
-            native_lazy: "1"
 
     steps:
       - name: "Checkout"
@@ -99,97 +84,34 @@ jobs:
           coverage: "pcov"
           ini-values: "zend.assertions=1, apc.enable_cli=1"
 
-      - name: "Allow dev dependencies"
-        run: |
-          composer config minimum-stability dev
-          composer remove --no-update --dev phpbench/phpbench phpdocumentor/guides-cli
-          composer require --no-update symfony/console:^8 symfony/var-exporter:^8 doctrine/dbal:^4.4
-          composer require --dev --no-update symfony/cache:^8
-        if: "${{ matrix.stability == 'dev' }}"
-
       - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
         if: "${{ matrix.dbal-version != 'default' }}"
 
-      - name: "Downgrade VarExporter"
-        run: 'composer require --no-update "symfony/var-exporter:^6.4 || ^7.4"'
-        if: "${{ matrix.native_lazy == '0' }}"
-
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@v4"
         with:
           composer-options: "--ignore-platform-req=php+"
-          dependency-versions: "${{ matrix.deps }}"
 
       - name: "Run PHPUnit"
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage-no-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
-            ENABLE_NATIVE_LAZY_OBJECTS: ${{ matrix.native_lazy }}
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
-      - name: "Run PHPUnit with Second Level Cache and PHPUnit 10"
-        run: |
-          vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml \
-            --exclude-group=performance,non-cacheable,locking_functional \
-            --coverage-clover=coverage-cache.xml
-        if: "${{ matrix.php-version == '8.1' }}"
+      - name: "Run PHPUnit with Second Level Cache"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
-            ENABLE_NATIVE_LAZY_OBJECTS: ${{ matrix.native_lazy }}
-
-      - name: "Run PHPUnit with Second Level Cache and PHPUnit 11+"
-        run: |
-          vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml \
-            --exclude-group=performance \
-            --exclude-group=non-cacheable \
-            --exclude-group=locking_functional \
-            --coverage-clover=coverage-cache.xml
-        if: "${{ matrix.php-version != '8.1' }}"
-        env:
-            ENABLE_SECOND_LEVEL_CACHE: 1
-            ENABLE_NATIVE_LAZY_OBJECTS: ${{ matrix.native_lazy }}
+            ORM_PROXY_IMPLEMENTATION: "${{ matrix.proxy }}"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v6"
+        uses: "actions/upload-artifact@v7"
         with:
-          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.deps }}-${{ matrix.stability }}-${{ matrix.native_lazy }}-coverage"
+          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.proxy }}-coverage"
           path: "coverage*.xml"
 
 
-  phpunit-deprecations:
-    name: "PHPUnit (fail on deprecations)"
-    runs-on: "ubuntu-24.04"
-
-    steps:
-      -   name: "Checkout"
-          uses: "actions/checkout@v5"
-          with:
-            fetch-depth: 2
-
-      -   name: "Install PHP"
-          uses: "shivammathur/setup-php@v2"
-          with:
-            php-version: "8.5"
-            extensions: "apcu, pdo, sqlite3"
-            coverage: "pcov"
-            ini-values: "zend.assertions=1, apc.enable_cli=1"
-
-      -   name: "Allow dev dependencies"
-          run: composer config minimum-stability dev
-
-      -   name: "Install dependencies with Composer"
-          uses: "ramsey/composer-install@v3"
-          with:
-            composer-options: "--ignore-platform-req=php+"
-            dependency-versions: "highest"
-
-      -   name: "Run PHPUnit"
-          run: "vendor/bin/phpunit -c ci/github/phpunit/sqlite3.xml --fail-on-deprecation"
-          env:
-            ENABLE_SECOND_LEVEL_CACHE: 0
-            ENABLE_NATIVE_LAZY_OBJECTS: 1
-
-
   phpunit-postgres:
     name: >
       ${{ format('PostgreSQL {0} - PHP {1} - DBAL {2} - ext. {3}',
@@ -210,19 +132,19 @@ jobs:
           - "8.5"
         dbal-version:
           - "default"
-          - "3.7"
+          - "3@dev"
         postgres-version:
           - "17"
         extension:
           - pdo_pgsql
           - pgsql
         include:
-          - php-version: "8.2"
-            dbal-version: "4@dev"
+          - php-version: "8.0"
+            dbal-version: "2.13"
             postgres-version: "14"
             extension: pdo_pgsql
           - php-version: "8.2"
-            dbal-version: "3.7"
+            dbal-version: "default"
             postgres-version: "9.6"
             extension: pdo_pgsql
 
@@ -257,7 +179,7 @@ jobs:
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@v4"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -265,7 +187,7 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v6"
+        uses: "actions/upload-artifact@v7"
         with:
           name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.extension }}-coverage"
           path: "coverage.xml"
@@ -291,13 +213,17 @@ jobs:
           - "8.5"
         dbal-version:
           - "default"
-          - "3.7"
-          - "4@dev"
+          - "3@dev"
         mariadb-version:
           - "11.4"
         extension:
           - "mysqli"
           - "pdo_mysql"
+        include:
+          - php-version: "8.0"
+            dbal-version: "2.13"
+            mariadb-version: "10.6"
+            extension: "pdo_mysql"
 
     services:
       mariadb:
@@ -331,7 +257,7 @@ jobs:
           extensions: "${{ matrix.extension }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@v4"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -339,7 +265,7 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v6"
+        uses: "actions/upload-artifact@v7"
         with:
           name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage.xml"
@@ -365,7 +291,7 @@ jobs:
           - "8.5"
         dbal-version:
           - "default"
-          - "3.7"
+          - "3@dev"
         mysql-version:
           - "5.7"
           - "8.0"
@@ -373,12 +299,8 @@ jobs:
           - "mysqli"
           - "pdo_mysql"
         include:
-          - php-version: "8.2"
-            dbal-version: "4@dev"
-            mysql-version: "8.0"
-            extension: "mysqli"
-          - php-version: "8.2"
-            dbal-version: "4@dev"
+          - php-version: "8.0"
+            dbal-version: "2.13"
             mysql-version: "8.0"
             extension: "pdo_mysql"
 
@@ -413,7 +335,7 @@ jobs:
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@v4"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -422,31 +344,56 @@ jobs:
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
 
-      - name: "Run PHPUnit with Second Level Cache and PHPUnit 10"
-        run: |
-          vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml \
-            --exclude-group=performance,non-cacheable,locking_functional \
-            --coverage-clover=coverage-no-cache.xml"
-        if: "${{ matrix.php-version == '8.1' }}"
-        env:
-            ENABLE_SECOND_LEVEL_CACHE: 1
-      - name: "Run PHPUnit with Second Level Cache and PHPUnit 11+"
-        run: |
-          vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml \
-            --exclude-group=performance \
-            --exclude-group=non-cacheable \
-            --exclude-group=locking_functional \
-            --coverage-clover=coverage-no-cache.xml
-        if: "${{ matrix.php-version != '8.1' }}"
+      - name: "Run PHPUnit with Second Level Cache"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --exclude-group performance,non-cacheable,locking_functional --coverage-clover=coverage-no-cache.xml"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
 
       - name: "Upload coverage files"
-        uses: "actions/upload-artifact@v6"
+        uses: "actions/upload-artifact@v7"
         with:
           name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage*.xml"
 
+
+  phpunit-lower-php-versions:
+    name: >
+      SQLite - 
+      ${{ format('PHP {0} - deps {1}',
+        matrix.php-version || 'Ø',
+        matrix.deps || 'Ø'
+      ) }}
+    runs-on: "ubuntu-22.04"
+
+    strategy:
+      matrix:
+        php-version:
+          - "7.1"
+        deps:
+          - "highest"
+          - "lowest"
+
+    steps:
+      - name: "Checkout"
+        uses: "actions/checkout@v6"
+        with:
+          fetch-depth: 2
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          php-version: "${{ matrix.php-version }}"
+          ini-values: "zend.assertions=1, apc.enable_cli=1"
+
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v4"
+        with:
+          dependency-versions: "${{ matrix.deps }}"
+
+      - name: "Run PHPUnit"
+        run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_sqlite.xml"
+
+
   upload_coverage:
     name: "Upload coverage to Codecov"
     runs-on: "ubuntu-22.04"
@@ -465,12 +412,12 @@ jobs:
           fetch-depth: 2
 
       - name: "Download coverage files"
-        uses: "actions/download-artifact@v7"
+        uses: "actions/download-artifact@v8"
         with:
           path: "reports"
 
       - name: "Upload to Codecov"
-        uses: "codecov/codecov-action@v5"
+        uses: "codecov/codecov-action@v6"
         with:
           directory: reports
         env:

.github/workflows/documentation.yml

@@ -17,4 +17,4 @@ on:
 jobs:
   documentation:
     name: "Documentation"
-    uses: "doctrine/.github/.github/workflows/documentation.yml@13.1.0"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@14.0.0"

.github/workflows/phpbench.yml

@@ -32,7 +32,7 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - "8.1"
+          - "7.4"
 
     steps:
       - name: "Checkout"
@@ -48,7 +48,7 @@ jobs:
           ini-values: "zend.assertions=1, apc.enable_cli=1"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v3"
+        uses: "ramsey/composer-install@v4"
 
       - name: "Run PHPBench"
         run: "vendor/bin/phpbench run --report=default"

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

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

.github/workflows/stale.yml

@@ -1,24 +0,0 @@
-name: 'Close stale pull requests'
-on:
-  schedule:
-    - cron: '0 3 * * *'
-
-jobs:
-  stale:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/stale@v9
-        with:
-          stale-pr-message: >
-            There hasn't been any activity on this pull request in the past 90 days, so
-            it has been marked as stale and it will be closed automatically if no
-            further activity occurs in the next 7 days.
-
-            If you want to continue working on it, please leave a comment.
-
-          close-pr-message: >
-            This pull request was closed due to inactivity.
-
-          days-before-stale:    -1
-          days-before-pr-stale: 90
-          days-before-pr-close: 7

.github/workflows/static-analysis.yml

@@ -22,35 +22,52 @@ on:
 
 jobs:
   static-analysis-phpstan:
-    name: Static Analysis with PHPStan
-    runs-on: ubuntu-22.04
+    name: "Static Analysis with PHPStan"
+    runs-on: "ubuntu-22.04"
 
     strategy:
+      fail-fast: false
       matrix:
+        dbal-version:
+          - "default"
+        persistence-version:
+          - "default"
         include:
-        - dbal-version: default
-          config: phpstan.neon
-        - dbal-version: 3.8.2
-          config: phpstan-dbal3.neon
+          - dbal-version: "2.13"
+            persistence-version: "default"
+          - dbal-version: "default"
+            persistence-version: "2.5"
 
     steps:
       - name: "Checkout code"
         uses: "actions/checkout@v6"
 
-      - name: Install PHP
-        uses: shivammathur/setup-php@v2
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
         with:
-          coverage: none
+          coverage: "none"
           php-version: "8.4"
-          tools: cs2pr
 
-      - name: Require specific DBAL version
+      - name: "Require specific DBAL version"
         run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
         if: "${{ matrix.dbal-version != 'default' }}"
 
+      - name: "Require specific persistence version"
+        run: "composer require doctrine/persistence ^$([ ${{ matrix.persistence-version }} = default ] && echo '3.1' || echo ${{ matrix.persistence-version }}) --no-update"
 
-      - name: Install dependencies with Composer
-        uses: ramsey/composer-install@v2
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v4"
+        with:
+          dependency-versions: "highest"
 
-      - name: Run static analysis with phpstan/phpstan
-        run: "vendor/bin/phpstan analyse -c ${{ matrix.config }} --error-format=checkstyle | cs2pr"
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version == 'default'}}"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -c phpstan-dbal2.neon"
+        if: "${{ matrix.dbal-version == '2.13' }}"
+
+      - name: "Run a static analysis with phpstan/phpstan"
+        run: "vendor/bin/phpstan analyse -c phpstan-persistence2.neon"
+        if: "${{ matrix.dbal-version == 'default' && matrix.persistence-version != 'default'}}"

.github/workflows/website-schema.yml

@@ -1,21 +0,0 @@
-
-name: "Website config validation"
-
-on:
-  pull_request:
-    branches:
-      - "*.x"
-    paths:
-      - ".doctrine-project.json"
-      - ".github/workflows/website-schema.yml"
-  push:
-    branches:
-      - "*.x"
-    paths:
-      - ".doctrine-project.json"
-      - ".github/workflows/website-schema.yml"
-
-jobs:
-  json-validate:
-    name: "Validate JSON schema"
-    uses: "doctrine/.github/.github/workflows/website-schema.yml@7.1.0"

CONTRIBUTING.md

@@ -57,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/3.0.x/tests/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 @@
-|                      [4.0.x][4.0]                      |                      [3.7.x][3.7]                      |                      [3.6.x][3.6]                      |                      [2.21.x][2.21]                      |                      [2.20.x][2.20]                      |
+|                      [4.0.x][4.0]                      |                      [3.6.x][3.6]                      |                      [3.5.x][3.5]                      |                      [2.21.x][2.21]                      |                      [2.20.x][2.20]                      |
 |:------------------------------------------------------:|:------------------------------------------------------:|:------------------------------------------------------:|:--------------------------------------------------------:|:--------------------------------------------------------:|
-|       [![Build status][4.0 image]][4.0 workflow]       |       [![Build status][3.7 image]][3.7 workflow]       |       [![Build status][3.6 image]][3.6 workflow]       |       [![Build status][2.21 image]][2.21 workflow]       |       [![Build status][2.20 image]][2.20 workflow]       |
-| [![Coverage Status][4.0 coverage image]][4.0 coverage] | [![Coverage Status][3.7 coverage image]][3.7 coverage] | [![Coverage Status][3.6 coverage image]][3.6 coverage] | [![Coverage Status][2.21 coverage image]][2.21 coverage] | [![Coverage Status][2.20 coverage image]][2.20 coverage] |
+|       [![Build status][4.0 image]][4.0 workflow]       |       [![Build status][3.6 image]][3.6 workflow]       |       [![Build status][3.5 image]][3.5 workflow]       |       [![Build status][2.21 image]][2.21 workflow]       |       [![Build status][2.20 image]][2.20 workflow]       |
+| [![Coverage Status][4.0 coverage image]][4.0 coverage] | [![Coverage Status][3.6 coverage image]][3.6 coverage] | [![Coverage Status][3.5 coverage image]][3.5 coverage] | [![Coverage Status][2.21 coverage image]][2.21 coverage] | [![Coverage Status][2.20 coverage image]][2.20 coverage] |
 
-Doctrine ORM is an object-relational mapper for PHP 8.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
@@ -21,16 +23,16 @@ without requiring unnecessary code duplication.
   [4.0 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A4.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.7 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.7.x
-  [3.7]: https://github.com/doctrine/orm/tree/3.7.x
-  [3.7 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A3.7.x
-  [3.7 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.7.x/graph/badge.svg
-  [3.7 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.7.x
   [3.6 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.6.x
   [3.6]: https://github.com/doctrine/orm/tree/3.6.x
   [3.6 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A3.6.x
   [3.6 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.6.x/graph/badge.svg
   [3.6 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.6.x
+  [3.5 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.5.x
+  [3.5]: https://github.com/doctrine/orm/tree/3.5.x
+  [3.5 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A3.5.x
+  [3.5 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.5.x/graph/badge.svg
+  [3.5 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.5.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 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A2.21.x

bin/doctrine

@@ -0,0 +1,4 @@
+#!/usr/bin/env php
+<?php
+
+include(__DIR__ . '/doctrine.php');

bin/doctrine-pear.php

@@ -0,0 +1,43 @@
+<?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');
+$classLoader->register();
+
+$classLoader = new \Doctrine\Common\ClassLoader('Symfony');
+$classLoader->register();
+
+$configFile = getcwd() . DIRECTORY_SEPARATOR . 'cli-config.php';
+
+$helperSet = null;
+if (file_exists($configFile)) {
+    if ( ! is_readable($configFile)) {
+        trigger_error(
+            'Configuration file [' . $configFile . '] does not have read permission.', E_USER_ERROR
+        );
+    }
+
+    require $configFile;
+
+    foreach ($GLOBALS as $helperSetCandidate) {
+        if ($helperSetCandidate instanceof \Symfony\Component\Console\Helper\HelperSet) {
+            $helperSet = $helperSetCandidate;
+            break;
+        }
+    }
+}
+
+$helperSet = ($helperSet) ?: new \Symfony\Component\Console\Helper\HelperSet();
+
+\Doctrine\ORM\Tools\Console\ConsoleRunner::run($helperSet);

bin/doctrine.bat

@@ -0,0 +1,9 @@
+@echo off
+
+if "%PHPBIN%" == "" set PHPBIN=@php_bin@
+if not exist "%PHPBIN%" if "%PHP_PEAR_PHP_BIN%" neq "" goto USE_PEAR_PATH
+GOTO RUN
+:USE_PEAR_PATH
+set PHPBIN=%PHP_PEAR_PHP_BIN%
+:RUN
+"%PHPBIN%" "@bin_dir@\doctrine" %*

bin/doctrine.php

@@ -0,0 +1,62 @@
+<?php
+
+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'
+];
+
+foreach ($autoloadFiles as $autoloadFile) {
+    if (file_exists($autoloadFile)) {
+        require_once $autoloadFile;
+        break;
+    }
+}
+
+$directories = [getcwd(), getcwd() . DIRECTORY_SEPARATOR . 'config'];
+
+$configFile = null;
+foreach ($directories as $directory) {
+    $configFile = $directory . DIRECTORY_SEPARATOR . 'cli-config.php';
+
+    if (file_exists($configFile)) {
+        break;
+    }
+}
+
+if ( ! file_exists($configFile)) {
+    ConsoleRunner::printCliConfigTemplate();
+    exit(1);
+}
+
+if ( ! is_readable($configFile)) {
+    echo 'Configuration file [' . $configFile . '] does not have read permission.' . "\n";
+    exit(1);
+}
+
+$commands = [];
+
+$helperSet = require $configFile;
+
+if ( ! ($helperSet instanceof HelperSet)) {
+    foreach ($GLOBALS as $helperSetCandidate) {
+        if ($helperSetCandidate instanceof HelperSet) {
+            $helperSet = $helperSetCandidate;
+            break;
+        }
+    }
+}
+
+ConsoleRunner::run($helperSet, $commands);

ci/github/phpunit/mysqli.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -18,13 +14,9 @@
         <var name="db_port" value="3306"/>
         <var name="db_user" value="root" />
         <var name="db_dbname" value="doctrine_tests" />
-        <var name="db_default_table_option_charset" value="utf8mb4" />
-        <var name="db_default_table_option_collation" value="utf8mb4_unicode_ci" />
-        <var name="db_default_table_option_engine" value="InnoDB" />
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -33,11 +25,11 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
 
     <groups>
         <exclude>

ci/github/phpunit/pdo_mysql.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -18,13 +14,9 @@
         <var name="db_port" value="3306"/>
         <var name="db_user" value="root" />
         <var name="db_dbname" value="doctrine_tests" />
-        <var name="db_default_table_option_charset" value="utf8mb4" />
-        <var name="db_default_table_option_collation" value="utf8mb4_unicode_ci" />
-        <var name="db_default_table_option_engine" value="InnoDB" />
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -33,11 +25,12 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
+
 
     <groups>
         <exclude>

ci/github/phpunit/pdo_pgsql.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -21,7 +17,6 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -30,11 +25,11 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
 
     <groups>
         <exclude>

ci/github/phpunit/pdo_sqlite.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -19,7 +15,6 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -28,11 +23,11 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
 
     <groups>
         <exclude>

ci/github/phpunit/pgsql.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -21,7 +17,6 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -30,11 +25,11 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
 
     <groups>
         <exclude>

ci/github/phpunit/sqlite3.xml

@@ -3,13 +3,9 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         beStrictAboutTodoAnnotatedTests="true"
          failOnRisky="true"
-         cacheDirectory=".phpunit.cache"
+         convertDeprecationsToExceptions="true"
 >
     <php>
         <ini name="error_reporting" value="-1" />
@@ -19,7 +15,6 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -28,11 +23,11 @@
         </testsuite>
     </testsuites>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
+    <filter>
+        <whitelist>
             <directory suffix=".php">../../../src</directory>
-        </include>
-    </source>
+        </whitelist>
+    </filter>
 
     <groups>
         <exclude>

composer.json

@@ -31,34 +31,44 @@
     ],
     "homepage": "https://www.doctrine-project.org/projects/orm.html",
     "require": {
-        "php": "^8.1",
+        "php": "^7.1 || ^8.0",
         "ext-ctype": "*",
         "composer-runtime-api": "^2",
-        "doctrine/collections": "^2.2",
-        "doctrine/dbal": "^3.8.2 || ^4",
+        "doctrine/cache": "^1.12.1 || ^2.1.1",
+        "doctrine/collections": "^1.5 || ^2.1",
+        "doctrine/common": "^3.0.3",
+        "doctrine/dbal": "^2.13.1 || ^3.2",
         "doctrine/deprecations": "^0.5.3 || ^1",
         "doctrine/event-manager": "^1.2 || ^2",
         "doctrine/inflector": "^1.4 || ^2.0",
         "doctrine/instantiator": "^1.3 || ^2",
-        "doctrine/lexer": "^3",
-        "doctrine/persistence": "^3.3.1 || ^4",
+        "doctrine/lexer": "^2 || ^3",
+        "doctrine/persistence": "^2.4 || ^3",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^5.4 || ^6.0 || ^7.0 || ^8.0",
-        "symfony/var-exporter": "^6.3.9 || ^7.0 || ^8.0"
+        "symfony/console": "^4.2 || ^5.0 || ^6.0 || ^7.0 || ^8.0",
+        "symfony/polyfill-php72": "^1.23",
+        "symfony/polyfill-php80": "^1.16"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^14.0",
-        "phpbench/phpbench": "^1.0",
-        "phpstan/extension-installer": "^1.4",
-        "phpstan/phpstan": "2.1.23",
-        "phpstan/phpstan-deprecation-rules": "^2",
-        "phpunit/phpunit": "^10.5.0 || ^11.5",
+        "doctrine/annotations": "^1.13 || ^2",
+        "doctrine/coding-standard": "^9.0.2 || ^14.0",
+        "phpbench/phpbench": "^0.16.10 || ^1.0",
+        "phpstan/extension-installer": "~1.1.0 || ^1.4",
+        "phpstan/phpstan": "~1.4.10 || 2.1.23",
+        "phpstan/phpstan-deprecation-rules": "^1 || ^2",
+        "phpunit/phpunit": "^7.5 || ^8.5 || ^9.6",
         "psr/log": "^1 || ^2 || ^3",
-        "symfony/cache": "^5.4 || ^6.2 || ^7.0 || ^8.0"
+        "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 || ^8.0"
+    },
+    "conflict": {
+        "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/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": {
@@ -72,6 +82,9 @@
             "Doctrine\\Tests\\": "tests/Tests"
         }
     },
+    "bin": [
+        "bin/doctrine"
+    ],
     "config": {
         "allow-plugins": {
             "composer/package-versions-deprecated": true,

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

@@ -140,6 +140,11 @@ Now we're going to create the ``point`` type and implement all required methods.
             return $value;
         }
 
+        public function canRequireSQLConversion()
+        {
+            return true;
+        }
+
         public function convertToPHPValueSQL($sqlExpr, AbstractPlatform $platform)
         {
             return sprintf('AsText(%s)', $sqlExpr);

docs/en/cookbook/aggregate-fields.rst

@@ -352,7 +352,7 @@ the database using a FOR UPDATE.
     use Bank\Entities\Account;
     use Doctrine\DBAL\LockMode;
 
-    $account = $em->find(Account::class, $accId, LockMode::PESSIMISTIC_WRITE);
+    $account = $em->find(Account::class, $accId, LockMode::PESSIMISTIC_READ);
 
 Keeping Updates and Deletes in Sync
 -----------------------------------

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

@@ -40,8 +40,7 @@ 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
 example:
 
--  Modify the Output walker to get the raw SQL via ``Query->getSQL()``
-   with interpolated parameters.
+
 -  Modify the AST to generate a Count Query to be used with a
    paginator for any given DQL query.
 -  Modify the Output Walker to generate vendor-specific SQL
@@ -51,7 +50,7 @@ example:
 -  Modify the Output walker to pretty print the SQL for debugging
    purposes.
 
-In this cookbook-entry I will show examples of the first three
+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
@@ -224,39 +223,3 @@ huge benefits with using vendor specific features. This would still
 allow you write DQL queries instead of NativeQueries to make use of
 vendor specific features.
 
-Modifying the Output Walker to get the raw SQL with interpolated parameters
----------------------------------------------------------------------------
-
-Sometimes we may want to log or trace the raw SQL being generated from its DQL
-for profiling slow queries afterwards or audit queries that changed many rows
-``$query->getSQL()`` will give us the prepared statement being passed to database
-with all values of SQL parameters being replaced by positional ``?`` or named ``:name``
-as parameters are interpolated into prepared statements by the database while executing the SQL.
-``$query->getParameters()`` will give us details about SQL parameters that we've provided.
-So we can create an output walker to interpolate all SQL parameters that will be
-passed into prepared statement in PHP before database handle them internally:
-
-.. literalinclude:: dql-custom-walkers/InterpolateParametersSQLOutputWalker.php
-   :language: php
-
-Then you may get the raw SQL with this output walker:
-
-.. code-block:: php
-
-    <?php
-    $query
-        ->where('t.int IN (:ints)')->setParameter(':ints', [1, 2])
-        ->orWhere('t.string IN (?0)')->setParameter(0, ['3', '4'])
-        ->orWhere("t.bool = ?1")->setParameter('?1', true)
-        ->orWhere("t.string = :string")->setParameter(':string', 'ABC')
-        ->setHint(\Doctrine\ORM\Query::HINT_CUSTOM_OUTPUT_WALKER, InterpolateParametersSQLOutputWalker::class)
-        ->getSQL();
-
-The where clause of the returned SQL should be like:
-
-.. code-block:: sql
-
-    WHERE t0_.int IN (1, 2)
-       OR t0_.string IN ('3', '4')
-       OR t0_.bool = 1
-       OR t0_.string = 'ABC'

docs/en/cookbook/dql-custom-walkers/InterpolateParametersSQLOutputWalker.php

@@ -1,47 +0,0 @@
-<?php
-use Doctrine\DBAL\ArrayParameterType;
-use Doctrine\DBAL\ParameterType;
-use Doctrine\DBAL\Types\BooleanType;
-use Doctrine\DBAL\Types\Exception\ValueNotConvertible;
-use Doctrine\DBAL\Types\Type;
-use Doctrine\ORM\Query\AST;
-use Doctrine\ORM\Query\SqlOutputWalker;
-
-class InterpolateParametersSQLOutputWalker extends SqlOutputWalker
-{
-    /** {@inheritdoc} */
-    public function walkInputParameter(AST\InputParameter $inputParam): string
-    {
-        $parameter = $this->getQuery()->getParameter($inputParam->name);
-        if ($parameter === null) {
-            return '?';
-        }
-
-        $value = $parameter->getValue();
-        /** @var ParameterType|ArrayParameterType|int|string $typeName */
-        /** @see \Doctrine\ORM\Query\ParameterTypeInferer::inferType() */
-        $typeName = $parameter->getType();
-        $platform = $this->getConnection()->getDatabasePlatform();
-        $processParameterType = static fn(ParameterType $type) => static fn($value): string =>
-            (match ($type) { /** @see Type::getBindingType() */
-                ParameterType::NULL => 'NULL',
-                ParameterType::INTEGER => $value,
-                ParameterType::BOOLEAN => (new BooleanType())->convertToDatabaseValue($value, $platform),
-                ParameterType::STRING, ParameterType::ASCII => $platform->quoteStringLiteral($value),
-                default => throw new ValueNotConvertible($value, $type->name)
-            });
-
-        if (is_string($typeName) && Type::hasType($typeName)) {
-            return Type::getType($typeName)->convertToDatabaseValue($value, $platform);
-        }
-        if ($typeName instanceof ParameterType) {
-            return $processParameterType($typeName)($value);
-        }
-        if ($typeName instanceof ArrayParameterType && is_array($value)) {
-            $type = ArrayParameterType::toElementParameterType($typeName);
-            return implode(', ', array_map($processParameterType($type), $value));
-        }
-
-        throw new ValueNotConvertible($value, $typeName);
-    }
-}

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

@@ -232,33 +232,6 @@ vendors SQL parser to show us further errors in the parsing
 process, for example if the Unit would not be one of the supported
 values by MySql.
 
-Typed functions
----------------
-By default, result of custom functions is fetched as-is from the database driver.
-If you want to be sure that the type is always the same, then your custom function needs to 
-implement ``Doctrine\ORM\Query\AST\TypedExpression``. Then, the result is wired
-through ``Doctrine\DBAL\Types\Type::convertToPhpValue()`` of the ``Type`` returned in ``getReturnType()``.
-
-.. code-block:: php
-
-    <?php
-
-    use Doctrine\DBAL\Types\Type;
-    use Doctrine\DBAL\Types\Types;
-    use Doctrine\ORM\Query\AST\Functions\FunctionNode;
-    use Doctrine\ORM\Query\AST\TypedExpression;
-
-    class DateDiff extends FunctionNode implements TypedExpression
-    {
-        // ...
-
-        public function getReturnType(): Type
-        {
-            return Type::getType(Types::INTEGER);
-        }
-    }
-
-
 Conclusion
 ----------
 

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

@@ -0,0 +1,75 @@
+Implementing the Notify ChangeTracking Policy
+=============================================
+
+.. 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
+boilerplate code. This recipe will show you how this boilerplate
+code should look like. We will implement it on a
+`Layer Supertype <https://martinfowler.com/eaaCatalog/layerSupertype.html>`_
+for all our domain objects.
+
+.. note::
+
+    The notify change tracking policy is deprecated and will be removed in ORM 3.0.
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
+
+Implementing NotifyPropertyChanged
+----------------------------------
+
+The NOTIFY policy is based on the assumption that the entities
+notify interested listeners of changes to their properties. For
+that purpose, a class that wants to use this policy needs to
+implement the ``NotifyPropertyChanged`` interface from the
+``Doctrine\Common`` namespace.
+
+.. code-block:: php
+
+    <?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) {
+                foreach ($this->listeners as $listener) {
+                    $listener->propertyChanged($this, $propName, $oldValue, $newValue);
+                }
+            }
+        }
+    }
+
+Then, in each property setter of concrete, derived domain classes,
+you need to invoke onPropertyChanged as follows to notify
+listeners:
+
+.. code-block:: php
+
+    <?php
+    // 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);
+                $this->data = $data;
+            }
+        }
+    }
+
+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/mysql-enums.rst

@@ -43,21 +43,20 @@ entities:
 .. code-block:: php
 
     <?php
-    #[Entity]
+    /** @Entity */
     class Article
     {
-        public const STATUS_VISIBLE = 'visible';
-        public const STATUS_INVISIBLE = 'invisible';
+        const STATUS_VISIBLE = 'visible';
+        const STATUS_INVISIBLE = 'invisible';
 
-        #[Column(type: "string")]
+        /** @Column(type="string") */
         private $status;
 
-        public function setStatus(string $status): void
+        public function setStatus($status)
         {
-            if (!in_array($status, [self::STATUS_VISIBLE, self::STATUS_INVISIBLE], true)) {
+            if (!in_array($status, array(self::STATUS_VISIBLE, self::STATUS_INVISIBLE))) {
                 throw new \InvalidArgumentException("Invalid status");
             }
-
             $this->status = $status;
         }
     }
@@ -68,10 +67,10 @@ the **columnDefinition** attribute.
 .. code-block:: php
 
     <?php
-    #[Entity]
+    /** @Entity */
     class Article
     {
-        #[Column(type: "string", columnDefinition: "ENUM('visible', 'invisible')")]
+        /** @Column(type="string", columnDefinition="ENUM('visible', 'invisible')") */
         private $status;
     }
 
@@ -93,33 +92,37 @@ For example for the previous enum type:
 
     class EnumVisibilityType extends Type
     {
-        private const ENUM_VISIBILITY = 'enumvisibility';
-        private const STATUS_VISIBLE = 'visible';
-        private const STATUS_INVISIBLE = 'invisible';
+        const ENUM_VISIBILITY = 'enumvisibility';
+        const STATUS_VISIBLE = 'visible';
+        const STATUS_INVISIBLE = 'invisible';
 
-        public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform): string
+        public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform)
         {
             return "ENUM('visible', 'invisible')";
         }
 
-        public function convertToPHPValue(mixed $value, AbstractPlatform $platform): mixed
+        public function convertToPHPValue($value, AbstractPlatform $platform)
         {
             return $value;
         }
 
-        public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): string
+        public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
-            if (!in_array($value, [self::STATUS_VISIBLE, self::STATUS_INVISIBLE], true)) {
+            if (!in_array($value, array(self::STATUS_VISIBLE, self::STATUS_INVISIBLE))) {
                 throw new \InvalidArgumentException("Invalid status");
             }
-
             return $value;
         }
 
-        public function getName(): string
+        public function getName()
         {
             return self::ENUM_VISIBILITY;
         }
+
+        public function requiresSQLCommentHint(AbstractPlatform $platform)
+        {
+            return true;
+        }
     }
 
 You can register this type with ``Type::addType('enumvisibility', 'MyProject\DBAL\EnumVisibilityType');``.
@@ -128,10 +131,10 @@ Then in your entity you can just use this type:
 .. code-block:: php
 
     <?php
-    #[Entity]
+    /** @Entity */
     class Article
     {
-        #[Column(type: "enumvisibility")]
+        /** @Column(type="enumvisibility") */
         private $status;
     }
 
@@ -148,33 +151,37 @@ You can generalize this approach easily to create a base class for enums:
     abstract class EnumType extends Type
     {
         protected $name;
-        protected $values = [];
+        protected $values = array();
 
-        public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform): string
+        public function getSQLDeclaration(array $fieldDeclaration, AbstractPlatform $platform)
         {
-            $values = array_map(fn($val) => "'".$val."'", $this->values);
+            $values = array_map(function($val) { return "'".$val."'"; }, $this->values);
 
             return "ENUM(".implode(", ", $values).")";
         }
 
-        public function convertToPHPValue(mixed $value, AbstractPlatform $platform): mixed
+        public function convertToPHPValue($value, AbstractPlatform $platform)
         {
             return $value;
         }
 
-        public function convertToDatabaseValue(mixed $value, AbstractPlatform $platform): mixed
+        public function convertToDatabaseValue($value, AbstractPlatform $platform)
         {
-            if (!in_array($value, $this->values, true)) {
+            if (!in_array($value, $this->values)) {
                 throw new \InvalidArgumentException("Invalid '".$this->name."' value.");
             }
-
             return $value;
         }
 
-        public function getName(): string
+        public function getName()
         {
             return $this->name;
         }
+
+        public function requiresSQLCommentHint(AbstractPlatform $platform)
+        {
+            return true;
+        }
     }
 
 With this base class you can define an enum as easily as:
@@ -187,5 +194,6 @@ With this base class you can define an enum as easily as:
     class EnumVisibilityType extends EnumType
     {
         protected $name = 'enumvisibility';
-        protected $values = ['visible', 'invisible'];
+        protected $values = array('visible', 'invisible');
     }
+

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

@@ -155,7 +155,7 @@ As you can see, we have a method "setBlockEntity" which ties a potential strateg
          * 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 a
-           #[Column] attribute or setup your xml files correctly
+           #[Column] attribute or setup your yaml or xml files correctly
          * @var string
          */
         protected $strategyClassName;

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

@@ -71,6 +71,23 @@ First Attributes:
         public function assertCustomerAllowedBuying() {}
     }
 
+As Annotations:
+
+.. code-block:: php
+
+    <?php
+    /**
+     * @Entity
+     * @HasLifecycleCallbacks
+     */
+    class Order
+    {
+        /**
+         * @PrePersist @PreUpdate
+         */
+        public function assertCustomerAllowedBuying() {}
+    }
+
 In XML Mappings:
 
 .. code-block:: xml

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

@@ -162,13 +162,15 @@ requiring timezoned datetimes:
     <?php
     namespace Shipping;
 
-     #[Entity]
+    /**
+     * @Entity
+     */
     class Event
     {
-        #[Column(type: 'datetime')]
+        /** @Column(type="datetime") */
         private $created;
 
-        #[Column(type: 'string')]
+        /** @Column(type="string") */
         private $timezone;
 
         /**

docs/en/index.rst

@@ -1,4 +1,4 @@
-Welcome to Doctrine ORM's documentation!
+Welcome to Doctrine 2 ORM's documentation!
 ==========================================
 
 The Doctrine documentation is comprised of tutorials, a reference section and
@@ -38,8 +38,10 @@ Mapping Objects onto a Database
   :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:`PHP <reference/php-mapping>`
 
 Working with Objects
@@ -72,7 +74,6 @@ Advanced Topics
 * :doc:`TypedFieldMapper <reference/typedfieldmapper>`
 * :doc:`Improving Performance <reference/improving-performance>`
 * :doc:`Caching <reference/caching>`
-* :doc:`Partial Hydration <reference/partial-hydration>`
 * :doc:`Partial Objects <reference/partial-objects>`
 * :doc:`Change Tracking Policies <reference/change-tracking-policies>`
 * :doc:`Best Practices <reference/best-practices>`
@@ -111,6 +112,7 @@ Cookbook
 
 * **Implementation**:
   :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>` \|

docs/en/reference/advanced-configuration.rst

@@ -19,7 +19,7 @@ steps of configuration.
 
     // ...
 
-    if ($applicationMode === "development") {
+    if ($applicationMode == "development") {
         $queryCache = new ArrayAdapter();
         $metadataCache = new ArrayAdapter();
     } else {
@@ -29,21 +29,16 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = new AttributeDriver(['/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');
+    $config->setProxyNamespace('MyProject\Proxies');
 
-    if (PHP_VERSION_ID > 80400) {
-        $config->enableNativeLazyObjects(true);
+    if ($applicationMode == "development") {
+        $config->setAutoGenerateProxyClasses(true);
     } else {
-        $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
-        $config->setProxyNamespace('MyProject\Proxies');
-
-        if ($applicationMode === "development") {
-            $config->setAutoGenerateProxyClasses(true);
-        } else {
-            $config->setAutoGenerateProxyClasses(false);
-        }
+        $config->setAutoGenerateProxyClasses(false);
     }
 
     $connection = DriverManager::getConnection([
@@ -76,27 +71,8 @@ Configuration Options
 The following sections describe all the configuration options
 available on a ``Doctrine\ORM\Configuration`` instance.
 
-.. _reference-native-lazy-objects:
-
-Native Lazy Objects (**OPTIONAL**)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-With PHP 8.4 we recommend that you use native lazy objects instead of
-the code generation approach using the ``symfony/var-exporter`` Ghost trait.
-
-With Doctrine 4, the minimal requirement will become PHP 8.4 and native lazy objects
-will become the only approach to lazy loading.
-
-.. code-block:: php
-
-    <?php
-    $config->enableNativeLazyObjects(true);
-
-Proxy Directory
-~~~~~~~~~~~~~~~
-
-Required except if you use native lazy objects with PHP 8.4.
-This setting will be removed in the future.
+Proxy Directory (**REQUIRED**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -109,11 +85,8 @@ classes. For a detailed explanation on proxy classes and how they
 are used in Doctrine, refer to the "Proxy Objects" section further
 down.
 
-Proxy Namespace
-~~~~~~~~~~~~~~~
-
-Required except if you use native lazy objects with PHP 8.4.
-This setting will be removed in the future.
+Proxy Namespace (**REQUIRED**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -138,16 +111,21 @@ Gets or sets the metadata driver implementation that is used by
 Doctrine to acquire the object-relational metadata for your
 classes.
 
-There are currently 3 available implementations:
+There are currently 5 available implementations:
 
 
 -  ``Doctrine\ORM\Mapping\Driver\AttributeDriver``
 -  ``Doctrine\ORM\Mapping\Driver\XmlDriver``
 -  ``Doctrine\ORM\Mapping\Driver\DriverChain``
+-  ``Doctrine\ORM\Mapping\Driver\AnnotationDriver`` (deprecated and will
+  be removed in ``doctrine/orm`` 3.0)
+-  ``Doctrine\ORM\Mapping\Driver\YamlDriver`` (deprecated and will be
+   removed in ``doctrine/orm`` 3.0)
 
 Throughout the most part of this manual the AttributeDriver is
 used in the examples. For information on the usage of the
-XmlDriver please refer to the dedicated chapter ``XML Mapping``.
+AnnotationDriver, XmlDriver or YamlDriver please refer to the dedicated
+chapters ``Annotation Reference``, ``XML Mapping`` and ``YAML Mapping``.
 
 The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
 
@@ -156,59 +134,15 @@ The attribute driver can be injected in the ``Doctrine\ORM\Configuration``:
     <?php
     use Doctrine\ORM\Mapping\Driver\AttributeDriver;
 
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
     $config->setMetadataDriverImpl($driverImpl);
 
 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. Metadata drivers can accept either
-a single directory as a string or an array of directories.
-
-AttributeDriver also accepts ``Doctrine\Persistence\Mapping\Driver\ClassLocator``,
-allowing one to customize file discovery logic. You may choose to use Symfony Finder, or
-utilize directory scan with ``FileClassLocator::createFromDirectories()``:
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\ORM\Mapping\Driver\AttributeDriver;
-	use Doctrine\Persistence\Mapping\Driver\FileClassLocator;
-
-	$paths = ['/path/to/lib/MyProject/Entities'];
-	$classLocator = FileClassLocator::createFromDirectories($paths);
-
-    $driverImpl = new AttributeDriver($classLocator);
-    $config->setMetadataDriverImpl($driverImpl);
-
-With this feature, you're empowered to provide a fine-grained iterator of only necessary
-files to the Driver. For example, if you are using Vertical Slice architecture, you can
-exclude ``*Test.php``, ``*Controller.php``, ``*Service.php``, etc.:
-
-.. code-block:: php
-
-    <?php
-	use Symfony\Component\Finder\Finder;
-
-	$finder = new Finder()->files()->in($paths)
-		->name('*.php')
-		->notName(['*Test.php', '*Controller.php', '*Service.php']);
-
-	$classLocator = new FileClassLocator($finder);
-
-If you know the list of class names you want to track, use
-``Doctrine\Persistence\Mapping\Driver\ClassNames``:
-
-.. code-block:: php
-
-    <?php
-	use Doctrine\Persistence\Mapping\Driver\ClassNames;
-	use App\Entity\{Article, Book};
-
-	$entityClasses = [Article::class, Book::class];
-	$classLocator = new ClassNames($entityClasses);
-
-	$driverImpl = new AttributeDriver($classLocator);
-	$config->setMetadataDriverImpl($driverImpl);
+the console could not work correctly. All of metadata drivers
+accept either a single directory as a string or an array of
+directories. With this feature a single driver can support multiple
+directories of Entities.
 
 Metadata Cache (**RECOMMENDED**)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -221,9 +155,9 @@ Metadata Cache (**RECOMMENDED**)
 
 Gets or sets the cache adapter to use for caching metadata
 information, that is, all the information you supply via attributes,
-xml, 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
+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
 ``Psr\Cache\CacheItemPoolInterface`` interface.
 
 Usage of a metadata cache is highly recommended.
@@ -271,9 +205,6 @@ deprecated ``Doctrine\DBAL\Logging\SQLLogger`` interface.
 Auto-generating Proxy Classes (**OPTIONAL**)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This setting is not required if you use native lazy objects with PHP 8.4
-and will be removed in the future.
-
 Proxy classes can either be generated manually through the Doctrine
 Console or automatically at runtime by Doctrine. The configuration
 option that controls this behavior is:
@@ -494,7 +425,7 @@ 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
-PHP. You can use the MappingDriverChain Metadata implementations to
+YAML. You can use the MappingDriverChain Metadata implementations to
 aggregate these drivers based on namespaces:
 
 .. code-block:: php
@@ -504,7 +435,7 @@ aggregate these drivers based on namespaces:
 
     $chain = new MappingDriverChain();
     $chain->addDriver($xmlDriver, 'Doctrine\Tests\Models\Company');
-    $chain->addDriver($phpDriver, 'Doctrine\Tests\ORM\Mapping');
+    $chain->addDriver($yamlDriver, 'Doctrine\Tests\ORM\Mapping');
 
 Based on the namespace of the entity the loading of entities is
 delegated to the appropriate driver. The chain semantics come from

docs/en/reference/architecture.rst

@@ -18,7 +18,7 @@ well.
 Requirements
 ------------
 
-Doctrine ORM requires a minimum of PHP 8.1. For greatly improved
+Doctrine ORM requires a minimum of PHP 7.1. For greatly improved
 performance it is also recommended that you use APC with PHP.
 
 Doctrine ORM Packages
@@ -33,13 +33,14 @@ Doctrine ORM is divided into four main packages.
 -  ORM (depends on DBAL+Persistence+Collections)
 
 This manual mainly covers the ORM package, sometimes touching parts
-of the underlying DBAL and Persistence packages. The Doctrine codebase
-is split into these packages for a few reasons:
+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...
 
 
--  to make things more maintainable and decoupled
--  to allow you to use the code in Doctrine Persistence and Collections without the ORM or DBAL
--  to allow you to use the DBAL without the ORM
+-  ...make things more maintainable and decoupled
+-  ...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
 
 Collection, Event Manager and Persistence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -79,9 +80,8 @@ Entities
 An entity is a lightweight, persistent domain object. An entity can
 be any regular PHP class observing the following restrictions:
 
--  An entity class can be final or read-only when
-   you use :ref:`native lazy objects <reference-native-lazy-objects>`.
-   It may contain final methods or read-only properties too.
+-  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

docs/en/reference/association-mapping.rst

@@ -56,6 +56,27 @@ A many-to-one association is the most common association between objects. Exampl
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * @ManyToOne(targetEntity="Address")
+             * @JoinColumn(name="address_id", referencedColumnName="id")
+             */
+            private Address|null $address = null;
+        }
+
+        /** @Entity */
+        class Address
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -66,6 +87,18 @@ A many-to-one association is the most common association between objects. Exampl
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToOne:
+            address:
+              targetEntity: Address
+              joinColumn:
+                name: address_id
+                referencedColumnName: id
+
+
 .. note::
 
     The above ``#[JoinColumn]`` is optional as it would default
@@ -121,6 +154,30 @@ references one ``Shipment`` entity.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Product
+        {
+            // ...
+
+            /**
+             * One Product has One Shipment.
+             * @OneToOne(targetEntity="Shipment")
+             * @JoinColumn(name="shipment_id", referencedColumnName="id")
+             */
+            private Shipment|null $shipment = null;
+
+            // ...
+        }
+
+        /** @Entity */
+        class Shipment
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -131,6 +188,17 @@ references one ``Shipment`` entity.
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment:
+              targetEntity: Shipment
+              joinColumn:
+                name: shipment_id
+                referencedColumnName: id
+
 Note that the ``#[JoinColumn]`` is not really necessary in this example,
 as the defaults would be the same.
 
@@ -191,6 +259,38 @@ object.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Customer
+        {
+            // ...
+
+            /**
+             * One Customer has One Cart.
+             * @OneToOne(targetEntity="Cart", mappedBy="customer")
+             */
+            private Cart|null $cart = null;
+
+            // ...
+        }
+
+        /** @Entity */
+        class Cart
+        {
+            // ...
+
+            /**
+             * One Cart has One Customer.
+             * @OneToOne(targetEntity="Customer", inversedBy="cart")
+             * @JoinColumn(name="customer_id", referencedColumnName="id")
+             */
+            private Customer|null $customer = null;
+
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -204,6 +304,22 @@ object.
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Customer:
+          oneToOne:
+            cart:
+              targetEntity: Cart
+              mappedBy: customer
+        Cart:
+          oneToOne:
+            customer:
+              targetEntity: Customer
+              inversedBy: cart
+              joinColumn:
+                name: customer_id
+                referencedColumnName: id
+
 Note that the @JoinColumn is not really necessary in this example,
 as the defaults would be the same.
 
@@ -312,6 +428,41 @@ bidirectional many-to-one.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?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", 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", inversedBy="features")
+             * @JoinColumn(name="product_id", referencedColumnName="id")
+             */
+            private Product|null $product = null;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -325,6 +476,24 @@ bidirectional many-to-one.
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToMany:
+            features:
+              targetEntity: Feature
+              mappedBy: product
+        Feature:
+          type: entity
+          manyToOne:
+            product:
+              targetEntity: Product
+              inversedBy: features
+              joinColumn:
+                name: product_id
+                referencedColumnName: id
+
 Note that the @JoinColumn is not really necessary in this example,
 as the defaults would be the same.
 
@@ -387,6 +556,39 @@ The following example sets up such a unidirectional one-to-many association:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * 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 Collection $phonenumbers;
+
+            public function __construct()
+            {
+                $this->phonenumbers = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
+        /** @Entity */
+        class Phonenumber
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -404,6 +606,24 @@ The following example sets up such a unidirectional one-to-many association:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            phonenumbers:
+              targetEntity: Phonenumber
+              joinTable:
+                name: users_phonenumbers
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  phonenumber_id:
+                    referencedColumnName: id
+                    unique: true
+
+
 Generates the following MySQL Schema:
 
 .. code-block:: sql
@@ -464,6 +684,33 @@ database perspective is known as an adjacency list approach.
             }
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class Category
+        {
+            // ...
+            /**
+             * One Category has Many Categories.
+             * @OneToMany(targetEntity="Category", mappedBy="parent")
+             * @var Collection<int, Category>
+             */
+            private Collection $children;
+
+            /**
+             * Many Categories have One Category.
+             * @ManyToOne(targetEntity="Category", inversedBy="children")
+             * @JoinColumn(name="parent_id", referencedColumnName="id")
+             */
+            private Category|null $parent = null;
+            // ...
+
+            public function __construct() {
+                $this->children = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -473,6 +720,19 @@ database perspective is known as an adjacency list approach.
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Category:
+          type: entity
+          oneToMany:
+            children:
+              targetEntity: Category
+              mappedBy: parent
+          manyToOne:
+            parent:
+              targetEntity: Category
+              inversedBy: children
+
 Note that the @JoinColumn is not really necessary in this example,
 as the defaults would be the same.
 
@@ -527,6 +787,38 @@ entities:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Groups.
+             * @ManyToMany(targetEntity="Group")
+             * @JoinTable(name="users_groups",
+             *      joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
+             *      inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
+             *      )
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+
+            // ...
+
+            public function __construct() {
+                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+        }
+
+        /** @Entity */
+        class Group
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -544,6 +836,22 @@ entities:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            groups:
+              targetEntity: Group
+              joinTable:
+                name: users_groups
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  group_id:
+                    referencedColumnName: id
+
 Generated MySQL Schema:
 
 .. code-block:: sql
@@ -631,6 +939,47 @@ one is bidirectional.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity */
+        class User
+        {
+            // ...
+
+            /**
+             * Many Users have Many Groups.
+             * @ManyToMany(targetEntity="Group", inversedBy="users")
+             * @JoinTable(name="users_groups")
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+
+            public function __construct() {
+                $this->groups = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
+        /** @Entity */
+        class Group
+        {
+            // ...
+            /**
+             * Many Groups have Many Users.
+             * @ManyToMany(targetEntity="User", mappedBy="groups")
+             * @var Collection<int, User>
+             */
+            private Collection $users;
+
+            public function __construct() {
+                $this->users = new \Doctrine\Common\Collections\ArrayCollection();
+            }
+
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -652,6 +1001,30 @@ one is bidirectional.
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            groups:
+              targetEntity: Group
+              inversedBy: users
+              joinTable:
+                name: users_groups
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  group_id:
+                    referencedColumnName: id
+
+        Group:
+          type: entity
+          manyToMany:
+            users:
+              targetEntity: User
+              mappedBy: groups
+
 The MySQL schema is exactly the same as for the Many-To-Many
 uni-directional case above.
 
@@ -799,6 +1172,12 @@ As an example, consider this mapping:
         #[OneToOne(targetEntity: Shipment::class)]
         private Shipment|null $shipment = null;
 
+    .. code-block:: annotation
+
+        <?php
+        /** @OneToOne(targetEntity="Shipment") */
+        private Shipment|null $shipment = null;
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -807,6 +1186,14 @@ As an example, consider this mapping:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment:
+              targetEntity: Shipment
+
 This is essentially the same as the following, more verbose,
 mapping:
 
@@ -820,6 +1207,16 @@ mapping:
         #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
         private Shipment|null $shipment = null;
 
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * One Product has One Shipment.
+         * @OneToOne(targetEntity="Shipment")
+         * @JoinColumn(name="shipment_id", referencedColumnName="id")
+         */
+        private Shipment|null $shipment = null;
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -830,6 +1227,17 @@ mapping:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment:
+              targetEntity: Shipment
+              joinColumn:
+                name: shipment_id
+                referencedColumnName: id
+
 The @JoinTable definition used for many-to-many mappings has
 similar defaults. As an example, consider this mapping:
 
@@ -847,6 +1255,20 @@ similar defaults. As an example, consider this mapping:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /**
+             * @ManyToMany(targetEntity="Group")
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -855,6 +1277,14 @@ similar defaults. As an example, consider this mapping:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            groups:
+              targetEntity: Group
+
 This is essentially the same as the following, more verbose, mapping:
 
 .. configuration-block::
@@ -877,6 +1307,25 @@ This is essentially the same as the following, more verbose, mapping:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /**
+             * Many Users have Many Groups.
+             * @ManyToMany(targetEntity="Group")
+             * @JoinTable(name="User_Group",
+             *      joinColumns={@JoinColumn(name="User_id", referencedColumnName="id")},
+             *      inverseJoinColumns={@JoinColumn(name="Group_id", referencedColumnName="id")}
+             *      )
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -894,6 +1343,22 @@ This is essentially the same as the following, more verbose, mapping:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            groups:
+              targetEntity: Group
+              joinTable:
+                name: User_Group
+                joinColumns:
+                  User_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  Group_id:
+                    referencedColumnName: id
+
 In that case, the name of the join table defaults to a combination
 of the simple, unqualified class names of the participating
 classes, separated by an underscore character. The names of the
@@ -913,6 +1378,12 @@ associations as they will be set based on type. So that:
         #[OneToOne]
         private Shipment $shipment;
 
+    .. code-block:: annotation
+
+        <?php
+        /** @OneToOne */
+        private Shipment $shipment;
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -921,6 +1392,13 @@ associations as they will be set based on type. So that:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment: ~
+
 Is essentially the same as following:
 
 .. configuration-block::
@@ -953,6 +1431,17 @@ Is essentially the same as following:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Product:
+          type: entity
+          oneToOne:
+            shipment:
+              targetEntity: Shipment
+              joinColumn:
+                name: shipment_id
+                referencedColumnName: id
+
 If you accept these defaults, you can reduce the mapping code to a
 minimum.
 

docs/en/reference/attributes-reference.rst

@@ -4,9 +4,8 @@ Attributes Reference
 PHP 8 adds native support for metadata with its "Attributes" feature.
 Doctrine ORM provides support for mapping metadata using PHP attributes as of version 2.9.
 
-The attributes metadata support is closely modelled after the already
-existing and now removed annotation metadata supported since the first
-version 2.0.
+The attributes metadata support is closely modelled after the already existing
+annotation metadata supported since the first version 2.0.
 
 Index
 -----
@@ -175,10 +174,6 @@ Optional parameters:
 -  **unique**: Boolean value to determine if the value of the column
    should be unique across all rows of the underlying entities table.
 
--  **index**: Boolean value to generate an index for this column.
-   For more advanced usages, take a look at :ref:`#[Index] <attrref_index>`.
-   If not specified, default value is ``false``.
-
 -  **nullable**: Determines if NULL values allowed for this column.
     If not specified, default value is ``false``.
 
@@ -249,9 +244,6 @@ Examples:
     #[Column(type: "string", length: 32, unique: true, nullable: false)]
     protected $username;
 
-    #[Column(type: "string", index: true)]
-    protected $firstName;
-
     #[Column(type: "string", columnDefinition: "CHAR(2) NOT NULL")]
     protected $country;
 
@@ -322,6 +314,7 @@ Example:
         Entity,
         ChangeTrackingPolicy("DEFERRED_IMPLICIT"),
         ChangeTrackingPolicy("DEFERRED_EXPLICIT"),
+        ChangeTrackingPolicy("NOTIFY")
     ]
     class User {}
 
@@ -496,8 +489,9 @@ used as default.
 Optional parameters:
 
 -  **strategy**: Set the name of the identifier generation strategy.
-   Valid values are ``AUTO``, ``SEQUENCE``, ``IDENTITY``, ``CUSTOM`` and
-   ``NONE``. If not specified, the default value is ``AUTO``.
+   Valid values are ``AUTO``, ``SEQUENCE``, ``IDENTITY``, ``UUID``
+   (deprecated), ``CUSTOM`` and ``NONE``.
+   If not specified, the default value is ``AUTO``.
 
 Example:
 
@@ -668,6 +662,11 @@ and in the Context of a :ref:`#[ManyToMany] <attrref_manytomany>`. If this attri
 are missing they will be computed considering the field's name and the current
 :doc:`naming strategy <namingstrategy>`.
 
+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. This is only required
+on PHP 8.0, where nested attributes are not yet supported.
+
 Optional parameters:
 
 -  **name**: Column name that holds the foreign key identifier for
@@ -678,7 +677,6 @@ Optional parameters:
 -  **unique**: Determines whether this relation is exclusive between the
    affected entities and should be enforced as such on the database
    constraint level. Defaults to false.
--  **deferrable**: Determines whether this relation constraint can be deferred. Defaults to false.
 -  **nullable**: Determine whether the related entity is required, or if
    null is an allowed state for the relation. Defaults to true.
 -  **onDelete**: Cascade Action (Database-level)
@@ -720,6 +718,10 @@ details of the database join table. If you do not specify
 ``#[JoinTable]`` on these relations reasonable mapping defaults apply
 using the affected table and the column names.
 
+A notable difference to the annotation metadata support, ``#[JoinColumn]``
+and ``#[InverseJoinColumn]`` can be specified at the property level and are not
+nested within the ``#[JoinTable]`` attribute.
+
 Required attribute:
 
 -  **name**: Database name of the join-table
@@ -935,7 +937,7 @@ Example:
     #[OneToMany(
         targetEntity: "Phonenumber",
         mappedBy: "user",
-        cascade: ["persist", "remove"],
+        cascade: ["persist", "remove", "merge"],
         orphanRemoval: true)
     ]
     public $phonenumbers;
@@ -1142,7 +1144,7 @@ Marker attribute that defines a specified column as version attribute used in
 an :ref:`optimistic locking <transactions-and-concurrency_optimistic-locking>`
 scenario. It only works on :ref:`#[Column] <attrref_column>` attributes that have
 the type ``integer`` or ``datetime``. Setting ``#[Version]`` on a property with
-:ref:`#[Id] <attrref_id>` is not supported.
+:ref:`#[Id <attrref_id>` is not supported.
 
 Example:
 

docs/en/reference/basic-mapping.rst

@@ -47,14 +47,17 @@ mapping metadata:
 -  :doc:`Attributes <attributes-reference>`
 -  :doc:`XML <xml-mapping>`
 -  :doc:`PHP code <php-mapping>`
+-  :doc:`Docblock Annotations <annotations-reference>` (deprecated and will be removed in ``doctrine/orm`` 3.0)
+-  :doc:`YAML <yaml-mapping>` (deprecated and will be removed in ``doctrine/orm`` 3.0.)
 
 This manual will usually show mapping metadata via attributes, though
-many examples also show the equivalent configuration in XML.
+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 (attributes, XML, etc.) it is stored in an instance
+    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.
@@ -74,6 +77,17 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+
+        /** @Entity */
+        class Message
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -82,6 +96,12 @@ Marking our ``Message`` class as an entity for Doctrine is straightforward:
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          # ...
+
 With no additional information, Doctrine expects the entity to be saved
 into a table with the same name as the class in our case ``Message``.
 You can change this by configuring information about the table:
@@ -101,6 +121,21 @@ You can change this by configuring information about the table:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Table;
+
+        /**
+         * @Entity
+         * @Table(name="message")
+         */
+        class Message
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -109,6 +144,13 @@ You can change this by configuring information about the table:
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          table: message
+          # ...
+
 Now the class ``Message`` will be saved and fetched from the table ``message``.
 
 Property Mapping
@@ -140,6 +182,23 @@ specified, ``string`` is used as the default.
             private $postedAt;
         }
 
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Mapping\Entity;
+        use Doctrine\ORM\Mapping\Column;
+
+        /** @Entity */
+        class Message
+        {
+            /** @Column(type="integer") */
+            private $id;
+            /** @Column(length=140) */
+            private $text;
+            /** @Column(type="datetime", name="posted_at") */
+            private $postedAt;
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -150,6 +209,19 @@ specified, ``string`` is used as the default.
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          fields:
+            id:
+              type: integer
+            text:
+              length: 140
+            postedAt:
+              type: datetime
+              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. So in this example:
 
@@ -168,7 +240,7 @@ Here is a complete list of ``Column``s attributes (all optional):
 - ``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.
+- ``enumType`` (requires PHP 8.1 and ``doctrine/orm`` 2.11): The PHP enum class name to convert the database value into. See :ref:`reference-enum-mapping`.
 - ``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.
@@ -190,22 +262,6 @@ PHP class, Doctrine also allows you to specify default values for
 database columns using the ``default`` key in the ``options`` array of
 the ``Column`` attribute.
 
-When using XML, you can specify object instances using the ``<object>``
-element:
-
-.. code-block:: xml
-
-    <field name="createdAt" type="datetime" insertable="false" updatable="false">
-        <options>
-            <option name="default">
-                <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp"/>
-            </option>
-        </options>
-    </field>
-
-The ``<object>`` element requires a ``class`` attribute specifying the
-fully qualified class name to instantiate.
-
 .. configuration-block::
    .. literalinclude:: basic-mapping/DefaultValues.php
        :language: attribute
@@ -245,8 +301,6 @@ These are the "automatic" mapping rules:
 | Any other type        | ``Types::STRING``             |
 +-----------------------+-------------------------------+
 
-.. versionadded:: 2.11
-
 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``.
 
@@ -257,69 +311,159 @@ and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
 
 :doc:`Read more about TypedFieldMapper <typedfieldmapper>`.
 
-Property Hooks
---------------
+.. _reference-enum-mapping:
 
-.. versionadded:: 3.4
+Mapping PHP Enums
+-----------------
 
-Doctrine supports mapping hooked properties as long as they have a backed property
-and are not virtual.
+.. versionadded:: 2.11
 
+Doctrine natively supports mapping PHP backed enums to database columns.
+A backed enum is a PHP enum that the same scalar type (``string`` or ``int``)
+assigned to each case. Doctrine stores the scalar value in the database and
+converts it back to the enum instance when hydrating the entity.
 
-.. configuration-block::
+Using ``enumType`` provides three main benefits:
 
-    .. code-block:: attribute
+- **Automatic conversion**: Doctrine handles the conversion in both directions
+  transparently. When loading an entity, scalar values from the database are
+  converted into enum instances. When persisting, enum instances are reduced
+  to their scalar ``->value`` before being sent to the database.
+- **Type-safety**: Entity properties contain enum instances directly. Your
+  getters return ``Suit`` instead of ``string``, removing the need to call
+  ``Suit::from()`` manually.
+- **Validation**: When a database value does not match any enum case, Doctrine
+  throws a ``MappingException`` during hydration instead of silently returning
+  an invalid value.
 
-        <?php
-        use Doctrine\ORM\Mapping\Column;
-        use Doctrine\DBAL\Types\Types;
+This feature works with all database platforms supported by Doctrine (MySQL,
+PostgreSQL, SQLite, etc.) as it relies on standard column types (``string``,
+``integer``, ``json``, ``simple_array``) rather than any vendor-specific enum
+type.
 
-        #[Entity]
-        class Message
-        {
-            #[Column(type: Types::INTEGER)]
-            private $id;
-            #[Column(type: Types::STRING)]
-            public string $language = 'de' {
-                // Override the "read" action with arbitrary logic.
-                get => strtoupper($this->language);
+.. note::
 
-                // Override the "write" action with arbitrary logic.
-                set {
-                    $this->language = strtolower($value);
-                }
-            }
-        }
+    This is unrelated to the MySQL-specific ``ENUM`` column type covered in
+    :doc:`the MySQL Enums cookbook entry </cookbook/mysql-enums>`.
 
-    .. code-block:: xml
+Defining an Enum
+~~~~~~~~~~~~~~~~
 
-        <doctrine-mapping>
-          <entity name="Message">
-            <field name="id" type="integer" />
-            <field name="language" />
-          </entity>
-        </doctrine-mapping>
+.. literalinclude:: basic-mapping/Suit.php
+    :language: php
 
-If you attempt to map a virtual property with ``#[Column]`` an exception will be thrown.
+Only backed enums (``string`` or ``int``) are supported. Unit enums (without
+a scalar value) cannot be mapped.
 
-Some caveats apply to the use of property hooks, as they behave differently when accessing the property through
-the entity or directly through DQL/EntityRepository. Because the property hook can modify the value of the property in a way
-that value and raw value are different, you have to use the raw value representation when querying for the property.
+Single-Value Columns
+~~~~~~~~~~~~~~~~~~~~
+
+Use the ``enumType`` option on ``#[Column]`` to map a property to a backed enum.
+The underlying database column stores the enum's scalar value (``string`` or ``int``).
+
+.. literalinclude:: basic-mapping/EnumMapping.php
+    :language: php
+
+When the PHP property is typed with the enum class, Doctrine automatically
+infers the appropriate column type (``string`` for string-backed enums,
+``integer`` for int-backed enums) and sets ``enumType``. You can also specify
+the column ``type`` explicitly.
+
+Storing Collections of Enums
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can store multiple enum values in a single column by combining ``enumType``
+with a collection column type: ``json`` or ``simple_array``.
+
+.. note::
+
+    Automatic type inference does not apply to collection columns. When the
+    PHP property is typed as ``array``, Doctrine cannot detect the enum class.
+    You must specify both ``type`` and ``enumType`` explicitly.
+
+.. literalinclude:: basic-mapping/EnumCollectionMapping.php
+    :language: php
+
+With ``json``, the values are stored as a JSON array (e.g. ``["hearts","spades"]``).
+With ``simple_array``, the values are stored as a comma-separated string
+(e.g. ``hearts,spades``).
+
+In both cases, Doctrine converts each element to and from the enum
+automatically during hydration and persistence.
+
+.. tip::
+
+    Use ``json`` when enum values may contain commas, when you need to store
+    int-backed enums (as it preserves value types), when the column also
+    stores complex/nested data structures, or when you want to query individual
+    values using database-native JSON operators (e.g. PostgreSQL ``jsonb``).
+    Prefer ``simple_array`` for a compact, human-readable storage of
+    string-backed enums whose values do not contain commas.
+
++-------------------+-----------------------------+-------------------------------+
+| Column type       | Database storage            | PHP type                      |
++===================+=============================+===============================+
+| ``string``        | ``hearts``                  | ``Suit``                      |
++-------------------+-----------------------------+-------------------------------+
+| ``integer``       | ``1``                       | ``Priority``                  |
++-------------------+-----------------------------+-------------------------------+
+| ``json``          | ``["hearts","spades"]``     | ``array<Suit>``               |
++-------------------+-----------------------------+-------------------------------+
+| ``simple_array``  | ``hearts,spades``           | ``array<Suit>``               |
++-------------------+-----------------------------+-------------------------------+
+
+Nullable Enums
+~~~~~~~~~~~~~~
+
+Enum columns can be nullable. When the database value is ``NULL``, Doctrine
+preserves it as ``null`` without triggering any validation error.
 
 .. code-block:: php
 
     <?php
-    $queryBuilder = $entityManager->createQueryBuilder();
-    $queryBuilder->select('m')
-        ->from(Message::class, 'm')
-        ->where('m.language = :language')
-        ->setParameter('language', 'de'); // Use lower case here for raw value representation
+    #[ORM\Column(type: 'string', nullable: true, enumType: Suit::class)]
+    private Suit|null $suit = null;
 
-    $query = $queryBuilder->getQuery();
-    $result = $query->getResult();
+Default Values
+~~~~~~~~~~~~~~
 
-    $messageRepository = $entityManager->getRepository(Message::class);
-    $deMessages = $messageRepository->findBy(['language' => 'de']); // Use lower case here for raw value representation
+You can specify a database-level default using an enum case directly in the
+column options:
+
+.. code-block:: php
+
+    <?php
+    #[ORM\Column(options: ['default' => Suit::Hearts])]
+    public Suit $suit;
+
+Using Enums in Queries
+~~~~~~~~~~~~~~~~~~~~~~
+
+Enum instances can be used directly as parameters in DQL, QueryBuilder, and
+repository methods. Doctrine converts them to their scalar value automatically.
+
+.. code-block:: php
+
+    <?php
+    // QueryBuilder
+    $qb = $em->createQueryBuilder();
+    $qb->select('c')
+        ->from(Card::class, 'c')
+        ->where('c.suit = :suit')
+        ->setParameter('suit', Suit::Clubs);
+
+    // Repository
+    $cards = $em->getRepository(Card::class)->findBy(['suit' => Suit::Clubs]);
+
+XML Mapping
+~~~~~~~~~~~
+
+When using XML mapping, the ``enum-type`` attribute is used on ``<field>``
+elements:
+
+.. code-block:: xml
+
+    <field name="suit" type="string" enum-type="App\Entity\Suit" />
 
 .. _reference-mapping-types:
 
@@ -372,6 +516,20 @@ the field that serves as the identifier with the ``#[Id]`` attribute.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @Column(type="integer")
+             * @GeneratedValue
+             */
+            private int|null $id = null;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -383,27 +541,24 @@ the field that serves as the identifier with the ``#[Id]`` attribute.
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            # fields here
+
 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.
-If you are using `doctrine/dbal` 4, we now recommend using ``IDENTITY``
-for PostgreSQL, and ``AUTO`` resolves to it because of that.
-You can stick with ``SEQUENCE`` while still using the ``AUTO``
-strategy, by configuring what it defaults to.
-
-.. code-block:: php
-
-    <?php
-    use Doctrine\DBAL\Platforms\PostgreSQLPlatform;
-    use Doctrine\ORM\Configuration;
-
-    $config = new Configuration();
-    $config->setIdentityGenerationPreferences([
-        PostgreSQLPlatform::class => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
-    ]);
 
 .. _identifier-generation-strategies:
 
@@ -420,26 +575,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, SQL Anywhere and
-   PostgreSQL (on DBAL 4) and, for historical reasons, ``SEQUENCE``
-   for Oracle and PostgreSQL (on DBAL 3). This strategy provides
-   full portability.
+   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``
-   on DBAL 3, ``GENERATED BY DEFAULT AS IDENTITY`` on DBAL 4).
+   (``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
+   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]`` attribute.
-   It will allow you to pass a :ref:`class of your own to generate the identifiers. <attrref_customidgenerator>`
+   It will allow you to pass a :ref:`class of your own to generate the identifiers. <annref_customidgenerator>`
 
 Sequence Generator
 ^^^^^^^^^^^^^^^^^^
@@ -462,6 +617,20 @@ besides specifying the sequence's name:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class Message
+        {
+            /**
+             * @Id
+             * @GeneratedValue(strategy="SEQUENCE")
+             * @SequenceGenerator(sequenceName="message_seq", initialValue=1, allocationSize=100)
+             */
+            protected int|null $id = null;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -473,6 +642,20 @@ besides specifying the sequence's name:
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Message:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: SEQUENCE
+              sequenceGenerator:
+                sequenceName: message_seq
+                allocationSize: 100
+                initialValue: 1
+
 The initial value specifies at which value the sequence should
 start.
 

docs/en/reference/basic-mapping/DefaultValues.php

@@ -4,8 +4,6 @@ declare(strict_types=1);
 
 namespace App\Entity;
 
-use DateTime;
-use Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp;
 use Doctrine\ORM\Mapping\Column;
 use Doctrine\ORM\Mapping\Entity;
 
@@ -14,7 +12,4 @@ class Message
 {
     #[Column(options: ['default' => 'Hello World!'])]
     private string $text;
-
-    #[Column(options: ['default' => new CurrentTimestamp()], insertable: false, updatable: false)]
-    private DateTime $createdAt;
 }

docs/en/reference/basic-mapping/EnumCollectionMapping.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Player
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private int $id;
+
+    /** @var list<Suit> */
+    #[ORM\Column(type: 'json', enumType: Suit::class)]
+    private array $favouriteSuits = [];
+
+    /** @var list<Suit> */
+    #[ORM\Column(type: 'simple_array', enumType: Suit::class)]
+    private array $allowedSuits = [];
+}

docs/en/reference/basic-mapping/EnumMapping.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity;
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Card
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private int $id;
+
+    #[ORM\Column(enumType: Suit::class)]
+    private Suit $suit;
+}

docs/en/reference/basic-mapping/Suit.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Entity;
+
+enum Suit: string
+{
+    case Hearts   = 'hearts';
+    case Diamonds = 'diamonds';
+    case Clubs    = 'clubs';
+    case Spades   = 'spades';
+}

docs/en/reference/basic-mapping/default-values.xml

@@ -5,12 +5,5 @@
         <option name="default">Hello World!</option>
       </options>
     </field>
-    <field name="createdAt" insertable="false" updatable="false">
-      <options>
-        <option name="default">
-            <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp"/>
-        </option>
-      </options>
-    </field>
   </entity>
 </doctrine-mapping>

docs/en/reference/best-practices.rst

@@ -43,7 +43,7 @@ should use events judiciously.
 Use cascades judiciously
 ------------------------
 
-Automatic cascades of the persist/remove/etc. operations are
+Automatic cascades of the persist/remove/merge/etc. operations are
 very handy but should be used wisely. Do NOT simply add all
 cascades to all associations. Think about which cascades actually
 do make sense for you for a particular association, given the

docs/en/reference/caching.rst

@@ -109,7 +109,7 @@ Metadata Cache
 ~~~~~~~~~~~~~~
 
 Your class metadata can be parsed from a few different sources like
-XML, Attributes, etc. Instead of parsing this
+YAML, XML, Attributes, Annotations etc. Instead of parsing this
 information on each request we should cache it using one of the cache
 drivers.
 

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

@@ -5,7 +5,7 @@ Change tracking is the process of determining what has changed in
 managed entities since the last time they were synchronized with
 the database.
 
-Doctrine provides 2 different change tracking policies, each having
+Doctrine provides 3 different change tracking policies, each having
 its particular advantages and disadvantages. The change tracking
 policy can be defined on a per-class basis (or more precisely,
 per-hierarchy).
@@ -56,3 +56,122 @@ This policy can be configured as follows:
     {
         // ...
     }
+
+Notify
+~~~~~~
+
+.. note::
+
+    The notify change tracking policy is deprecated and will be removed in ORM 3.0.
+    (\ `Details <https://github.com/doctrine/orm/issues/8383>`_)
+
+This policy is based on the assumption that the entities notify
+interested listeners of changes to their properties. For that
+purpose, a class that wants to use this policy needs to implement
+the ``NotifyPropertyChanged`` interface from the Doctrine
+namespace. As a guideline, such an implementation can look as
+follows:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\Persistence\NotifyPropertyChanged,
+        Doctrine\Persistence\PropertyChangedListener;
+
+    #[Entity]
+    #[ChangeTrackingPolicy('NOTIFY')]
+    class MyEntity implements NotifyPropertyChanged
+    {
+        // ...
+
+        private array $_listeners = array();
+
+        public function addPropertyChangedListener(PropertyChangedListener $listener): void
+        {
+            $this->_listeners[] = $listener;
+        }
+    }
+
+Then, in each property setter of this class or derived classes, you
+need to notify all the ``PropertyChangedListener`` instances. As an
+example we add a convenience method on ``MyEntity`` that shows this
+behaviour:
+
+.. code-block:: php
+
+    <?php
+    // ...
+
+    class MyEntity implements NotifyPropertyChanged
+    {
+        // ...
+
+        protected function _onPropertyChanged($propName, $oldValue, $newValue): void
+        {
+            if ($this->_listeners) {
+                foreach ($this->_listeners as $listener) {
+                    $listener->propertyChanged($this, $propName, $oldValue, $newValue);
+                }
+            }
+        }
+
+        public function setData($data): void
+        {
+            if ($data != $this->data) {
+                $this->_onPropertyChanged('data', $this->data, $data);
+                $this->data = $data;
+            }
+        }
+    }
+
+You have to invoke ``_onPropertyChanged`` inside every method that
+changes the persistent state of ``MyEntity``.
+
+The check whether the new value is different from the old one is
+not mandatory but recommended. That way you also have full control
+over when you consider a property changed.
+
+If your entity contains an embeddable, you will need to notify
+separately for each property in the embeddable when it changes
+for example:
+
+.. code-block:: php
+
+    <?php
+    // ...
+
+    class MyEntity implements NotifyPropertyChanged
+    {
+        public function setEmbeddable(MyValueObject $embeddable): void
+        {
+            if (!$embeddable->equals($this->embeddable)) {
+                // notice the entityField.embeddableField notation for referencing the property
+                $this->_onPropertyChanged('embeddable.prop1', $this->embeddable->getProp1(), $embeddable->getProp1());
+                $this->_onPropertyChanged('embeddable.prop2', $this->embeddable->getProp2(), $embeddable->getProp2());
+                $this->embeddable = $embeddable;
+            }
+        }
+    }
+
+This would update all the fields of the embeddable, you may wish to
+implement a diff method on your embedded object which returns only
+the changed fields.
+
+The negative point of this policy is obvious: You need implement an
+interface and write some plumbing code. But also note that we tried
+hard to keep this notification functionality abstract. Strictly
+speaking, it has nothing to do with the persistence layer and the
+Doctrine ORM or DBAL. You may find that property notification
+events come in handy in many other scenarios as well. As mentioned
+earlier, the ``Doctrine\Common`` namespace is not that evil and
+consists solely of very small classes and interfaces that have
+almost no external dependencies (none to the DBAL and none to the
+ORM) and that you can easily take with you should you want to swap
+out the persistence layer. This change tracking policy does not
+introduce a dependency on the Doctrine DBAL/ORM or the persistence
+layer.
+
+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

@@ -56,22 +56,42 @@ access point to ORM functionality provided by Doctrine.
         'dbname'   => 'foo',
     ];
 
-    $config = ORMSetup::createAttributeMetadataConfig($paths, $isDevMode);
-    // on PHP < 8.4, use ORMSetup::createAttributeMetadataConfiguration() instead
+    $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 = ['/path/to/xml-mappings'];
-    $config = ORMSetup::createXMLMetadataConfig($paths, $isDevMode);
-    // on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration() instead
+    $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 = ['/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 ``ORMSetup`` methods several assumptions are made:
 
 -  If ``$isDevMode`` is true caching is done in memory with the ``ArrayAdapter``. Proxy objects are recreated on every request.

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

@@ -490,7 +490,7 @@ where you can generate an arbitrary join with the following syntax:
 .. code-block:: php
 
     <?php
-    $query = $em->createQuery('SELECT u FROM User u JOIN Banlist b ON u.email = b.email');
+    $query = $em->createQuery('SELECT u FROM User u JOIN Banlist b WITH u.email = b.email');
 
 With an arbitrary join the result differs from the joins using a mapped property.
 The result of an arbitrary join is an one dimensional array with a mix of the entity from the ``SELECT``
@@ -513,21 +513,19 @@ it loads all the related ``Banlist`` objects corresponding to this ``User``. Thi
 when the DQL is switched to an arbitrary join.
 
 .. note::
-    The differences between WHERE, WITH, ON and HAVING clauses may be
+    The differences between WHERE, WITH and HAVING clauses may be
     confusing.
 
     - WHERE is applied to the results of an entire query
-    - ON is applied to arbitrary joins as the join condition. For
-      arbitrary joins (SELECT f, b FROM Foo f, Bar b ON f.id = b.id)
-      the ON is required, even if it is 1 = 1. WITH is also
-      supported as alternative keyword for that case for BC reasons.
-    - WITH is applied to an association join as an additional condition.
+    - WITH is applied to a join as an additional condition. For
+      arbitrary joins (SELECT f, b FROM Foo f, Bar b WITH f.id = b.id)
+      the WITH is required, even if it is 1 = 1
     - HAVING is applied to the results of a query after
       aggregation (GROUP BY)
 
 
-Partial Hydration Syntax
-^^^^^^^^^^^^^^^^^^^^^^^^
+Partial Object Syntax
+^^^^^^^^^^^^^^^^^^^^^
 
 By default when you run a DQL query in Doctrine and select only a
 subset of the fields for a given entity, you do not receive objects
@@ -535,7 +533,7 @@ back. Instead, you receive only arrays as a flat rectangular result
 set, similar to how you would if you were just using SQL directly
 and joining some data.
 
-If you want to select partial objects or fields in array hydration you can use the ``partial``
+If you want to select partial objects you can use the ``partial``
 DQL keyword:
 
 .. code-block:: php
@@ -544,13 +542,12 @@ DQL keyword:
     $query = $em->createQuery('SELECT partial u.{id, username} FROM CmsUser u');
     $users = $query->getResult(); // array of partially loaded CmsUser objects
 
-You can use the partial syntax when joining as well:
+You use the partial syntax when joining as well:
 
 .. code-block:: php
 
     <?php
     $query = $em->createQuery('SELECT partial u.{id, username}, partial a.{id, name} FROM CmsUser u JOIN u.articles a');
-    $usersArray = $query->getArrayResult(); // array of partially loaded CmsUser and CmsArticle fields
     $users = $query->getResult(); // array of partially loaded CmsUser objects
 
 "NEW" Operator Syntax
@@ -590,101 +587,7 @@ And then use the ``NEW`` DQL keyword :
     $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, e.email, a.city, SUM(o.value)) FROM Customer c JOIN c.email e JOIN c.address a JOIN c.orders o GROUP BY c');
     $users = $query->getResult(); // array of CustomerDTO
 
-You can also nest several DTO :
-
-.. code-block:: php
-
-    <?php
-    class CustomerDTO
-    {
-        public function __construct(string $name, string $email, AddressDTO $address, string|null $value = null)
-        {
-            // Bind values to the object properties.
-        }
-    }
-
-    class AddressDTO
-    {
-        public function __construct(string $street, string $city, string $zip)
-        {
-            // Bind values to the object properties.
-        }
-    }
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, e.email, NEW AddressDTO(a.street, a.city, a.zip)) FROM Customer c JOIN c.email e JOIN c.address a');
-    $users = $query->getResult(); // array of CustomerDTO
-
-Note that you can only pass scalar expressions or other Data Transfer Objects to the constructor.
-
-If you use your data transfer objects for multiple queries, and you would rather not have to
-specify arguments that precede the ones you are really interested in, you can use named arguments.
-
-Consider the following DTO, which uses optional arguments:
-
-.. code-block:: php
-
-    <?php
-
-    class CustomerDTO
-    {
-        public function __construct(
-            public string|null $name = null,
-            public string|null $email = null,
-            public string|null $city = null,
-            public mixed|null $value = null,
-            public AddressDTO|null $address = null,
-        ) {
-        }
-    }
-
-You can specify arbitrary arguments in an arbitrary order by using the named argument syntax, and the ORM will try to match argument names with the selected column names.
-The syntax relies on the NAMED keyword, like so:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT NEW NAMED CustomerDTO(a.city, c.name) FROM Customer c JOIN c.address a');
-    $users = $query->getResult(); // array of CustomerDTO
-
-    // CustomerDTO => {name : 'SMITH', email: null, city: 'London', value: null}
-
-ORM will also give precedence to column aliases over column names :
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT NEW NAMED CustomerDTO(c.name, CONCAT(a.city, ' ' , a.zip) AS value) FROM Customer c JOIN c.address a');
-    $users = $query->getResult(); // array of CustomerDTO
-
-    // CustomerDTO => {name : 'DOE', email: null, city: null, value: 'New York 10011'}
-
-To define a custom name for a DTO constructor argument, you can either alias the column with the ``AS`` keyword.
-
-The ``NAMED`` keyword must precede all DTO you want to instantiate :
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT NEW NAMED CustomerDTO(c.name, NEW NAMED AddressDTO(a.street, a.city, a.zip) AS address) FROM Customer c JOIN c.address a');
-    $users = $query->getResult(); // array of CustomerDTO
-
-    // CustomerDTO => {name : 'DOE', email: null, city: null, value: 'New York 10011'}
-
-If two arguments have the same name, a ``DuplicateFieldException`` is thrown.
-If a field cannot be matched with a property name, a ``NoMatchingPropertyException`` is thrown. This typically happens when using functions without aliasing them.
-
-You can hydrate an entity nested in a DTO :
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT NEW CustomerDTO(c.name, a AS address) FROM Customer c JOIN c.address a');
-    $users = $query->getResult(); // array of CustomerDTO
-
-    // CustomerDTO => {name : 'DOE', email: null, address : {city: 'New York', zip: '10011', address: 'Abbey Road'}
+Note that you can only pass scalar expressions to the constructor.
 
 Using INDEX BY
 ~~~~~~~~~~~~~~
@@ -1411,7 +1314,8 @@ Result Cache API:
 
     $query->setResultCacheDriver(new ApcCache());
 
-    $query->enableResultCache(3600);
+    $query->useResultCache(true)
+          ->setResultCacheLifeTime(3600);
 
     $result = $query->getResult(); // cache miss
 
@@ -1421,8 +1325,8 @@ Result Cache API:
     $query->setResultCacheId('my_query_result');
     $result = $query->getResult(); // saved in given result cache id.
 
-    // or call enableResultCache() with all parameters:
-    $query->enableResultCache(3600, 'my_query_result');
+    // or call useResultCache() with all parameters:
+    $query->useResultCache(true, 3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
@@ -1612,8 +1516,8 @@ Identifiers
     /* Alias Identification declaration (the "u" of "FROM User u") */
     AliasIdentificationVariable :: = identifier
 
-    /* identifier that must be a class name (the "User" of "FROM User u"), possibly as a fully qualified class name */
-    AbstractSchemaName ::= fully_qualified_name | identifier
+    /* identifier that must be a class name (the "User" of "FROM User u"), possibly as a fully qualified class name or namespace-aliased */
+    AbstractSchemaName ::= fully_qualified_name | aliased_name | identifier
 
     /* Alias ResultVariable declaration (the "total" of "COUNT(*) AS total") */
     AliasResultVariable = identifier
@@ -1700,26 +1604,20 @@ From, Join and Index by
     SubselectIdentificationVariableDeclaration ::= IdentificationVariableDeclaration
     RangeVariableDeclaration                   ::= AbstractSchemaName ["AS"] AliasIdentificationVariable
     JoinAssociationDeclaration                 ::= JoinAssociationPathExpression ["AS"] AliasIdentificationVariable [IndexBy]
-    Join                                       ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN" (JoinAssociationDeclaration ["WITH" ConditionalExpression] | RangeVariableDeclaration [("ON" | "WITH") ConditionalExpression])
+    Join                                       ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN" (JoinAssociationDeclaration | RangeVariableDeclaration) ["WITH" ConditionalExpression]
     IndexBy                                    ::= "INDEX" "BY" SingleValuedPathExpression
 
-.. note::
-    Using the ``WITH`` keyword for the ``ConditionalExpression`` of a
-    ``RangeVariableDeclaration`` is deprecated and will be removed in
-    ORM 4.0. Use the ``ON`` keyword instead.
-
 Select Expressions
 ~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
-    SelectExpression              ::= (IdentificationVariable | ScalarExpression | AggregateExpression | FunctionDeclaration | PartialObjectExpression | "(" Subselect ")" | CaseExpression | NewObjectExpression) [["AS"] ["HIDDEN"] AliasResultVariable]
-    SimpleSelectExpression        ::= (StateFieldPathExpression | IdentificationVariable | FunctionDeclaration | AggregateExpression | "(" Subselect ")" | ScalarExpression) [["AS"] AliasResultVariable]
-    PartialObjectExpression       ::= "PARTIAL" IdentificationVariable "." PartialFieldSet
-    PartialFieldSet               ::= "{" SimpleStateField {"," SimpleStateField}* "}"
-    NewObjectExpression           ::= "NEW" AbstractSchemaName "(" NewObjectArg {"," NewObjectArg}* ")"
-    NewObjectArg                  ::= (ScalarExpression | "(" Subselect ")" | NewObjectExpression | EntityAsDtoArgumentExpression) ["AS" AliasResultVariable]
-    EntityAsDtoArgumentExpression ::= IdentificationVariable
+    SelectExpression        ::= (IdentificationVariable | ScalarExpression | AggregateExpression | FunctionDeclaration | PartialObjectExpression | "(" Subselect ")" | CaseExpression | NewObjectExpression) [["AS"] ["HIDDEN"] AliasResultVariable]
+    SimpleSelectExpression  ::= (StateFieldPathExpression | IdentificationVariable | FunctionDeclaration | AggregateExpression | "(" Subselect ")" | ScalarExpression) [["AS"] AliasResultVariable]
+    PartialObjectExpression ::= "PARTIAL" IdentificationVariable "." PartialFieldSet
+    PartialFieldSet         ::= "{" SimpleStateField {"," SimpleStateField}* "}"
+    NewObjectExpression     ::= "NEW" AbstractSchemaName "(" NewObjectArg {"," NewObjectArg}* ")"
+    NewObjectArg            ::= ScalarExpression | "(" Subselect ")"
 
 Conditional Expressions
 ~~~~~~~~~~~~~~~~~~~~~~~

docs/en/reference/events.rst

@@ -260,6 +260,40 @@ specific to a particular entity class's lifecycle.
                 $this->value = 'changed from preUpdate callback!';
             }
         }
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Event\PrePersistEventArgs;
+
+        /**
+         * @Entity
+         * @HasLifecycleCallbacks
+         */
+        class User
+        {
+            // ...
+
+            /** @Column(type="string", length=255) */
+            public $value;
+
+            /** @PrePersist */
+            public function doStuffOnPrePersist(PrePersistEventArgs $eventArgs)
+            {
+                $this->createdAt = date('Y-m-d H:i:s');
+            }
+
+            /** @PrePersist */
+            public function doOtherStuffOnPrePersist()
+            {
+                $this->value = 'changed from prePersist callback!';
+            }
+
+            /** @PreUpdate */
+            public function doStuffOnPreUpdate(PreUpdateEventArgs $eventArgs)
+            {
+                $this->value = 'changed from preUpdate callback!';
+            }
+        }
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
@@ -277,6 +311,17 @@ specific to a particular entity class's lifecycle.
                 </lifecycle-callbacks>
             </entity>
         </doctrine-mapping>
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            # ...
+            value:
+              type: string(255)
+          lifecycleCallbacks:
+            prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersist ]
+            preUpdate: [ doStuffOnPreUpdate ]
 
 Lifecycle Callbacks Event Argument
 ----------------------------------
@@ -749,6 +794,16 @@ An entity listener is a lifecycle listener class used for an entity.
         {
             // ....
         }
+    .. code-block:: annotation
+
+        <?php
+        namespace MyProject\Entity;
+
+        /** @Entity @EntityListeners({"UserListener"}) */
+        class User
+        {
+            // ....
+        }
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -759,6 +814,13 @@ An entity listener is a lifecycle listener class used for an entity.
                 <!-- .... -->
             </entity>
         </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Entity\User:
+          type: entity
+          entityListeners:
+            UserListener:
+          # ....
 
 .. _reference-entity-listeners:
 
@@ -831,6 +893,45 @@ you need to map the listener method using the event type mapping:
             public function postLoadHandler(User $user, PostLoadEventArgs $event): void { // ... }
         }
 
+    .. code-block:: annotation
+
+        <?php
+        use Doctrine\ORM\Event\PostLoadEventArgs;
+        use Doctrine\ORM\Event\PostPersistEventArgs;
+        use Doctrine\ORM\Event\PostRemoveEventArgs;
+        use Doctrine\ORM\Event\PostUpdateEventArgs;
+        use Doctrine\ORM\Event\PreFlushEventArgs;
+        use Doctrine\ORM\Event\PrePersistEventArgs;
+        use Doctrine\ORM\Event\PreRemoveEventArgs;
+        use Doctrine\ORM\Event\PreUpdateEventArgs;
+
+        class UserListener
+        {
+            /** @PrePersist */
+            public function prePersistHandler(User $user, PrePersistEventArgs $event): void { // ... }
+
+            /** @PostPersist */
+            public function postPersistHandler(User $user, PostPersistEventArgs $event): void { // ... }
+
+            /** @PreUpdate */
+            public function preUpdateHandler(User $user, PreUpdateEventArgs $event): void { // ... }
+
+            /** @PostUpdate */
+            public function postUpdateHandler(User $user, PostUpdateEventArgs $event): void { // ... }
+
+            /** @PostRemove */
+            public function postRemoveHandler(User $user, PostRemoveEventArgs $event): void { // ... }
+
+            /** @PreRemove */
+            public function preRemoveHandler(User $user, PreRemoveEventArgs $event): void { // ... }
+
+            /** @PreFlush */
+            public function preFlushHandler(User $user, PreFlushEventArgs $event): void { // ... }
+
+            /** @PostLoad */
+            public function postLoadHandler(User $user, PostLoadEventArgs $event): void { // ... }
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -853,6 +954,24 @@ you need to map the listener method using the event type mapping:
                 <!-- .... -->
             </entity>
         </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Entity\User:
+          type: entity
+          entityListeners:
+            UserListener:
+              preFlush: [preFlushHandler]
+              postLoad: [postLoadHandler]
+
+              postPersist: [postPersistHandler]
+              prePersist: [prePersistHandler]
+
+              postUpdate: [postUpdateHandler]
+              preUpdate: [preUpdateHandler]
+
+              postRemove: [postRemoveHandler]
+              preRemove: [preRemoveHandler]
+          # ....
 
 .. note::
 
@@ -875,8 +994,7 @@ Specifying an entity listener instance :
 
     // User.php
 
-    #[Entity]
-    #[EntityListeners(["UserListener"])
+    /** @Entity @EntityListeners({"UserListener"}) */
     class User
     {
         // ....
@@ -934,7 +1052,7 @@ Load ClassMetadata Event
 
 ``loadClassMetadata`` - The ``loadClassMetadata`` event occurs after the
 mapping metadata for a class has been loaded from a mapping source
-(attributes/xml) in to a ``Doctrine\ORM\Mapping\ClassMetadata`` instance.
+(attributes/annotations/xml/yaml) in to a ``Doctrine\ORM\Mapping\ClassMetadata`` instance.
 You can hook in to this process and manipulate the instance.
 This event is not a lifecycle callback.
 

docs/en/reference/inheritance-mapping.rst

@@ -16,7 +16,7 @@ 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). They
-are not query-able, and do not require an ``#[Id]`` property.
+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
@@ -208,6 +208,30 @@ Example:
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        namespace MyProject\Model;
+
+        /**
+         * @Entity
+         * @InheritanceType("SINGLE_TABLE")
+         * @DiscriminatorColumn(name="discr", type="string")
+         * @DiscriminatorMap({"person" = "Person", "employee" = "Employee"})
+         */
+        class Person
+        {
+            // ...
+        }
+
+        /**
+         * @Entity
+         */
+        class Employee extends Person
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -225,6 +249,21 @@ Example:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        MyProject\Model\Person:
+          type: entity
+          inheritanceType: SINGLE_TABLE
+          discriminatorColumn:
+            name: discr
+            type: string
+          discriminatorMap:
+            person: Person
+            employee: Employee
+
+        MyProject\Model\Employee:
+          type: entity
+
 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``.
@@ -417,6 +456,58 @@ Example:
         {
         }
 
+    .. code-block:: annotation
+
+        <?php
+        // user mapping
+        namespace MyProject\Model;
+        /**
+         * @MappedSuperclass
+         */
+        class User
+        {
+            // other fields mapping
+
+            /**
+             * @ManyToMany(targetEntity="Group", inversedBy="users")
+             * @JoinTable(name="users_groups",
+             *  joinColumns={@JoinColumn(name="user_id", referencedColumnName="id")},
+             *  inverseJoinColumns={@JoinColumn(name="group_id", referencedColumnName="id")}
+             * )
+             * @var Collection<int, Group>
+             */
+            protected Collection $groups;
+
+            /**
+             * @ManyToOne(targetEntity="Address")
+             * @JoinColumn(name="address_id", referencedColumnName="id")
+             */
+            protected Address|null $address = null;
+        }
+
+        // admin mapping
+        namespace MyProject\Model;
+        /**
+         * @Entity
+         * @AssociationOverrides({
+         *      @AssociationOverride(name="groups",
+         *          joinTable=@JoinTable(
+         *              name="users_admingroups",
+         *              joinColumns=@JoinColumn(name="adminuser_id"),
+         *              inverseJoinColumns=@JoinColumn(name="admingroup_id")
+         *          )
+         *      ),
+         *      @AssociationOverride(name="address",
+         *          joinColumns=@JoinColumn(
+         *              name="adminaddress_id", referencedColumnName="id"
+         *          )
+         *      )
+         * })
+         */
+        class Admin extends User
+        {
+        }
+
     .. code-block:: xml
 
         <!-- user mapping -->
@@ -426,6 +517,7 @@ Example:
                 <many-to-many field="groups" target-entity="Group" inversed-by="users">
                     <cascade>
                         <cascade-persist/>
+                        <cascade-merge/>
                         <cascade-detach/>
                     </cascade>
                     <join-table name="users_groups">
@@ -462,6 +554,51 @@ Example:
                 </association-overrides>
             </entity>
         </doctrine-mapping>
+    .. code-block:: yaml
+
+        # user mapping
+        MyProject\Model\User:
+          type: mappedSuperclass
+          # other fields mapping
+          manyToOne:
+            address:
+              targetEntity: Address
+              joinColumn:
+                name: address_id
+                referencedColumnName: id
+              cascade: [ persist, merge ]
+          manyToMany:
+            groups:
+              targetEntity: Group
+              joinTable:
+                name: users_groups
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  group_id:
+                    referencedColumnName: id
+              cascade: [ persist, merge, detach ]
+
+        # admin mapping
+        MyProject\Model\Admin:
+          type: entity
+          associationOverride:
+            address:
+              joinColumn:
+                adminaddress_id:
+                  name: adminaddress_id
+                  referencedColumnName: id
+            groups:
+              joinTable:
+                name: users_admingroups
+                joinColumns:
+                  adminuser_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  admingroup_id:
+                    referencedColumnName: id
+
 
 Things to note:
 
@@ -525,6 +662,51 @@ Could be used by an entity that extends a mapped superclass to override a field
         {
         }
 
+    .. code-block:: annotation
+
+        <?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({
+         *      @AttributeOverride(name="id",
+         *          column=@Column(
+         *              name     = "guest_id",
+         *              type     = "integer",
+         *              length   = 140
+         *          )
+         *      ),
+         *      @AttributeOverride(name="name",
+         *          column=@Column(
+         *              name     = "guest_name",
+         *              nullable = false,
+         *              unique   = true,
+         *              length   = 240
+         *          )
+         *      )
+         * })
+         */
+        class Guest extends User
+        {
+        }
+
     .. code-block:: xml
 
         <!-- user mapping -->
@@ -537,6 +719,7 @@ Could be used by an entity that extends a mapped superclass to override a field
                 <many-to-one field="address" target-entity="Address">
                     <cascade>
                         <cascade-persist/>
+                        <cascade-merge/>
                     </cascade>
                     <join-column name="address_id" referenced-column-name="id"/>
                 </many-to-one>
@@ -557,6 +740,42 @@ Could be used by an entity that extends a mapped superclass to override a field
                 </attribute-overrides>
             </entity>
         </doctrine-mapping>
+    .. code-block:: yaml
+
+        # user mapping
+        MyProject\Model\User:
+          type: mappedSuperclass
+          id:
+            id:
+              type: integer
+              column: user_id
+              length: 150
+              generator:
+                strategy: AUTO
+          fields:
+            name:
+              type: string
+              column: user_name
+              length: 250
+              nullable: true
+              unique: false
+          #other fields mapping
+
+
+        # guest mapping
+        MyProject\Model\Guest:
+          type: entity
+          attributeOverride:
+            id:
+              column: guest_id
+              type: integer
+              length: 140
+            name:
+              column: guest_name
+              type: string
+              length: 240
+              nullable: false
+              unique: true
 
 Things to note:
 

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

@@ -65,6 +65,15 @@ Where the ``attribute_name`` column contains the key and
 The feature request for persistence of primitive value arrays
 `is described in the DDC-298 ticket <https://github.com/doctrine/orm/issues/3743>`_.
 
+Cascade Merge with Bi-directional Associations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two bugs now that concern the use of cascade merge in combination with bi-directional associations.
+Make sure to study the behavior of cascade merge if you are using it:
+
+-  `DDC-875 <https://github.com/doctrine/orm/issues/5398>`_ Merge can sometimes add the same entity twice into a collection
+-  `DDC-763 <https://github.com/doctrine/orm/issues/5277>`_ Cascade merge on associated entities can insert too many rows through "Persistence by Reachability"
+
 Custom Persisters
 ~~~~~~~~~~~~~~~~~
 

docs/en/reference/metadata-drivers.rst

@@ -16,6 +16,13 @@ metadata:
 -  **Attributes** (AttributeDriver)
 -  **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``
@@ -37,7 +44,11 @@ an entity.
         $em->getConfiguration()->setMetadataCacheImpl(new ApcuCache());
 
 
-All the drivers are in the ``Doctrine\ORM\Mapping\Driver`` namespace:
+If you want to use one of the included core metadata drivers you need to
+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
 

docs/en/reference/namingstrategy.rst

@@ -110,28 +110,28 @@ You need to create a class which implements ``Doctrine\ORM\Mapping\NamingStrateg
     <?php
     class MyAppNamingStrategy implements NamingStrategy
     {
-        public function classToTableName(string $className): string
+        public function classToTableName($className)
         {
             return 'MyApp_' . substr($className, strrpos($className, '\\') + 1);
         }
-        public function propertyToColumnName(string $propertyName): string
+        public function propertyToColumnName($propertyName)
         {
             return $propertyName;
         }
-        public function referenceColumnName(): string
+        public function referenceColumnName()
         {
             return 'id';
         }
-        public function joinColumnName(string $propertyName, ?string $className = null): string
+        public function joinColumnName($propertyName, $className = null)
         {
             return $propertyName . '_' . $this->referenceColumnName();
         }
-        public function joinTableName(string $sourceEntity, string $targetEntity, string $propertyName): string
+        public function joinTableName($sourceEntity, $targetEntity, $propertyName = null)
         {
             return strtolower($this->classToTableName($sourceEntity) . '_' .
                     $this->classToTableName($targetEntity));
         }
-        public function joinKeyColumnName(string $entityName, ?string $referencedColumnName): string
+        public function joinKeyColumnName($entityName, $referencedColumnName = null)
         {
             return strtolower($this->classToTableName($entityName) . '_' .
                     ($referencedColumnName ?: $this->referenceColumnName()));

docs/en/reference/native-sql.rst

@@ -465,3 +465,477 @@ above would result in partial objects if any objects in the result
 are actually a subtype of User. When using DQL, Doctrine
 automatically includes the necessary joins for this mapping
 strategy but with native SQL it is your responsibility.
+
+Named Native Query
+------------------
+
+.. note::
+
+    Named Native Queries are deprecated as of version 2.9 and will be removed in ORM 3.0
+
+You can also map a native query using a named native query mapping.
+
+To achieve that, you must describe the SQL resultset structure
+using named native query (and sql resultset mappings if is a several resultset mappings).
+
+Like named query, a named native query can be defined at class level or in a XML or YAML file.
+
+
+A resultSetMapping parameter is defined in @NamedNativeQuery,
+it represents the name of a defined @SqlResultSetMapping.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+        /**
+         * @NamedNativeQueries({
+         *      @NamedNativeQuery(
+         *          name            = "fetchMultipleJoinsEntityResults",
+         *          resultSetMapping= "mappingMultipleJoinsEntityResults",
+         *          query           = "SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username"
+         *      ),
+         * })
+         * @SqlResultSetMappings({
+         *      @SqlResultSetMapping(
+         *          name    = "mappingMultipleJoinsEntityResults",
+         *          entities= {
+         *              @EntityResult(
+         *                  entityClass = "__CLASS__",
+         *                  fields      = {
+         *                      @FieldResult(name = "id",       column="u_id"),
+         *                      @FieldResult(name = "name",     column="u_name"),
+         *                      @FieldResult(name = "status",   column="u_status"),
+         *                  }
+         *              ),
+         *              @EntityResult(
+         *                  entityClass = "Address",
+         *                  fields      = {
+         *                      @FieldResult(name = "id",       column="a_id"),
+         *                      @FieldResult(name = "zip",      column="a_zip"),
+         *                      @FieldResult(name = "country",  column="a_country"),
+         *                  }
+         *              )
+         *          },
+         *          columns = {
+         *              @ColumnResult("numphones")
+         *          }
+         *      )
+         *})
+         */
+         class User
+        {
+            /** @Id @Column(type="integer") @GeneratedValue */
+            public $id;
+
+            /** @Column(type="string", length=50, nullable=true) */
+            public $status;
+
+            /** @Column(type="string", length=255, unique=true) */
+            public $username;
+
+            /** @Column(type="string", length=255) */
+            public $name;
+
+            /** @OneToMany(targetEntity="Phonenumber") */
+            public $phonenumbers;
+
+            /** @OneToOne(targetEntity="Address") */
+            public $address;
+
+            // ....
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\User">
+                <named-native-queries>
+                    <named-native-query name="fetchMultipleJoinsEntityResults" result-set-mapping="mappingMultipleJoinsEntityResults">
+                        <query>SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingMultipleJoinsEntityResults">
+                        <entity-result entity-class="__CLASS__">
+                            <field-result name="id" column="u_id"/>
+                            <field-result name="name" column="u_name"/>
+                            <field-result name="status" column="u_status"/>
+                        </entity-result>
+                        <entity-result entity-class="Address">
+                            <field-result name="id" column="a_id"/>
+                            <field-result name="zip" column="a_zip"/>
+                            <field-result name="country" column="a_country"/>
+                        </entity-result>
+                        <column-result name="numphones"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\User:
+          type: entity
+          namedNativeQueries:
+            fetchMultipleJoinsEntityResults:
+              name: fetchMultipleJoinsEntityResults
+              resultSetMapping: mappingMultipleJoinsEntityResults
+              query: SELECT u.id AS u_id, u.name AS u_name, u.status AS u_status, a.id AS a_id, a.zip AS a_zip, a.country AS a_country, COUNT(p.phonenumber) AS numphones FROM users u INNER JOIN addresses a ON u.id = a.user_id INNER JOIN phonenumbers p ON u.id = p.user_id GROUP BY u.id, u.name, u.status, u.username, a.id, a.zip, a.country ORDER BY u.username
+          sqlResultSetMappings:
+            mappingMultipleJoinsEntityResults:
+              name: mappingMultipleJoinsEntityResults
+              columnResult:
+                0:
+                  name: numphones
+              entityResult:
+                0:
+                  entityClass: __CLASS__
+                  fieldResult:
+                    0:
+                      name: id
+                      column: u_id
+                    1:
+                      name: name
+                      column: u_name
+                    2:
+                      name: status
+                      column: u_status
+                1:
+                  entityClass: Address
+                  fieldResult:
+                    0:
+                      name: id
+                      column: a_id
+                    1:
+                      name: zip
+                      column: a_zip
+                    2:
+                      name: country
+                      column: a_country
+
+
+Things to note:
+    - The resultset mapping declares the entities retrieved by this native query.
+    - Each field of the entity is bound to a SQL alias (or column name).
+    - All fields of the entity including the ones of subclasses
+      and the foreign key columns of related entities have to be present in the SQL query.
+    - Field definitions are optional provided that they map to the same
+      column name as the one declared on the class property.
+    - ``__CLASS__`` is an alias for the mapped class
+
+
+In the above example,
+the ``fetchJoinedAddress`` named query use the joinMapping result set mapping.
+This mapping returns 2 entities, User and Address, each property is declared and associated to a column name,
+actually the column name retrieved by the query.
+
+Let's now see an implicit declaration of the property / column.
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name                = "findAll",
+             *          resultSetMapping    = "mappingFindAll",
+             *          query               = "SELECT * FROM addresses"
+             *      ),
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingFindAll",
+             *          entities= {
+             *              @EntityResult(
+             *                  entityClass = "Address"
+             *              )
+             *          }
+             *      )
+             * })
+             */
+           class Address
+           {
+                /**  @Id @Column(type="integer") @GeneratedValue */
+                public $id;
+
+                /** @Column() */
+                public $country;
+
+                /** @Column() */
+                public $zip;
+
+                /** @Column()*/
+                public $city;
+
+                // ....
+            }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-queries>
+                    <named-native-query name="findAll" result-set-mapping="mappingFindAll">
+                        <query>SELECT * FROM addresses</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingFindAll">
+                        <entity-result entity-class="Address"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            findAll:
+              resultSetMapping: mappingFindAll
+              query: SELECT * FROM addresses
+          sqlResultSetMappings:
+            mappingFindAll:
+              name: mappingFindAll
+              entityResult:
+                address:
+                  entityClass: Address
+
+
+In this example, we only describe the entity member of the result set mapping.
+The property / column mappings is done using the entity mapping values.
+In this case the model property is bound to the model_txt column.
+If the association to a related entity involve a composite primary key,
+a @FieldResult element should be used for each foreign key column.
+The @FieldResult name is composed of the property name for the relationship,
+followed by a dot ("."), followed by the name or the field or property of the primary key.
+
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name            = "fetchJoinedAddress",
+             *          resultSetMapping= "mappingJoinedAddress",
+             *          query           = "SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?"
+             *      ),
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingJoinedAddress",
+             *          entities= {
+             *              @EntityResult(
+             *                  entityClass = "__CLASS__",
+             *                  fields      = {
+             *                      @FieldResult(name = "id"),
+             *                      @FieldResult(name = "name"),
+             *                      @FieldResult(name = "status"),
+             *                      @FieldResult(name = "address.id", column = "a_id"),
+             *                      @FieldResult(name = "address.zip", column = "a_zip"),
+             *                      @FieldResult(name = "address.city", column = "a_city"),
+             *                      @FieldResult(name = "address.country", column = "a_country"),
+             *                  }
+             *              )
+             *          }
+             *      )
+             * })
+             */
+            class User
+            {
+                /** @Id @Column(type="integer") @GeneratedValue */
+                public $id;
+
+                /** @Column(type="string", length=50, nullable=true) */
+                public $status;
+
+                /** @Column(type="string", length=255, unique=true) */
+                public $username;
+
+                /** @Column(type="string", length=255) */
+                public $name;
+
+                /** @OneToOne(targetEntity="Address") */
+                public $address;
+
+                // ....
+            }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\User">
+                <named-native-queries>
+                    <named-native-query name="fetchJoinedAddress" result-set-mapping="mappingJoinedAddress">
+                        <query>SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?</query>
+                    </named-native-query>
+                </named-native-queries>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingJoinedAddress">
+                        <entity-result entity-class="__CLASS__">
+                            <field-result name="id"/>
+                            <field-result name="name"/>
+                            <field-result name="status"/>
+                            <field-result name="address.id" column="a_id"/>
+                            <field-result name="address.zip"  column="a_zip"/>
+                            <field-result name="address.city"  column="a_city"/>
+                            <field-result name="address.country" column="a_country"/>
+                        </entity-result>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\User:
+          type: entity
+          namedNativeQueries:
+            fetchJoinedAddress:
+              name: fetchJoinedAddress
+              resultSetMapping: mappingJoinedAddress
+              query: SELECT u.id, u.name, u.status, a.id AS a_id, a.country AS a_country, a.zip AS a_zip, a.city AS a_city FROM users u INNER JOIN addresses a ON u.id = a.user_id WHERE u.username = ?
+          sqlResultSetMappings:
+            mappingJoinedAddress:
+              entityResult:
+                0:
+                  entityClass: __CLASS__
+                  fieldResult:
+                    0:
+                      name: id
+                    1:
+                      name: name
+                    2:
+                      name: status
+                    3:
+                      name: address.id
+                      column: a_id
+                    4:
+                      name: address.zip
+                      column: a_zip
+                    5:
+                      name: address.city
+                      column: a_city
+                    6:
+                      name: address.country
+                      column: a_country
+
+
+
+If you retrieve a single entity and if you use the default mapping,
+you can use the resultClass attribute instead of resultSetMapping:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name           = "find-by-id",
+             *          resultClass    = "Address",
+             *          query          = "SELECT * FROM addresses"
+             *      ),
+             * })
+             */
+           class Address
+           {
+                // ....
+           }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-queries>
+                    <named-native-query name="find-by-id" result-class="Address">
+                        <query>SELECT * FROM addresses WHERE id = ?</query>
+                    </named-native-query>
+                </named-native-queries>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            findAll:
+              name: findAll
+              resultClass: Address
+              query: SELECT * FROM addresses
+
+
+In some of your native queries, you'll have to return scalar values,
+for example when building report queries.
+You can map them in the @SqlResultsetMapping through @ColumnResult.
+You actually can even mix, entities and scalar returns in the same native query (this is probably not that common though).
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+        namespace MyProject\Model;
+            /**
+             * @NamedNativeQueries({
+             *      @NamedNativeQuery(
+             *          name            = "count",
+             *          resultSetMapping= "mappingCount",
+             *          query           = "SELECT COUNT(*) AS count FROM addresses"
+             *      )
+             * })
+             * @SqlResultSetMappings({
+             *      @SqlResultSetMapping(
+             *          name    = "mappingCount",
+             *          columns = {
+             *              @ColumnResult(
+             *                  name = "count"
+             *              )
+             *          }
+             *      )
+             * })
+             */
+           class Address
+           {
+                // ....
+           }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Address">
+                <named-native-query name="count" result-set-mapping="mappingCount">
+                    <query>SELECT COUNT(*) AS count FROM addresses</query>
+                </named-native-query>
+                <sql-result-set-mappings>
+                    <sql-result-set-mapping name="mappingCount">
+                        <column-result name="count"/>
+                    </sql-result-set-mapping>
+                </sql-result-set-mappings>
+            </entity>
+        </doctrine-mapping>
+    .. code-block:: yaml
+
+        MyProject\Model\Address:
+          type: entity
+          namedNativeQueries:
+            count:
+              name: count
+              resultSetMapping: mappingCount
+              query: SELECT COUNT(*) AS count FROM addresses
+          sqlResultSetMappings:
+            mappingCount:
+              name: mappingCount
+              columnResult:
+                count:
+                  name: count

docs/en/reference/partial-hydration.rst

@@ -1,15 +0,0 @@
-Partial Hydration
-=================
-
-Partial hydration of entities is allowed in the array hydrator, when
-only a subset of the fields of an entity are loaded from the database
-and the nested results are still created based on the entity relationship structure.
-
-.. code-block:: php
-
-    <?php
-    $users = $em->createQuery("SELECT PARTIAL u.{id,name}, partial a.{id,street} FROM MyApp\Domain\User u JOIN u.addresses a")
-                ->getArrayResult();
-
-This is a useful optimization when you are not interested in all fields of an entity
-for performance reasons, for example in use-cases for exporting or rendering lots of data.

docs/en/reference/partial-objects.rst

@@ -1,11 +1,19 @@
 Partial Objects
 ===============
 
+
+.. note::
+
+    Creating Partial Objects through DQL is deprecated and
+    will be removed in the future, use data transfer object
+    support in DQL instead. (\ `Details
+    <https://github.com/doctrine/orm/issues/8471>`_)
+
 A partial object is an object whose state is not fully initialized
 after being reconstituted from the database and that is
 disconnected from the rest of its data. The following section will
 describe why partial objects are problematic and what the approach
-of Doctrine to this problem is.
+of Doctrine2 to this problem is.
 
 .. note::
 
@@ -86,3 +94,5 @@ When should I force partial objects?
 Mainly for optimization purposes, but be careful of premature
 optimization as partial objects lead to potentially more fragile
 code.
+
+

docs/en/reference/php-mapping.rst

@@ -1,20 +1,97 @@
 PHP Mapping
 ===========
 
-Doctrine ORM also allows you to provide the ORM metadata in the form of plain
-PHP code using the ``ClassMetadata`` API. You can write the code in inside of a
-static function named ``loadMetadata($class)`` on the entity class itself.
+Doctrine ORM also allows you to provide the ORM metadata in the form
+of plain PHP code using the ``ClassMetadata`` API. You can write
+the code in PHP files or inside of a static function named
+``loadMetadata($class)`` on the entity class itself.
+
+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``:
+
+.. code-block:: php
+
+    <?php
+    $driver = new PHPDriver('/path/to/php/mapping/files');
+    $em->getConfiguration()->setMetadataDriverImpl($driver);
+
+Now imagine we had an entity named ``Entities\User`` and we wanted
+to write a mapping file for it using the above configured
+``PHPDriver`` instance:
+
+.. code-block:: php
+
+    <?php
+    namespace Entities;
+
+    class User
+    {
+        private $id;
+        private $username;
+    }
+
+To write the mapping information you just need to create a file
+named ``Entities.User.php`` inside of the
+``/path/to/php/mapping/files`` folder:
+
+.. code-block:: php
+
+    <?php
+    // /path/to/php/mapping/files/Entities.User.php
+
+    $metadata->mapField(array(
+       'id' => true,
+       'fieldName' => 'id',
+       'type' => 'integer'
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'username',
+       'type' => 'string',
+       'options' => array(
+           'fixed' => true,
+           'comment' => "User's login name"
+       )
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'login_count',
+       'type' => 'integer',
+       'nullable' => false,
+       'options' => array(
+           'unsigned' => true,
+           'default' => 0
+       )
+    ));
+
+Now we can easily retrieve the populated ``ClassMetadata`` instance
+where the ``PHPDriver`` includes the file and the
+``ClassMetadataFactory`` caches it for later retrieval:
+
+.. code-block:: php
+
+    <?php
+    $class = $em->getClassMetadata('Entities\User');
+    // or
+    $class = $em->getMetadataFactory()->getMetadataFor('Entities\User');
 
 Static Function
 ---------------
 
-In addition to other drivers using configuration languages you can also
-programatically 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 attributes. For this you just
-need to use the ``StaticPHPDriver``:
+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 attributes or
+annotations. For this you just need to use the ``StaticPHPDriver``:
 
 .. code-block:: php
 
@@ -87,11 +164,13 @@ The API of the ClassMetadataBuilder has the following methods with a fluent inte
 -   ``setTable($name)``
 -   ``addIndex(array $columns, $indexName)``
 -   ``addUniqueConstraint(array $columns, $constraintName)``
+-   ``addNamedQuery($name, $dqlQuery)``
 -   ``setJoinedTableInheritance()``
 -   ``setSingleTableInheritance()``
 -   ``setDiscriminatorColumn($name, $type = 'string', $length = 255, $columnDefinition = null, $enumType = null, $options = [])``
 -   ``addDiscriminatorMapClass($name, $class)``
 -   ``setChangeTrackingPolicyDeferredExplicit()``
+-   ``setChangeTrackingPolicyNotify()``
 -   ``addLifecycleEvent($methodName, $event)``
 -   ``addManyToOne($name, $targetEntity, $inversedBy = null)``
 -   ``addInverseOneToOne($name, $targetEntity, $mappedBy)``
@@ -193,6 +272,7 @@ Inheritance Getters
 -  ``isInheritanceTypeNone()``
 -  ``isInheritanceTypeJoined()``
 -  ``isInheritanceTypeSingleTable()``
+-  ``isInheritanceTypeTablePerClass()``
 -  ``isInheritedField($fieldName)``
 -  ``isInheritedAssociation($fieldName)``
 
@@ -202,6 +282,7 @@ Change Tracking Getters
 
 -  ``isChangeTrackingDeferredExplicit()``
 -  ``isChangeTrackingDeferredImplicit()``
+-  ``isChangeTrackingNotify()``
 
 Field & Association Getters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -209,7 +290,6 @@ Field & Association Getters
 
 -  ``isUniqueField($fieldName)``
 -  ``isNullable($fieldName)``
--  ``isIndexed($fieldName)``
 -  ``getColumnName($fieldName)``
 -  ``getFieldMapping($fieldName)``
 -  ``getAssociationMapping($fieldName)``

docs/en/reference/query-builder.rst

@@ -344,10 +344,10 @@ the Query object which can be retrieved from ``EntityManager#createQuery()``.
 Executing a Query
 ^^^^^^^^^^^^^^^^^
 
-The QueryBuilder is only a builder object - it has no means of actually
-executing the Query. Additional functionality, such as enabling the result cache,
-cannot be set on the QueryBuilder itself. This is why you must always convert
-a QueryBuilder instance into a Query object:
+The QueryBuilder is a builder object only -  it has no means of actually
+executing the Query. Additionally a set of parameters such as query hints
+cannot be set on the QueryBuilder itself. This is why you always have to convert
+a querybuilder instance into a Query object:
 
 .. code-block:: php
 
@@ -355,8 +355,9 @@ a QueryBuilder instance into a Query object:
     // $qb instanceof QueryBuilder
     $query = $qb->getQuery();
 
-    // Enable the result cache
-    $query->enableResultCache(3600, 'my_custom_id');
+    // Set additional Query options
+    $query->setQueryHint('foo', 'bar');
+    $query->useResultCache('my_cache_id');
 
     // Execute Query
     $result = $query->getResult();
@@ -554,24 +555,6 @@ using ``addCriteria``:
     $qb->addCriteria($criteria);
     // then execute your query like normal
 
-Adding hints to a Query
-^^^^^^^^^^^^^^^^^^^^^^^
-
-You can also set query hints to a QueryBuilder by using ``setHint``:
-
-.. code-block:: php
-
-    <?php
-    // ...
-
-    // $qb instanceof QueryBuilder
-    $qb->setHint('hintName', 'hintValue');
-    // then execute your query like normal
-
-The query hint can hold anything the usual query hints can hold
-except null. Those hints will be applied to the query when the
-query is created.
-
 Low Level API
 ^^^^^^^^^^^^^
 
@@ -628,21 +611,3 @@ same query of example 6 written using
       ->add('from', new Expr\From('User', 'u'))
       ->add('where', new Expr\Comparison('u.id', '=', '?1'))
       ->add('orderBy', new Expr\OrderBy('u.name', 'ASC'));
-
-Binding Parameters to Placeholders
-----------------------------------
-
-It is often not necessary to know about the exact placeholder names when
-building a query. You can use a helper method to bind a value to a placeholder
-and directly use that placeholder in your query as a return value:
-
-.. code-block:: php
-
-    <?php
-    // $qb instanceof QueryBuilder
-
-    $qb->select('u')
-        ->from('User', 'u')
-        ->where('u.email = ' .  $qb->createNamedParameter($userInputEmail))
-    ;
-    // SELECT u FROM User u WHERE email = :dcValue1

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

@@ -295,6 +295,30 @@ level cache region.
             // other properties and methods
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Cache("NONSTRICT_READ_WRITE")
+         */
+        class State
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected int|null $id = null;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected string $name;
+
+            // other properties and methods
+        }
+
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
@@ -311,6 +335,24 @@ level cache region.
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Country:
+          type: entity
+          cache:
+            usage: READ_ONLY
+            region: my_entity_region
+          id:
+            id:
+              type: integer
+              id: true
+              generator:
+                strategy: IDENTITY
+          fields:
+            name:
+              type: string
+
+
 Association cache definition
 ----------------------------
 The most common use case is to cache entities. But we can also cache relationships.
@@ -347,6 +389,44 @@ It caches the primary keys of association and cache each element will be cached
             // other properties and methods
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /**
+         * @Entity
+         * @Cache("NONSTRICT_READ_WRITE")
+         */
+        class State
+        {
+            /**
+             * @Id
+             * @GeneratedValue
+             * @Column(type="integer")
+             */
+            protected int|null $id = null;
+
+            /**
+             * @Column(unique=true)
+             */
+            protected string $name;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @ManyToOne(targetEntity="Country")
+             * @JoinColumn(name="country_id", referencedColumnName="id")
+             */
+            protected Country|null $country;
+
+            /**
+             * @Cache("NONSTRICT_READ_WRITE")
+             * @OneToMany(targetEntity="City", mappedBy="state")
+             * @var Collection<int, City>
+             */
+            protected Collection $cities;
+
+            // other properties and methods
+        }
+
     .. code-block:: xml
 
         <?xml version="1.0" encoding="utf-8"?>
@@ -378,6 +458,38 @@ It caches the primary keys of association and cache each element will be cached
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        State:
+          type: entity
+          cache:
+            usage: NONSTRICT_READ_WRITE
+          id:
+            id:
+              type: integer
+              id: true
+              generator:
+                strategy: IDENTITY
+          fields:
+            name:
+              type: string
+
+          manyToOne:
+            state:
+              targetEntity: Country
+              joinColumns:
+                country_id:
+                  referencedColumnName: id
+              cache:
+                usage: NONSTRICT_READ_WRITE
+
+          oneToMany:
+            cities:
+              targetEntity:City
+              mappedBy: state
+              cache:
+                usage: NONSTRICT_READ_WRITE
+
 .. note::
 
     for this to work, the target entity must also be marked as cacheable.

docs/en/reference/tools.rst

@@ -83,8 +83,18 @@ The following Commands are currently available:
    cache drivers.
 -  ``orm:clear-cache:result`` Clear result cache of the various
    cache drivers.
+-  ``orm:convert-d1-schema`` Converts Doctrine 1.X schema into a
+   Doctrine 2.X schema.
+-  ``orm:convert-mapping`` Convert mapping information between
+   supported formats.
+-  ``orm:ensure-production-settings`` Verify that Doctrine is
+   properly configured for a production environment.
+-  ``orm:generate-entities`` Generate entity classes and method
+   stubs from your mapping information.
 -  ``orm:generate-proxies`` Generates proxy classes for entity
-   classes. Deprecated in favor of using native lazy objects.
+   classes.
+-  ``orm:generate-repositories`` Generate repository classes from
+   your mapping information.
 -  ``orm:run-dql`` Executes arbitrary DQL directly from the command
    line.
 -  ``orm:schema-tool:create`` Processes the schema and either
@@ -96,15 +106,15 @@ The following Commands are currently available:
 -  ``orm:schema-tool:update`` Processes the schema and either
    update the database schema of EntityManager Storage Connection or
    generate the SQL output.
--  ``orm:debug:event-manager`` Lists event listeners for an entity
-   manager, optionally filtered by event name.
--  ``orm:debug:entity-listeners`` Lists entity listeners for a given
-   entity, optionally filtered by event name.
 
-The following alias is defined:
+For these commands are also available aliases:
 
 
+-  ``orm:convert:d1-schema`` is alias for ``orm:convert-d1-schema``.
+-  ``orm:convert:mapping`` is alias for ``orm:convert-mapping``.
+-  ``orm:generate:entities`` is alias for ``orm:generate-entities``.
 -  ``orm:generate:proxies`` is alias for ``orm:generate-proxies``.
+-  ``orm:generate:repositories`` is alias for ``orm:generate-repositories``.
 
 .. note::
 
@@ -215,6 +225,163 @@ will output the SQL for the ran operation.
 
     $ php bin/doctrine orm:schema-tool:create --dump-sql
 
+Entity Generation
+-----------------
+
+Generate entity classes and method stubs from your mapping information.
+
+.. code-block:: php
+
+    $ 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
+in your entities after using this command.
+
+It is possible to use the EntityGenerator on code that you have already written. It will
+not be lost. The EntityGenerator will only append new code to your
+file and will not delete the old code. However this approach may still be prone
+to error and we suggest you use code repositories such as GIT or SVN to make
+backups of your code.
+
+It makes sense to generate the entity code if you are using entities as Data
+Access Objects only and don't put much additional logic on them. If you are
+however putting much more logic on the entities you should refrain from using
+the entity-generator and code your entities manually.
+
+.. note::
+
+    Even if you specified Inheritance options in your
+    XML or YAML Mapping files the generator cannot generate the base and
+    child classes for you correctly, because it doesn't know which
+    class is supposed to extend which. You have to adjust the entity
+    code manually for inheritance to work!
+
+
+Convert Mapping Information
+---------------------------
+
+Convert mapping information between supported formats.
+
+This is an **execute one-time** command. It should not be necessary for
+you to call this method multiple times, especially when using the ``--from-database``
+flag.
+
+Converting an existing database schema into mapping files only solves about 70-80%
+of the necessary mapping information. Additionally the detection from an existing
+database cannot detect inverse associations, inheritance types,
+entities with foreign keys as primary keys and many of the
+semantical operations on associations such as cascade.
+
+.. note::
+
+    There is no need to convert YAML or XML mapping files to annotations
+    every time you make changes. All mapping drivers are first class citizens
+    in Doctrine 2 and can be used as runtime mapping for the ORM. See the
+    docs on XML and YAML Mapping for an example how to register this metadata
+    drivers as primary mapping source.
+
+To convert some mapping information between the various supported
+formats you can use the ``ClassMetadataExporter`` to get exporter
+instances for the different formats:
+
+.. code-block:: php
+
+    <?php
+    $cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
+
+Once you have a instance you can use it to get an exporter. For
+example, the yml exporter:
+
+.. code-block:: php
+
+    <?php
+    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
+
+Now you can export some ``ClassMetadata`` instances:
+
+.. code-block:: php
+
+    <?php
+    $classes = array(
+      $em->getClassMetadata('Entities\User'),
+      $em->getClassMetadata('Entities\Profile')
+    );
+    $exporter->setMetadata($classes);
+    $exporter->export();
+
+This functionality is also available from the command line to
+convert your loaded mapping information to another format. The
+``orm:convert-mapping`` command accepts two arguments, the type to
+convert to and the path to generate it:
+
+.. code-block:: php
+
+    $ 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 ``ClassMetadata`` instances and generate YAML, XML, etc. from
+them.
+
+.. note::
+
+    Reverse Engineering is a **one-time** process that can get you started with a project.
+    Converting an existing database schema into mapping files only detects about 70-80%
+    of the necessary mapping information. Additionally the detection from an existing
+    database cannot detect inverse associations, inheritance types,
+    entities with foreign keys as primary keys and many of the
+    semantical operations on associations such as cascade.
+
+First you need to retrieve the metadata instances with the
+``DatabaseDriver``:
+
+.. code-block:: php
+
+    <?php
+    $em->getConfiguration()->setMetadataDriverImpl(
+        new \Doctrine\ORM\Mapping\Driver\DatabaseDriver(
+            $em->getConnection()->getSchemaManager()
+        )
+    );
+
+    $cmf = new \Doctrine\ORM\Tools\DisconnectedClassMetadataFactory();
+    $cmf->setEntityManager($em);
+    $metadata = $cmf->getAllMetadata();
+
+Now you can get an exporter instance and export the loaded metadata
+to yml:
+
+.. code-block:: php
+
+    <?php
+    $cme = new \Doctrine\ORM\Tools\Export\ClassMetadataExporter();
+    $exporter = $cme->getExporter('yml', '/path/to/export/yml');
+    $exporter->setMetadata($metadata);
+    $exporter->export();
+
+You can also reverse engineer a database using the
+``orm:convert-mapping`` command:
+
+.. code-block:: php
+
+    $ php bin/doctrine orm:convert-mapping --from-database yml /path/to/mapping-path-converted-to-yml
+
+.. note::
+
+    Reverse Engineering is not always working perfectly
+    depending on special cases. It will only detect Many-To-One
+    relations (even if they are One-To-One) and will try to create
+    entities from Many-To-Many tables. It also has problems with naming
+    of foreign keys that have multiple column names. Any Reverse
+    Engineered Database-Schema needs considerable manual work to become
+    a useful domain model.
+
+
 Runtime vs Development Mapping Validation
 -----------------------------------------
 

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

@@ -202,6 +202,17 @@ example we'll use an integer.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="integer") */
+            private int $version;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -210,6 +221,15 @@ example we'll use an integer.
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            version:
+              type: integer
+              version: true
+
 Alternatively a datetime type can be used (which maps to a SQL
 timestamp or datetime):
 
@@ -226,6 +246,17 @@ timestamp or datetime):
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+        class User
+        {
+            // ...
+            /** @Version @Column(type="datetime") */
+            private DateTime $version;
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -234,6 +265,15 @@ timestamp or datetime):
           </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          fields:
+            version:
+              type: datetime
+              version: true
+
 Version numbers (not timestamps) should however be preferred as
 they can not potentially conflict in a highly concurrent
 environment, unlike timestamps where this is a possibility,

docs/en/reference/typedfieldmapper.rst

@@ -47,6 +47,21 @@ Then, an entity using the ``CustomIdObject`` typed field will be correctly assig
             // ...
         }
 
+    .. 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>
@@ -161,4 +176,4 @@ You need to create a class which implements ``Doctrine\ORM\Mapping\TypedFieldMap
 
     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.
+    that behaves like the ``DefaultTypedFieldMapper`` and does not modify the type once its set prior in the chain.

docs/en/reference/unitofwork.rst

@@ -129,10 +129,16 @@ optimize the performance of the Flush Operation:
 - Temporarily mark entities as read only. If you have a very large UnitOfWork
   but know that a large set of entities has not changed, just mark them as read
   only with ``$entityManager->getUnitOfWork()->markReadOnly($entity)``.
+- Flush only a single entity with ``$entityManager->flush($entity)``.
 - Use :doc:`Change Tracking Policies <change-tracking-policies>` to use more
   explicit strategies of notifying the UnitOfWork what objects/properties
   changed.
 
+.. note::
+
+    Flush only a single entity with ``$entityManager->flush($entity)`` is deprecated and will be removed in ORM 3.0.
+    (\ `Details <https://github.com/doctrine/orm/issues/8459>`_)
+
 Query Internals
 ---------------
 

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

@@ -415,7 +415,7 @@ Transitive persistence / Cascade Operations
 Doctrine ORM provides a mechanism for transitive persistence through cascading of certain operations.
 Each association to another entity or a collection of
 entities can be configured to automatically cascade the following operations to the associated entities:
-``persist``, ``remove``, ``detach``, ``refresh`` or ``all``.
+``persist``, ``remove``, ``merge``, ``detach``, ``refresh`` or ``all``.
 
 The main use case for ``cascade: persist`` is to avoid "exposing" associated entities to your PHP application.
 Continuing with the User-Comment example of this chapter, this is how the creation of a new user and a new

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

@@ -166,7 +166,7 @@ your code. See the following code:
 
     Traversing the object graph for parts that are lazy-loaded will
     easily trigger lots of SQL queries and will perform badly if used
-    too heavily. Make sure to use DQL to fetch-join all the parts of the
+    to heavily. Make sure to use DQL to fetch-join all the parts of the
     object-graph that you need as efficiently as possible.
 
 
@@ -414,6 +414,77 @@ automatically without invoking the ``detach`` method:
 The ``detach`` operation is usually not as frequently needed and
 used as ``persist`` and ``remove``.
 
+Merging entities
+----------------
+
+Merging entities refers to the merging of (usually detached)
+entities into the context of an EntityManager so that they become
+managed again. To merge the state of an entity into an
+EntityManager use the ``EntityManager#merge($entity)`` method. The
+state of the passed entity will be merged into a managed copy of
+this entity and this copy will subsequently be returned.
+
+Example:
+
+.. code-block:: php
+
+    <?php
+    $detachedEntity = unserialize($serializedEntity); // some detached entity
+    $entity = $em->merge($detachedEntity);
+    // $entity now refers to the fully managed copy returned by the merge operation.
+    // The EntityManager $em now manages the persistence of $entity as usual.
+
+
+The semantics of the merge operation, applied to an entity X, are
+as follows:
+
+
+-  If X is a detached entity, the state of X is copied onto a
+   pre-existing managed entity instance X' of the same identity.
+-  If X is a new entity instance, a new managed copy X' will be
+   created and the state of X is copied onto this managed instance.
+-  If X is a removed entity instance, an InvalidArgumentException
+   will be thrown.
+-  If X is a managed entity, it is ignored by the merge operation,
+   however, the merge operation is cascaded to entities referenced by
+   relationships from X if these relationships have been mapped with
+   the cascade element value MERGE or ALL (see ":ref:`transitive-persistence`").
+-  For all entities Y referenced by relationships from X having the
+   cascade element value MERGE or ALL, Y is merged recursively as Y'.
+   For all such Y referenced by X, X' is set to reference Y'. (Note
+   that if X is managed then X is the same object as X'.)
+-  If X is an entity merged to X', with a reference to another
+   entity Y, where cascade=MERGE or cascade=ALL is not specified, then
+   navigation of the same association from X' yields a reference to a
+   managed object Y' with the same persistent identity as Y.
+
+The ``merge`` operation will throw an ``OptimisticLockException``
+if the entity being merged uses optimistic locking through a
+version field and the versions of the entity being merged and the
+managed copy don't match. This usually means that the entity has
+been modified while being detached.
+
+The ``merge`` operation is usually not as frequently needed and
+used as ``persist`` and ``remove``. The most common scenario for
+the ``merge`` operation is to reattach entities to an EntityManager
+that come from some cache (and are therefore detached) and you want
+to modify and persist such an entity.
+
+.. warning::
+
+    If you need to perform multiple merges of entities that share certain subparts
+    of their object-graphs and cascade merge, then you have to call ``EntityManager#clear()`` between the
+    successive calls to ``EntityManager#merge()``. Otherwise you might end up with
+    multiple copies of the "same" object in the database, however with different ids.
+
+.. note::
+
+    If you load some detached entities from a cache and you do
+    not need to persist or delete them or otherwise make use of them
+    without the need for persistence services there is no need to use
+    ``merge``. I.e. you can simply pass detached objects from a cache
+    directly to the view.
+
 
 Synchronization with the Database
 ---------------------------------
@@ -524,7 +595,7 @@ during development.
 .. note::
 
     Do not invoke ``flush`` after every change to an entity
-    or every single invocation of persist/remove/... This is an
+    or every single invocation of persist/remove/merge/... This is an
     anti-pattern and unnecessarily reduces the performance of your
     application. Instead, form units of work that operate on your
     objects and call ``flush`` when you are done. While serving a
@@ -792,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 Attribute or XML 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.

docs/en/reference/xml-mapping.rst

@@ -2,8 +2,7 @@ XML Mapping
 ===========
 
 The XML mapping driver enables you to provide the ORM metadata in
-form of XML documents. It requires the ``dom`` extension in order to be
-able to validate your mapping documents against its XML Schema.
+form of XML documents.
 
 The XML driver is backed by an XML Schema document that describes
 the structure of a mapping document. The most recent version of the
@@ -46,7 +45,7 @@ In order to work, this requires certain conventions:
 .. code-block:: php
 
     <?php
-    $driver->getLocator()->setFileExtension('.xml');
+    $driver->setFileExtension('.xml');
 
 It is recommended to put all XML mapping documents in a single
 folder but you can spread the documents over several folders if you
@@ -112,6 +111,7 @@ of several common elements:
 
             <indexes>
                 <index name="name_idx" columns="name"/>
+                <index columns="user_email"/>
             </indexes>
 
             <unique-constraints>
@@ -130,7 +130,7 @@ of several common elements:
             </id>
 
             <field name="name" column="name" type="string" length="50" nullable="true" unique="true" />
-            <field name="email" column="user_email" type="string" index="true" column-definition="CHAR(32) NOT NULL" />
+            <field name="email" column="user_email" type="string" column-definition="CHAR(32) NOT NULL" />
 
             <one-to-one field="address" target-entity="Address" inversed-by="user">
                 <cascade><cascade-remove /></cascade>
@@ -254,8 +254,6 @@ Optional attributes:
    only.
 -  unique - Should this field contain a unique value across the
    table? Defaults to false.
--  index - Should an index be created for this column? Defaults to
-   false.
 -  nullable - Should this field allow NULL as a value? Defaults to
    false.
 -  insertable - Should this field be inserted? Defaults to true.
@@ -693,6 +691,7 @@ specified by their respective tags:
 
 
 -  ``<cascade-persist />``
+-  ``<cascade-merge />``
 -  ``<cascade-remove />``
 -  ``<cascade-refresh />``
 -  ``<cascade-detach />``

docs/en/reference/yaml-mapping.rst

@@ -0,0 +1,158 @@
+YAML Mapping
+============
+
+.. 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.
+
+The YAML mapping driver enables you to provide the ORM metadata in
+form of YAML documents.
+
+The YAML mapping document of a class is loaded on-demand the first
+time it is requested and subsequently stored in the metadata cache.
+In order to work, this requires certain conventions:
+
+
+-  Each entity/mapped superclass must get its own dedicated YAML
+   mapping document.
+-  The name of the mapping document must consist of the fully
+   qualified name of the class, where namespace separators are
+   replaced by dots (.).
+-  All mapping documents should get the extension ".dcm.yml" to
+   identify it as a Doctrine mapping file. This is more of a
+   convention and you are not forced to do this. You can change the
+   file extension easily enough.
+
+.. code-block:: php
+
+    <?php
+    $driver->setFileExtension('.yml');
+
+It is recommended to put all YAML mapping documents in a single
+folder but you can spread the documents over several folders if you
+want to. In order to tell the YamlDriver where to look for your
+mapping documents, supply an array of paths as the first argument
+of the constructor, like this:
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Mapping\Driver\YamlDriver;
+
+    // $config instanceof Doctrine\ORM\Configuration
+    $driver = new YamlDriver(array('/path/to/files'));
+    $config->setMetadataDriverImpl($driver);
+
+Simplified YAML Driver
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Symfony project sponsored a driver that simplifies usage of the YAML Driver.
+The changes between the original driver are:
+
+- File Extension is .orm.yml
+- Filenames are shortened, "MyProject\\Entities\\User" will become User.orm.yml
+- You can add a global file and add multiple entities in this file.
+
+Configuration of this client works a little bit different:
+
+.. code-block:: php
+
+    <?php
+    $namespaces = array(
+        '/path/to/files1' => 'MyProject\Entities',
+        '/path/to/files2' => 'OtherProject\Entities'
+    );
+    $driver = new \Doctrine\ORM\Mapping\Driver\SimplifiedYamlDriver($namespaces);
+    $driver->setGlobalBasename('global'); // global.orm.yml
+
+Example
+-------
+
+As a quick start, here is a small example document that makes use
+of several common elements:
+
+.. code-block:: yaml
+
+    # Doctrine.Tests.ORM.Mapping.User.dcm.yml
+    Doctrine\Tests\ORM\Mapping\User:
+      type: entity
+      repositoryClass: Doctrine\Tests\ORM\Mapping\UserRepository
+      table: cms_users
+      schema: schema_name # The schema the table lies in, for platforms that support schemas (Optional, >= 2.5)
+      readOnly: true
+      indexes:
+        name_index:
+          columns: [ name ]
+      id:
+        id:
+          type: integer
+          generator:
+            strategy: AUTO
+      fields:
+        name:
+          type: string
+          length: 50
+        email:
+          type: string
+          length: 32
+          column: user_email
+          unique: true
+          options:
+            fixed: true
+            comment: User's email address
+        loginCount:
+          type: integer
+          column: login_count
+          nullable: false
+          options:
+            unsigned: true
+            default: 0
+      oneToOne:
+        address:
+          targetEntity: Address
+          joinColumn:
+            name: address_id
+            referencedColumnName: id
+            onDelete: CASCADE
+      oneToMany:
+        phonenumbers:
+          targetEntity: Phonenumber
+          mappedBy: user
+          cascade: ["persist", "merge"]
+      manyToMany:
+        groups:
+          targetEntity: Group
+          joinTable:
+            name: cms_users_groups
+            joinColumns:
+              user_id:
+                referencedColumnName: id
+            inverseJoinColumns:
+              group_id:
+                referencedColumnName: id
+      lifecycleCallbacks:
+        prePersist: [ doStuffOnPrePersist, doOtherStuffOnPrePersistToo ]
+        postPersist: [ doStuffOnPostPersist ]
+
+Be aware that class-names specified in the YAML files should be
+fully qualified.
+
+Reference
+~~~~~~~~~~~~~~~~~~~~~~
+
+Unique Constraints
+------------------
+
+It is possible to define unique constraints by the following declaration:
+
+.. code-block:: yaml
+
+    # ECommerceProduct.orm.yml
+    ECommerceProduct:
+      type: entity
+      fields:
+        # definition of some fields
+      uniqueConstraints:
+        search_idx:
+          columns: [ name, email ]
+

docs/en/sidebar.rst

@@ -5,6 +5,8 @@
    :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
@@ -35,10 +37,11 @@
    reference/query-builder
    reference/native-sql
    reference/change-tracking-policies
-   reference/partial-hydration
    reference/partial-objects
+   reference/annotations-reference
    reference/attributes-reference
    reference/xml-mapping
+   reference/yaml-mapping
    reference/php-mapping
    reference/caching
    reference/improving-performance
@@ -64,6 +67,7 @@
    cookbook/dql-user-defined-functions
    cookbook/generated-columns
    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

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

@@ -50,6 +50,38 @@ and year of production as primary keys:
             }
         }
 
+    .. code-block:: annotation
+
+        <?php
+        namespace VehicleCatalogue\Model;
+
+        /**
+         * @Entity
+         */
+        class Car
+        {
+            /** @Id @Column(type="string") */
+            private string $name;
+            /** @Id @Column(type="integer") */
+            private int $year;
+
+            public function __construct($name, $year)
+            {
+                $this->name = $name;
+                $this->year = $year;
+            }
+
+            public function getModelName(): string
+            {
+                return $this->name;
+            }
+
+            public function getYearOfProduction(): int
+            {
+                return $this->year;
+            }
+        }
+
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
@@ -64,6 +96,16 @@ and year of production as primary keys:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        VehicleCatalogue\Model\Car:
+          type: entity
+          id:
+            name:
+              type: string
+            year:
+              type: integer
+
 Now you can use this entity:
 
 .. code-block:: php
@@ -119,6 +161,7 @@ The semantics of mapping identity through foreign entities are easy:
 -   Only allowed on Many-To-One or One-To-One associations.
 -   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.
 
 Use-Case 1: Dynamic Attributes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -172,6 +215,57 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
             }
         }
 
+    .. code-block:: annotation
+
+        <?php
+        namespace Application\Model;
+
+        use Doctrine\Common\Collections\ArrayCollection;
+
+        /**
+         * @Entity
+         */
+        class Article
+        {
+            /** @Id @Column(type="integer") @GeneratedValue */
+            private int|null $id = null;
+            /** @Column(type="string") */
+            private string $title;
+
+            /**
+             * @OneToMany(targetEntity="ArticleAttribute", mappedBy="article", cascade={"ALL"}, indexBy="attribute")
+             * @var Collection<int, ArticleAttribute>
+             */
+            private Collection $attributes;
+
+            public function addAttribute($name, $value): void
+            {
+                $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
+            }
+        }
+
+        /**
+         * @Entity
+         */
+        class ArticleAttribute
+        {
+            /** @Id @ManyToOne(targetEntity="Article", inversedBy="attributes") */
+            private Article|null $article;
+
+            /** @Id @Column(type="string") */
+            private string $attribute;
+
+            /** @Column(type="string") */
+            private string $value;
+
+            public function __construct($name, $value, $article)
+            {
+                $this->attribute = $name;
+                $this->value = $value;
+                $this->article = $article;
+            }
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
@@ -190,6 +284,24 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
 
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Application\Model\ArticleAttribute:
+          type: entity
+          id:
+            article:
+              associationKey: true
+            attribute:
+              type: string
+          fields:
+            value:
+              type: string
+          manyToOne:
+            article:
+              targetEntity: Article
+              inversedBy: attributes
+
+
 Use-Case 2: Simple Derived Identity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -217,6 +329,26 @@ One good example for this is a user-address relationship:
             private User|null $user = null;
         }
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+
+        Address:
+          type: entity
+          id:
+            user:
+              associationKey: true
+          oneToOne:
+            user:
+              targetEntity: User
+
+
 Use-Case 3: Join-Table with Metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -250,7 +382,7 @@ of products purchased and maybe even the current price.
 
         public function __construct(
             #[ManyToOne(targetEntity: Customer::class)]
-            private Customer $customer
+            private Customer $customer,
         ) {
             $this->items = new ArrayCollection();
             $this->created = new DateTime("now");
@@ -295,7 +427,6 @@ of products purchased and maybe even the current price.
             $this->order = $order;
             $this->product = $product;
             $this->offeredPrice = $product->getCurrentPrice();
-            $this->amount = $amount;
         }
     }
 

docs/en/tutorials/embeddables.rst

@@ -44,6 +44,33 @@ instead of simply adding the respective columns to the ``User`` class.
             private string $country;
         }
 
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address") */
+            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:: xml
 
         <doctrine-mapping>
@@ -59,6 +86,22 @@ instead of simply adding the respective columns to the ``User`` class.
             </embeddable>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          embedded:
+            address:
+              class: Address
+
+        Address:
+          type: embeddable
+          fields:
+            street: { type: string }
+            postalCode: { type: string }
+            city: { type: string }
+            country: { type: string }
+
 In terms of your database schema, Doctrine will automatically inline all
 columns from the ``Address`` class into the table of the ``User`` class,
 just as if you had declared them directly there.
@@ -104,12 +147,32 @@ The following example shows you how to set your prefix to ``myPrefix_``:
             private Address $address;
         }
 
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address", columnPrefix = "myPrefix_") */
+            private $address;
+        }
+
     .. code-block:: xml
 
         <entity name="User">
             <embedded name="address" class="Address" column-prefix="myPrefix_" />
         </entity>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          embedded:
+            address:
+              class: Address
+              columnPrefix: myPrefix_
+
 To have Doctrine drop the prefix and use the value object's property name
 directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
 
@@ -126,12 +189,32 @@ directly, set ``columnPrefix=false`` (``use-column-prefix="false"`` for XML):
             private Address $address;
         }
 
+    .. code-block:: annotation
+
+        <?php
+
+        /** @Entity */
+        class User
+        {
+            /** @Embedded(class = "Address", columnPrefix = false) */
+            private Address $address;
+        }
+
     .. code-block:: xml
 
         <entity name="User">
             <embedded name="address" class="Address" use-column-prefix="false" />
         </entity>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          embedded:
+            address:
+              class: Address
+              columnPrefix: false
+
 
 DQL
 ---

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

@@ -17,7 +17,6 @@ can be called without triggering a full load of the collection:
 -  ``Collection#contains($entity)``
 -  ``Collection#containsKey($key)``
 -  ``Collection#count()``
--  ``Collection#first()``
 -  ``Collection#get($key)``
 -  ``Collection#isEmpty()``
 -  ``Collection#slice($offset, $length = null)``
@@ -67,6 +66,23 @@ switch to extra lazy as shown in these examples:
             public Collection $users;
         }
 
+    .. code-block:: annotation
+
+        <?php
+        namespace Doctrine\Tests\Models\CMS;
+
+        /**
+         * @Entity
+         */
+        class CmsGroup
+        {
+            /**
+             * @ManyToMany(targetEntity="CmsUser", mappedBy="groups", fetch="EXTRA_LAZY")
+             * @var Collection<int, CmsUser>
+             */
+            public Collection $users;
+        }
+
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
@@ -80,3 +96,14 @@ switch to extra lazy as shown in these examples:
                 <many-to-many field="users" target-entity="CmsUser" mapped-by="groups" fetch="EXTRA_LAZY" />
             </entity>
         </doctrine-mapping>
+
+    .. code-block:: yaml
+
+        Doctrine\Tests\Models\CMS\CmsGroup:
+          type: entity
+          # ...
+          manyToMany:
+            users:
+              targetEntity: CmsUser
+              mappedBy: groups
+              fetch: EXTRA_LAZY

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

@@ -0,0 +1,26 @@
+Getting Started: Database First
+===============================
+
+.. note:: *Development Workflows*
+
+    When you :doc:`Code First <getting-started>`, you
+    start with developing Objects and then map them onto your database. When
+    you :doc:`Model First <getting-started-models>`, you are modelling your application using tools (for
+    example UML) and generate database schema and PHP code from this model.
+    When you have a Database First, you already have a database schema
+    and generate the corresponding PHP code from it.
+
+.. note::
+
+    This getting started guide is in development.
+
+Development of new applications often starts with an existing database schema.
+When the database schema is the starting point for your application, then
+development is said to use the *Database First* approach to Doctrine.
+
+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 spun off a subproject, Doctrine CodeGenerator, that will fill this gap and
+allow you to do *Database First* development.

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

@@ -0,0 +1,24 @@
+Getting Started: Model First
+============================
+
+.. note:: *Development Workflows*
+
+    When you :doc:`Code First <getting-started>`, you
+    start with developing Objects and then map them onto your database. When
+    you Model First, you are modelling your application using tools (for
+    example UML) and generate database schema and PHP code from this model.
+    When you have a :doc:`Database First <getting-started-database>`, then you already have a database schema
+    and generate the corresponding PHP code from it.
+
+.. note::
+
+    This getting started guide is in development.
+
+There are applications when you start with a high-level description of the
+model using modelling tools such as UML. Modelling tools could also be Excel,
+XML or CSV files that describe the model in some structured way. If your
+application is using a modelling tool, then the development workflow is said to
+be a  *Model First* approach to Doctrine2.
+
+In this workflow you always change the model description and then regenerate
+both PHP code and database schema from this model.

docs/en/tutorials/getting-started.rst

@@ -27,7 +27,7 @@ What is Doctrine?
 -----------------
 
 Doctrine ORM is an `object-relational mapper (ORM) <https://en.wikipedia.org/wiki/Object-relational_mapping>`_
-for PHP that provides transparent persistence for PHP objects. It uses the Data Mapper
+for PHP 7.1+ that provides transparent persistence for PHP objects. It uses the Data Mapper
 pattern at the heart, aiming for a complete separation of your domain/business
 logic from the persistence in a relational database management system.
 
@@ -49,9 +49,8 @@ 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 can be final or read-only when you use
-:ref:`native lazy objects <reference-native-lazy-objects>`.
-It may contain final methods or read-only properties too.
+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
 -----------------------------
@@ -83,9 +82,10 @@ that directory with the following contents:
 
     {
         "require": {
-            "doctrine/orm": "^3",
-            "doctrine/dbal": "^4",
-            "symfony/cache": "^7"
+            "doctrine/orm": "^2.11.0",
+            "doctrine/dbal": "^3.2",
+            "symfony/yaml": "^5.4",
+            "symfony/cache": "^5.4"
         },
         "autoload": {
             "psr-0": {"": "src/"}
@@ -107,8 +107,12 @@ Add the following directories::
     doctrine2-tutorial
     |-- config
     |   `-- xml
+    |   `-- yaml
     `-- src
 
+.. 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
@@ -139,15 +143,23 @@ step:
     require_once "vendor/autoload.php";
 
     // Create a simple "default" Doctrine ORM configuration for Attributes
-    $config = ORMSetup::createAttributeMetadataConfig( // on PHP < 8.4, use ORMSetup::createAttributeMetadataConfiguration()
+    $config = ORMSetup::createAttributeMetadataConfiguration(
         paths: [__DIR__ . '/src'],
         isDevMode: true,
     );
-    // or if you prefer XML
-    // $config = ORMSetup::createXMLMetadataConfig( // on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration()
+    // 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,
+    // );
 
     // configuring the database connection
     $connection = DriverManager::getConnection([
@@ -158,6 +170,10 @@ step:
     // obtaining the entity manager
     $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.
+
 The ``require_once`` statement sets up the class autoloading for Doctrine and
 its dependencies using Composer's autoloader.
 
@@ -484,8 +500,8 @@ 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 attributes directly in
-the Entity class itself, or in an external XML file. This
-Getting Started guide will demonstrate metadata mappings using both
+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::
@@ -511,6 +527,33 @@ methods, but you only need to choose one.
             // .. (other code)
         }
 
+    .. code-block:: annotation
+
+        <?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:: xml
 
         <!-- config/xml/Product.dcm.xml -->
@@ -528,6 +571,25 @@ methods, but you only need to choose one.
               </entity>
         </doctrine-mapping>
 
+.. 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.
+
+    .. code-block:: yaml
+
+        # config/yaml/Product.dcm.yml
+        Product:
+          type: entity
+          table: products
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            name:
+              type: string
+
 The top-level ``entity`` definition specifies information about
 the class and table name. The primitive type ``Product#name`` is
 defined as a ``field`` attribute. The ``id`` property is defined with
@@ -535,7 +597,7 @@ the ``id`` tag.  It has a ``generator`` tag nested inside, which
 specifies that the primary key generation mechanism should automatically
 use the database platform's native id generation strategy (for
 example, AUTO INCREMENT in the case of MySql, or Sequences in the
-case of PostgreSQL and Oracle).
+case of PostgreSql and Oracle).
 
 Now that we have defined our first entity and its metadata,
 let's update the database schema:
@@ -1020,6 +1082,59 @@ the ``Product`` before:
             // ... (other code)
         }
 
+    .. code-block:: annotation
+
+        <?php
+        // src/Bug.php
+
+        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", inversedBy="assignedBugs")
+             */
+            private User|null $engineer;
+
+            /**
+             * @ORM\ManyToOne(targetEntity="User", inversedBy="reportedBugs")
+             */
+            private User|null $reporter;
+
+            /**
+             * @ORM\ManyToMany(targetEntity="Product")
+             */
+            private Collection $products;
+
+            // ... (other code)
+        }
+
     .. code-block:: xml
 
         <!-- config/xml/Bug.dcm.xml -->
@@ -1044,6 +1159,40 @@ the ``Product`` before:
             </entity>
         </doctrine-mapping>
 
+.. 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.
+
+    .. code-block:: yaml
+
+        # config/yaml/Bug.dcm.yml
+        Bug:
+          type: entity
+          table: bugs
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            description:
+              type: text
+            created:
+              type: datetime
+            status:
+              type: string
+          manyToOne:
+            reporter:
+              targetEntity: User
+              inversedBy: reportedBugs
+            engineer:
+              targetEntity: User
+              inversedBy: assignedBugs
+          manyToMany:
+            products:
+              targetEntity: Product
+
+
 Here we have the entity, id and primitive type definitions.
 For the "created" field we have used the ``datetime`` type,
 which translates the YYYY-mm-dd HH:mm:ss database format
@@ -1100,6 +1249,47 @@ Finally, we'll add metadata mappings for the ``User`` entity.
             // .. (other code)
         }
 
+    .. code-block:: annotation
+
+        <?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")
+             * @var int
+             */
+            private int|null $id = null;
+
+            /**
+             * @ORM\Column(type="string")
+             * @var string
+             */
+            private string $name;
+
+            /**
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="reporter")
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
+             */
+            private Collection $reportedBugs;
+
+            /**
+             * @ORM\OneToMany(targetEntity="Bug", mappedBy="engineer")
+             * @var Collection<int, Bug> An ArrayCollection of Bug objects.
+             */
+            private Collection $assignedBugs;
+
+            // .. (other code)
+        }
     .. code-block:: xml
 
         <!-- config/xml/User.dcm.xml -->
@@ -1120,7 +1310,33 @@ Finally, we'll add metadata mappings for the ``User`` entity.
              </entity>
         </doctrine-mapping>
 
-Here are some new things to mention about the ``one-to-many`` tags.
+.. 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.
+
+    .. code-block:: yaml
+
+        # config/yaml/User.dcm.yml
+        User:
+          type: entity
+          table: users
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            name:
+              type: string
+          oneToMany:
+            reportedBugs:
+              targetEntity: Bug
+              mappedBy: reporter
+            assignedBugs:
+              targetEntity: Bug
+              mappedBy: engineer
+
+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
@@ -1288,7 +1504,7 @@ The console output of this script is then:
     result set to retrieve entities from the database. DQL boils down to a
     Native SQL statement and a ``ResultSetMapping`` instance itself. Using
     Native SQL you could even use stored procedures for data retrieval, or
-    make use of advanced non-portable database queries like PostgreSQL's
+    make use of advanced non-portable database queries like PostgreSql's
     recursive queries.
 
 
@@ -1584,6 +1800,21 @@ we have to adjust the metadata slightly.
             // ...
         }
 
+    .. code-block:: annotation
+
+        <?php
+
+        use Doctrine\ORM\Mapping as ORM;
+
+        /**
+         * @ORM\Entity(repositoryClass="BugRepository")
+         * @ORM\Table(name="bugs")
+         */
+        class Bug
+        {
+            // ...
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
@@ -1596,6 +1827,16 @@ we have to adjust the metadata slightly.
               </entity>
         </doctrine-mapping>
 
+.. 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.
+
+    .. code-block:: yaml
+
+        Bug:
+          type: entity
+          repositoryClass: BugRepository
+
 Now we can remove our query logic in all the places and instead use them through the EntityRepository.
 As an example here is the code of the first use case "List of Bugs":
 

docs/en/tutorials/ordered-associations.rst

@@ -27,6 +27,22 @@ can specify the ``#[OrderBy]`` in the following way:
             private Collection $groups;
         }
 
+    .. code-block:: annotation
+
+        <?php
+        /** @Entity **/
+        class User
+        {
+            // ...
+
+            /**
+             * @ManyToMany(targetEntity="Group")
+             * @OrderBy({"name" = "ASC"})
+             * @var Collection<int, Group>
+             */
+            private Collection $groups;
+        }
+
     .. code-block:: xml
 
         <doctrine-mapping>
@@ -39,6 +55,23 @@ can specify the ``#[OrderBy]`` in the following way:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        User:
+          type: entity
+          manyToMany:
+            groups:
+              orderBy: { 'name': 'ASC' }
+              targetEntity: Group
+              joinTable:
+                name: users_groups
+                joinColumns:
+                  user_id:
+                    referencedColumnName: id
+                inverseJoinColumns:
+                  group_id:
+                    referencedColumnName: id
+
 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 (,).

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

@@ -64,7 +64,7 @@ which has mapping metadata that is overridden by the attribute above:
         #[Column(name: 'trait_foo', type: 'integer', length: 100, nullable: true, unique: true)]
         protected int $foo;
 
-        #[OneToOne(targetEntity: Bar::class, cascade: ['persist'])]
+        #[OneToOne(targetEntity: Bar::class, cascade: ['persist', 'merge'])]
         #[JoinColumn(name: 'example_trait_bar_id', referencedColumnName: 'id')]
         protected Bar|null $bar = null;
     }
@@ -79,4 +79,4 @@ The case for just extending a class would be just the same but:
         // ...
     }
 
-Overriding is also supported via XML (:ref:`examples <inheritence_mapping_overrides>`).
+Overriding is also supported via XML and YAML (:ref:`examples <inheritence_mapping_overrides>`).

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

@@ -24,7 +24,9 @@ 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.
 
 The code and mappings for the Market entity looks like this:
 
@@ -32,9 +34,16 @@ The code and mappings for the Market entity looks like this:
     .. literalinclude:: working-with-indexed-associations/Market.php
         :language: attribute
 
+    .. literalinclude:: working-with-indexed-associations/Market-annotations.php
+        :language: annotation
+
     .. literalinclude:: working-with-indexed-associations/market.xml
         :language: xml
 
+    .. literalinclude:: working-with-indexed-associations/market.yaml
+        :language: yaml
+
+
 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)``
 we pick a stock traded on the particular market by symbol. If this stock doesn't exist an exception is thrown.
@@ -74,6 +83,47 @@ here are the code and mappings for it:
             }
         }
 
+    .. code-block:: annotation
+
+        <?php
+        namespace Doctrine\Tests\Models\StockExchange;
+
+        /**
+         * @Entity
+         * @Table(name="exchange_stocks")
+         */
+        class Stock
+        {
+            /**
+             * @Id @GeneratedValue @Column(type="integer")
+             * @var int
+             */
+            private int|null $id = null;
+
+            /**
+             * @Column(type="string", unique=true)
+             */
+            private string $symbol;
+
+            /**
+             * @ManyToOne(targetEntity="Market", inversedBy="stocks")
+             * @var Market
+             */
+            private Market|null $market = null;
+
+            public function __construct($symbol, Market $market)
+            {
+                $this->symbol = $symbol;
+                $this->market = $market;
+                $market->addStock($this);
+            }
+
+            public function getSymbol(): string
+            {
+                return $this->symbol;
+            }
+        }
+
     .. code-block:: xml
 
         <?xml version="1.0" encoding="UTF-8"?>
@@ -92,6 +142,23 @@ here are the code and mappings for it:
             </entity>
         </doctrine-mapping>
 
+    .. code-block:: yaml
+
+        Doctrine\Tests\Models\StockExchange\Stock:
+          type: entity
+          id:
+            id:
+              type: integer
+              generator:
+                strategy: AUTO
+          fields:
+            symbol:
+              type: string
+          manyToOne:
+            market:
+              targetEntity: Market
+              inversedBy: stocks
+
 Querying indexed associations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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.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

@@ -35,6 +35,7 @@
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:element name="cascade-all" type="orm:emptyType" minOccurs="0"/>
       <xs:element name="cascade-persist" type="orm:emptyType" minOccurs="0"/>
+      <xs:element name="cascade-merge" type="orm:emptyType" minOccurs="0"/>
       <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"/>
@@ -81,6 +82,36 @@
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>
 
+  <xs:complexType name="named-query">
+    <xs:attribute name="name" type="xs:string" use="required" />
+    <xs:attribute name="query" type="xs:string" use="required" />
+    <xs:anyAttribute namespace="##other"/>
+  </xs:complexType>
+
+  <xs:complexType name="named-queries">
+    <xs:sequence>
+      <xs:element name="named-query" type="orm:named-query" minOccurs="1" maxOccurs="unbounded" />
+      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
+    </xs:sequence>
+  </xs:complexType>
+
+  <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" />
+    <xs:attribute name="result-set-mapping" type="xs:string" />
+  </xs:complexType>
+
+  <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"/>
@@ -112,6 +143,23 @@
     <xs:attribute name="discriminator-column" type="xs:string" use="optional" />
   </xs:complexType>
 
+  <xs:complexType name="sql-result-set-mapping">
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
+        <xs:choice minOccurs="0" maxOccurs="unbounded">
+            <xs:element name="entity-result" type="orm:entity-result"/>
+            <xs:element name="column-result" type="orm:column-result"/>
+        </xs:choice>
+        <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
+    </xs:choice>
+    <xs:attribute name="name" type="xs:string" use="required" />
+  </xs:complexType>
+
+  <xs:complexType name="sql-result-set-mappings">
+    <xs:choice minOccurs="0" maxOccurs="unbounded">
+      <xs:element name="sql-result-set-mapping" type="orm:sql-result-set-mapping" minOccurs="1" maxOccurs="unbounded" />
+    </xs:choice>
+  </xs:complexType>
+
   <xs:complexType name="cache">
     <xs:attribute name="usage" type="orm:cache-usage-type" />
     <xs:attribute name="region" type="xs:string" />
@@ -127,6 +175,9 @@
       <xs:element name="discriminator-map" type="orm:discriminator-map" minOccurs="0"/>
       <xs:element name="lifecycle-callbacks" type="orm:lifecycle-callbacks" minOccurs="0" maxOccurs="1" />
       <xs:element name="entity-listeners" type="orm:entity-listeners" minOccurs="0" maxOccurs="1" />
+      <xs:element name="named-queries" type="orm:named-queries" minOccurs="0" maxOccurs="1" />
+      <xs:element name="named-native-queries" type="orm:named-native-queries" minOccurs="0" maxOccurs="1" />
+      <xs:element name="sql-result-set-mappings" type="orm:sql-result-set-mappings" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="id" type="orm:id" minOccurs="0" maxOccurs="unbounded" />
       <xs:element name="field" type="orm:field" minOccurs="0" maxOccurs="unbounded"/>
       <xs:element name="embedded" type="orm:embedded" minOccurs="0" maxOccurs="unbounded"/>
@@ -155,20 +206,10 @@
     </xs:restriction>
   </xs:simpleType>
 
-  <xs:complexType name="object">
-    <xs:attribute name="class" type="xs:string" use="required"/>
-    <xs:anyAttribute namespace="##other"/>
-  </xs:complexType>
-
   <xs:complexType name="option" mixed="true">
-    <xs:choice minOccurs="0" maxOccurs="1">
-      <xs:element name="object" type="orm:object"/>
-      <xs:sequence>
-        <xs:choice minOccurs="0" maxOccurs="unbounded">
-          <xs:element name="option" type="orm:option"/>
-          <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
-        </xs:choice>
-      </xs:sequence>
+    <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"/>
@@ -198,6 +239,7 @@
     <xs:restriction base="xs:token">
       <xs:enumeration value="DEFERRED_IMPLICIT"/>
       <xs:enumeration value="DEFERRED_EXPLICIT"/>
+      <xs:enumeration value="NOTIFY"/>
     </xs:restriction>
   </xs:simpleType>
 
@@ -205,6 +247,7 @@
     <xs:restriction base="xs:token">
       <xs:enumeration value="SINGLE_TABLE"/>
       <xs:enumeration value="JOINED"/>
+      <xs:enumeration value="TABLE_PER_CLASS"/>
     </xs:restriction>
   </xs:simpleType>
 
@@ -214,6 +257,7 @@
       <xs:enumeration value="SEQUENCE"/>
       <xs:enumeration value="IDENTITY"/>
       <xs:enumeration value="AUTO"/>
+      <xs:enumeration value="UUID"/>
       <xs:enumeration value="CUSTOM" />
     </xs:restriction>
   </xs:simpleType>
@@ -253,7 +297,6 @@
     <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="index" 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" />

phpcs.xml.dist

@@ -11,7 +11,7 @@
     <!-- Ignore warnings, show progress of the run and show sniff names -->
     <arg value="nps"/>
 
-    <config name="php_version" value="80100"/>
+    <config name="php_version" value="70100"/>
 
     <file>src</file>
     <file>tests</file>
@@ -20,38 +20,38 @@
     <exclude-pattern>*/tests/Tests/ORM/Tools/Export/export/*</exclude-pattern>
 
     <rule ref="Doctrine">
+        <exclude name="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingAnyTypeHint" />
+        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingReturnTypeHint"/>
+        <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint" />
         <exclude name="SlevomatCodingStandard.Exceptions.ReferenceThrowableOnly.ReferencedGeneralException"/>
         <exclude name="SlevomatCodingStandard.ControlStructures.EarlyExit"/>
         <exclude name="SlevomatCodingStandard.Classes.SuperfluousAbstractClassNaming"/>
         <exclude name="SlevomatCodingStandard.Classes.SuperfluousExceptionNaming"/>
-        <exclude name="SlevomatCodingStandard.Classes.ModernClassNameReference.ClassNameReferencedViaFunctionCall"/>
+    </rule>
+
+    <rule ref="SlevomatCodingStandard.Commenting.RequireOneLineDocComment.MultiLineDocComment">
+        <!-- Remove when dropping PHPUnit 7 -->
+        <exclude-pattern>*/tests/*</exclude-pattern>
     </rule>
 
     <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint">
+        <exclude-pattern>*/src/*</exclude-pattern>
         <!--
             that class extends another one inside src/ and can therefore not
             have more native typehints since its parent cannot have them: that
             would break signature compatibility.
         -->
         <exclude-pattern>tests/Tests/Mocks/HydratorMockStatement.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/Models/Cache/ComplexAction.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/Models/DDC117/DDC117ArticleDetails.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/Models/DDC117/DDC117Translation.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/ORM/Functional/Ticket/DDC2579Test.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/ORM/Functional/ValueObjectsTest.php</exclude-pattern>
     </rule>
 
-    <rule ref="SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingAnyTypeHint">
-        <exclude-pattern>tests/*</exclude-pattern>
-    </rule>
-
-    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint">
-        <exclude-pattern>tests/*</exclude-pattern>
+    <rule ref="SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint">
+        <exclude-pattern>*/src/*</exclude-pattern>
     </rule>
 
     <rule ref="PSR1.Classes.ClassDeclaration.MultipleClasses">
-        <exclude-pattern>src/Mapping/Driver/LoadMappingFileImplementation.php</exclude-pattern>
-        <exclude-pattern>src/Mapping/GetReflectionClassImplementation.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/Driver/CompatibilityAnnotationDriver.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/CommandCompatibility.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Helper/EntityManagerHelper.php</exclude-pattern>
         <exclude-pattern>tests/*</exclude-pattern>
     </rule>
 
@@ -70,6 +70,14 @@
         <exclude-pattern>src/Tools/ToolEvents.php</exclude-pattern>
     </rule>
 
+    <rule ref="SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingTraversableTypeHintSpecification">
+        <!-- https://github.com/doctrine/annotations/issues/129 -->
+        <exclude-pattern>src/Mapping/Column.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/Index.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/Table.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/UniqueConstraint.php</exclude-pattern>
+    </rule>
+
     <rule ref="SlevomatCodingStandard.Operators.DisallowEqualOperators.DisallowedNotEqualOperator">
         <exclude-pattern>src/Internal/Hydration/AbstractHydrator.php</exclude-pattern>
     </rule>
@@ -86,6 +94,7 @@
         <exclude-pattern>src/Mapping/Cache.php</exclude-pattern>
         <exclude-pattern>src/Mapping/ChangeTrackingPolicy.php</exclude-pattern>
         <exclude-pattern>src/Mapping/Column.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/ColumnResult.php</exclude-pattern>
         <exclude-pattern>src/Mapping/CustomIdGenerator.php</exclude-pattern>
         <exclude-pattern>src/Mapping/DiscriminatorColumn.php</exclude-pattern>
         <exclude-pattern>src/Mapping/DiscriminatorMap.php</exclude-pattern>
@@ -93,6 +102,8 @@
         <exclude-pattern>src/Mapping/Embedded.php</exclude-pattern>
         <exclude-pattern>src/Mapping/Entity.php</exclude-pattern>
         <exclude-pattern>src/Mapping/EntityListeners.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/EntityResult.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/FieldResult.php</exclude-pattern>
         <exclude-pattern>src/Mapping/GeneratedValue.php</exclude-pattern>
         <exclude-pattern>src/Mapping/HasLifecycleCallbacks.php</exclude-pattern>
         <exclude-pattern>src/Mapping/Id.php</exclude-pattern>
@@ -104,6 +115,10 @@
         <exclude-pattern>src/Mapping/ManyToMany.php</exclude-pattern>
         <exclude-pattern>src/Mapping/ManyToOne.php</exclude-pattern>
         <exclude-pattern>src/Mapping/MappedSuperclass.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/NamedNativeQueries.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/NamedNativeQuery.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/NamedQueries.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/NamedQuery.php</exclude-pattern>
         <exclude-pattern>src/Mapping/OneToMany.php</exclude-pattern>
         <exclude-pattern>src/Mapping/OneToOne.php</exclude-pattern>
         <exclude-pattern>src/Mapping/OrderBy.php</exclude-pattern>
@@ -116,6 +131,8 @@
         <exclude-pattern>src/Mapping/PreRemove.php</exclude-pattern>
         <exclude-pattern>src/Mapping/PreUpdate.php</exclude-pattern>
         <exclude-pattern>src/Mapping/SequenceGenerator.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/SqlResultSetMapping.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/SqlResultSetMappings.php</exclude-pattern>
         <exclude-pattern>src/Mapping/Table.php</exclude-pattern>
         <exclude-pattern>src/Mapping/UniqueConstraint.php</exclude-pattern>
         <exclude-pattern>src/Mapping/Version.php</exclude-pattern>
@@ -125,36 +142,6 @@
         <exclude-pattern>src/Cache/DefaultQueryCache.php</exclude-pattern>
     </rule>
 
-    <rule ref="SlevomatCodingStandard.Commenting.ForbiddenAnnotations">
-        <properties>
-            <property name="forbiddenAnnotations" type="array">
-                <!--
-                    From Doctrine Coding Standard:
-                    Forbid useless annotations - Git and LICENCE file provide more accurate information
-                -->
-                <element value="@api"/>
-                <element value="@author"/>
-                <element value="@category"/>
-                <element value="@copyright"/>
-                <element value="@created"/>
-                <element value="@license"/>
-                <element value="@package"/>
-                <element value="@since"/>
-                <element value="@subpackage"/>
-                <element value="@version"/>
-
-                <!-- Additionally forbid oldschool PHPUnit annotations to force the usage of attributes -->
-                <element value="@covers"/>
-                <element value="@depends"/>
-                <element value="@dataProvider"/>
-                <element value="@group"/>
-                <element value="@requires"/>
-                <element value="@test"/>
-                <element value="@testWith"/>
-            </property>
-        </properties>
-    </rule>
-
     <rule ref="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming">
         <exclude-pattern>src/EntityManagerInterface.php</exclude-pattern>
     </rule>
@@ -210,6 +197,9 @@
         <exclude-pattern>tests/Tests/Models/DDC1590/DDC1590User.php</exclude-pattern>
     </rule>
 
+    <rule ref="SlevomatCodingStandard.Commenting.ForbiddenAnnotations.AnnotationForbidden">
+        <exclude-pattern>tests/Tests/ORM/Functional/Ticket/DDC832Test.php</exclude-pattern>
+    </rule>
 
     <rule ref="Squiz.Classes.ValidClassName.NotCamelCaps">
         <!-- we need to test what happens with an stdClass proxy -->
@@ -234,11 +224,12 @@
 
     <rule ref="PSR2.Methods.MethodDeclaration.Underscore">
         <exclude-pattern>src/AbstractQuery.php</exclude-pattern>
-        <exclude-pattern>src/Mapping/ClassMetadata.php</exclude-pattern>
+        <exclude-pattern>src/Mapping/ClassMetadataInfo.php</exclude-pattern>
         <exclude-pattern>src/NativeQuery.php</exclude-pattern>
         <exclude-pattern>src/Query.php</exclude-pattern>
         <exclude-pattern>src/Query/TreeWalkerAdapter.php</exclude-pattern>
         <exclude-pattern>src/Tools/Export/Driver/AbstractExporter.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/AnnotationExporter.php</exclude-pattern>
         <exclude-pattern>src/Tools/Export/Driver/PhpExporter.php</exclude-pattern>
         <!-- extending a class from another package -->
         <exclude-pattern>tests/Tests/Mocks/DatabasePlatformMock.php</exclude-pattern>
@@ -248,6 +239,20 @@
     </rule>
 
     <rule ref="Squiz.NamingConventions.ValidVariableName.PublicHasUnderscore">
+        <exclude-pattern>src/AbstractQuery.php</exclude-pattern>
+        <exclude-pattern>src/Configuration.php</exclude-pattern>
+        <exclude-pattern>src/EntityRepository.php</exclude-pattern>
+        <exclude-pattern>src/Internal/Hydration/AbstractHydrator.php</exclude-pattern>
+        <exclude-pattern>src/Query/Exec/AbstractSqlExecutor.php</exclude-pattern>
+        <exclude-pattern>src/Query/Exec/AbstractSqlExecutor.php</exclude-pattern>
+        <exclude-pattern>src/Query/Printer.php</exclude-pattern>
+        <exclude-pattern>src/Tools/EntityRepositoryGenerator.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Console/Helper/EntityManagerHelper.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/AbstractExporter.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/AnnotationExporter.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/PhpExporter.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/XmlExporter.php</exclude-pattern>
+        <exclude-pattern>src/Tools/Export/Driver/YamlExporter.php</exclude-pattern>
         <!-- the impact of changing this would be too big -->
         <exclude-pattern>tests/Tests/OrmFunctionalTestCase.php</exclude-pattern>
     </rule>
@@ -262,7 +267,6 @@
         <!-- Using @group and Group entity in the same file -->
         <exclude-pattern>tests/Tests/ORM/Functional/Ticket/DDC1885Test.php</exclude-pattern>
         <exclude-pattern>tests/Tests/ORM/Functional/Ticket/DDC1843Test.php</exclude-pattern>
-        <exclude-pattern>tests/Tests/ORM/Mapping/ClassMetadataFactoryTest.php</exclude-pattern>
     </rule>
 
     <rule ref="Generic.CodeAnalysis.EmptyStatement.DetectedElse">
@@ -277,4 +281,9 @@
         <!-- https://github.com/doctrine/orm/issues/8537 -->
         <exclude-pattern>src/QueryBuilder.php</exclude-pattern>
     </rule>
+
+    <rule ref="SlevomatCodingStandard.PHP.UselessParentheses">
+        <!-- We need those parentheses to make enum access seem like valid syntax on PHP 7 -->
+        <exclude-pattern>src/Mapping/Driver/XmlDriver.php</exclude-pattern>
+    </rule>
 </ruleset>

phpstan-dbal2.neon

@@ -0,0 +1,122 @@
+includes:
+    - phpstan-baseline.neon
+    - phpstan-params.neon
+
+parameters:
+    reportUnmatchedIgnoredErrors: false
+
+    ignoreErrors:
+        # PHPStan doesn't understand our method_exists() safeguards.
+        - '/Call to function method_exists.*/'
+        - '/Call to an undefined method Doctrine\\DBAL\\Connection::createSchemaManager\(\)\./'
+        # Class name will change in DBAL 3.
+        - '/^Class Doctrine\\DBAL\\Platforms\\PostgreSQLPlatform not found\.$/'
+        - '/^Class Doctrine\\DBAL\\Platforms\\AbstractMySQLPlatform not found\.$/'
+        - '/^Class Doctrine\\DBAL\\Platforms\\MySQLPlatform not found\.$/'
+        -
+            message: '/Doctrine\\DBAL\\Platforms\\MyS(ql|QL)Platform/'
+            path: src/Mapping/ClassMetadataFactory.php
+
+        # Forward compatibility for DBAL 3.5
+        - '/^Call to an undefined method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getAlterSchemaSQL\(\).$/'
+
+        # Forward compatibility for DBAL 3.4
+        - '/^Call to an undefined method Doctrine\\DBAL\\Cache\\QueryCacheProfile::[gs]etResultCache\(\)\.$/'
+        -
+            message: '/^Call to an undefined static method Doctrine\\DBAL\\Configuration::[gs]etResultCache\(\)\.$/'
+            path: src/Configuration.php
+        -
+            message: '/^Parameter #3 \$resultCache of class Doctrine\\DBAL\\Cache\\QueryCacheProfile constructor/'
+            path: src/AbstractQuery.php
+        -
+            message: '/^Parameter #2 \$\w+ of method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getDateAdd\w+Expression\(\) expects int, string given\.$/'
+            path: src/Query/AST/Functions/DateAddFunction.php
+        -
+            message: '/^Parameter #2 \$\w+ of method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getDateSub\w+Expression\(\) expects int, string given\.$/'
+            path: src/Query/AST/Functions/DateSubFunction.php
+
+        # False positive
+        -
+            message: '/^Call to an undefined method Doctrine\\Common\\Cache\\Cache::deleteAll\(\)\.$/'
+            count: 1
+            path: src/Tools/Console/Command/ClearCache/ResultCommand.php
+        # See https://github.com/doctrine/dbal/pull/5129
+        -
+            message: '/^Parameter #3 \$startPos of method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getLocateExpression\(\) expects int\|false, string given\.$/'
+            count: 1
+            path: src/Query/AST/Functions/LocateFunction.php
+
+        # Won't get fixed in DBAL 2
+        -
+            message: '#.*deleteItem.*expects string.*#'
+            count: 1
+            path: src/Query.php
+
+        -
+            message: '#.*get(Drop|Create)SchemaS(ql|QL).*should return list.*but returns array.*#'
+            count: 2
+            path: src/Tools/SchemaTool.php
+
+        -
+            message: '#introspectSchema#'
+            count: 2
+            identifier: 'method.notFound'
+            path: src/Tools/SchemaTool.php
+
+        -
+            message: '#getMaxIdentifierLength#'
+            identifier: 'method.deprecatedClass'
+            path: src/Mapping/ClassMetadataFactory.php
+
+        -
+            message: "#^Parameter \\#2 \\$start of method Doctrine\\\\DBAL\\\\Platforms\\\\AbstractPlatform\\:\\:getSubstringExpression\\(\\) expects int, string given\\.$#"
+            count: 1
+            path: src/Query/AST/Functions/SubstringFunction.php
+
+        -
+            message: "#^Parameter \\#3 \\$length of method Doctrine\\\\DBAL\\\\Platforms\\\\AbstractPlatform\\:\\:getSubstringExpression\\(\\) expects int\\|null, string\\|null given\\.$#"
+            count: 1
+            path: src/Query/AST/Functions/SubstringFunction.php
+
+        -
+            message: '#^Class Doctrine\\DBAL\\Platforms\\MySQLPlatform not found\.$#'
+            count: 2
+            path: src/Mapping/ClassMetadataFactory.php
+
+        - '~^Call to deprecated method getSQLResultCasing\(\) of class Doctrine\\DBAL\\Platforms\\AbstractPlatform\.$~'
+        -
+            message: '~deprecated class Doctrine\\DBAL\\Tools\\Console\\Command\\ImportCommand\:~'
+            path: src/Tools/Console/ConsoleRunner.php
+
+        -
+            message: '#^Method Doctrine\\ORM\\AbstractQuery\:\:getHydrationCacheId\(\) should return array\{string, string\} but returns array\<string\>\.$#'
+            path: src/AbstractQuery.php
+
+        -
+            message: '#^Method Doctrine\\ORM\\Internal\\Hydration\\AbstractHydrator\:\:\w+\(\) has parameter \$stmt with no value type specified in iterable type Doctrine\\DBAL\\Driver\\ResultStatement\.$#'
+            path: src/Internal/Hydration/AbstractHydrator.php
+
+        -
+            message: '#^Parameter \#1 \$key of method Psr\\Cache\\CacheItemPoolInterface\:\:deleteItem\(\) expects string, string\|false given\.$#'
+            path: src/Query
+
+
+        # Symfony cache supports passing a key prefix to the clear method.
+        - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
+
+        # Persistence 2 support
+        -
+            message: '/clear.*invoked with 1 parameter/'
+            path: src/EntityRepository.php
+        -
+            message: '#^Class Doctrine\\Persistence\\ObjectManagerAware not found\.$#'
+            path: src/UnitOfWork.php
+        -
+            message: '#^Call to method injectObjectManager\(\) on an unknown class Doctrine\\Persistence\\ObjectManagerAware\.$#'
+            path: src/UnitOfWork.php
+
+        -
+            message: '#contains generic type.*but class.*is not generic#'
+            paths:
+                - src/Mapping/Driver/XmlDriver.php
+                - src/Mapping/Driver/YamlDriver.php

phpstan-dbal3.neon

@@ -1,162 +0,0 @@
-includes:
-    - phpstan-baseline.neon
-    - phpstan-params.neon
-
-parameters:
-    reportUnmatchedIgnoredErrors: false # Some errors in the baseline only apply to DBAL 4
-    ignoreErrors:
-        # Symfony cache supports passing a key prefix to the clear method.
-        - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
-
-        # We can be certain that those values are not matched.
-        -
-            message: '~^Match expression does not handle remaining values:~'
-            path: src/Utility/PersisterHelper.php
-
-        # DBAL 4 compatibility
-        -
-            message: '~^Method Doctrine\\ORM\\Query\\AST\\Functions\\TrimFunction::getTrimMode\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Query/AST/Functions/TrimFunction.php
-
-        -
-            message: '~.*getTrimExpression.*expects int.*~'
-            path: src/Query/AST/Functions/TrimFunction.php
-
-        -
-            message: '~^Call to static method unquoted\(\) on an unknown class Doctrine\\DBAL\\Schema\\Name\\Identifier\.$~'
-            path: src/Tools/SchemaTool.php
-
-        -
-            message: '~^Instantiated class Doctrine\\DBAL\\Schema\\Name\\UnqualifiedName not found\.$~'
-            path: src/Tools/SchemaTool.php
-
-        -
-            message: '~^Call to an undefined method Doctrine\\DBAL\\Schema\\Table::addPrimaryKeyConstraint\(\)\.$~'
-            path: src/Tools/SchemaTool.php
-
-        -
-            message: '~^Call to static method quoted\(\) on an unknown class Doctrine\\DBAL\\Schema\\Name\\Identifier\.$~'
-            path: src/Tools/SchemaTool.php
-
-        -
-            message: '~^Call to an undefined method Doctrine\\DBAL\\Schema\\Table\:\:getObjectName\(\)\.$~'
-            path: src/Mapping/Driver/DatabaseDriver.php
-
-        -
-            message: '~^Call to an undefined method Doctrine\\DBAL\\Schema\\ForeignKeyConstraint::get.*\.$~'
-            identifier: method.notFound
-
-        -
-            message: '~createComparator~'
-            identifier: arguments.count
-
-        -
-            message: '~UnqualifiedName~'
-            identifier: class.notFound
-
-        -
-            message: '~IndexedColumn~'
-            identifier: class.notFound
-
-        -
-            message: '~PrimaryKeyConstraint~'
-            identifier: class.notFound
-
-        -
-            message: '~IndexType~'
-            identifier: class.notFound
-
-        -
-            message: '~dropForeignKey~'
-            identifier: method.notFound
-
-        -
-            message: '~getIndexedColumns~'
-            identifier: method.notFound
-
-        -
-            message: '~getPrimaryKeyConstraint~'
-            identifier: method.notFound
-
-        -
-            message: '~PrimaryKeyConstraint~'
-            identifier: class.notFound
-            path: src/Tools/SchemaTool.php
-
-        -
-            message: '~^Call to method toString.*UnqualifiedName\.$~'
-            path: src/Tools/SchemaTool.php
-
-        - '~^Call to method getObjectName\(\) on an unknown class Doctrine\\DBAL\\Schema\\NamedObject\.$~'
-
-        - '~^Class Doctrine\\DBAL\\Platforms\\SQLitePlatform not found\.$~'
-
-        - '~^Class Doctrine\\DBAL\\Schema\\NamedObject not found\.$~'
-
-        -
-            message: '~sort~'
-            identifier: argument.unresolvableType
-            path: src/Mapping/Driver/DatabaseDriver.php
-
-        -
-            message: '#^Parameter \#1 \$asset of static method Doctrine\\ORM\\Mapping\\Driver\\DatabaseDriver\:\:getAssetName\(\) expects Doctrine\\DBAL\\Schema\\AbstractAsset, Doctrine\\DBAL\\Schema\\Column\|false given\.$#'
-            identifier: argument.type
-            path: src/Mapping/Driver/DatabaseDriver.php
-
-        -
-            message: '#^Instantiated class Doctrine\\DBAL\\Schema\\DefaultExpression\\\w+ not found\.$#'
-            identifier: class.notFound
-            path: src/Tools/SchemaTool.php
-
-
-        # To be removed in 4.0
-        -
-            message: '#Negated boolean expression is always false\.#'
-            paths:
-                - src/Mapping/Driver/AttributeDriver.php
-
-        -
-            message: '~^Call to deprecated method getEventManager\(\) of class Doctrine\\DBAL\\Connection\.$~'
-            path: src/EntityManager.php
-        -
-            message: '~deprecated class Doctrine\\DBAL\\Tools\\Console\\Command\\ReservedWordsCommand\:~'
-            path: src/Tools/Console/ConsoleRunner.php
-
-        # Compatibility with Persistence 3
-        -
-            message: '#Expression on left side of \?\? is not nullable.#'
-            path: src/Mapping/Driver/AttributeDriver.php
-
-        -
-            message: '~^Method Doctrine\\ORM\\Utility\\PersisterHelper\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Utility/PersisterHelper.php
-
-        -
-            message: '~inferParameterTypes.*should return~'
-            path: src/Utility/PersisterHelper.php
-
-        -
-            message: '~.*appendLockHint.*expects.*LockMode given~'
-            paths:
-                - src/Persisters/Entity/BasicEntityPersister.php
-                - src/Persisters/Entity/JoinedSubclassPersister.php
-
-        -
-            message: '~.*executeStatement.*expects~'
-            path: src/Query/Exec/MultiTableUpdateExecutor.php
-
-        -
-            message: '~method_exists.*getEventManager~'
-            path: src/EntityManager.php
-
-        -
-            message: '~method_exists.*getIdentitySequence~'
-            path: src/Mapping/ClassMetadataFactory.php
-
-        -
-            message: '~expand(Criteria)?Parameters.*should return array~'
-            path: src/Persisters/Entity/BasicEntityPersister.php
-
-        -
-            message: '~inferType.*never returns~'
-            path: src/Query/ParameterTypeInferer.php

phpstan-persistence2.neon

@@ -0,0 +1,122 @@
+includes:
+    - phpstan-baseline.neon
+    - phpstan-params.neon
+
+parameters:
+    reportUnmatchedIgnoredErrors: false
+
+    ignoreErrors:
+        # deprecations from doctrine/dbal:3.x
+        - '/^Call to an undefined method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getGuidExpression\(\).$/'
+
+        # Fallback logic for DBAL 2
+        -
+            message: '/Parameter #2 \$command of static method Doctrine\\ORM\\Tools\\Console\\ConsoleRunner\:\:addCommandToApplication\(\) expects Symfony\\Component\\Console\\Command\\Command/'
+            path: src/Tools/Console/ConsoleRunner.php
+
+        - '/^Class Doctrine\\DBAL\\Platforms\\SQLAnywherePlatform not found\.$/'
+        - '/^Call to method \w+\(\) on an unknown class Doctrine\\DBAL\\Platforms\\SQLAnywherePlatform\.$/'
+
+        -
+            message: '/^Call to an undefined method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getSQLResultCasing\(\)\.$/'
+            path: src/Internal/SQLResultCasing.php
+        -
+            message: '/^Parameter \$stmt of method .* has invalid type Doctrine\\DBAL\\Driver\\ResultStatement\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Class Doctrine\\DBAL\\Driver\\ResultStatement not found\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Call to static method ensure\(\) on an unknown class Doctrine\\DBAL\\ForwardCompatibility\\Result\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Instanceof between Doctrine\\DBAL\\Platforms\\AbstractPlatform and Doctrine\\DBAL\\Platforms\\MySQLPlatform will always evaluate to false\.$/'
+            path: src/Utility/LockSqlHelper.php
+
+        # Compatibility with Collections 1
+        -
+            message: '#^Method Doctrine\\ORM\\EntityRepository\:\:matching\(\) should return Doctrine\\Common\\Collections\\AbstractLazyCollection\<int, T of object\>&Doctrine\\Common\\Collections\\Selectable\<int, T of object\> but returns Doctrine\\ORM\\LazyCriteriaCollection\<\(int\|string\), object\>\.$#'
+
+        # Forward compatibility with Collections 3
+        -
+            message: '#^Parameter \$order of anonymous function has invalid type Doctrine\\Common\\Collections\\Order\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        -
+            message: '#^Anonymous function has invalid return type Doctrine\\Common\\Collections\\Order\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        -
+            message: '#^Access to property \$value on an unknown class Doctrine\\Common\\Collections\\Order\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        -
+            message: '#^Call to static method from\(\) on an unknown class Doctrine\\Common\\Collections\\Order\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        -
+            message: '#^Call to an undefined method Doctrine\\Common\\Collections\\Criteria\:\:orderings\(\)\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        -
+            message: '#^Method .+\:\:mapToOrderEnumIfAvailable\(\) has invalid return type Doctrine\\Common\\Collections\\Order\.$#'
+            path: src/Internal/CriteriaOrderings.php
+
+        # False positive
+        -
+            message: '/^Call to an undefined method Doctrine\\Common\\Cache\\Cache::deleteAll\(\)\.$/'
+            count: 1
+            path: src/Tools/Console/Command/ClearCache/ResultCommand.php
+
+        # Symfony cache supports passing a key prefix to the clear method.
+        - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
+
+        -
+            message: '#contains generic type.*but class.*is not generic#'
+            paths:
+                - src/Mapping/Driver/XmlDriver.php
+                - src/Mapping/Driver/YamlDriver.php
+
+        # Extending a deprecated class conditionally to maintain BC
+        -
+            message: '~deprecated class Doctrine\\Persistence\\Mapping\\Driver\\AnnotationDriver\:~'
+            path: src/Mapping/Driver/CompatibilityAnnotationDriver.php
+
+        # We're sniffing for this deprecated class in order to detect Persistence 2
+        -
+            message: '~deprecated class Doctrine\\Common\\Persistence\\PersistentObject\:~'
+            path: src/EntityManager.php
+
+        -
+            message: '#Cannot access offset \S+ on .*ClassMetadata.*#'
+            paths:
+                - src/Mapping/Driver/XmlDriver.php
+                - src/Mapping/Driver/YamlDriver.php
+
+        -
+            message: '#^Parameter \#1 \$orderings of method Doctrine\\Common\\Collections\\Criteria\:\:orderBy\(\) expects array\<string\>, array\<string, Doctrine\\Common\\Collections\\Order\|string\> given\.$#'
+            path: src/PersistentCollection.php
+
+        -
+            message: '#^Parameter \#5 \.\.\.\$args of static method Doctrine\\Deprecations\\Deprecation\:\:trigger\(\) expects float\|int\|string, string\|false given\.$#'
+            path: src/Mapping/ClassMetadataFactory.php
+
+        -
+            message: '#^Parameter \#1 \$classNames of method Doctrine\\ORM\\Mapping\\ClassMetadataInfo\<object\>\:\:setParentClasses\(\) expects list\<class\-string\>, array\<string\> given\.$#'
+            path: src/Mapping/ClassMetadataFactory.php
+
+        -
+            message: '#loadMappingFile#'
+            identifier: 'return.type'
+            path: src/Mapping/Driver/XmlDriver.php
+
+        -
+            message: '#injectObjectManager#'
+            identifier: 'method.deprecatedInterface'
+            path: src/UnitOfWork.php
+
+        -
+            message: '#^Static method Doctrine\\Common\\Collections\\Criteria\:\:create\(\) invoked with 1 parameter, 0 required\.$#'
+            identifier: arguments.count
+            count: 3
+            path: src/Persisters/Collection/OneToManyPersister.php

phpstan.neon

@@ -4,53 +4,49 @@ includes:
 
 parameters:
     ignoreErrors:
+        # deprecations from doctrine/dbal:3.x
+        - '/^Call to an undefined method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getGuidExpression\(\).$/'
+
+        # Fallback logic for DBAL 2
+        -
+            message: '/Parameter #2 \$command of static method Doctrine\\ORM\\Tools\\Console\\ConsoleRunner\:\:addCommandToApplication\(\) expects Symfony\\Component\\Console\\Command\\Command/'
+            path: src/Tools/Console/ConsoleRunner.php
+
+        - '/^Class Doctrine\\DBAL\\Platforms\\SQLAnywherePlatform not found\.$/'
+        - '/^Call to method \w+\(\) on an unknown class Doctrine\\DBAL\\Platforms\\SQLAnywherePlatform\.$/'
+
+        -
+            message: '/^Call to an undefined method Doctrine\\DBAL\\Platforms\\AbstractPlatform::getSQLResultCasing\(\)\.$/'
+            path: src/Internal/SQLResultCasing.php
+        -
+            message: '/^Parameter \$stmt of method .* has invalid type Doctrine\\DBAL\\Driver\\ResultStatement\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Class Doctrine\\DBAL\\Driver\\ResultStatement not found\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Call to static method ensure\(\) on an unknown class Doctrine\\DBAL\\ForwardCompatibility\\Result\.$/'
+            path: src/Internal/Hydration/AbstractHydrator.php
+        -
+            message: '/^Instanceof between Doctrine\\DBAL\\Platforms\\AbstractPlatform and Doctrine\\DBAL\\Platforms\\MySQLPlatform will always evaluate to false\.$/'
+            path: src/Utility/LockSqlHelper.php
+
+        # False positive
+        -
+            message: '/^Call to an undefined method Doctrine\\Common\\Cache\\Cache::deleteAll\(\)\.$/'
+            count: 1
+            path: src/Tools/Console/Command/ClearCache/ResultCommand.php
+
         # Symfony cache supports passing a key prefix to the clear method.
         - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
 
-        # We can be certain that those values are not matched.
+        # Persistence 2 support
         -
-            message: '~^Match expression does not handle remaining values:~'
-            path: src/Utility/PersisterHelper.php
-
-        # The return type is already narrow enough.
-        - '~^Method Doctrine\\ORM\\Query\\ParameterTypeInferer\:\:inferType\(\) never returns ''[a-z_]+'' so it can be removed from the return type\.$~'
-        - '~^Method Doctrine\\ORM\\Query\\ParameterTypeInferer\:\:inferType\(\) never returns Doctrine\\DBAL\\(?:Array)?ParameterType\:\:[A-Z_]+ so it can be removed from the return type\.$~'
-
-        # DBAL 4 compatibility
+            message: '/clear.*invoked with 1 parameter/'
+            path: src/EntityRepository.php
         -
-            message: '~^Method Doctrine\\ORM\\Query\\AST\\Functions\\TrimFunction::getTrimMode\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Query/AST/Functions/TrimFunction.php
-        -
-            message: '~^Method Doctrine\\ORM\\Utility\\PersisterHelper\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Utility/PersisterHelper.php
-
-        # Compatibility with DBAL 3
-        # See https://github.com/doctrine/dbal/pull/3480
-        -
-            message: '~^Result of method Doctrine\\DBAL\\Connection::commit\(\) \(void\) is used\.$~'
+            message: '#^Class Doctrine\\Persistence\\ObjectManagerAware not found\.$#'
             path: src/UnitOfWork.php
         -
-            message: '~^Strict comparison using === between null and false will always evaluate to false\.$~'
+            message: '#^Call to method injectObjectManager\(\) on an unknown class Doctrine\\Persistence\\ObjectManagerAware\.$#'
             path: src/UnitOfWork.php
-        -
-            message: '~^Variable \$e on left side of \?\? always exists and is not nullable\.$~'
-            path: src/UnitOfWork.php
-
-        -
-            message: '~^Parameter #2 \$command of static method Doctrine\\ORM\\Tools\\Console\\ConsoleRunner::addCommandToApplication\(\) expects Symfony\\Component\\Console\\Command\\Command, Doctrine\\DBAL\\Tools\\Console\\Command\\ReservedWordsCommand given\.$~'
-            path: src/Tools/Console/ConsoleRunner.php
-
-        -
-            message: '~Strict comparison using \=\=\= between callable\(\)\: mixed and null will always evaluate to false\.~'
-            path: src/Tools/SchemaTool.php
-
-        # To be removed in 4.0
-        -
-            message: '#Negated boolean expression is always false\.#'
-            paths:
-                - src/Mapping/Driver/AttributeDriver.php
-
-        # Compatibility with Persistence 3
-        -
-            message: '#Expression on left side of \?\? is not nullable.#'
-            path: src/Mapping/Driver/AttributeDriver.php

phpunit.xml.dist

@@ -14,15 +14,10 @@
 <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
-         beStrictAboutOutputDuringTests="true"
-         displayDetailsOnTestsThatTriggerDeprecations="true"
-         displayDetailsOnTestsThatTriggerNotices="true"
-         displayDetailsOnTestsThatTriggerWarnings="true"
-         failOnNotice="true"
-         failOnWarning="true"
+         verbose="false"
          failOnRisky="true"
+         convertDeprecationsToExceptions="true"
          bootstrap="./tests/Tests/TestInit.php"
-         cacheDirectory=".phpunit.cache"
 >
     <testsuites>
         <testsuite name="Doctrine ORM Test Suite">
@@ -36,45 +31,42 @@
             <group>locking_functional</group>
         </exclude>
     </groups>
-    <php>
-        <ini name="error_reporting" value="-1"/>
-        <!-- "Real" test database -->
-        <var name="db_driver" value="pdo_sqlite"/>
-        <var name="db_memory" value="true"/>
-        <!-- to use another database driver / credentials, provide them like so:
-          <var name="db_driver" value="pdo_mysql"/>
-          <var name="db_host" value="localhost" />
-          <var name="db_user" value="root" />
-          <var name="db_password" value="" />
-          <var name="db_dbname" value="doctrine_tests" />
-          <var name="db_port" value="3306"/>-->
-        <!--<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit">-->
-        <!--
-         At the start of each test run, we will drop and recreate the test database.
 
-         By default we assume that the `db_` config above has unrestricted access to the provided database
-         platform.
+  <php>
+    <ini name="error_reporting" value="-1" />
+    <!-- "Real" test database -->
+    <var name="db_driver" value="pdo_sqlite"/>
+    <var name="db_memory" value="true"/>
+      <!-- to use another database driver / credentials, provide them like so:
+      <var name="db_driver" value="pdo_mysql"/>
+      <var name="db_host" value="localhost" />
+      <var name="db_user" value="root" />
+      <var name="db_password" value="" />
+      <var name="db_dbname" value="doctrine_tests" />
+      <var name="db_port" value="3306"/>-->
+    <!--<var name="db_event_subscribers" value="Doctrine\DBAL\Event\Listeners\OracleSessionInit">-->
 
-         If you prefer, you can provide a restricted user above and a separate `privileged_db` config
-         block to provide details of a privileged connection to use for the setup / teardown actions.
+    <!--
+     At the start of each test run, we will drop and recreate the test database.
 
-         Note that these configurations are not merged - if you specify a `privileged_db_driver` then
-         you must also specify all the other options that your driver requires.
+     By default we assume that the `db_` config above has unrestricted access to the provided database
+     platform.
 
-        <var name="privileged_db_driver" value="pdo_mysql"/>
-        <var name="privileged_db_host" value="localhost" />
-        <var name="privileged_db_user" value="root" />
-        <var name="privileged_db_password" value="" />
-        <var name="privileged_db_dbname" value="doctrine_tests_tmp" />
-        <var name="privileged_db_port" value="3306"/>
-        -->
-        <env name="COLUMNS" value="120"/>
-        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
-    </php>
+     If you prefer, you can provide a restricted user above and a separate `privileged_db` config
+     block to provide details of a privileged connection to use for the setup / teardown actions.
+
+     Note that these configurations are not merged - if you specify a `privileged_db_driver` then
+     you must also specify all the other options that your driver requires.
+
+    <var name="privileged_db_driver" value="pdo_mysql"/>
+    <var name="privileged_db_host" value="localhost" />
+    <var name="privileged_db_user" value="root" />
+    <var name="privileged_db_password" value="" />
+    <var name="privileged_db_dbname" value="doctrine_tests_tmp" />
+    <var name="privileged_db_port" value="3306"/>
+    -->
+
+    <env name="COLUMNS" value="120"/>
+  </php>
 
-    <source ignoreSuppressionOfDeprecations="true">
-        <include>
-            <directory>src</directory>
-        </include>
-    </source>
 </phpunit>

src/Cache.php

@@ -38,69 +38,127 @@ interface Cache
      */
     public const MODE_REFRESH = 4;
 
-    public function getEntityCacheRegion(string $className): Region|null;
+    /**
+     * @param string $className The entity class.
+     *
+     * @return Region|null
+     */
+    public function getEntityCacheRegion($className);
 
-    public function getCollectionCacheRegion(string $className, string $association): Region|null;
+    /**
+     * @param string $className   The entity class.
+     * @param string $association The field name that represents the association.
+     *
+     * @return Region|null
+     */
+    public function getCollectionCacheRegion($className, $association);
 
     /**
      * Determine whether the cache contains data for the given entity "instance".
+     *
+     * @param string $className  The entity class.
+     * @param mixed  $identifier The entity identifier
+     *
+     * @return bool true if the underlying cache contains corresponding data; false otherwise.
      */
-    public function containsEntity(string $className, mixed $identifier): bool;
+    public function containsEntity($className, $identifier);
 
     /**
      * Evicts the entity data for a particular entity "instance".
+     *
+     * @param string $className  The entity class.
+     * @param mixed  $identifier The entity identifier.
+     *
+     * @return void
      */
-    public function evictEntity(string $className, mixed $identifier): void;
+    public function evictEntity($className, $identifier);
 
     /**
      * Evicts all entity data from the given region.
+     *
+     * @param string $className The entity metadata.
+     *
+     * @return void
      */
-    public function evictEntityRegion(string $className): void;
+    public function evictEntityRegion($className);
 
     /**
      * Evict data from all entity regions.
+     *
+     * @return void
      */
-    public function evictEntityRegions(): void;
+    public function evictEntityRegions();
 
     /**
      * Determine whether the cache contains data for the given collection.
+     *
+     * @param string $className       The entity class.
+     * @param string $association     The field name that represents the association.
+     * @param mixed  $ownerIdentifier The identifier of the owning entity.
+     *
+     * @return bool true if the underlying cache contains corresponding data; false otherwise.
      */
-    public function containsCollection(string $className, string $association, mixed $ownerIdentifier): bool;
+    public function containsCollection($className, $association, $ownerIdentifier);
 
     /**
      * Evicts the cache data for the given identified collection instance.
+     *
+     * @param string $className       The entity class.
+     * @param string $association     The field name that represents the association.
+     * @param mixed  $ownerIdentifier The identifier of the owning entity.
+     *
+     * @return void
      */
-    public function evictCollection(string $className, string $association, mixed $ownerIdentifier): void;
+    public function evictCollection($className, $association, $ownerIdentifier);
 
     /**
      * Evicts all entity data from the given region.
+     *
+     * @param string $className   The entity class.
+     * @param string $association The field name that represents the association.
+     *
+     * @return void
      */
-    public function evictCollectionRegion(string $className, string $association): void;
+    public function evictCollectionRegion($className, $association);
 
     /**
      * Evict data from all collection regions.
+     *
+     * @return void
      */
-    public function evictCollectionRegions(): void;
+    public function evictCollectionRegions();
 
     /**
      * Determine whether the cache contains data for the given query.
+     *
+     * @param string $regionName The cache name given to the query.
+     *
+     * @return bool true if the underlying cache contains corresponding data; false otherwise.
      */
-    public function containsQuery(string $regionName): bool;
+    public function containsQuery($regionName);
 
     /**
      * Evicts all cached query results under the given name, or default query cache if the region name is NULL.
+     *
+     * @param string|null $regionName The cache name associated to the queries being cached.
+     *
+     * @return void
      */
-    public function evictQueryRegion(string|null $regionName = null): void;
+    public function evictQueryRegion($regionName = null);
 
     /**
      * Evict data from all query regions.
+     *
+     * @return void
      */
-    public function evictQueryRegions(): void;
+    public function evictQueryRegions();
 
     /**
      * Get query cache by region name or create a new one if none exist.
      *
      * @param string|null $regionName Query cache region name, or default query cache if the region name is NULL.
+     *
+     * @return QueryCache The Query Cache associated with the region name.
      */
-    public function getQueryCache(string|null $regionName = null): QueryCache;
+    public function getQueryCache($regionName = null);
 }

src/Cache/AssociationCacheEntry.php

@@ -4,16 +4,35 @@ declare(strict_types=1);
 
 namespace Doctrine\ORM\Cache;
 
+/**
+ * Association cache entry
+ */
 class AssociationCacheEntry implements CacheEntry
 {
     /**
-     * @param array<string, mixed> $identifier The entity identifier.
-     * @param class-string         $class      The entity class name
+     * The entity identifier
+     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var array<string, mixed>
      */
-    public function __construct(
-        public readonly string $class,
-        public readonly array $identifier,
-    ) {
+    public $identifier;
+
+    /**
+     * The entity class name
+     *
+     * @readonly Public only for performance reasons, it should be considered immutable.
+     * @var class-string
+     */
+    public $class;
+
+    /**
+     * @param class-string         $class      The entity class.
+     * @param array<string, mixed> $identifier The entity identifier.
+     */
+    public function __construct($class, array $identifier)
+    {
+        $this->class      = $class;
+        $this->identifier = $identifier;
     }
 
     /**
@@ -22,8 +41,10 @@ class AssociationCacheEntry implements CacheEntry
      * This method allow Doctrine\Common\Cache\PhpFileCache compatibility
      *
      * @param array<string, mixed> $values array containing property values
+     *
+     * @return AssociationCacheEntry
      */
-    public static function __set_state(array $values): self
+    public static function __set_state(array $values)
     {
         return new self($values['class'], $values['identifier']);
     }

src/Cache/CacheConfiguration.php

@@ -11,49 +11,72 @@ use Doctrine\ORM\Cache\Logging\CacheLogger;
  */
 class CacheConfiguration
 {
-    private CacheFactory|null $cacheFactory          = null;
-    private RegionsConfiguration|null $regionsConfig = null;
-    private CacheLogger|null $cacheLogger            = null;
-    private QueryCacheValidator|null $queryValidator = null;
+    /** @var CacheFactory|null */
+    private $cacheFactory;
 
-    public function getCacheFactory(): CacheFactory|null
+    /** @var RegionsConfiguration|null */
+    private $regionsConfig;
+
+    /** @var CacheLogger|null */
+    private $cacheLogger;
+
+    /** @var QueryCacheValidator|null */
+    private $queryValidator;
+
+    /** @return CacheFactory|null */
+    public function getCacheFactory()
     {
         return $this->cacheFactory;
     }
 
-    public function setCacheFactory(CacheFactory $factory): void
+    /** @return void */
+    public function setCacheFactory(CacheFactory $factory)
     {
         $this->cacheFactory = $factory;
     }
 
-    public function getCacheLogger(): CacheLogger|null
+    /** @return CacheLogger|null */
+    public function getCacheLogger()
     {
          return $this->cacheLogger;
     }
 
-    public function setCacheLogger(CacheLogger $logger): void
+    /** @return void */
+    public function setCacheLogger(CacheLogger $logger)
     {
         $this->cacheLogger = $logger;
     }
 
-    public function getRegionsConfiguration(): RegionsConfiguration
+    /** @return RegionsConfiguration */
+    public function getRegionsConfiguration()
     {
-        return $this->regionsConfig ??= new RegionsConfiguration();
+        if ($this->regionsConfig === null) {
+            $this->regionsConfig = new RegionsConfiguration();
+        }
+
+        return $this->regionsConfig;
     }
 
-    public function setRegionsConfiguration(RegionsConfiguration $regionsConfig): void
+    /** @return void */
+    public function setRegionsConfiguration(RegionsConfiguration $regionsConfig)
     {
         $this->regionsConfig = $regionsConfig;
     }
 
-    public function getQueryValidator(): QueryCacheValidator
+    /** @return QueryCacheValidator */
+    public function getQueryValidator()
     {
-        return $this->queryValidator ??= new TimestampQueryCacheValidator(
-            $this->cacheFactory->getTimestampRegion(),
-        );
+        if ($this->queryValidator === null) {
+            $this->queryValidator = new TimestampQueryCacheValidator(
+                $this->cacheFactory->getTimestampRegion()
+            );
+        }
+
+         return $this->queryValidator;
     }
 
-    public function setQueryValidator(QueryCacheValidator $validator): void
+    /** @return void */
+    public function setQueryValidator(QueryCacheValidator $validator)
     {
         $this->queryValidator = $validator;
     }

src/Cache/CacheException.php

@@ -5,22 +5,57 @@ declare(strict_types=1);
 namespace Doctrine\ORM\Cache;
 
 use Doctrine\ORM\Exception\ORMException;
-use LogicException;
 
 use function sprintf;
 
 /**
  * Exception for cache.
  */
-class CacheException extends LogicException implements ORMException
+class CacheException extends ORMException
 {
-    public static function updateReadOnlyCollection(string $sourceEntity, string $fieldName): self
+    /**
+     * @param string $sourceEntity
+     * @param string $fieldName
+     *
+     * @return CacheException
+     */
+    public static function updateReadOnlyCollection($sourceEntity, $fieldName)
     {
         return new self(sprintf('Cannot update a readonly collection "%s#%s"', $sourceEntity, $fieldName));
     }
 
-    public static function nonCacheableEntity(string $entityName): self
+    /**
+     * @deprecated This method is not used anymore.
+     *
+     * @param string $entityName
+     *
+     * @return CacheException
+     */
+    public static function updateReadOnlyEntity($entityName)
+    {
+        return new self(sprintf('Cannot update a readonly entity "%s"', $entityName));
+    }
+
+    /**
+     * @param string $entityName
+     *
+     * @return CacheException
+     */
+    public static function nonCacheableEntity($entityName)
     {
         return new self(sprintf('Entity "%s" not configured as part of the second-level cache.', $entityName));
     }
+
+    /**
+     * @deprecated This method is not used anymore.
+     *
+     * @param string $entityName
+     * @param string $field
+     *
+     * @return CacheException
+     */
+    public static function nonCacheableEntityAssociation($entityName, $field)
+    {
+        return new self(sprintf('Entity association field "%s#%s" not configured as part of the second-level cache.', $entityName, $field));
+    }
 }