Merge pull request #12364 from seb-jean/cursor-pagination

Add cursor-based pagination

.doctrine-project.json

@@ -12,112 +12,58 @@
             "upcoming": true
         },
         {
-            "name": "3.1",
-            "branchName": "3.1.x",
-            "slug": "3.1",
+            "name": "3.7",
+            "branchName": "3.7.x",
+            "slug": "3.7",
             "upcoming": true
         },
         {
-            "name": "3.0",
-            "branchName": "3.0.x",
-            "slug": "3.0",
+            "name": "3.6",
+            "branchName": "3.6.x",
+            "slug": "3.6",
             "current": true
         },
         {
-            "name": "2.19",
-            "branchName": "2.19.x",
-            "slug": "2.19",
+            "name": "2.21",
+            "branchName": "2.21.x",
+            "slug": "2.21",
             "upcoming": true
         },
         {
-            "name": "2.18",
-            "branchName": "2.18.x",
-            "slug": "2.18",
+            "name": "2.20",
+            "branchName": "2.20.x",
+            "slug": "2.20",
             "maintained": true
         },
+        {
+            "name": "2.19",
+            "slug": "2.19",
+            "maintained": false
+        },
+        {
+            "name": "2.18",
+            "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
         }
     ]
 }

.gitattributes

@@ -11,13 +11,10 @@ build.properties.dev export-ignore
 build.xml export-ignore
 CONTRIBUTING.md export-ignore
 phpunit.xml.dist export-ignore
-run-all.sh export-ignore
 phpcs.xml.dist export-ignore
 phpbench.json export-ignore
 phpstan.neon export-ignore
 phpstan-baseline.neon export-ignore
-phpstan-dbal2.neon export-ignore
+phpstan-dbal3.neon export-ignore
 phpstan-params.neon export-ignore
 phpstan-persistence2.neon export-ignore
-psalm.xml export-ignore
-psalm-baseline.xml export-ignore

.github/ISSUE_TEMPLATE/BC_Break.md

@@ -1,37 +0,0 @@
----
-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

@@ -1,34 +0,0 @@
----
-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

@@ -1,18 +0,0 @@
----
-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

@@ -1,6 +0,0 @@
----
-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

@@ -0,0 +1,9 @@
+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@3.0.0"
+    uses: "doctrine/.github/.github/workflows/coding-standards.yml@13.1.0"

.github/workflows/composer-lint.yml

@@ -0,0 +1,20 @@
+name: "Composer Lint"
+
+on:
+  pull_request:
+    branches:
+      - "*.x"
+    paths:
+      - ".github/workflows/composer-lint.yml"
+      - "composer.json"
+  push:
+    branches:
+      - "*.x"
+    paths:
+      - ".github/workflows/composer-lint.yml"
+      - "composer.json"
+
+jobs:
+  composer-lint:
+    name: "Composer Lint"
+    uses: "doctrine/.github/.github/workflows/composer-lint.yml@13.1.0"

.github/workflows/continuous-integration.yml

@@ -1,4 +1,4 @@
-name: "Continuous Integration"
+name: "CI: PHPUnit"
 
 on:
   pull_request:
@@ -9,7 +9,6 @@ on:
       - ci/**
       - composer.*
       - src/**
-      - phpunit.xml.dist
       - tests/**
   push:
     branches:
@@ -19,7 +18,6 @@ on:
       - ci/**
       - composer.*
       - src/**
-      - phpunit.xml.dist
       - tests/**
 
 env:
@@ -27,7 +25,14 @@ env:
 
 jobs:
   phpunit-smoke-check:
-    name: "PHPUnit with SQLite"
+    name: >
+      SQLite -
+      ${{ format('PHP {0} - DBAL {1} - ext. {2} - proxy {3}',
+        matrix.php-version || 'Ø',
+        matrix.dbal-version || 'Ø',
+        matrix.extension || 'Ø',
+        matrix.proxy || 'Ø'
+      ) }}
     runs-on: "ubuntu-22.04"
 
     strategy:
@@ -36,6 +41,8 @@ jobs:
           - "8.1"
           - "8.2"
           - "8.3"
+          - "8.4"
+          - "8.5"
         dbal-version:
           - "default"
           - "3.7"
@@ -44,21 +51,43 @@ jobs:
           - "pdo_sqlite"
         deps:
           - "highest"
+        stability:
+          - "stable"
+        native_lazy:
+          - "0"
         include:
           - php-version: "8.2"
             dbal-version: "4@dev"
             extension: "pdo_sqlite"
+            stability: "stable"
+            native_lazy: "0"
           - php-version: "8.2"
             dbal-version: "4@dev"
             extension: "sqlite3"
+            stability: "stable"
+            native_lazy: "0"
           - php-version: "8.1"
             dbal-version: "default"
             deps: "lowest"
             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"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
@@ -70,12 +99,24 @@ 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@v2"
+        uses: "ramsey/composer-install@v3"
         with:
           composer-options: "--ignore-platform-req=php+"
           dependency-versions: "${{ matrix.deps }}"
@@ -84,21 +125,79 @@ jobs:
         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 }}
 
-      - 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"
+      - 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' }}"
         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 }}
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v3"
+        uses: "actions/upload-artifact@v7"
         with:
-          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
+          name: "phpunit-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.deps }}-${{ matrix.stability }}-${{ matrix.native_lazy }}-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: "PHPUnit with PostgreSQL"
+    name: >
+      ${{ format('PostgreSQL {0} - PHP {1} - DBAL {2} - ext. {3}',
+        matrix.postgres-version || 'Ø',
+        matrix.php-version || 'Ø',
+        matrix.dbal-version || 'Ø',
+        matrix.extension || 'Ø'
+      ) }}
     runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
@@ -107,11 +206,13 @@ jobs:
         php-version:
           - "8.2"
           - "8.3"
+          - "8.4"
+          - "8.5"
         dbal-version:
           - "default"
           - "3.7"
         postgres-version:
-          - "15"
+          - "17"
         extension:
           - pdo_pgsql
           - pgsql
@@ -139,7 +240,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
@@ -156,7 +257,7 @@ jobs:
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v2"
+        uses: "ramsey/composer-install@v3"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -164,14 +265,20 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/pdo_pgsql.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v3"
+        uses: "actions/upload-artifact@v7"
         with:
-          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
+          name: "${{ github.job }}-${{ matrix.postgres-version }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-${{ matrix.extension }}-coverage"
           path: "coverage.xml"
 
 
   phpunit-mariadb:
-    name: "PHPUnit with MariaDB"
+    name: >
+      ${{ format('MariaDB {0} - PHP {1} - DBAL {2} - ext. {3}',
+        matrix.mariadb-version || 'Ø',
+        matrix.php-version || 'Ø',
+        matrix.dbal-version || 'Ø',
+        matrix.extension || 'Ø'
+      ) }}
     runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
@@ -180,12 +287,14 @@ jobs:
         php-version:
           - "8.2"
           - "8.3"
+          - "8.4"
+          - "8.5"
         dbal-version:
           - "default"
           - "3.7"
           - "4@dev"
         mariadb-version:
-          - "10.9"
+          - "11.4"
         extension:
           - "mysqli"
           - "pdo_mysql"
@@ -194,18 +303,18 @@ jobs:
       mariadb:
         image: "mariadb:${{ matrix.mariadb-version }}"
         env:
-          MYSQL_ALLOW_EMPTY_PASSWORD: yes
-          MYSQL_DATABASE: "doctrine_tests"
+          MARIADB_ALLOW_EMPTY_ROOT_PASSWORD: yes
+          MARIADB_DATABASE: "doctrine_tests"
 
         options: >-
-          --health-cmd "mysqladmin ping --silent"
+          --health-cmd "healthcheck.sh --connect --innodb_initialized"
 
         ports:
           - "3306:3306"
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
@@ -222,7 +331,7 @@ jobs:
           extensions: "${{ matrix.extension }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v2"
+        uses: "ramsey/composer-install@v3"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -230,14 +339,20 @@ jobs:
         run: "vendor/bin/phpunit -c ci/github/phpunit/${{ matrix.extension }}.xml --coverage-clover=coverage.xml"
 
       - name: "Upload coverage file"
-        uses: "actions/upload-artifact@v3"
+        uses: "actions/upload-artifact@v7"
         with:
           name: "${{ github.job }}-${{ matrix.mariadb-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage.xml"
 
 
   phpunit-mysql:
-    name: "PHPUnit with MySQL"
+    name: >
+      ${{ format('MySQL {0} - PHP {1} - DBAL {2} - ext. {3}',
+        matrix.mysql-version || 'Ø',
+        matrix.php-version || 'Ø',
+        matrix.dbal-version || 'Ø',
+        matrix.extension || 'Ø'
+      ) }}
     runs-on: "ubuntu-22.04"
     needs: "phpunit-smoke-check"
 
@@ -246,6 +361,8 @@ jobs:
         php-version:
           - "8.2"
           - "8.3"
+          - "8.4"
+          - "8.5"
         dbal-version:
           - "default"
           - "3.7"
@@ -279,7 +396,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
@@ -296,7 +413,7 @@ jobs:
         if: "${{ matrix.dbal-version != 'default' }}"
 
       - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v2"
+        uses: "ramsey/composer-install@v3"
         with:
           composer-options: "--ignore-platform-req=php+"
 
@@ -305,13 +422,27 @@ jobs:
         env:
             ENABLE_SECOND_LEVEL_CACHE: 0
 
-      - 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"
+      - 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' }}"
         env:
             ENABLE_SECOND_LEVEL_CACHE: 1
 
       - name: "Upload coverage files"
-        uses: "actions/upload-artifact@v3"
+        uses: "actions/upload-artifact@v7"
         with:
           name: "${{ github.job }}-${{ matrix.mysql-version }}-${{ matrix.extension }}-${{ matrix.php-version }}-${{ matrix.dbal-version }}-coverage"
           path: "coverage*.xml"
@@ -319,6 +450,8 @@ jobs:
   upload_coverage:
     name: "Upload coverage to Codecov"
     runs-on: "ubuntu-22.04"
+    # Only run on PRs from forks
+    if: "github.event.pull_request.head.repo.full_name != github.repository"
     needs:
       - "phpunit-smoke-check"
       - "phpunit-postgres"
@@ -327,16 +460,18 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
       - name: "Download coverage files"
-        uses: "actions/download-artifact@v3"
+        uses: "actions/download-artifact@v8"
         with:
           path: "reports"
 
       - name: "Upload to Codecov"
-        uses: "codecov/codecov-action@v3"
+        uses: "codecov/codecov-action@v5"
         with:
           directory: reports
+        env:
+          CODECOV_TOKEN: "${{ secrets.CODECOV_TOKEN }}"

.github/workflows/documentation.yml

@@ -5,40 +5,16 @@ on:
     branches:
       - "*.x"
     paths:
-      - .github/workflows/documentation.yml
-      - docs/**
+      - ".github/workflows/documentation.yml"
+      - "docs/**"
   push:
     branches:
       - "*.x"
     paths:
-      - .github/workflows/documentation.yml
-      - docs/**
+      - ".github/workflows/documentation.yml"
+      - "docs/**"
 
 jobs:
-  validate-with-guides:
-    name: "Validate documentation with phpDocumentor/guides"
-    runs-on: "ubuntu-22.04"
-
-    steps:
-      - name: "Checkout code"
-        uses: "actions/checkout@v4"
-
-      - name: "Install PHP"
-        uses: "shivammathur/setup-php@v2"
-        with:
-          coverage: "none"
-          php-version: "8.2"
-
-      - name: "Remove existing composer file"
-        run: "rm composer.json"
-
-      - name: "Require phpdocumentor/guides-cli"
-        run: "composer require --dev phpdocumentor/guides-cli --no-update"
-
-      - name: "Install dependencies with Composer"
-        uses: "ramsey/composer-install@v2"
-        with:
-          dependency-versions: "highest"
-
-      - name: "Run guides-cli"
-        run: "vendor/bin/guides -vvv --no-progress docs/en 2>&1 | grep -v 'No template found for rendering directive' | ( ! grep WARNING )"
+  documentation:
+    name: "Documentation"
+    uses: "doctrine/.github/.github/workflows/documentation.yml@13.1.0"

.github/workflows/phpbench.yml

@@ -36,7 +36,7 @@ jobs:
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
         with:
           fetch-depth: 2
 
@@ -47,15 +47,8 @@ jobs:
           coverage: "pcov"
           ini-values: "zend.assertions=1, apc.enable_cli=1"
 
-      - name: "Cache dependencies installed with composer"
-        uses: "actions/cache@v3"
-        with:
-          path: "~/.composer/cache"
-          key: "php-${{ matrix.php-version }}-composer-locked-${{ hashFiles('composer.lock') }}"
-          restore-keys: "php-${{ matrix.php-version }}-composer-locked-"
-
-      - name: "Install dependencies with composer"
-        run: "composer update --no-interaction --no-progress"
+      - name: "Install dependencies with Composer"
+        uses: "ramsey/composer-install@v3"
 
       - name: "Run PHPBench"
         run: "vendor/bin/phpbench run --report=default"

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

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

.github/workflows/stale.yml

@@ -0,0 +1,24 @@
+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

@@ -9,7 +9,6 @@ on:
       - composer.*
       - src/**
       - phpstan*
-      - psalm*
       - tests/StaticAnalysis/**
   push:
     branches:
@@ -19,7 +18,6 @@ on:
       - composer.*
       - src/**
       - phpstan*
-      - psalm*
       - tests/StaticAnalysis/**
 
 jobs:
@@ -37,13 +35,13 @@ jobs:
 
     steps:
       - name: "Checkout code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v6"
 
       - name: Install PHP
         uses: shivammathur/setup-php@v2
         with:
           coverage: none
-          php-version: "8.2"
+          php-version: "8.4"
           tools: cs2pr
 
       - name: Require specific DBAL version
@@ -56,34 +54,3 @@ jobs:
 
       - name: Run static analysis with phpstan/phpstan
         run: "vendor/bin/phpstan analyse -c ${{ matrix.config }} --error-format=checkstyle | cs2pr"
-
-  static-analysis-psalm:
-    name: Static Analysis with Psalm
-    runs-on: ubuntu-22.04
-
-    strategy:
-      matrix:
-        dbal-version:
-        - default
-        - 3.8.2
-
-    steps:
-      - name: "Checkout code"
-        uses: "actions/checkout@v4"
-
-      - name: Install PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          coverage: none
-          php-version: "8.2"
-          tools: cs2pr
-
-      - name: Require specific DBAL version
-        run: "composer require doctrine/dbal ^${{ matrix.dbal-version }} --no-update"
-        if: "${{ matrix.dbal-version != 'default' }}"
-
-      - name: Install dependencies with Composer
-        uses: ramsey/composer-install@v2
-
-      - name: Run static analysis with Vimeo Psalm
-        run: vendor/bin/psalm --shepherd

.github/workflows/website-schema.yml

@@ -0,0 +1,21 @@
+
+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"

README.md

@@ -1,9 +1,7 @@
-|                      [4.0.x][4.0]                      |                      [3.1.x][3.1]                      |                      [3.0.x][3.0]                       |                      [2.19.x][2.19]                      |                      [2.18.x][2.18]                       |
-|:------------------------------------------------------:|:------------------------------------------------------:|:-------------------------------------------------------:|:--------------------------------------------------------:|:---------------------------------------------------------:|
-|           [![Build status][4.0 image]][4.0]            |           [![Build status][3.1 image]][3.1]            |            [![Build status][3.0 image]][3.0]            |           [![Build status][2.19 image]][2.19]            |            [![Build status][2.18 image]][2.18]            |
-| [![Coverage Status][4.0 coverage image]][4.0 coverage] | [![Coverage Status][3.1 coverage image]][3.1 coverage] | [![Coverage Status][3.0 coverage image]][3.0 coverage]  | [![Coverage Status][2.19 coverage image]][2.19 coverage] | [![Coverage Status][2.18 coverage image]][2.18 coverage]  |
-
-[<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
+|                      [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]                      |
+|:------------------------------------------------------:|:------------------------------------------------------:|:------------------------------------------------------:|:--------------------------------------------------------:|:--------------------------------------------------------:|
+|       [![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] |
 
 Doctrine ORM is an object-relational mapper for PHP 8.1+ that provides transparent persistence
 for PHP objects. It sits on top of a powerful database abstraction layer (DBAL). One of its key features
@@ -20,21 +18,26 @@ without requiring unnecessary code duplication.
 
   [4.0 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=4.0.x
   [4.0]: https://github.com/doctrine/orm/tree/4.0.x
+  [4.0 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.1 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.1.x
-  [3.1]: https://github.com/doctrine/orm/tree/3.1.x
-  [3.1 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.1.x/graph/badge.svg
-  [3.1 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.1.x
-  [3.0 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=3.0.x
-  [3.0]: https://github.com/doctrine/orm/tree/3.0.x
-  [3.0 coverage image]: https://codecov.io/gh/doctrine/orm/branch/3.0.x/graph/badge.svg
-  [3.0 coverage]: https://codecov.io/gh/doctrine/orm/branch/3.0.x
-  [2.19 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.19.x
-  [2.19]: https://github.com/doctrine/orm/tree/2.19.x
-  [2.19 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.19.x/graph/badge.svg
-  [2.19 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.19.x
-  [2.18 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.18.x
-  [2.18]: https://github.com/doctrine/orm/tree/2.18.x
-  [2.18 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.18.x/graph/badge.svg
-  [2.18 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.18.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
+  [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
+  [2.21 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.21.x/graph/badge.svg
+  [2.21 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.21.x
+  [2.20 image]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml/badge.svg?branch=2.20.x
+  [2.20]: https://github.com/doctrine/orm/tree/2.20.x
+  [2.20 workflow]: https://github.com/doctrine/orm/actions/workflows/continuous-integration.yml?query=branch%3A2.20.x
+  [2.20 coverage image]: https://codecov.io/gh/doctrine/orm/branch/2.20.x/graph/badge.svg
+  [2.20 coverage]: https://codecov.io/gh/doctrine/orm/branch/2.20.x

UPGRADE.md

@@ -1,5 +1,363 @@
+Note about upgrading: Doctrine uses static and runtime mechanisms to raise
+awareness about deprecated code.
+
+- Use of `@deprecated` docblock that is detected by IDEs (like PHPStorm) or
+  Static Analysis tools (like Psalm, phpstan)
+- Use of our low-overhead runtime deprecation API, details:
+  https://github.com/doctrine/deprecations/
+
+# Upgrade to 3.x General Notes
+
+We recommend you upgrade to DBAL 3 first before upgrading to ORM 3. See
+the DBAL upgrade docs: https://github.com/doctrine/dbal/blob/3.10.x/UPGRADE.md
+
+Rather than doing several major upgrades at once, we recommend you do the following:
+
+- upgrade to DBAL 3
+- deploy and monitor
+- upgrade to ORM 3
+- deploy and monitor
+- upgrade to DBAL 4
+- deploy and monitor
+
+If you are using Symfony, the recommended minimal Doctrine Bundle version is 2.15
+to run with ORM 3.
+
+At this point, we recommend upgrading to PHP 8.4 first and then directly from
+ORM 2.19 to 3.5 and up so that you can skip the lazy ghost proxy generation
+and directly start using native lazy objects.
+
+# Upgrade to 3.7
+
+## Conditional breaking changes
+
+3.7 adds support for `doctrine/collections` 3. If you upgrade to that version
+of `doctrine/collections`, there are breaking changes in `doctrine/orm` as well,
+because of cross-package inheritance and type declarations.
+
+Most notably, `Doctrine\ORM\PersistentCollection::add` no longer returns a boolean:
+
+```diff
+- public function add(mixed $value): bool
++ public function add(mixed $value): void
+```
+
+That method always returned `true`, so you can safely stop using the return
+value before upgrading.
+
+Also, if you extend `Doctrine\ORM\Persisters\SqlValueVisitor`, you need to
+ensure the following methods have a return type in your subclasses:
+
+- `walkComparison()`
+- `walkCompositeExpression()`
+- `walkValue()`
+
+## Deprecate `EventManager` return type in `EntityManager` methods
+
+The return type of the following methods has been changed from
+`Doctrine\Common\EventManager` to `Doctrine\Common\EventManagerInterface`:
+
+- `Doctrine\ORM\Decorator\EntityManagerDecorator::getEventManager()`
+- `Doctrine\ORM\EntityManager::getEventManager()`
+- `Doctrine\ORM\EntityManagerInterface::getEventManager()`
+
+All three methods continue to return an instance of `EventManager`, however
+relying on that is deprecated and will no longer be the guaranteed in 4.0.
+
+# Upgrade to 3.6
+
+## Deprecate using string expression for default values in mappings
+
+Using a string expression for default values in field mappings is deprecated.
+Use `Doctrine\DBAL\Schema\DefaultExpression` instances instead.
+
+Here is how to address this deprecation when mapping entities using PHP attributes:
+
+```diff
+ use DateTime;
++use Doctrine\DBAL\Schema\DefaultExpression\CurrentDate;
++use Doctrine\DBAL\Schema\DefaultExpression\CurrentTime;
++use Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp;
+ use Doctrine\ORM\Mapping as ORM;
+
+ #[ORM\Entity]
+ final class TimeEntity
+ {
+     #[ORM\Id]
+     #[ORM\Column]
+     public int $id;
+
+-    #[ORM\Column(options: ['default' => 'CURRENT_TIMESTAMP'], insertable: false, updatable: false)]
++    #[ORM\Column(options: ['default' => new CurrentTimestamp()], insertable: false, updatable: false)]
+     public DateTime $createdAt;
+
+-    #[ORM\Column(options: ['default' => 'CURRENT_TIME'], insertable: false, updatable: false)]
++    #[ORM\Column(options: ['default' => new CurrentTime()], insertable: false, updatable: false)]
+     public DateTime $createdTime;
+
+-    #[ORM\Column(options: ['default' => 'CURRENT_DATE'], insertable: false, updatable: false)]
++    #[ORM\Column(options: ['default' => new CurrentDate()], insertable: false, updatable: false)]
+     public DateTime $createdDate;
+ }
+```
+
+Here is how to do the same when mapping entities using XML:
+
+```diff
+ <?xml version="1.0" encoding="UTF-8"?>
+
+ <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
+                           https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
+
+     <entity name="Doctrine\Tests\ORM\Functional\XmlTimeEntity">
+         <id name="id" type="integer" column="id">
+             <generator strategy="AUTO"/>
+         </id>
+
+         <field name="createdAt" type="datetime" insertable="false" updatable="false">
+             <options>
+-                <option name="default">CURRENT_TIMESTAMP</option>
++                <option name="default">
++                    <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp"/>
++                </option>
+             </options>
+         </field>
+
+         <field name="createdAtImmutable" type="datetime_immutable" insertable="false" updatable="false">
+             <options>
+-                <option name="default">CURRENT_TIMESTAMP</option>
++                <option name="default">
++                    <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentTimestamp"/>
++                </option>
+             </options>
+         </field>
+
+         <field name="createdTime" type="time" insertable="false" updatable="false">
+             <options>
+-                <option name="default">CURRENT_TIME</option>
++                <option name="default">
++                    <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentTime"/>
++                </option>
+             </options>
+         </field>
+         <field name="createdDate" type="date" insertable="false" updatable="false">
+             <options>
+-                <option name="default">CURRENT_DATE</option>
++                <option name="default">
++                    <object class="Doctrine\DBAL\Schema\DefaultExpression\CurrentDate"/>
++                </option>
+             </options>
+         </field>
+     </entity>
+ </doctrine-mapping>
+```
+
+
+## Deprecate `FieldMapping::$default`
+
+The `default` property of `Doctrine\ORM\Mapping\FieldMapping` is deprecated and
+will be removed in 4.0. Instead, use `FieldMapping::$options['default']`.
+
+## Deprecate specifying `nullable` on columns that end up being used in a primary key
+
+Specifying `nullable` on join columns that are part of a primary key is
+deprecated and will be an error in 4.0.
+
+This can happen when using a join column mapping together with an id mapping,
+or when using a join column mapping or an inverse join column mapping on a
+many-to-many relationship.
+
+```diff
+ class User
+ {
+     #[ORM\Id]
+     #[ORM\Column(type: 'integer')]
+     private int $id;
+
+     #[ORM\Id]
+     #[ORM\ManyToOne(targetEntity: Family::class, inversedBy: 'users')]
+-    #[ORM\JoinColumn(name: 'family_id', referencedColumnName: 'id', nullable: true)]
++    #[ORM\JoinColumn(name: 'family_id', referencedColumnName: 'id')]
+     private ?Family $family;
+
+     #[ORM\ManyToMany(targetEntity: Group::class)]
+     #[ORM\JoinTable(name: 'user_group')]
+-    #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id', nullable: true)]
+-    #[ORM\InverseJoinColumn(name: 'group_id', referencedColumnName: 'id', nullable: true)]
++    #[ORM\JoinColumn(name: 'user_id', referencedColumnName: 'id')]
++    #[ORM\InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
+     private Collection $groups;
+ }
+```
+
+## Deprecate `Doctrine\ORM\QueryBuilder::add('join', ...)` with a list of join parts
+
+Using `Doctrine\ORM\QueryBuilder::add('join', ...)` with a list of join parts
+is deprecated in favor of using an associative array of join parts with the
+root alias as key.
+
+## Deprecate using the `WITH` keyword for arbitrary DQL joins
+
+Using the `WITH` keyword to specify the condition for an arbitrary DQL join is
+deprecated in favor of using the `ON` keyword (similar to the SQL syntax for
+joins).
+The `WITH` keyword is now meant to be used only for filtering conditions in
+association joins.
+
+# Upgrade to 3.5
+
+See the General notes to upgrading to 3.x versions above.
+
+## Deprecate not using native lazy objects on PHP 8.4+
+
+Having native lazy objects disabled on PHP 8.4+ is deprecated and will not be
+possible in 4.0.
+
+You can enable them through configuration:
+
+```php
+$config->enableNativeLazyObjects(true);
+```
+
+As a consequence, methods, parameters and commands related to userland lazy
+objects have been deprecated on PHP 8.4+:
+
+- `Doctrine\ORM\Tools\Console\Command\GenerateProxiesCommand`
+- `Doctrine\ORM\Configuration::getAutoGenerateProxyClasses()`
+- `Doctrine\ORM\Configuration::getProxyDir()`
+- `Doctrine\ORM\Configuration::getProxyNamespace()`
+- `Doctrine\ORM\Configuration::setAutoGenerateProxyClasses()`
+- `Doctrine\ORM\Configuration::setProxyDir()`
+- `Doctrine\ORM\Configuration::setProxyNamespace()`
+- Passing more than one argument to `Doctrine\ORM\Proxy\ProxyFactory::__construct()`
+
+Additionally, some methods of ORMSetup have been deprecated in favor of a new
+counterpart.
+
+- `Doctrine\ORM\ORMSetup::createAttributeMetadataConfiguration()` is deprecated in favor of
+  `Doctrine\ORM\ORMSetup::createAttributeMetadataConfig()`
+- `Doctrine\ORM\ORMSetup::createXMLMetadataConfiguration()` is deprecated in favor of
+  `Doctrine\ORM\ORMSetup::createXMLMetadataConfig()`
+- `Doctrine\ORM\ORMSetup::createConfiguration()` is deprecated in favor of
+  `Doctrine\ORM\ORMSetup::createConfig()`
+
+## Deprecate methods for configuring no longer configurable features
+
+Since 3.0, lazy ghosts are enabled unconditionally, and so is rejecting ID
+collisions in the identity map.
+
+As a consequence, the following methods are deprecated and will be removed in 4.0:
+* `Doctrine\ORM\Configuration::setLazyGhostObjectEnabled()`
+* `Doctrine\ORM\Configuration::isLazyGhostObjectEnabled()`
+* `Doctrine\ORM\Configuration::setRejectIdCollisionInIdentityMap()`
+* `Doctrine\ORM\Configuration::isRejectIdCollisionInIdentityMapEnabled()`
+
+# Upgrade to 3.4.1
+
+## BC BREAK: You can no longer use the `.*` notation to get all fields of an entity in a DTO
+
+This feature was introduced in 3.4.0, and introduces several issues, so we
+decide to remove it before it is used too widely.
+
+# Upgrade to 3.4
+
+See the General notes to upgrading to 3.x versions above.
+
+## Discriminator Map class duplicates
+
+Using the same class several times in a discriminator map is deprecated.
+In 4.0, this will be an error.
+
+## `Doctrine\ORM\Mapping\ClassMetadata::$reflFields` deprecated
+
+To better support property hooks and lazy proxies in the future, `$reflFields` had to
+be deprecated because we cannot use the PHP internal reflection API directly anymore.
+
+The property was changed from an array to an object of type `LegacyReflectionFields`
+that implements `ArrayAccess`.
+
+Use the new `Doctrine\ORM\Mapping\PropertyAccessors\PropertyAccessor` API and access
+through `Doctrine\ORM\Mapping\ClassMetadata::$propertyAccessors` instead.
+
+Companion accessor methods are deprecated as well.
+
+# Upgrade to 3.3
+
+See the General notes to upgrading to 3.x versions above.
+
+## Deprecate `DatabaseDriver`
+
+The class `Doctrine\ORM\Mapping\Driver\DatabaseDriver` is deprecated without replacement.
+
+## Add `Doctrine\ORM\Query\OutputWalker` interface, deprecate `Doctrine\ORM\Query\SqlWalker::getExecutor()`
+
+Output walkers should implement the new `\Doctrine\ORM\Query\OutputWalker` interface and create
+`Doctrine\ORM\Query\Exec\SqlFinalizer` instances instead of `Doctrine\ORM\Query\Exec\AbstractSqlExecutor`s.
+The output walker must not base its workings on the query `firstResult`/`maxResult` values, so that the
+`SqlFinalizer` can be kept in the query cache and used regardless of the actual `firstResult`/`maxResult` values.
+Any operation dependent on `firstResult`/`maxResult` should take place within the `SqlFinalizer::createExecutor()`
+method. Details can be found at https://github.com/doctrine/orm/pull/11188.
+
+
+# Upgrade to 3.2
+
+See the General notes to upgrading to 3.x versions above.
+
+## Deprecate the `NotSupported` exception
+
+The class `Doctrine\ORM\Exception\NotSupported` is deprecated without replacement.
+
+## Deprecate remaining `Serializable` implementation
+
+Relying on `SequenceGenerator` implementing the `Serializable` is deprecated
+because that interface won't be implemented in ORM 4 anymore.
+
+The following methods are deprecated:
+
+* `SequenceGenerator::serialize()`
+* `SequenceGenerator::unserialize()`
+
+## `orm:schema-tool:update` option `--complete` is deprecated
+
+That option behaves as a no-op, and is deprecated. It will be removed in 4.0.
+
+## Deprecate properties `$indexes` and `$uniqueConstraints` of `Doctrine\ORM\Mapping\Table`
+
+The properties `$indexes` and `$uniqueConstraints` have been deprecated since they had no effect at all.
+The preferred way of defining indices and unique constraints is by
+using the `\Doctrine\ORM\Mapping\UniqueConstraint` and `\Doctrine\ORM\Mapping\Index` attributes.
+
+# Upgrade to 3.1
+
+See the General notes to upgrading to 3.x versions above.
+
+## Deprecate `Doctrine\ORM\Mapping\ReflectionEnumProperty`
+
+This class is deprecated and will be removed in 4.0.
+Instead, use `Doctrine\Persistence\Reflection\EnumReflectionProperty` from
+`doctrine/persistence`.
+
+## Deprecate passing null to `ClassMetadata::fullyQualifiedClassName()`
+
+Passing `null` to `Doctrine\ORM\ClassMetadata::fullyQualifiedClassName()` is
+deprecated and will no longer be possible in 4.0.
+
+## Deprecate array access
+
+Using array access on instances of the following classes is deprecated:
+
+- `Doctrine\ORM\Mapping\DiscriminatorColumnMapping`
+- `Doctrine\ORM\Mapping\EmbedClassMapping`
+- `Doctrine\ORM\Mapping\FieldMapping`
+- `Doctrine\ORM\Mapping\JoinColumnMapping`
+- `Doctrine\ORM\Mapping\JoinTableMapping`
+
 # Upgrade to 3.0
 
+See the General notes to upgrading to 3.x versions above.
+
 ## BC BREAK: Calling `ClassMetadata::getAssociationMappedByTargetField()` with the owning side of an association now throws an exception
 
 Previously, calling
@@ -25,6 +383,9 @@ so `$targetEntity` is a first argument now. This change affects only non-named a
 When using the `AUTO` strategy to let Doctrine determine the identity generation mechanism for
 an entity, and when using `doctrine/dbal` 4, PostgreSQL now uses `IDENTITY`
 instead of `SEQUENCE` or `SERIAL`.
+
+There are three ways to handle this change.
+
 * If you want to upgrade your existing tables to identity columns, you will need to follow [migration to identity columns on PostgreSQL](https://www.doctrine-project.org/projects/doctrine-dbal/en/4.0/how-to/postgresql-identity-migration.html)
 * If you want to keep using SQL sequences, you need to configure the ORM this way:
 ```php
@@ -37,6 +398,27 @@ $configuration->setIdentityGenerationPreferences([
     PostgreSQLPlatform::CLASS => ClassMetadata::GENERATOR_TYPE_SEQUENCE,
 ]);
 ```
+* You can change individual entities to use the `SEQUENCE` strategy instead of `AUTO`:
+```php
+
+diff --git a/src/Entity/Example.php b/src/Entity/Example.php
+index 28be8df378..3b7d61bda6 100644
+--- a/src/Entity/Example.php
++++ b/src/Entity/Example.php
+@@ -38,7 +38,7 @@ class Example
+
+     #[ORM\Id]
+     #[ORM\Column(type: 'integer')]
+-    #[ORM\GeneratedValue(strategy: 'AUTO')]
++    #[ORM\GeneratedValue(strategy: 'SEQUENCE')]
+     private int $id;
+
+     #[Assert\Length(max: 255)]
+```
+The later two options require a small database migration that will remove the default
+expression fetching the next value from the sequence. It's not strictly necessary to
+do this migration because the code will work anyway. A benefit of this approach is
+that you can just make and roll out the code changes first and then migrate the database later.
 
 ## BC BREAK: Throw exceptions when using illegal attributes on Embeddable
 
@@ -46,12 +428,44 @@ now they throw an exception.
 
 ## BC BREAK: Partial objects are removed
 
-- The `PARTIAL` keyword in DQL no longer exists.
-- `Doctrine\ORM\Query\AST\PartialObjectExpression`is removed.
-- `Doctrine\ORM\Query\SqlWalker::HINT_PARTIAL` and
+WARNING: This was relaxed in ORM 3.2 when partial was re-allowed for array-hydration.
+
+- The `PARTIAL` keyword in DQL no longer exists (reintroduced in ORM 3.2)
+- `Doctrine\ORM\Query\AST\PartialObjectExpression` is removed. (reintroduced in ORM 3.2)
+- `Doctrine\ORM\Query\SqlWalker::HINT_PARTIAL` (reintroduced in ORM 3.2) and
   `Doctrine\ORM\Query::HINT_FORCE_PARTIAL_LOAD` are removed.
 - `Doctrine\ORM\EntityManager*::getPartialReference()` is removed.
 
+## BC BREAK: Enforce ArrayCollection Type on `\Doctrine\ORM\QueryBuilder::setParameters(ArrayCollection $parameters)`
+
+The argument $parameters can no longer be a key=>value array. Only ArrayCollection types are allowed.
+
+### Before
+
+```php
+$qb = $em->createQueryBuilder()
+    ->select('u')
+    ->from('User', 'u')
+    ->where('u.id = :user_id1 OR u.id = :user_id2')
+    ->setParameters(array(
+        'user_id1' => 1,
+        'user_id2' => 2
+    ));
+```
+
+### After
+
+```php
+$qb = $em->createQueryBuilder()
+    ->select('u')
+    ->from('User', 'u')
+    ->where('u.id = :user_id1 OR u.id = :user_id2')
+    ->setParameters(new ArrayCollection(array(
+        new Parameter('user_id1', 1),
+        new Parameter('user_id2', 2)
+    )));
+```
+
 ## BC BREAK: `Doctrine\ORM\Persister\Entity\EntityPersister::executeInserts()` return type changed to `void`
 
 Implementors should adapt to the new signature, and should call
@@ -674,6 +1088,59 @@ following classes and methods:
 
 Use `toIterable()` instead.
 
+# Upgrade to 2.20
+
+## Add `Doctrine\ORM\Query\OutputWalker` interface, deprecate `Doctrine\ORM\Query\SqlWalker::getExecutor()`
+
+Output walkers should implement the new `\Doctrine\ORM\Query\OutputWalker` interface and create
+`Doctrine\ORM\Query\Exec\SqlFinalizer` instances instead of `Doctrine\ORM\Query\Exec\AbstractSqlExecutor`s.
+The output walker must not base its workings on the query `firstResult`/`maxResult` values, so that the
+`SqlFinalizer` can be kept in the query cache and used regardless of the actual `firstResult`/`maxResult` values.
+Any operation dependent on `firstResult`/`maxResult` should take place within the `SqlFinalizer::createExecutor()`
+method. Details can be found at https://github.com/doctrine/orm/pull/11188.
+
+## Explictly forbid property hooks
+
+Property hooks are not supported yet by Doctrine ORM. Until support is added,
+they are explicitly forbidden because the support would result in a breaking
+change in behavior.
+
+Progress on this is tracked at https://github.com/doctrine/orm/issues/11624 .
+
+## PARTIAL DQL syntax is undeprecated
+
+Use of the PARTIAL keyword is not deprecated anymore in DQL, because we will be
+able to support PARTIAL objects with PHP 8.4 Lazy Objects and
+Symfony/VarExporter in a better way. When we decided to remove this feature
+these two abstractions did not exist yet.
+
+WARNING: If you want to upgrade to 3.x and still use PARTIAL keyword in DQL
+with array or object hydrators, then you have to directly migrate to ORM 3.3.x or higher.
+PARTIAL keyword in DQL is not available in 3.0, 3.1 and 3.2 of ORM.
+
+## Deprecate `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()`
+
+Use the `\Doctrine\ORM\Query::HINT_CUSTOM_OUTPUT_WALKER` query hint to set the output walker
+class instead of setting it through the `\Doctrine\ORM\Query\Parser::setCustomOutputTreeWalker()` method
+on the parser instance.
+
+# Upgrade to 2.19
+
+## Deprecate calling `ClassMetadata::getAssociationMappedByTargetField()` with the owning side of an association
+
+Calling
+`Doctrine\ORM\Mapping\ClassMetadata::getAssociationMappedByTargetField()` with
+the owning side of an association returns `null`, which is undocumented, and
+wrong according to the phpdoc of the parent method.
+
+If you do not know whether you are on the owning or inverse side of an association,
+you can use  `Doctrine\ORM\Mapping\ClassMetadata::isAssociationInverseSide()`
+to find out.
+
+## Deprecate `Doctrine\ORM\Query\Lexer::T_*` constants
+
+Use `Doctrine\ORM\Query\TokenType::T_*` instead.
+
 # Upgrade to 2.17
 
 ## Deprecate annotations classes for named queries
@@ -1871,7 +2338,7 @@ from 2.0 have to configure the annotation driver if they don't use `Configuratio
 
 ## Scalar mappings can now be omitted from DQL result
 
-You are now allowed to mark scalar SELECT expressions as HIDDEN an they are not hydrated anymore.
+You are now allowed to mark scalar SELECT expressions as HIDDEN and they are not hydrated anymore.
 Example:
 
 SELECT u, SUM(a.id) AS HIDDEN numArticles FROM User u LEFT JOIN u.Articles a ORDER BY numArticles DESC HAVING numArticles > 10

ci/github/phpunit/mysqli.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -19,6 +24,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -27,7 +33,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

ci/github/phpunit/pdo_mysql.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -19,6 +24,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -27,7 +33,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

ci/github/phpunit/pdo_pgsql.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -16,6 +21,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -24,7 +30,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

ci/github/phpunit/pdo_sqlite.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -14,6 +19,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -22,7 +28,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

ci/github/phpunit/pgsql.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -16,6 +21,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -24,7 +30,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

ci/github/phpunit/sqlite3.xml

@@ -3,6 +3,11 @@
          xsi:noNamespaceSchemaLocation="../../../vendor/phpunit/phpunit/phpunit.xsd"
          colors="true"
          beStrictAboutOutputDuringTests="true"
+         displayDetailsOnTestsThatTriggerDeprecations="true"
+         displayDetailsOnTestsThatTriggerNotices="true"
+         displayDetailsOnTestsThatTriggerWarnings="true"
+         failOnNotice="true"
+         failOnWarning="true"
          failOnRisky="true"
          cacheDirectory=".phpunit.cache"
 >
@@ -14,6 +19,7 @@
 
         <!-- necessary change for some CLI/console output test assertions -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
 
     <testsuites>
@@ -22,7 +28,7 @@
         </testsuite>
     </testsuites>
 
-    <source>
+    <source ignoreSuppressionOfDeprecations="true">
         <include>
             <directory suffix=".php">../../../src</directory>
         </include>

composer.json

@@ -1,65 +1,86 @@
 {
     "name": "doctrine/orm",
-    "type": "library",
     "description": "Object-Relational-Mapper for PHP",
-    "keywords": ["orm", "database"],
-    "homepage": "https://www.doctrine-project.org/projects/orm.html",
     "license": "MIT",
-    "authors": [
-        {"name": "Guilherme Blanco", "email": "guilhermeblanco@gmail.com"},
-        {"name": "Roman Borschel", "email": "roman@code-factory.org"},
-        {"name": "Benjamin Eberlei", "email": "kontakt@beberlei.de"},
-        {"name": "Jonathan Wage", "email": "jonwage@gmail.com"},
-        {"name": "Marco Pivetta", "email": "ocramius@gmail.com"}
+    "type": "library",
+    "keywords": [
+        "orm",
+        "database"
     ],
-    "config": {
-        "allow-plugins": {
-            "composer/package-versions-deprecated": true,
-            "dealerdirect/phpcodesniffer-composer-installer": true
+    "authors": [
+        {
+            "name": "Guilherme Blanco",
+            "email": "guilhermeblanco@gmail.com"
         },
-        "sort-packages": true
-    },
+        {
+            "name": "Roman Borschel",
+            "email": "roman@code-factory.org"
+        },
+        {
+            "name": "Benjamin Eberlei",
+            "email": "kontakt@beberlei.de"
+        },
+        {
+            "name": "Jonathan Wage",
+            "email": "jonwage@gmail.com"
+        },
+        {
+            "name": "Marco Pivetta",
+            "email": "ocramius@gmail.com"
+        }
+    ],
+    "homepage": "https://www.doctrine-project.org/projects/orm.html",
     "require": {
         "php": "^8.1",
-        "composer-runtime-api": "^2",
         "ext-ctype": "*",
-        "doctrine/collections": "^2.1",
+        "composer-runtime-api": "^2",
+        "doctrine/collections": "^2.2 || ^3",
         "doctrine/dbal": "^3.8.2 || ^4",
         "doctrine/deprecations": "^0.5.3 || ^1",
-        "doctrine/event-manager": "^1.2 || ^2",
+        "doctrine/event-manager": "^2.1.1",
         "doctrine/inflector": "^1.4 || ^2.0",
         "doctrine/instantiator": "^1.3 || ^2",
         "doctrine/lexer": "^3",
-        "doctrine/persistence": "^3.1.1",
+        "doctrine/persistence": "^3.3.1 || ^4",
         "psr/cache": "^1 || ^2 || ^3",
-        "symfony/console": "^5.4 || ^6.0 || ^7.0",
-        "symfony/var-exporter": "~6.2.13 || ^6.3.2 || ^7.0"
+        "symfony/console": "^5.4 || ^6.0 || ^7.0 || ^8.0",
+        "symfony/var-exporter": "^6.3.9 || ^7.0 || ^8.0"
     },
     "require-dev": {
-        "doctrine/coding-standard": "^12.0",
+        "doctrine/coding-standard": "^14.0",
         "phpbench/phpbench": "^1.0",
-        "phpstan/phpstan": "1.10.59",
-        "phpunit/phpunit": "^10.4.0",
+        "phpstan/extension-installer": "^1.4",
+        "phpstan/phpstan": "2.1.23",
+        "phpstan/phpstan-deprecation-rules": "^2",
+        "phpunit/phpunit": "^10.5.0 || ^11.5",
         "psr/log": "^1 || ^2 || ^3",
-        "squizlabs/php_codesniffer": "3.7.2",
-        "symfony/cache": "^5.4 || ^6.2 || ^7.0",
-        "vimeo/psalm": "5.22.2"
+        "symfony/cache": "^5.4 || ^6.2 || ^7.0 || ^8.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"
     },
     "autoload": {
-        "psr-4": { "Doctrine\\ORM\\": "src" }
+        "psr-4": {
+            "Doctrine\\ORM\\": "src"
+        }
     },
     "autoload-dev": {
         "psr-4": {
-            "Doctrine\\Tests\\": "tests/Tests",
+            "Doctrine\\Performance\\": "tests/Performance",
             "Doctrine\\StaticAnalysis\\": "tests/StaticAnalysis",
-            "Doctrine\\Performance\\": "tests/Performance"
+            "Doctrine\\Tests\\": "tests/Tests"
         }
     },
-    "archive": {
-        "exclude": ["!vendor", "tests", "*phpunit.xml", "build.xml", "build.properties", "composer.phar", "vendor/satooshi", "lib/vendor", "*.swp"]
+    "config": {
+        "allow-plugins": {
+            "composer/package-versions-deprecated": true,
+            "dealerdirect/phpcodesniffer-composer-installer": true,
+            "phpstan/extension-installer": true
+        },
+        "sort-packages": true
+    },
+    "scripts": {
+        "docs": "composer --working-dir docs update && ./docs/vendor/bin/build-docs.sh @additional_args"
     }
 }

docs/.gitignore

@@ -1,4 +1,3 @@
-en/_exts/configurationblock.pyc
-build
-en/_build
-.idea
+composer.lock
+vendor/
+output/

docs/.gitmodules

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

docs/README.md

@@ -1,18 +1,18 @@
 # Doctrine ORM Documentation
 
+The documentation is written in [ReStructured Text](https://docutils.sourceforge.io/rst.html).
+
 ## How to Generate:
-Using Ubuntu 14.04 LTS:
 
-1. Run ./bin/install-dependencies.sh
-2. Run ./bin/generate-docs.sh
+In the project root, run
 
-It will generate the documentation into the build directory of the checkout.
+    composer docs
 
+This will generate the documentation into the `docs/output` subdirectory.
 
-## Theme issues
+To browse the documentation, you need to run a webserver:
 
-If you get a "Theme error", check if the `en/_theme` subdirectory is empty,
-in which case you will need to run:
+    cd docs/output
+    php -S localhost:8000
 
-1. git submodule init
-2. git submodule update
+Now the documentation is available at [http://localhost:8000](http://localhost:8000).

docs/bin/generate-docs.sh

@@ -1,10 +0,0 @@
-#!/bin/bash
-EXECPATH=`dirname $0`
-cd $EXECPATH
-cd ..
-
-rm build -Rf
-sphinx-build en build
-
-sphinx-build -b latex en build/pdf
-rubber --into build/pdf --pdf build/pdf/Doctrine2ORM.tex

docs/bin/install-dependencies.sh

@@ -1,2 +0,0 @@
-#!/bin/bash
-sudo apt-get update && sudo apt-get install -y python2.7 python-sphinx python-pygments

docs/composer.json

@@ -0,0 +1,9 @@
+{
+    "name": "doctrine/orm-docs",
+    "description": "Documentation for the Object-Relational Mapper\"",
+    "type": "library",
+    "license": "MIT",
+    "require-dev": {
+        "doctrine/docs-builder": "^1.0"
+    }
+}

docs/en/Makefile

@@ -1,89 +0,0 @@
-# Makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
-help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Doctrine2ORM.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Doctrine2ORM.qhc"
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."

docs/en/_exts/configurationblock.py

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

docs/en/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_READ);
+    $account = $em->find(Account::class, $accId, LockMode::PESSIMISTIC_WRITE);
 
 Keeping Updates and Deletes in Sync
 -----------------------------------

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

@@ -40,7 +40,8 @@ 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
@@ -50,7 +51,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 two
+In this cookbook-entry I will show examples of the first three
 points. There are probably much more use-cases.
 
 Generic count query for pagination
@@ -101,8 +102,16 @@ The ``Paginate::count(Query $query)`` looks like:
     {
         static public function count(Query $query)
         {
-            /** @var Query $countQuery */
-            $countQuery = clone $query;
+            /*
+               To avoid changing the $query passed into the method and to make sure a possibly existing
+               ResultSetMapping is discarded, we create a new query object any copy relevant data over.
+            */
+            $countQuery = new Query($query->getEntityManager());
+            $countQuery->setDQL($query->getDQL());
+            $countQuery->setParameters(clone $query->getParameters());
+            foreach ($query->getHints() as $name => $value) {
+                $countQuery->setHint($name, $value);
+            }
 
             $countQuery->setHint(Query::HINT_CUSTOM_TREE_WALKERS, array('DoctrineExtensions\Paginate\CountSqlWalker'));
             $countQuery->setFirstResult(null)->setMaxResults(null);
@@ -111,7 +120,7 @@ The ``Paginate::count(Query $query)`` looks like:
         }
     }
 
-It clones the query, resets the limit clause first and max results
+This resets the limit clause first and max results
 and registers the ``CountSqlWalker`` custom tree walker which
 will modify the AST to execute a count query. The walkers
 implementation is:
@@ -215,3 +224,39 @@ 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

@@ -0,0 +1,47 @@
+<?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,6 +232,33 @@ 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/generated-columns.rst

@@ -0,0 +1,44 @@
+Generated Columns
+=================
+
+Generated columns, sometimes also called virtual columns, are populated by
+the database engine itself. They are a tool for performance optimization, to
+avoid calculating a value on each query.
+
+You can define generated columns on entities and have Doctrine map the values
+to your entity.
+
+Declaring a generated column
+----------------------------
+
+There is no explicit mapping instruction for generated columns. Instead, you
+specify that the column should not be written to, and define a custom column
+definition.
+
+.. literalinclude:: generated-columns/Person.php
+   :language: php
+
+* ``insertable``, ``updatable``: Setting these to false tells Doctrine to never
+  write this column - writing to a generated column would result in an error
+  from the database.
+* ``columnDefinition``: We specify the full DDL to create the column. To allow
+  to use database specific features, this attribute does not use Doctrine Query
+  Language but native SQL. Note that you need to reference columns by their
+  database name (either explicitly set in the mapping or per the current
+  :doc:`naming strategy <../reference/namingstrategy>`).
+  Be aware that specifying a column definition makes the ``SchemaTool``
+  completely ignore all other configuration for this column. See also
+  :ref:`#[Column] <attrref_column>`
+* ``generated``: Specifying that this column is always generated tells Doctrine
+  to update the field on the entity with the value from the database after
+  every write operation.
+
+Advanced example: Extracting a value from a JSON structure
+----------------------------------------------------------
+
+Lets assume we have an entity that stores a blogpost as structured JSON.
+To avoid extracting all titles on the fly when listing the posts, we create a
+generated column with the field.
+
+.. literalinclude:: generated-columns/Article.php
+   :language: php

docs/en/cookbook/generated-columns/Article.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Article
+{
+    #[ORM\Id]
+    #[ORM\GeneratedValue]
+    #[ORM\Column]
+    private int $id;
+
+    /**
+     * When working with Postgres, it is recommended to use the jsonb
+     * format for better performance.
+     */
+    #[ORM\Column(options: ['jsonb' => true])]
+    private array $content;
+
+    /**
+     * Because we specify NOT NULL, inserting will fail if the content does
+     * not have a string in the title field.
+     */
+    #[ORM\Column(
+        insertable: false,
+        updatable: false,
+        columnDefinition: "VARCHAR(255) generated always as (content->>'title') stored NOT NULL",
+        generated: 'ALWAYS',
+    )]
+    private string $title;
+}

docs/en/cookbook/generated-columns/Person.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+class Person
+{
+    #[ORM\Column(type: 'string')]
+    private string $firstName;
+
+    #[ORM\Column(type: 'string', name: 'name')]
+    private string $lastName;
+
+    #[ORM\Column(
+        type: 'string',
+        insertable: false,
+        updatable: false,
+        columnDefinition: "VARCHAR(255) GENERATED ALWAYS AS (concat(firstName, ' ', name) stored NOT NULL",
+        generated: 'ALWAYS',
+    )]
+    private string $fullName;
+}

docs/en/cookbook/mysql-enums.rst

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

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

@@ -11,7 +11,7 @@ What we offer are hooks to execute any kind of validation.
 .. note::
 
     You don't need to validate your entities in the lifecycle
-    events. Its only one of many options. Of course you can also
+    events. It is only one of many options. Of course you can also
     perform validations in value setters or any other method of your
     entities that are used in your code.
 

docs/en/index.rst

@@ -13,7 +13,6 @@ If this documentation is not helping to answer questions you have about
 Doctrine ORM don't panic. You can get help from different sources:
 
 -  There is a :doc:`FAQ <reference/faq>` with answers to frequent questions.
--  The `Doctrine Mailing List <https://groups.google.com/group/doctrine-user>`_
 -  Slack chat room `#orm <https://www.doctrine-project.org/slack>`_
 -  Report a bug on `GitHub <https://github.com/doctrine/orm/issues>`_.
 -  On `StackOverflow <https://stackoverflow.com/questions/tagged/doctrine-orm>`_
@@ -73,6 +72,8 @@ 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>`
 * :doc:`Metadata Drivers <reference/metadata-drivers>`
@@ -100,6 +101,7 @@ Cookbook
 
 * **Patterns**:
   :doc:`Aggregate Fields <cookbook/aggregate-fields>` \|
+  :doc:`Generated/Virtual Columns <cookbook/generated-columns>` \|
   :doc:`Decorator Pattern <cookbook/decorator-pattern>` \|
   :doc:`Strategy Pattern <cookbook/strategy-cookbook-introduction>`
 
@@ -119,4 +121,5 @@ Cookbook
 
 * **Custom Datatypes**
   :doc:`MySQL Enums <cookbook/mysql-enums>`
+  :doc:`Custom Mapping Types <cookbook/custom-mapping-types>`
   :doc:`Advanced Field Value Conversion <cookbook/advanced-field-value-conversion-using-custom-mapping-types>`

docs/en/make.bat

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

docs/en/reference/advanced-configuration.rst

@@ -19,7 +19,7 @@ steps of configuration.
 
     // ...
 
-    if ($applicationMode == "development") {
+    if ($applicationMode === "development") {
         $queryCache = new ArrayAdapter();
         $metadataCache = new ArrayAdapter();
     } else {
@@ -29,16 +29,21 @@ steps of configuration.
 
     $config = new Configuration;
     $config->setMetadataCache($metadataCache);
-    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities'], true);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
     $config->setMetadataDriverImpl($driverImpl);
     $config->setQueryCache($queryCache);
-    $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
-    $config->setProxyNamespace('MyProject\Proxies');
 
-    if ($applicationMode == "development") {
-        $config->setAutoGenerateProxyClasses(true);
+    if (PHP_VERSION_ID > 80400) {
+        $config->enableNativeLazyObjects(true);
     } else {
-        $config->setAutoGenerateProxyClasses(false);
+        $config->setProxyDir('/path/to/myproject/lib/MyProject/Proxies');
+        $config->setProxyNamespace('MyProject\Proxies');
+
+        if ($applicationMode === "development") {
+            $config->setAutoGenerateProxyClasses(true);
+        } else {
+            $config->setAutoGenerateProxyClasses(false);
+        }
     }
 
     $connection = DriverManager::getConnection([
@@ -71,8 +76,27 @@ Configuration Options
 The following sections describe all the configuration options
 available on a ``Doctrine\ORM\Configuration`` instance.
 
-Proxy Directory (***REQUIRED***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _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.
 
 .. code-block:: php
 
@@ -85,8 +109,11 @@ 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***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Proxy Namespace
+~~~~~~~~~~~~~~~
+
+Required except if you use native lazy objects with PHP 8.4.
+This setting will be removed in the future.
 
 .. code-block:: php
 
@@ -98,8 +125,8 @@ Gets or sets the namespace to use for generated proxy classes. For
 a detailed explanation on proxy classes and how they are used in
 Doctrine, refer to the "Proxy Objects" section further down.
 
-Metadata Driver (***REQUIRED***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Metadata Driver (**REQUIRED**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -129,18 +156,62 @@ 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'], true);
+    $driverImpl = new AttributeDriver(['/path/to/lib/MyProject/Entities']);
     $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. 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.
+the console could not work correctly. Metadata drivers can accept either
+a single directory as a string or an array of directories.
 
-Metadata Cache (***RECOMMENDED***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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);
+
+Metadata Cache (**RECOMMENDED**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -161,8 +232,8 @@ For development you should use an array cache like
 ``Symfony\Component\Cache\Adapter\ArrayAdapter``
 which only caches data on a per-request basis.
 
-Query Cache (***RECOMMENDED***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Query Cache (**RECOMMENDED**)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -184,8 +255,8 @@ For development you should use an array cache like
 ``Symfony\Component\Cache\Adapter\ArrayAdapter``
 which only caches data on a per-request basis.
 
-SQL Logger (***Optional***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SQL Logger (**Optional**)
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: php
 
@@ -197,8 +268,11 @@ Gets or sets the logger to use for logging all SQL statements
 executed by Doctrine. The logger class must implement the
 deprecated ``Doctrine\DBAL\Logging\SQLLogger`` interface.
 
-Auto-generating Proxy Classes (***OPTIONAL***)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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
@@ -274,7 +348,7 @@ requests.
 Connection
 ----------
 
-The ``$connection`` passed as the first argument to he constructor of
+The ``$connection`` passed as the first argument to the constructor of
 ``EntityManager`` has to be an instance of ``Doctrine\DBAL\Connection``.
 You can use the factory ``Doctrine\DBAL\DriverManager::getConnection()``
 to create such a connection. The DBAL configuration is explained in the
@@ -441,7 +515,7 @@ correctly if sub-namespaces use different metadata driver
 implementations.
 
 
-Default Repository (***OPTIONAL***)
+Default Repository (**OPTIONAL**)
 -----------------------------------
 
 Specifies the FQCN of a subclass of the EntityRepository.
@@ -456,7 +530,7 @@ That will be available for all entities without a custom repository class.
 The default value is ``Doctrine\ORM\EntityRepository``.
 Any repository class must be a subclass of EntityRepository otherwise you got an ORMException
 
-Ignoring entities (***OPTIONAL***)
+Ignoring entities (**OPTIONAL**)
 -----------------------------------
 
 Specifies the Entity FQCNs to ignore.

docs/en/reference/architecture.rst

@@ -18,7 +18,7 @@ well.
 Requirements
 ------------
 
-Doctrine ORM requires a minimum of PHP 7.1. For greatly improved
+Doctrine ORM requires a minimum of PHP 8.1. For greatly improved
 performance it is also recommended that you use APC with PHP.
 
 Doctrine ORM Packages
@@ -33,14 +33,13 @@ 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 code base
-is split in to these packages for a few reasons and they are to...
+of the underlying DBAL and Persistence packages. The Doctrine codebase
+is split into these packages for a few reasons:
 
 
--  ...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
+-  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
 
 Collection, Event Manager and Persistence
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,8 +79,9 @@ Entities
 An entity is a lightweight, persistent domain object. An entity can
 be any regular PHP class observing the following restrictions:
 
--  An entity class must not be final nor read-only but
-   it may contain final methods or read-only properties.
+-  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.
 -  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
@@ -168,7 +168,7 @@ recommended, at least not as long as an entity instance still holds
 references to proxy objects or is still managed by an EntityManager.
 By default, serializing proxy objects does not initialize them. On
 unserialization, resulting objects are detached from the entity
-manager and cannot be initialiazed anymore. You can implement the
+manager and cannot be initialized anymore. You can implement the
 ``__serialize()`` method if you want to change that behavior, but
 then you need to ensure that you won't generate large serialized
 object graphs and take care of circular associations.

docs/en/reference/association-mapping.rst

@@ -870,8 +870,8 @@ This is essentially the same as the following, more verbose, mapping:
              * @var Collection<int, Group>
              */
             #[JoinTable(name: 'User_Group')]
-            #[JoinColumn(name: 'User_id', referencedColumnName: 'id')]
-            #[InverseJoinColumn(name: 'Group_id', referencedColumnName: 'id')]
+            #[JoinColumn(name: 'user_id', referencedColumnName: 'id')]
+            #[InverseJoinColumn(name: 'group_id', referencedColumnName: 'id')]
             #[ManyToMany(targetEntity: Group::class)]
             private Collection $groups;
             // ...
@@ -884,10 +884,10 @@ This is essentially the same as the following, more verbose, mapping:
                 <many-to-many field="groups" target-entity="Group">
                     <join-table name="User_Group">
                         <join-columns>
-                            <join-column id="User_id" referenced-column-name="id" />
+                            <join-column id="user_id" referenced-column-name="id" />
                         </join-columns>
                         <inverse-join-columns>
-                            <join-column id="Group_id" referenced-column-name="id" />
+                            <join-column id="group_id" referenced-column-name="id" />
                         </inverse-join-columns>
                     </join-table>
                 </many-to-many>
@@ -903,8 +903,7 @@ defaults to "id", just as in one-to-one or many-to-one mappings.
 
 Additionally, when using typed properties with Doctrine 2.9 or newer
 you can skip ``targetEntity`` in ``ManyToOne`` and ``OneToOne``
-associations as they will be set based on type. Also ``nullable``
-attribute on ``JoinColumn`` will be inherited from PHP type. So that:
+associations as they will be set based on type. So that:
 
 .. configuration-block::
 
@@ -931,7 +930,7 @@ Is essentially the same as following:
         <?php
         /** One Product has One Shipment. */
         #[OneToOne(targetEntity: Shipment::class)]
-        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id', nullable: false)]
+        #[JoinColumn(name: 'shipment_id', referencedColumnName: 'id')]
         private Shipment $shipment;
 
     .. code-block:: annotation
@@ -940,7 +939,7 @@ Is essentially the same as following:
         /**
          * One Product has One Shipment.
          * @OneToOne(targetEntity="Shipment")
-         * @JoinColumn(name="shipment_id", referencedColumnName="id", nullable=false)
+         * @JoinColumn(name="shipment_id", referencedColumnName="id")
          */
         private Shipment $shipment;
 
@@ -949,7 +948,7 @@ Is essentially the same as following:
         <doctrine-mapping>
             <entity class="Product">
                 <one-to-one field="shipment" target-entity="Shipment">
-                    <join-column name="shipment_id" referenced-column-name="id" nulable=false />
+                    <join-column name="shipment_id" referenced-column-name="id" nullable=false />
                 </one-to-one>
             </entity>
         </doctrine-mapping>

docs/en/reference/attributes-reference.rst

@@ -15,7 +15,7 @@ Index
 -  :ref:`#[AttributeOverride] <attrref_attributeoverride>`
 -  :ref:`#[Column] <attrref_column>`
 -  :ref:`#[Cache] <attrref_cache>`
--  :ref:`#[ChangeTrackingPolicy <attrref_changetrackingpolicy>`
+-  :ref:`#[ChangeTrackingPolicy] <attrref_changetrackingpolicy>`
 -  :ref:`#[CustomIdGenerator] <attrref_customidgenerator>`
 -  :ref:`#[DiscriminatorColumn] <attrref_discriminatorcolumn>`
 -  :ref:`#[DiscriminatorMap] <attrref_discriminatormap>`
@@ -175,6 +175,10 @@ 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``.
 
@@ -214,12 +218,15 @@ Optional parameters:
    -  ``check``: Adds a check constraint type to the column (might not
       be supported by all vendors).
 
--  **columnDefinition**: DDL SQL snippet that starts after the column
+-  **columnDefinition**: Specify the DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
    This attribute allows to make use of advanced RMDBS features.
-   However you should make careful use of this feature and the
-   consequences. ``SchemaTool`` will not detect changes on the column correctly
-   anymore if you use ``columnDefinition``.
+   However, as this needs to be specified in the DDL native to the database,
+   the resulting schema changes are no longer portable. If you specify a
+   ``columnDefinition``, the ``SchemaTool`` ignores all other attributes
+   that are normally used to build the definition DDL. Changes to the
+   ``columnDefinition`` are not detected, you will need to manually create a
+   migration to apply changes.
 
    Additionally you should remember that the ``type``
    attribute still handles the conversion between PHP and Database
@@ -242,6 +249,9 @@ 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;
 
@@ -262,10 +272,11 @@ Examples:
     )]
     protected $loginCount;
 
-    // MySQL example: full_name char(41) GENERATED ALWAYS AS (concat(firstname,' ',lastname)),
+    // columnDefinition is raw SQL, not DQL. This example works for MySQL:
     #[Column(
         type: "string",
         name: "user_fullname",
+        columnDefinition: "VARCHAR(255) GENERATED ALWAYS AS (concat(firstname,' ',lastname))",
         insertable: false,
         updatable: false
     )]
@@ -366,7 +377,7 @@ Optional parameters:
 
 -  **type**: By default this is string.
 -  **length**: By default this is 255.
--  **columnDefinition**: By default this is null the definition according to the type will be used. This option allows to override it.
+-  **columnDefinition**: Allows to override how the column is generated. See the "columnDefinition" attribute on :ref:`#[Column] <attrref_column>`
 -  **enumType**: By default this is `null`. Allows to map discriminatorColumn value to PHP enum
 -  **options**: See "options" attribute on :ref:`#[Column] <attrref_column>`.
 
@@ -657,11 +668,6 @@ 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
@@ -672,13 +678,16 @@ 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)
 -  **columnDefinition**: DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
-   This attribute enables the use of advanced RMDBS features. Using
-   this attribute on ``#[JoinColumn]`` is necessary if you need slightly
+   This attribute enables the use of advanced RMDBS features. Note that you
+   need to reference columns by their database name (either explicitly set in
+   the mapping or per the current :doc:`naming strategy <namingstrategy>`).
+   Using this attribute on ``#[JoinColumn]`` is necessary if you need
    different column definitions for joining columns, for example
    regarding NULL/NOT NULL defaults. However by default a
    "columnDefinition" attribute on :ref:`#[Column] <attrref_column>` also sets
@@ -1133,7 +1142,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

@@ -167,6 +167,7 @@ Here is a complete list of ``Column``s attributes (all optional):
 - ``nullable`` (default: ``false``): Whether the column is nullable.
 - ``insertable`` (default: ``true``): Whether the column should be inserted.
 - ``updatable`` (default: ``true``): Whether the column should be updated.
+- ``generated`` (default: ``null``): Whether the generated strategy should be ``'NEVER'``, ``'INSERT'`` and ``ALWAYS``.
 - ``enumType`` (requires PHP 8.1 and ``doctrine/orm`` 2.11): The PHP enum class name to convert the database value into.
 - ``precision`` (default: 0): The precision for a decimal (exact numeric) column
   (applies only for decimal column),
@@ -181,6 +182,37 @@ Here is a complete list of ``Column``s attributes (all optional):
 - ``options``: Key-value pairs of options that get passed
   to the underlying database platform when generating DDL statements.
 
+Specifying default values
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+While it is possible to specify default values for properties in your
+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
+
+   .. literalinclude:: basic-mapping/default-values.xml
+       :language: xml
+
 .. _reference-php-mapping-types:
 
 PHP Types Mapping
@@ -213,6 +245,8 @@ 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``.
 
@@ -223,55 +257,81 @@ and a custom ``Doctrine\ORM\Mapping\TypedFieldMapper`` implementation.
 
 :doc:`Read more about TypedFieldMapper <typedfieldmapper>`.
 
+Property Hooks
+--------------
+
+.. versionadded:: 3.4
+
+Doctrine supports mapping hooked properties as long as they have a backed property
+and are not virtual.
+
+
+.. configuration-block::
+
+    .. code-block:: attribute
+
+        <?php
+        use Doctrine\ORM\Mapping\Column;
+        use Doctrine\DBAL\Types\Types;
+
+        #[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);
+
+                // Override the "write" action with arbitrary logic.
+                set {
+                    $this->language = strtolower($value);
+                }
+            }
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="Message">
+            <field name="id" type="integer" />
+            <field name="language" />
+          </entity>
+        </doctrine-mapping>
+
+If you attempt to map a virtual property with ``#[Column]`` an exception will be thrown.
+
+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.
+
+.. 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
+
+    $query = $queryBuilder->getQuery();
+    $result = $query->getResult();
+
+    $messageRepository = $entityManager->getRepository(Message::class);
+    $deMessages = $messageRepository->findBy(['language' => 'de']); // Use lower case here for raw value representation
+
 .. _reference-mapping-types:
 
 Doctrine Mapping Types
 ----------------------
 
-The ``type`` option used in the ``@Column`` accepts any of the existing
-Doctrine types or even your own custom types. A Doctrine type defines
+The ``type`` option used in the ``@Column`` accepts any of the
+`existing Doctrine DBAL types <https://docs.doctrine-project.org/projects/doctrine-dbal/en/stable/reference/types.html#reference>`_
+or :doc:`your own custom mapping types
+<../cookbook/custom-mapping-types>`. A Doctrine type defines
 the conversion between PHP and SQL types, independent from the database vendor
-you are using. All Mapping Types that ship with Doctrine are fully portable
-between the supported database systems.
-
-As an example, the Doctrine Mapping Type ``string`` defines the
-mapping from a PHP string to a SQL VARCHAR (or VARCHAR2 etc.
-depending on the RDBMS brand). Here is a quick overview of the
-built-in mapping types:
-
--  ``string``: Type that maps a SQL VARCHAR to a PHP string.
--  ``integer``: Type that maps a SQL INT to a PHP integer.
--  ``smallint``: Type that maps a database SMALLINT to a PHP
-   integer.
--  ``bigint``: Type that maps a database BIGINT to a PHP string.
--  ``boolean``: Type that maps a SQL boolean or equivalent (TINYINT) to a PHP boolean.
--  ``decimal``: Type that maps a SQL DECIMAL to a PHP string.
--  ``date``: Type that maps a SQL DATETIME to a PHP DateTime
-   object.
--  ``time``: Type that maps a SQL TIME to a PHP DateTime object.
--  ``datetime``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
-   DateTime object.
--  ``datetimetz``: Type that maps a SQL DATETIME/TIMESTAMP to a PHP
-   DateTime object with timezone.
--  ``text``: Type that maps a SQL CLOB to a PHP string.
--  ``object``: Type that maps a SQL CLOB to a PHP object using
-   ``serialize()`` and ``unserialize()``
--  ``array``: Type that maps a SQL CLOB to a PHP array using
-   ``serialize()`` and ``unserialize()``
--  ``simple_array``: Type that maps a SQL CLOB to a PHP array using
-   ``implode()`` and ``explode()``, with a comma as delimiter. *IMPORTANT*
-   Only use this type if you are sure that your values cannot contain a ",".
--  ``json_array``: Type that maps a SQL CLOB to a PHP array using
-   ``json_encode()`` and ``json_decode()``
--  ``float``: Type that maps a SQL Float (Double Precision) to a
-   PHP double. *IMPORTANT*: Works only with locale settings that use
-   decimal points as separator.
--  ``guid``: Type that maps a database GUID/UUID to a PHP string. Defaults to
-   varchar but uses a specific type if the platform supports it.
--  ``blob``: Type that maps a SQL BLOB to a PHP resource stream
-
-A cookbook article shows how to define :doc:`your own custom mapping types
-<../cookbook/custom-mapping-types>`.
+you are using.
 
 .. note::
 
@@ -360,17 +420,19 @@ Here is the list of possible generation strategies:
 
 -  ``AUTO`` (default): Tells Doctrine to pick the strategy that is
    preferred by the used database platform. The preferred strategies
-   are ``IDENTITY`` for MySQL, SQLite, MsSQL and SQL Anywhere and, for
-   historical reasons, ``SEQUENCE`` for Oracle and PostgreSQL. This
-   strategy provides full portability.
+   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.
 -  ``IDENTITY``: Tells Doctrine to use special identity columns in
    the database that generate a value on insertion of a row. This
    strategy does currently not provide full portability and is
    supported by the following platforms: MySQL/SQLite/SQL Anywhere
-   (``AUTO_INCREMENT``), MSSQL (``IDENTITY``) and PostgreSQL (``SERIAL``).
+   (``AUTO_INCREMENT``), MSSQL (``IDENTITY``) and PostgreSQL (``SERIAL``
+   on DBAL 3, ``GENERATED BY DEFAULT AS IDENTITY`` on DBAL 4).
 -  ``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.
 -  ``NONE``: Tells Doctrine that the identifiers are assigned (and
    thus generated) by your code. The assignment must take place before

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

@@ -0,0 +1,20 @@
+<?php
+
+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;
+
+#[Entity]
+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/default-values.xml

@@ -0,0 +1,16 @@
+<doctrine-mapping>
+  <entity name="Message">
+    <field name="text">
+      <options>
+        <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/configuration.rst

@@ -56,7 +56,8 @@ access point to ORM functionality provided by Doctrine.
         'dbname'   => 'foo',
     ];
 
-    $config = ORMSetup::createAttributeMetadataConfiguration($paths, $isDevMode);
+    $config = ORMSetup::createAttributeMetadataConfig($paths, $isDevMode);
+    // on PHP < 8.4, use ORMSetup::createAttributeMetadataConfiguration() instead
     $connection = DriverManager::getConnection($dbParams, $config);
     $entityManager = new EntityManager($connection, $config);
 
@@ -66,7 +67,8 @@ Or if you prefer XML:
 
     <?php
     $paths = ['/path/to/xml-mappings'];
-    $config = ORMSetup::createXMLMetadataConfiguration($paths, $isDevMode);
+    $config = ORMSetup::createXMLMetadataConfig($paths, $isDevMode);
+    // on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration() instead
     $connection = DriverManager::getConnection($dbParams, $config);
     $entityManager = new EntityManager($connection, $config);
 

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 WITH u.email = b.email');
+    $query = $em->createQuery('SELECT u FROM User u JOIN Banlist b ON 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,16 +513,46 @@ 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 and HAVING clauses may be
+    The differences between WHERE, WITH, ON and HAVING clauses may be
     confusing.
 
     - WHERE is applied to the results of an entire query
-    - 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
+    - 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.
     - HAVING is applied to the results of a query after
       aggregation (GROUP BY)
 
+
+Partial Hydration 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
+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``
+DQL keyword:
+
+.. code-block:: php
+
+    <?php
+    $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:
+
+.. 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
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -560,7 +590,101 @@ 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
 
-Note that you can only pass scalar expressions to the constructor.
+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'}
 
 Using INDEX BY
 ~~~~~~~~~~~~~~
@@ -976,7 +1100,7 @@ The Query class
 ---------------
 
 An instance of the ``Doctrine\ORM\Query`` class represents a DQL
-query. You create a Query instance be calling
+query. You create a Query instance by calling
 ``EntityManager#createQuery($dql)``, passing the DQL query string.
 Alternatively you can create an empty ``Query`` instance and invoke
 ``Query#setDQL($dql)`` afterwards. Here are some examples:
@@ -993,58 +1117,146 @@ Alternatively you can create an empty ``Query`` instance and invoke
     $q = $em->createQuery();
     $q->setDQL('select u from MyProject\Model\User u');
 
-Query Result Formats
-~~~~~~~~~~~~~~~~~~~~
+Query Result Formats (Hydration Modes)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The format in which the result of a DQL SELECT query is returned
-can be influenced by a so-called ``hydration mode``. A hydration
-mode specifies a particular way in which a SQL result set is
-transformed. Each hydration mode has its own dedicated method on
-the Query class. Here they are:
+The way in which the SQL result set of a DQL SELECT query is transformed
+to PHP is determined by the so-called "hydration mode".
 
+``getResult()``
+^^^^^^^^^^^^^^^
 
--  ``Query#getResult()``: Retrieves a collection of objects. The
-   result is either a plain collection of objects (pure) or an array
-   where the objects are nested in the result rows (mixed).
--  ``Query#getSingleResult()``: Retrieves a single object. If the
-   result contains more than one object, an ``NonUniqueResultException``
-   is thrown. If the result contains no objects, an ``NoResultException``
-   is thrown. The pure/mixed distinction does not apply.
--  ``Query#getOneOrNullResult()``: Retrieve a single object. If the
-   result contains more than one object, a ``NonUniqueResultException``
-   is thrown. If no object is found null will be returned.
--  ``Query#getArrayResult()``: Retrieves an array graph (a nested
-   array) that is largely interchangeable with the object graph
-   generated by ``Query#getResult()`` for read-only purposes.
+Retrieves a collection of objects. The result is either a plain collection of objects (pure) or an array
+where the objects are nested in the result rows (mixed):
 
-    .. note::
+.. code-block:: php
 
-        An array graph can differ from the corresponding object
-        graph in certain scenarios due to the difference of the identity
-        semantics between arrays and objects.
+    <?php
+    use Doctrine\ORM\AbstractQuery;
 
+    $query = $em->createQuery('SELECT u FROM User u');
+    $users = $query->getResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_OBJECT);
 
+- Objects fetched in a FROM clause are returned as a Set, that means every
+  object is only ever included in the resulting array once. This is the case
+  even when using JOIN or GROUP BY in ways that return the same row for an
+  object multiple times. If the hydrator sees the same object multiple times,
+  then it makes sure it is only returned once.
 
--  ``Query#getScalarResult()``: Retrieves a flat/rectangular result
-   set of scalar values that can contain duplicate data. The
-   pure/mixed distinction does not apply.
--  ``Query#getSingleScalarResult()``: Retrieves a single scalar
-   value from the result returned by the dbms. If the result contains
-   more than a single scalar value, an exception is thrown. The
-   pure/mixed distinction does not apply.
+- If an object is already in memory from a previous query of any kind, then
+  then the previous object is used, even if the database may contain more
+  recent data. This even happens if the previous object is still an unloaded proxy.
 
-Instead of using these methods, you can alternatively use the
-general-purpose method
-``Query#execute(array $params = [], $hydrationMode = Query::HYDRATE_OBJECT)``.
-Using this method you can directly supply the hydration mode as the
-second parameter via one of the Query constants. In fact, the
-methods mentioned earlier are just convenient shortcuts for the
-execute method. For example, the method ``Query#getResult()``
-internally invokes execute, passing in ``Query::HYDRATE_OBJECT`` as
-the hydration mode.
+``getArrayResult()``
+^^^^^^^^^^^^^^^^^^^^
 
-The use of the methods mentioned earlier is generally preferred as
-it leads to more concise code.
+Retrieves an array graph (a nested array) for read-only purposes.
+
+.. note::
+
+    An array graph can differ from the corresponding object
+    graph in certain scenarios due to the difference of the identity
+    semantics between arrays and objects.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getArrayResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_ARRAY);
+
+``getScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a flat/rectangular result set of scalar values that can contain duplicate data. The
+pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $users = $query->getScalarResult();
+    // same as:
+    $users = $query->getResult(AbstractQuery::HYDRATE_SCALAR);
+
+Fields from classes are prefixed by the DQL alias in the result.
+A query of the kind `SELECT u.name ...` returns a key `u_name` in the result rows.
+
+``getSingleScalarResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single scalar value from the result returned by the database. If the result contains
+more than a single scalar value, a ``NonUniqueResultException`` is thrown. The pure/mixed distinction does not apply.
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT COUNT(u.id) FROM User u');
+    $numUsers = $query->getSingleScalarResult();
+    // same as:
+    $numUsers = $query->getResult(AbstractQuery::HYDRATE_SINGLE_SCALAR);
+
+``getSingleColumnResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves an array from a one-dimensional array of scalar values:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT a.id FROM User u');
+    $ids = $query->getSingleColumnResult();
+    // same as:
+    $ids = $query->getResult(AbstractQuery::HYDRATE_SCALAR_COLUMN);
+
+``getSingleResult()``
+^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If the result contains no objects, a ``NoResultException`` is thrown. The pure/mixed distinction does not apply.
+
+``getOneOrNullResult()``
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves a single object. If the result contains more than one object, a ``NonUniqueResultException``
+is thrown. If no object is found, ``null`` will be returned.
+
+Custom Hydration Modes
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can easily add your own custom hydration modes by first
+creating a class which extends ``AbstractHydrator``:
+
+.. code-block:: php
+
+    <?php
+    namespace MyProject\Hydrators;
+
+    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
+
+    class CustomHydrator extends AbstractHydrator
+    {
+        protected function _hydrateAll()
+        {
+            return $this->_stmt->fetchAllAssociative();
+        }
+    }
+
+Next you just need to add the class to the ORM configuration:
+
+.. code-block:: php
+
+    <?php
+    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
+
+Now the hydrator is ready to be used in your queries:
+
+.. code-block:: php
+
+    <?php
+    $query = $em->createQuery('SELECT u FROM CmsUser u');
+    $results = $query->getResult('CustomHydrator');
 
 Pure and Mixed Results
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -1148,165 +1360,6 @@ will return the rows iterating the different top-level entities.
         [2] => Object (User)
         [3] => Object (Group)
 
-
-Hydration Modes
-~~~~~~~~~~~~~~~
-
-Each of the Hydration Modes makes assumptions about how the result
-is returned to user land. You should know about all the details to
-make best use of the different result formats:
-
-The constants for the different hydration modes are:
-
-
--  ``Query::HYDRATE_OBJECT``
--  ``Query::HYDRATE_ARRAY``
--  ``Query::HYDRATE_SCALAR``
--  ``Query::HYDRATE_SINGLE_SCALAR``
--  ``Query::HYDRATE_SCALAR_COLUMN``
-
-Object Hydration
-^^^^^^^^^^^^^^^^
-
-Object hydration hydrates the result set into the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_OBJECT);
-
-Sometimes the behavior in the object hydrator can be confusing, which is
-why we are listing as many of the assumptions here for reference:
-
-- Objects fetched in a FROM clause are returned as a Set, that means every
-  object is only ever included in the resulting array once. This is the case
-  even when using JOIN or GROUP BY in ways that return the same row for an
-  object multiple times. If the hydrator sees the same object multiple times,
-  then it makes sure it is only returned once.
-
-- If an object is already in memory from a previous query of any kind, then
-  then the previous object is used, even if the database may contain more
-  recent data. Data from the database is discarded. This even happens if the
-  previous object is still an unloaded proxy.
-
-This list might be incomplete.
-
-Array Hydration
-^^^^^^^^^^^^^^^
-
-You can run the same query with array hydration and the result set
-is hydrated into an array that represents the object graph:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_ARRAY);
-
-You can use the ``getArrayResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $users = $query->getArrayResult();
-
-Scalar Hydration
-^^^^^^^^^^^^^^^^
-
-If you want to return a flat rectangular result set instead of an
-object graph you can use scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $users = $query->getResult(Query::HYDRATE_SCALAR);
-    echo $users[0]['u_id'];
-
-The following assumptions are made about selected fields using
-Scalar Hydration:
-
-
-1. Fields from classes are prefixed by the DQL alias in the result.
-   A query of the kind 'SELECT u.name ..' returns a key 'u_name' in
-   the result rows.
-
-Single Scalar Hydration
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a query which returns just a single scalar value you can use
-single scalar hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT COUNT(a.id) FROM CmsUser u LEFT JOIN u.articles a WHERE u.username = ?1 GROUP BY u.id');
-    $query->setParameter(1, 'jwage');
-    $numArticles = $query->getResult(Query::HYDRATE_SINGLE_SCALAR);
-
-You can use the ``getSingleScalarResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $numArticles = $query->getSingleScalarResult();
-
-Scalar Column Hydration
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you have a query which returns a one-dimensional array of scalar values
-you can use scalar column hydration:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT a.id FROM CmsUser u');
-    $ids = $query->getResult(Query::HYDRATE_SCALAR_COLUMN);
-
-You can use the ``getSingleColumnResult()`` shortcut as well:
-
-.. code-block:: php
-
-    <?php
-    $ids = $query->getSingleColumnResult();
-
-Custom Hydration Modes
-^^^^^^^^^^^^^^^^^^^^^^
-
-You can easily add your own custom hydration modes by first
-creating a class which extends ``AbstractHydrator``:
-
-.. code-block:: php
-
-    <?php
-    namespace MyProject\Hydrators;
-
-    use Doctrine\ORM\Internal\Hydration\AbstractHydrator;
-
-    class CustomHydrator extends AbstractHydrator
-    {
-        protected function _hydrateAll()
-        {
-            return $this->_stmt->fetchAllAssociative();
-        }
-    }
-
-Next you just need to add the class to the ORM configuration:
-
-.. code-block:: php
-
-    <?php
-    $em->getConfiguration()->addCustomHydrationMode('CustomHydrator', 'MyProject\Hydrators\CustomHydrator');
-
-Now the hydrator is ready to be used in your queries:
-
-.. code-block:: php
-
-    <?php
-    $query = $em->createQuery('SELECT u FROM CmsUser u');
-    $results = $query->getResult('CustomHydrator');
-
 Iterating Large Result Sets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1358,8 +1411,7 @@ Result Cache API:
 
     $query->setResultCacheDriver(new ApcCache());
 
-    $query->useResultCache(true)
-          ->setResultCacheLifeTime(3600);
+    $query->enableResultCache(3600);
 
     $result = $query->getResult(); // cache miss
 
@@ -1369,8 +1421,8 @@ Result Cache API:
     $query->setResultCacheId('my_query_result');
     $result = $query->getResult(); // saved in given result cache id.
 
-    // or call useResultCache() with all parameters:
-    $query->useResultCache(true, 3600, 'my_query_result');
+    // or call enableResultCache() with all parameters:
+    $query->enableResultCache(3600, 'my_query_result');
     $result = $query->getResult(); // cache hit!
 
     // Introspection
@@ -1395,6 +1447,15 @@ exist mostly internal query hints that are not be consumed in
 userland. However the following few hints are to be used in
 userland:
 
+
+-  ``Query::HINT_FORCE_PARTIAL_LOAD`` - Allows to hydrate objects
+   although not all their columns are fetched. This query hint can be
+   used to handle memory consumption problems with large result-sets
+   that contain char or binary data. Doctrine has no way of implicitly
+   reloading this data. Partially loaded objects have to be passed to
+   ``EntityManager::refresh()`` if they are to be reloaded fully from
+   the database. This query hint is deprecated and will be removed
+   in the future (\ `Details <https://github.com/doctrine/orm/issues/8471>`_)
 -  ``Query::HINT_REFRESH`` - This query is used internally by
    ``EntityManager::refresh()`` and can be used in userland as well.
    If you specify this hint and a query returns the data for an entity
@@ -1639,18 +1700,26 @@ From, Join and Index by
     SubselectIdentificationVariableDeclaration ::= IdentificationVariableDeclaration
     RangeVariableDeclaration                   ::= AbstractSchemaName ["AS"] AliasIdentificationVariable
     JoinAssociationDeclaration                 ::= JoinAssociationPathExpression ["AS"] AliasIdentificationVariable [IndexBy]
-    Join                                       ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN" (JoinAssociationDeclaration | RangeVariableDeclaration) ["WITH" ConditionalExpression]
+    Join                                       ::= ["LEFT" ["OUTER"] | "INNER"] "JOIN" (JoinAssociationDeclaration ["WITH" ConditionalExpression] | RangeVariableDeclaration [("ON" | "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 | "(" Subselect ")" | CaseExpression | NewObjectExpression) [["AS"] ["HIDDEN"] AliasResultVariable]
-    SimpleSelectExpression  ::= (StateFieldPathExpression | IdentificationVariable | FunctionDeclaration | AggregateExpression | "(" Subselect ")" | ScalarExpression) [["AS"] AliasResultVariable]
-    NewObjectExpression     ::= "NEW" AbstractSchemaName "(" NewObjectArg {"," NewObjectArg}* ")"
-    NewObjectArg            ::= ScalarExpression | "(" Subselect ")"
+    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
 
 Conditional Expressions
 ~~~~~~~~~~~~~~~~~~~~~~~

docs/en/reference/events.rst

@@ -265,7 +265,7 @@ specific to a particular entity class's lifecycle.
         <?xml version="1.0" encoding="UTF-8"?>
 
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
             <entity name="User">

docs/en/reference/faq.rst

@@ -18,30 +18,6 @@ In your mapping configuration, the column definition (for example, the
 the ``charset`` and ``collation``. The default values are ``utf8`` and
 ``utf8_unicode_ci``, respectively.
 
-Entity Classes
---------------
-
-How can I add default values to a column?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Doctrine does not support to set the default values in columns through the "DEFAULT" keyword in SQL.
-This is not necessary however, you can just use your class properties as default values. These are then used
-upon insert:
-
-.. code-block:: php
-
-    class User
-    {
-        private const STATUS_DISABLED = 0;
-        private const STATUS_ENABLED = 1;
-
-        private string $algorithm = "sha1";
-        /** @var self::STATUS_* */
-        private int $status = self::STATUS_DISABLED;
-    }
-
-.
-
 Mapping
 -------
 

docs/en/reference/filters.rst

@@ -30,7 +30,7 @@ table alias of the SQL table of the entity.
 
 For the filter to correctly function, the following rules must be followed. Failure to do so will lead to unexpected results from the query cache.
   1. Parameters for the query should be set on the filter object by ``SQLFilter#setParameter()`` before the filter is used by the ORM ( i.e. do not set parameters inside ``SQLFilter#addFilterConstraint()`` function ).
-  2. The filter must be deterministic. Don't change the values base on external inputs.
+  2. The filter must be deterministic. Don't change the values based on external inputs.
 
 The ``SQLFilter#getParameter()`` function takes care of the proper quoting of parameters.
 

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 need not have an ``#[Id]`` property.
+are not query-able, and do not require 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,22 @@ Example:
             // ...
         }
 
+    .. code-block:: xml
+
+        <doctrine-mapping>
+          <entity name="MyProject\Model\Person" inheritance-type="SINGLE_TABLE">
+            <discriminator-column name="discr" type="string" />
+            <discriminator-map>
+                <discriminator-mapping value="person" class="MyProject\Model\Person"/>
+                <discriminator-mapping value="employee" class="MyProject\Model\Employee"/>
+            </discriminator-map>
+          </entity>
+        </doctrine-mapping>
+
+        <doctrine-mapping>
+            <entity name="MyProject\Model\Employee">
+            </entity>
+        </doctrine-mapping>
 
 In this example, the ``#[DiscriminatorMap]`` specifies that in the
 discriminator column, a value of "person" identifies a row as being of type

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

@@ -178,6 +178,14 @@ internally by the ORM currently refers to fields by their name only, without tak
 class containing the field into consideration. This makes it impossible to keep separate
 mapping configuration for both fields.
 
+Apart from that, in the case of having multiple ``private`` fields of the same name within
+the class hierarchy an entity or mapped superclass, the Collection filtering API cannot determine
+the right field to look at. Even if only one of these fields is actually mapped, the ``ArrayCollection``
+will not be able to tell, since it does not have access to any metadata.
+
+Thus, to avoid problems in this regard, it is best to avoid having multiple ``private`` fields of the
+same name in class hierarchies containing entity and mapped superclasses.
+
 Known Issues
 ------------
 

docs/en/reference/metadata-drivers.rst

@@ -70,8 +70,8 @@ implements the ``MappingDriver`` interface:
         /**
          * Loads the metadata for the specified class into the provided container.
          *
-         * @psalm-param class-string<T> $className
-         * @psalm-param ClassMetadata<T> $metadata
+         * @param class-string<T> $className
+         * @param ClassMetadata<T> $metadata
          *
          * @return void
          *
@@ -82,8 +82,7 @@ implements the ``MappingDriver`` interface:
         /**
          * Gets the names of all mapped classes known to this driver.
          *
-         * @return array<int, string> The names of all mapped classes known to this driver.
-         * @psalm-return list<class-string>
+         * @return list<class-string> The names of all mapped classes known to this driver.
          */
         public function getAllClassNames();
 
@@ -91,7 +90,7 @@ implements the ``MappingDriver`` interface:
          * Returns whether the class with the specified name should have its metadata loaded.
          * This is only the case if it is either mapped as an Entity or a MappedSuperclass.
          *
-         * @psalm-param class-string $className
+         * @param class-string $className
          *
          * @return bool
          */

docs/en/reference/partial-hydration.rst

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,88 @@
+Partial Objects
+===============
+
+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.
+
+.. note::
+
+    The partial object problem in general does not apply to
+    methods or queries where you do not retrieve the query result as
+    objects. Examples are: ``Query#getArrayResult()``,
+    ``Query#getScalarResult()``, ``Query#getSingleScalarResult()``,
+    etc.
+
+.. warning::
+
+    Use of partial objects is tricky. Fields that are not retrieved
+    from the database will not be updated by the UnitOfWork even if they
+    get changed in your objects. You can only promote a partial object
+    to a fully-loaded object by calling ``EntityManager#refresh()``
+    or a DQL query with the refresh flag.
+
+
+What is the problem?
+--------------------
+
+In short, partial objects are problematic because they are usually
+objects with broken invariants. As such, code that uses these
+partial objects tends to be very fragile and either needs to "know"
+which fields or methods can be safely accessed or add checks around
+every field access or method invocation. The same holds true for
+the internals, i.e. the method implementations, of such objects.
+You usually simply assume the state you need in the method is
+available, after all you properly constructed this object before
+you pushed it into the database, right? These blind assumptions can
+quickly lead to null reference errors when working with such
+partial objects.
+
+It gets worse with the scenario of an optional association (0..1 to
+1). When the associated field is NULL, you don't know whether this
+object does not have an associated object or whether it was simply
+not loaded when the owning object was loaded from the database.
+
+These are reasons why many ORMs do not allow partial objects at all
+and instead you always have to load an object with all its fields
+(associations being proxied). One secure way to allow partial
+objects is if the programming language/platform allows the ORM tool
+to hook deeply into the object and instrument it in such a way that
+individual fields (not only associations) can be loaded lazily on
+first access. This is possible in Java, for example, through
+bytecode instrumentation. In PHP though this is not possible, so
+there is no way to have "secure" partial objects in an ORM with
+transparent persistence.
+
+Doctrine, by default, does not allow partial objects. That means,
+any query that only selects partial object data and wants to
+retrieve the result as objects (i.e. ``Query#getResult()``) will
+raise an exception telling you that partial objects are dangerous.
+If you want to force a query to return you partial objects,
+possibly as a performance tweak, you can use the ``partial``
+keyword as follows:
+
+.. code-block:: php
+
+    <?php
+    $q = $em->createQuery("select partial u.{id,name} from MyApp\Domain\User u");
+
+You can also get a partial reference instead of a proxy reference by
+calling:
+
+.. code-block:: php
+
+    <?php
+    $reference = $em->getPartialReference('MyApp\Domain\User', 1);
+
+Partial references are objects with only the identifiers set as they
+are passed to the second argument of the ``getPartialReference()`` method.
+All other fields are null.
+
+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

@@ -209,6 +209,7 @@ 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 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:
+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:
 
 .. code-block:: php
 
@@ -355,9 +355,8 @@ a querybuilder instance into a Query object:
     // $qb instanceof QueryBuilder
     $query = $qb->getQuery();
 
-    // Set additional Query options
-    $query->setQueryHint('foo', 'bar');
-    $query->useResultCache('my_cache_id');
+    // Enable the result cache
+    $query->enableResultCache(3600, 'my_custom_id');
 
     // Execute Query
     $result = $query->getResult();
@@ -555,6 +554,24 @@ 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
 ^^^^^^^^^^^^^
 
@@ -611,3 +628,21 @@ 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

@@ -44,7 +44,7 @@ Something like below for an entity region:
 
 
 If the entity holds a collection that also needs to be cached.
-An collection region could look something like:
+A collection region could look something like:
 
 .. code-block:: php
 
@@ -133,7 +133,7 @@ Caching mode
   * Read Write cache employs locks before update/delete.
   * Use if data needs to be updated.
   * Slowest strategy.
-  * To use it a the cache region implementation must support locking.
+  * To use it the cache region implementation must support locking.
 
 
 Built-in cached persisters
@@ -299,7 +299,7 @@ level cache region.
 
         <?xml version="1.0" encoding="utf-8"?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="Country">
@@ -351,7 +351,7 @@ It caches the primary keys of association and cache each element will be cached
 
         <?xml version="1.0" encoding="utf-8"?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
           <entity name="State">
@@ -518,7 +518,7 @@ DELETE / UPDATE queries
 DQL UPDATE / DELETE statements are ported directly into a database and bypass
 the second-level cache.
 Entities that are already cached will NOT be invalidated.
-However the cached data could be evicted using the cache API or an special query hint.
+However the cached data could be evicted using the cache API or a special query hint.
 
 
 Execute the ``UPDATE`` and invalidate ``all cache entries`` using ``Query::HINT_CACHE_EVICT``

docs/en/reference/security.rst

@@ -118,7 +118,7 @@ entity might look like this:
         }
     }
 
-Now the possiblity of mass-assignment exists on this entity and can
+Now the possibility of mass-assignment exists on this entity and can
 be exploited by attackers to set the "isAdmin" flag to true on any
 object when you pass the whole request data to this method like:
 

docs/en/reference/tools.rst

@@ -22,7 +22,7 @@ have to register them yourself.
 All the commands of the Doctrine Console require access to the
 ``EntityManager``. You have to inject it into the console application.
 
-Here is an example of a the project-specific ``bin/doctrine`` binary.
+Here is an example of a project-specific ``bin/doctrine`` binary.
 
 .. code-block:: php
 
@@ -84,7 +84,7 @@ The following Commands are currently available:
 -  ``orm:clear-cache:result`` Clear result cache of the various
    cache drivers.
 -  ``orm:generate-proxies`` Generates proxy classes for entity
-   classes.
+   classes. Deprecated in favor of using native lazy objects.
 -  ``orm:run-dql`` Executes arbitrary DQL directly from the command
    line.
 -  ``orm:schema-tool:create`` Processes the schema and either
@@ -96,6 +96,10 @@ 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:
 

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

@@ -88,7 +88,7 @@ requirement.
 
 A more convenient alternative for explicit transaction demarcation is the use
 of provided control abstractions in the form of
-``Connection#transactional($func)`` and ``EntityManager#transactional($func)``.
+``Connection#transactional($func)`` and ``EntityManager#wrapInTransaction($func)``.
 When used, these control abstractions ensure that you never forget to rollback
 the transaction, in addition to the obvious code reduction. An example that is
 functionally equivalent to the previously shown code looks as follows:
@@ -96,21 +96,23 @@ functionally equivalent to the previously shown code looks as follows:
 .. code-block:: php
 
     <?php
+    // transactional with Connection instance
+    // $conn instanceof Connection
+    $conn->transactional(function($conn) {
+        // ... do some work
+        $user = new User;
+        $user->setName('George');
+    });
+
+    // transactional with EntityManager instance
     // $em instanceof EntityManager
-    $em->transactional(function($em) {
+    $em->wrapInTransaction(function($em) {
         // ... do some work
         $user = new User;
         $user->setName('George');
         $em->persist($user);
     });
 
-.. warning::
-
-    For historical reasons, ``EntityManager#transactional($func)`` will return
-    ``true`` whenever the return value of ``$func`` is loosely false.
-    Some examples of this include ``array()``, ``"0"``, ``""``, ``0``, and
-    ``null``.
-
 The difference between ``Connection#transactional($func)`` and
 ``EntityManager#transactional($func)`` is that the latter
 abstraction flushes the ``EntityManager`` prior to transaction

docs/en/reference/unitofwork.rst

@@ -102,7 +102,7 @@ How Doctrine Detects Changes
 ----------------------------
 
 Doctrine is a data-mapper that tries to achieve persistence-ignorance (PI).
-This means you map php objects into a relational database that don't
+This means you map PHP objects into a relational database that don't
 necessarily know about the database at all. A natural question would now be,
 "how does Doctrine even detect objects have changed?".
 

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

@@ -736,6 +736,35 @@ methods:
 
 .. note::
 
-    There is a limitation on the compatibility of Criteria comparisons.
-    You have to use scalar values only as the value in a comparison or
-    the behaviour between different backends is not the same.
+    Depending on whether the collection has already been loaded from the
+    database or not, criteria matching may happen at the database/SQL level
+    or on objects in memory. This may lead to different results and come
+    surprising, for example when a code change in one place leads to a collection
+    becoming initialized and, as a side effect, returning a different result
+    or even breaking a ``matching()`` call somewhere else. Also, collection
+    initialization state in practical use cases may differ from the one covered
+    in unit tests.
+
+    Database level comparisons are based on scalar representations of the values
+    stored in entity properties. The field names passed to expressions correspond
+    to property names. Comparison and sorting may be affected by
+    database-specific behavior. For example, MySQL enum types sort by index position,
+    not lexicographically by value.
+
+    In-memory handling is based on the ``Selectable`` API of `Doctrine Collections <https://www.doctrine-project.org/projects/doctrine-collections/en/stable/index.html#matching>`.
+    In this case, field names passed to expressions are being used to derive accessor
+    method names. Strict type comparisons are used for equal and not-equal checks,
+    and generally PHP language rules are being used for other comparison operators
+    or sorting.
+
+    As a general guidance, for consistent results use the Criteria API with scalar
+    values only. Note that ``DateTime`` and ``DateTimeImmutable`` are two predominant
+    examples of value objects that are *not* scalars.
+
+    Refrain from using special database-level column types or custom Doctrine Types
+    that may lead to database-specific comparison or sorting rules being applied, or
+    to database-level values being different from object field values.
+
+    Provide accessor methods for all entity fields used in criteria expressions,
+    and implement those methods in a way that their return value is the
+    same as the database-level value.

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
-    to heavily. Make sure to use DQL to fetch-join all the parts of the
+    too heavily. Make sure to use DQL to fetch-join all the parts of the
     object-graph that you need as efficiently as possible.
 
 
@@ -338,10 +338,11 @@ Performance of different deletion strategies
 Deleting an object with all its associated objects can be achieved
 in multiple ways with very different performance impacts.
 
-1. If an association is marked as ``CASCADE=REMOVE`` Doctrine ORM
-   will fetch this association. If its a Single association it will
-   pass this entity to
-   ``EntityManager#remove()``. If the association is a collection, Doctrine will loop over all    its elements and pass them to``EntityManager#remove()``.
+1. If an association is marked as ``CASCADE=REMOVE`` Doctrine ORM will
+   fetch this association. If it's a Single association it will pass
+   this entity to ``EntityManager#remove()``. If the association is a
+   collection, Doctrine will loop over all its elements and pass them to
+   ``EntityManager#remove()``.
    In both cases the cascade remove semantics are applied recursively.
    For large object graphs this removal strategy can be very costly.
 2. Using a DQL ``DELETE`` statement allows you to delete multiple

docs/en/reference/xml-mapping.rst

@@ -18,7 +18,7 @@ setup for the latest code in trunk.
 .. code-block:: xml
 
     <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -46,7 +46,7 @@ In order to work, this requires certain conventions:
 .. code-block:: php
 
     <?php
-    $driver->setFileExtension('.xml');
+    $driver->getLocator()->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
@@ -104,7 +104,7 @@ of several common elements:
     // Doctrine.Tests.ORM.Mapping.User.dcm.xml
     <?xml version="1.0" encoding="UTF-8"?>
     <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -112,7 +112,6 @@ of several common elements:
 
             <indexes>
                 <index name="name_idx" columns="name"/>
-                <index columns="user_email"/>
             </indexes>
 
             <unique-constraints>
@@ -131,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" column-definition="CHAR(32) NOT NULL" />
+            <field name="email" column="user_email" type="string" index="true" column-definition="CHAR(32) NOT NULL" />
 
             <one-to-one field="address" target-entity="Address" inversed-by="user">
                 <cascade><cascade-remove /></cascade>
@@ -255,6 +254,8 @@ 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.
@@ -770,7 +771,7 @@ entity relationship. You can define this in XML with the "association-key" attri
 .. code-block:: xml
 
     <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 

docs/en/sidebar.rst

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

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

@@ -54,7 +54,7 @@ and year of production as primary keys:
 
         <?xml version="1.0" encoding="UTF-8"?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -85,11 +85,12 @@ And for querying you can use arrays to both DQL and EntityRepositories:
     namespace VehicleCatalogue\Model;
 
     // $em is the EntityManager
-    $audi = $em->find("VehicleCatalogue\Model\Car", array("name" => "Audi A8", "year" => 2010));
+    $audi = $em->find("VehicleCatalogue\Model\Car", ["name" => "Audi A8", "year" => 2010]);
 
-    $dql = "SELECT c FROM VehicleCatalogue\Model\Car c WHERE c.id = ?1";
+    $dql = "SELECT c FROM VehicleCatalogue\Model\Car c WHERE c.name = ?1 AND c.year = ?2";
     $audi = $em->createQuery($dql)
-               ->setParameter(1, ["name" => "Audi A8", "year" => 2010])
+               ->setParameter(1, "Audi A8")
+               ->setParameter(2, 2010)
                ->getSingleResult();
 
 You can also use this entity in associations. Doctrine will then generate two foreign keys one for ``name``
@@ -145,7 +146,7 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
             #[OneToMany(targetEntity: ArticleAttribute::class, mappedBy: 'article', cascade: ['ALL'], indexBy: 'attribute')]
             private Collection $attributes;
 
-            public function addAttribute(string $name, ArticleAttribute $value): void
+            public function addAttribute(string $name, string $value): void
             {
                 $this->attributes[$name] = new ArticleAttribute($name, $value, $this);
             }
@@ -174,7 +175,7 @@ We keep up the example of an Article with arbitrary attributes, the mapping look
     .. code-block:: xml
 
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -249,7 +250,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");
@@ -294,6 +295,7 @@ 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/extra-lazy-associations.rst

@@ -17,7 +17,9 @@ 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)``
 
 For each of the above methods the following semantics apply:
@@ -69,7 +71,7 @@ switch to extra lazy as shown in these examples:
 
         <?xml version="1.0" encoding="UTF-8"?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 

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

@@ -1,26 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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 7.1+ that provides transparent persistence for PHP objects. It uses the Data Mapper
+for PHP 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,8 +49,9 @@ An entity contains persistable properties. A persistable property
 is an instance variable of the entity that is saved into and retrieved from the database
 by Doctrine's data mapping capabilities.
 
-An entity class must not be final nor read-only, although
-it can contain final methods or read-only properties.
+An 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 Example Model: Bug Tracker
 -----------------------------
@@ -138,13 +139,13 @@ step:
     require_once "vendor/autoload.php";
 
     // Create a simple "default" Doctrine ORM configuration for Attributes
-    $config = ORMSetup::createAttributeMetadataConfiguration(
-        paths: array(__DIR__."/src"),
+    $config = ORMSetup::createAttributeMetadataConfig( // on PHP < 8.4, use ORMSetup::createAttributeMetadataConfiguration()
+        paths: [__DIR__ . '/src'],
         isDevMode: true,
     );
     // or if you prefer XML
-    // $config = ORMSetup::createXMLMetadataConfiguration(
-    //    paths: array(__DIR__."/config/xml"),
+    // $config = ORMSetup::createXMLMetadataConfig( // on PHP < 8.4, use ORMSetup::createXMLMetadataConfiguration()
+    //    paths: [__DIR__ . '/config/xml'],
     //    isDevMode: true,
     //);
 
@@ -514,7 +515,7 @@ methods, but you only need to choose one.
 
         <!-- config/xml/Product.dcm.xml -->
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -534,7 +535,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:
@@ -1023,7 +1024,7 @@ the ``Product`` before:
 
         <!-- config/xml/Bug.dcm.xml -->
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -1103,7 +1104,7 @@ Finally, we'll add metadata mappings for the ``User`` entity.
 
         <!-- config/xml/User.dcm.xml -->
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-                          xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+                          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                           xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                               https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 
@@ -1287,7 +1288,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.
 
 
@@ -1586,7 +1587,7 @@ we have to adjust the metadata slightly.
     .. code-block:: xml
 
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 

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

@@ -9,7 +9,7 @@ i.e. attributes and associations metadata in particular. The example here shows
 the overriding of a class that uses a trait but is similar when extending a base
 class as shown at the end of this tutorial.
 
-Suppose we have a class ExampleEntityWithOverride. This class uses trait ExampleTrait:
+Suppose we have a class ``ExampleEntityWithOverride``. This class uses trait ``ExampleTrait``:
 
 .. code-block:: php
 
@@ -17,22 +17,20 @@ Suppose we have a class ExampleEntityWithOverride. This class uses trait Example
 
     #[Entity]
     #[AttributeOverrides([
-        new AttributeOverride('foo', [
-            'column' => new Column([
-                'name' => 'foo_overridden',
-                'type' => 'integer',
-                'length' => 140,
-                'nullable' => false,
-                'unique' => false,
-            ]),
-        ]),
+        new AttributeOverride('foo', new Column(
+            name: 'foo_overridden',
+            type: 'integer',
+            length: 140,
+            nullable: false,
+            unique: false,
+        )),
     ])]
     #[AssociationOverrides([
         new AssociationOverride('bar', [
-            'joinColumns' => new JoinColumn([
-                'name' => 'example_entity_overridden_bar_id',
-                'referencedColumnName' => 'id',
-            ]),
+            new JoinColumn(
+                name: 'example_entity_overridden_bar_id',
+                referencedColumnName: 'id',
+            ),
         ]),
     ])]
     class ExampleEntityWithOverride
@@ -47,7 +45,7 @@ Suppose we have a class ExampleEntityWithOverride. This class uses trait Example
         private $id;
     }
 
-The docblock is showing metadata override of the attribute and association type. It
+``#[AttributeOverrides]`` contains metadata override of the attribute and association type. It
 basically changes the names of the columns mapped for a property ``foo`` and for
 the association ``bar`` which relates to Bar class shown above. Here is the trait
 which has mapping metadata that is overridden by the attribute above:

docs/en/tutorials/pagination.rst

@@ -1,6 +1,41 @@
 Pagination
 ==========
 
+Doctrine ORM provides two pagination strategies for DQL queries. Both handle
+the low-level SQL plumbing, but they make different trade-offs:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Feature
+     - Offset ``Paginator``
+     - ``CursorPaginator``
+   * - Total count
+     - Yes
+     - No
+   * - Random access to page N
+     - Yes
+     - No
+   * - Stable under concurrent inserts/deletes
+     - No
+     - Yes
+   * - Performance on deep pages
+     - Degrades (OFFSET scan)
+     - Constant (index range scan)
+   * - Requires deterministic ORDER BY
+     - No
+     - Yes
+
+Choose the **Offset Paginator** when you need a total page count or want to
+let users jump to an arbitrary page number.
+
+Choose the **Cursor Paginator** when you need stable, high-performance
+pagination on large datasets and a simple previous/next navigation is
+sufficient.
+
+Offset-Based Pagination
+-----------------------
+
 Doctrine ORM ships with a Paginator for DQL queries. It
 has a very simple API and implements the SPL interfaces ``Countable`` and
 ``IteratorAggregate``.
@@ -58,3 +93,178 @@ In this way the `DISTINCT` keyword will be omitted and can bring important perfo
                            ->setHint(Paginator::HINT_ENABLE_DISTINCT, false)
                            ->setFirstResult(0)
                            ->setMaxResults(100);
+
+Cursor-Based Pagination
+-----------------------
+
+Doctrine ORM ships with a ``CursorPaginator`` for cursor-based pagination of DQL queries.
+Unlike offset-based pagination, cursor pagination uses opaque pointers (cursors) derived
+from the last seen row to fetch the next or previous page. This makes it stable and
+performant on large datasets — no matter how deep you paginate, the database always uses
+an index range scan instead of skipping rows.
+
+.. note::
+
+    Cursor pagination requires a **deterministic ``ORDER BY`` clause**. Every column
+    combination used for sorting must uniquely identify a position in the result set.
+    A common pattern is to sort by a timestamp and then by primary key as a tie-breaker.
+
+Basic Usage
+~~~~~~~~~~~
+
+The ``$cursor`` parameter is an opaque string produced by a previous call to
+``getNextCursorAsString()`` or ``getPreviousCursorAsString()``. On the first request
+it is ``null`` or an empty string ``''`` — both are treated identically as the first
+page. It is typically read from the incoming HTTP query string:
+
+.. code-block:: php
+
+    $cursor = $_GET['cursor'] ?? null; // null or '' on the first page
+
+.. code-block:: php
+
+    <?php
+    use Doctrine\ORM\Tools\CursorPagination\CursorPaginator;
+
+    $dql = 'SELECT p FROM BlogPost p ORDER BY p.createdAt DESC, p.id DESC';
+    $query = $entityManager->createQuery($dql);
+
+    $paginator = (new CursorPaginator($query))
+        ->paginate(cursor: $cursor, limit: 15);
+
+    foreach ($paginator as $post) {
+        echo $post->getTitle() . "\n";
+    }
+
+    echo $paginator->getPreviousCursorAsString(); // previous encoded cursor string
+    echo $paginator->getNextCursorAsString();     // next encoded cursor string
+
+Navigating Pages
+~~~~~~~~~~~~~~~~
+
+Pass the encoded cursor back on subsequent requests to move forward or backward:
+
+.. code-block:: php
+
+    <?php
+    // Next page
+    $paginator->paginate(15, $nextCursor);
+
+    // Previous page
+    $paginator->paginate(15, $previousCursor);
+
+The cursor is an encoded string containing the location at which the next query should begin fetching results, along with the navigation direction.
+
+API Reference
+~~~~~~~~~~~~~
+
+``CursorPaginator::paginate(?string $cursor, int $limit): self``
+    Executes the query and stores the results. Fetches ``$limit + 1`` rows to
+    detect whether a further page exists, then trims the extra row. Returns
+    ``$this`` for chaining.
+
+``CursorPaginator::getNextCursor(): Cursor``
+    Returns the ``Cursor`` object for the next page. Throws a ``LogicException``
+    if there is no next page — call ``hasNextPage()`` first.
+
+``CursorPaginator::getPreviousCursor(): Cursor``
+    Returns the ``Cursor`` object for the previous page. Throws a ``LogicException``
+    if there is no previous page — call ``hasPreviousPage()`` first.
+
+``CursorPaginator::getNextCursorAsString(): string``
+    Returns the encoded cursor to retrieve the next page. Throws a
+    ``LogicException`` if there is no next page — call ``hasNextPage()`` first.
+
+``CursorPaginator::getPreviousCursorAsString(): string``
+    Returns the encoded cursor to retrieve the previous page. Throws a
+    ``LogicException`` if there is no previous page — call ``hasPreviousPage()`` first.
+
+``CursorPaginator::hasNextPage(): bool``
+    Returns whether a next page is available.
+
+``CursorPaginator::hasPreviousPage(): bool``
+    Returns whether a previous page is available.
+
+``CursorPaginator::hasToPaginate(): bool``
+    Returns whether either a next or previous page exists (i.e. the result
+    set spans more than one page).
+
+``CursorPaginator::getValues(): array``
+    Returns the raw entity array for the current page.
+
+``CursorPaginator::getItems(): array``
+    Returns an array of ``CursorItem`` objects, each wrapping an entity and its
+    individual ``Cursor``. Useful when you need per-row cursors.
+
+``CursorPaginator::getCursorForItem(mixed $item, bool $isNext = true): Cursor``
+    Builds a ``Cursor`` pointing at a specific entity. ``$isNext = true`` means
+    "start *after* this item"; ``false`` means "start *before* this item".
+
+``CursorPaginator::count(): int``
+    Returns the number of items on the current page (implements ``Countable``).
+
+**Next page**
+
+.. code-block:: sql
+
+    SELECT ...
+    FROM   post p
+    WHERE  (p.created_at < :cursor_val_0)
+       OR  (p.created_at = :cursor_val_0 AND p.id < :cursor_id_1)
+    ORDER  BY p.created_at DESC, p.id DESC
+    LIMIT  16   -- limit + 1
+
+**Previous page**
+
+.. code-block:: sql
+
+    SELECT ...
+    FROM   post p
+    WHERE  (p.created_at > :cursor_val_0)
+       OR  (p.created_at = :cursor_val_0 AND p.id > :cursor_id_1)
+    ORDER  BY p.created_at ASC, p.id ASC   -- reversed
+    LIMIT  16
+
+HTML Template Example
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example shows how to render a paginated list with previous/next
+navigation links using the ``CursorPaginator`` in a PHP template:
+
+.. literalinclude:: pagination/cursor-pagination.php
+   :language: php
+
+Cursor Encoding
+~~~~~~~~~~~~~~~
+
+A cursor is serialized to a URL-safe string via ``Cursor::encodeToString()`` and
+deserialized back via the static ``Cursor::fromEncodedString()``. The format is a
+JSON object encoded with URL-safe Base64 (no padding):
+
+.. code-block:: json
+
+    {
+        "p.createdAt": "2024-01-15T10:30:00+00:00",
+        "p.id": 42,
+        "_isNext": true
+    }
+
+The ``_isNext`` flag distinguishes next-page cursors from previous-page cursors.
+All other keys are the DQL path expressions (``alias.field``) of the ``ORDER BY``
+columns, and their values are the database representations of the pivot row's
+field values.
+
+If you need a different serialization format (e.g. encryption), build it on top of
+a ``Cursor`` instance: call ``$cursor->toArray()`` to get the raw data, apply your
+own encoding, and reconstruct with ``new Cursor($parameters, $isNext)``.
+
+Limitations
+~~~~~~~~~~~
+
+- Every ``ORDER BY`` column must map to an entity field. Raw SQL expressions or
+  computed columns in ``ORDER BY`` are not supported.
+- ``COUNT`` queries are not available; cursor pagination does not know the total
+  number of results by design. If you need a total count, use the
+  offset-based ``Paginator`` described above.
+- The query must have at least one ``ORDER BY`` item; the paginator throws a
+  ``LogicException`` otherwise.

docs/en/tutorials/pagination/cursor-pagination.php

@@ -0,0 +1,31 @@
+<?php
+
+use Doctrine\ORM\Tools\CursorPagination\CursorPaginator;
+
+$cursor = $_GET['cursor'] ?? null;
+
+$query = $entityManager->createQuery('SELECT p FROM BlogPost p ORDER BY p.createdAt DESC, p.id DESC');
+
+/** @var CursorPaginator<BlogPost> $paginator */
+$paginator = (new CursorPaginator($query))
+    ->paginate(cursor: $cursor, limit: 15);
+?>
+<p><?= $paginator->count() ?> result(s) on this page.</p>
+
+<ul>
+    <?php foreach ($paginator as $post): ?>
+        <li><?= escape($post->getTitle()) ?></li>
+    <?php endforeach ?>
+</ul>
+
+<?php if ($paginator->hasToPaginate()): ?>
+    <nav>
+        <?php if ($paginator->hasPreviousPage()): ?>
+            <a href="?cursor=<?= escape($paginator->getPreviousCursorAsString()) ?>">Previous</a>
+        <?php endif ?>
+
+        <?php if ($paginator->hasNextPage()): ?>
+            <a href="?cursor=<?= escape($paginator->getNextCursorAsString()) ?>">Next</a>
+        <?php endif ?>
+    </nav>
+<?php endif ?>

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

@@ -29,83 +29,11 @@ You can map indexed associations by adding:
 The code and mappings for the Market entity looks like this:
 
 .. configuration-block::
-    .. code-block:: attribute
+    .. literalinclude:: working-with-indexed-associations/Market.php
+        :language: attribute
 
-        <?php
-        namespace Doctrine\Tests\Models\StockExchange;
-
-        use Doctrine\Common\Collections\ArrayCollection;
-        use Doctrine\Common\Collections\Collection;
-
-        #[Entity]
-        #[Table(name: 'exchange_markets')]
-        class Market
-        {
-            #[Id, Column(type: 'integer'), GeneratedValue]
-            private int|null $id = null;
-
-            #[Column(type: 'string')]
-            private string $name;
-
-            /** @var Collection<string, Stock> */
-            #[OneToMany(targetEntity: Stock::class, mappedBy: 'market', indexBy: 'symbol')]
-            private Collection $stocks;
-
-            public function __construct(string $name)
-            {
-                $this->name = $name;
-                $this->stocks = new ArrayCollection();
-            }
-
-            public function getId(): int|null
-            {
-                return $this->id;
-            }
-
-            public function getName(): string
-            {
-                return $this->name;
-            }
-
-            public function addStock(Stock $stock): void
-            {
-                $this->stocks[$stock->getSymbol()] = $stock;
-            }
-
-            public function getStock(string $symbol): Stock
-            {
-                if (!isset($this->stocks[$symbol])) {
-                    throw new \InvalidArgumentException("Symbol is not traded on this market.");
-                }
-
-                return $this->stocks[$symbol];
-            }
-
-            /** @return array<string, Stock> */
-            public function getStocks(): array
-            {
-                return $this->stocks->toArray();
-            }
-        }
-
-    .. code-block:: xml
-
-        <?xml version="1.0" encoding="UTF-8"?>
-        <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
-                                  https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
-
-            <entity name="Doctrine\Tests\Models\StockExchange\Market">
-                <id name="id" type="integer">
-                    <generator strategy="AUTO" />
-                </id>
-
-                <field name="name" type="string"/>
-
-                <one-to-many target-entity="Stock" mapped-by="market" field="stocks" index-by="symbol" />
-            </entity>
-        </doctrine-mapping>
+    .. literalinclude:: working-with-indexed-associations/market.xml
+        :language: xml
 
 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)``
@@ -150,7 +78,7 @@ here are the code and mappings for it:
 
         <?xml version="1.0" encoding="UTF-8"?>
         <doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
-              xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                                   https://www.doctrine-project.org/schemas/orm/doctrine-mapping.xsd">
 

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

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

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

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

doctrine-mapping.xsd

@@ -155,10 +155,20 @@
     </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="unbounded">
-      <xs:element name="option" type="orm:option"/>
-      <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
+    <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>
     <xs:attribute name="name" type="xs:NMTOKEN" use="required"/>
     <xs:anyAttribute namespace="##other"/>
@@ -243,6 +253,7 @@
     <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" />
@@ -321,7 +332,7 @@
     <xs:choice minOccurs="0" maxOccurs="unbounded">
       <xs:any minOccurs="0" maxOccurs="unbounded" namespace="##other"/>
     </xs:choice>
-    <xs:attribute name="value" type="xs:NMTOKEN" use="required"/>
+    <xs:attribute name="value" type="orm:type" use="required"/>
     <xs:attribute name="class" type="orm:fqcn" use="required"/>
     <xs:anyAttribute namespace="##other"/>
   </xs:complexType>

phpcs.xml.dist

@@ -1,5 +1,7 @@
 <?xml version="1.0"?>
-<ruleset>
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         name="PHP_CodeSniffer"
+         xsi:noNamespaceSchemaLocation="vendor/squizlabs/php_codesniffer/phpcs.xsd">
     <arg name="basepath" value="."/>
     <arg name="extensions" value="php"/>
     <arg name="parallel" value="80"/>
@@ -14,7 +16,6 @@
     <file>src</file>
     <file>tests</file>
 
-    <exclude-pattern>*/src/Mapping/InverseJoinColumn.php</exclude-pattern>
     <exclude-pattern>*/tests/Tests/Proxies/__CG__*</exclude-pattern>
     <exclude-pattern>*/tests/Tests/ORM/Tools/Export/export/*</exclude-pattern>
 
@@ -49,6 +50,10 @@
     </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/Persisters/SqlValueVisitorImplementation.php</exclude-pattern>
+        <exclude-pattern>src/PersistentCollectionImplementation.php</exclude-pattern>
         <exclude-pattern>tests/*</exclude-pattern>
     </rule>
 

phpstan-dbal3.neon

@@ -3,6 +3,13 @@ includes:
     - phpstan-params.neon
 
 parameters:
+    reportUnmatchedIgnoredErrors: false # Some errors in the baseline only apply to DBAL 4
+    excludePaths:
+        # Compatibility shims for Collections 2 vs Collections 3
+        # These have intentional signature mismatches that cannot be resolved
+        - src/PersistentCollectionImplementation.php
+        - src/Persisters/SqlValueVisitorImplementation.php
+
     ignoreErrors:
         # Symfony cache supports passing a key prefix to the clear method.
         - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
@@ -10,24 +17,159 @@ parameters:
         # We can be certain that those values are not matched.
         -
             message: '~^Match expression does not handle remaining values:~'
-            path: src/Persisters/Entity/BasicEntityPersister.php
+            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: '~^Method Doctrine\\ORM\\Persisters\\Entity\\BasicEntityPersister\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Persisters/Entity/BasicEntityPersister.php
 
         -
-            message: '~^Unreachable statement \- code above always terminates\.$~'
-            path: src/Mapping/AssociationMapping.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
+
+        # Methods used by excluded compatibility shim traits
+        -
+            message: '#^Method .* is unused\.$#'
+            paths:
+                - src/PersistentCollection.php
+                - src/Persisters/SqlValueVisitor.php

phpstan-params.neon

@@ -1,5 +1,5 @@
 parameters:
-    level: 5
+    level: 7
     paths:
         - src
         - tests/StaticAnalysis
@@ -8,4 +8,4 @@ parameters:
     earlyTerminatingMethodCalls:
         Doctrine\ORM\Query\Parser:
             - syntaxError
-    phpVersion: 80200
+    phpVersion: 80400

phpstan.neon

@@ -3,6 +3,12 @@ includes:
     - phpstan-params.neon
 
 parameters:
+    excludePaths:
+        # Compatibility shims for Collections 2 vs Collections 3
+        # These have intentional signature mismatches that cannot be resolved
+        - src/PersistentCollectionImplementation.php
+        - src/Persisters/SqlValueVisitorImplementation.php
+
     ignoreErrors:
         # Symfony cache supports passing a key prefix to the clear method.
         - '/^Method Psr\\Cache\\CacheItemPoolInterface\:\:clear\(\) invoked with 1 parameter, 0 required\.$/'
@@ -10,19 +16,19 @@ parameters:
         # We can be certain that those values are not matched.
         -
             message: '~^Match expression does not handle remaining values:~'
-            path: src/Persisters/Entity/BasicEntityPersister.php
+            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: '~^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\\Persisters\\Entity\\BasicEntityPersister\:\:getArrayBindingType\(\) never returns .* so it can be removed from the return type\.$~'
-            path: src/Persisters/Entity/BasicEntityPersister.php
-
-        -
-            message: '~^Unreachable statement \- code above always terminates\.$~'
-            path: src/Mapping/AssociationMapping.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
@@ -37,7 +43,7 @@ parameters:
             path: src/UnitOfWork.php
 
         -
-            message: '~^Parameter #1 \$command of method Symfony\\Component\\Console\\Application::add\(\) expects Symfony\\Component\\Console\\Command\\Command, Doctrine\\DBAL\\Tools\\Console\\Command\\ReservedWordsCommand given\.$~'
+            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
 
         -
@@ -49,3 +55,15 @@ parameters:
             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
+
+        # Methods used by excluded compatibility shim traits
+        -
+            message: '#^Method .* is unused\.$#'
+            paths:
+                - src/PersistentCollection.php
+                - src/Persisters/SqlValueVisitor.php

phpunit.xml.dist

@@ -14,6 +14,8 @@
 <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"
@@ -67,5 +69,12 @@
         <var name="privileged_db_port" value="3306"/>
         -->
         <env name="COLUMNS" value="120"/>
+        <env name="DOCTRINE_DEPRECATIONS" value="trigger"/>
     </php>
+
+    <source ignoreSuppressionOfDeprecations="true">
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
 </phpunit>

psalm.xml

@@ -1,245 +0,0 @@
-<?xml version="1.0"?>
-<psalm
-    errorLevel="2"
-    phpVersion="8.2"
-    resolveFromConfigFile="true"
-    findUnusedBaselineEntry="true"
-    findUnusedCode="false"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xmlns="https://getpsalm.org/schema/config"
-    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
-    errorBaseline="psalm-baseline.xml"
->
-    <projectFiles>
-        <directory name="src" />
-        <directory name="tests/StaticAnalysis" />
-        <ignoreFiles>
-            <directory name="vendor" />
-            <file name="src/Mapping/Driver/AttributeReader.php" />
-        </ignoreFiles>
-    </projectFiles>
-    <enableExtensions>
-        <extension name="simplexml" />
-    </enableExtensions>
-    <issueHandlers>
-        <DeprecatedClass>
-            <errorLevel type="suppress">
-                <!-- We wire the command as long as DBAL ships it -->
-                <referencedClass name="Doctrine\DBAL\Tools\Console\Command\ReservedWordsCommand" />
-                <!-- Remove on 3.0.x -->
-                <referencedClass name="Doctrine\ORM\Event\LifecycleEventArgs"/>
-                <referencedClass name="Doctrine\ORM\Exception\UnknownEntityNamespace"/>
-                <referencedClass name="Doctrine\ORM\Mapping\Driver\AnnotationDriver"/>
-                <referencedClass name="Doctrine\ORM\Mapping\Driver\YamlDriver"/>
-                <referencedClass name="Doctrine\ORM\Mapping\NamedNativeQueries"/>
-                <referencedClass name="Doctrine\ORM\Mapping\NamedNativeQuery"/>
-                <referencedClass name="Doctrine\ORM\Mapping\NamedQueries"/>
-                <referencedClass name="Doctrine\ORM\Mapping\NamedQuery"/>
-                <referencedClass name="Doctrine\ORM\Query\AST\InExpression"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Command\ConvertDoctrine1SchemaCommand"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Command\ConvertMappingCommand"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Command\EnsureProductionSettingsCommand"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Command\GenerateEntitiesCommand"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Command\GenerateRepositoriesCommand"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper"/>
-                <referencedClass name="Doctrine\ORM\Tools\Console\EntityManagerProvider\HelperSetManagerProvider"/>
-            </errorLevel>
-        </DeprecatedClass>
-        <DeprecatedMethod>
-            <errorLevel type="suppress">
-                <!-- Remove on 3.0.x -->
-                <!-- Compatibility with DBAL 3 -->
-                <referencedMethod name="Doctrine\DBAL\Connection::getEventManager"/>
-                <file name="src/Query/TreeWalkerChain.php"/>
-            </errorLevel>
-        </DeprecatedMethod>
-        <DocblockTypeContradiction>
-            <errorLevel type="suppress">
-                <!-- We're catching invalid input here. -->
-                <file name="src/Internal/Hydration/AbstractHydrator.php"/>
-
-                <!-- DBAL 3.2 forward compatibility -->
-                <file name="src/Tools/Pagination/CountOutputWalker.php"/>
-                <file name="src/Tools/Pagination/LimitSubqueryOutputWalker.php"/>
-                <!-- https://github.com/vimeo/psalm/issues/8520 -->
-                <file name="src/PersistentCollection.php"/>
-                <!-- Remove on 4.0.x -->
-                <file name="src/Mapping/Driver/AttributeDriver.php"/>
-                <file name="src/Mapping/Driver/XmlDriver.php"/>
-                <file name="src/ORMSetup.php"/>
-            </errorLevel>
-        </DocblockTypeContradiction>
-        <ForbiddenCode>
-            <errorLevel type="suppress">
-                <file name="src/Tools/Debug.php"/>
-            </errorLevel>
-        </ForbiddenCode>
-        <InvalidArgument>
-            <errorLevel type="suppress">
-                <referencedFunction name="Doctrine\ORM\Mapping\ClassMetadata::addInheritedAssociationMapping"/>
-            </errorLevel>
-        </InvalidArgument>
-        <InvalidArrayAccess>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/9160 -->
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-            </errorLevel>
-        </InvalidArrayAccess>
-        <InvalidArrayAssignment>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/9160 -->
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-            </errorLevel>
-        </InvalidArrayAssignment>
-        <LessSpecificReturnStatement>
-            <errorLevel type="suppress">
-                <!-- In DBAL 4, column precision is nullable. See https://github.com/doctrine/dbal/pull/3511 -->
-                <file name="src/Mapping/Driver/DatabaseDriver.php"/>
-            </errorLevel>
-        </LessSpecificReturnStatement>
-        <MoreSpecificReturnType>
-            <errorLevel type="suppress">
-                <!-- In DBAL 4, the default column value is mixed. See https://github.com/doctrine/dbal/pull/3511 -->
-                <file name="src/Mapping/Driver/DatabaseDriver.php"/>
-            </errorLevel>
-        </MoreSpecificReturnType>
-        <InvalidReturnType>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/8819 -->
-                <file name="src/Internal/Hydration/AbstractHydrator.php"/>
-            </errorLevel>
-        </InvalidReturnType>
-        <InvalidParamDefault>
-            <errorLevel type="suppress">
-                <!-- Remove on 3.0.x -->
-                <file name="src/Query/AST/InstanceOfExpression.php"/>
-            </errorLevel>
-        </InvalidParamDefault>
-        <InvalidPropertyAssignmentValue>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/9155 -->
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-            </errorLevel>
-        </InvalidPropertyAssignmentValue>
-        <MethodSignatureMismatch>
-            <errorLevel type="suppress">
-                <!-- See https://github.com/vimeo/psalm/issues/7357 -->
-                <file name="src/Mapping/ReflectionReadonlyProperty.php"/>
-            </errorLevel>
-        </MethodSignatureMismatch>
-        <MissingParamType>
-            <errorLevel type="suppress">
-                <!-- Persistence 2 compatibility -->
-                <file name="src/EntityManager.php"/>
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-                <file name="src/Mapping/ClassMetadata.php"/>
-            </errorLevel>
-        </MissingParamType>
-        <PossiblyInvalidArgument>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/9155 -->
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-            </errorLevel>
-        </PossiblyInvalidArgument>
-        <PossiblyNullArrayOffset>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/7878 -->
-                <file name="src/Persisters/Collection/ManyToManyPersister.php"/>
-            </errorLevel>
-        </PossiblyNullArrayOffset>
-        <PropertyNotSetInConstructor>
-            <errorLevel type="suppress">
-                <directory name="src/Query/AST" />
-            </errorLevel>
-        </PropertyNotSetInConstructor>
-        <PropertyTypeCoercion>
-            <errorLevel type="suppress">
-                <file name="src/Mapping/ClassMetadata.php"/>
-            </errorLevel>
-        </PropertyTypeCoercion>
-        <RedundantCastGivenDocblockType>
-            <errorLevel type="suppress">
-                <!-- Can be removed once the "getMaxResults" methods of those classes have native parameter types -->
-                <file name="src/Query.php"/>
-                <file name="src/QueryBuilder.php"/>
-            </errorLevel>
-        </RedundantCastGivenDocblockType>
-        <ReferenceConstraintViolation>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/9155 -->
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-            </errorLevel>
-        </ReferenceConstraintViolation>
-        <RiskyTruthyFalsyComparison>
-            <!-- TODO: Enable this new rule on higher branches. -->
-            <errorLevel type="suppress">
-                <directory name="src" />
-            </errorLevel>
-        </RiskyTruthyFalsyComparison>
-        <TooManyArguments>
-            <errorLevel type="suppress">
-                <!-- Symfony cache supports passing a key prefix to the clear method. -->
-                <referencedFunction name="Psr\Cache\CacheItemPoolInterface::clear"/>
-
-                <!-- Persistence 2 compatibility -->
-                <referencedFunction name="Doctrine\Persistence\ObjectManager::clear"/>
-
-                <!-- See https://github.com/doctrine/orm/issues/8850 -->
-                <referencedFunction name="Doctrine\DBAL\Connection::lastInsertId"/>
-
-                <!-- FIXME -->
-                <referencedFunction name="Doctrine\DBAL\DriverManager::getConnection"/>
-            </errorLevel>
-        </TooManyArguments>
-        <TypeDoesNotContainNull>
-            <errorLevel type="suppress">
-                <!-- DBAL 3 compatibility -->
-                <file name="src/Tools/SchemaTool.php"/>
-            </errorLevel>
-        </TypeDoesNotContainNull>
-        <TypeDoesNotContainType>
-            <errorLevel type="suppress">
-                <file name="src/Internal/SQLResultCasing.php"/>
-                <file name="src/Mapping/ClassMetadataFactory.php"/>
-                <!-- DBAL 3 compatibility -->
-                <file name="src/UnitOfWork.php"/>
-                <file name="src/Utility/LockSqlHelper.php"/>
-            </errorLevel>
-        </TypeDoesNotContainType>
-        <UndefinedClass>
-            <errorLevel type="suppress">
-                <!-- Compatibility with DBAL 3 -->
-                <referencedClass name="Doctrine\DBAL\Platforms\SQLitePlatform"/>
-            </errorLevel>
-        </UndefinedClass>
-        <UndefinedMethod>
-            <errorLevel type="suppress">
-                <!-- Compatibility with DBAL 3 -->
-                <referencedMethod name="Doctrine\DBAL\Connection::getEventManager"/>
-                <!-- FIXME -->
-                <referencedMethod name="Doctrine\DBAL\Schema\SchemaDiff::toSaveSql"/>
-            </errorLevel>
-        </UndefinedMethod>
-        <UndefinedPropertyFetch>
-            <errorLevel type="suppress">
-                <!-- https://github.com/vimeo/psalm/issues/7878 -->
-                <file name="src/Persisters/Collection/ManyToManyPersister.php"/>
-                <file name="src/PersistentCollection.php"/>
-                <file name="src/Utility/PersisterHelper.php"/>
-                <file name="src/Tools/SchemaValidator.php"/>
-            </errorLevel>
-        </UndefinedPropertyFetch>
-        <UnhandledMatchCondition>
-            <errorLevel type="suppress">
-                <!-- We can be certain that those values are not matched. -->
-                <file name="src/Persisters/Entity/BasicEntityPersister.php"/>
-            </errorLevel>
-        </UnhandledMatchCondition>
-        <ArgumentTypeCoercion>
-            <errorLevel type="suppress">
-                <!-- See https://github.com/JetBrains/phpstorm-stubs/pull/1383 -->
-                <file name="src/Mapping/ClassMetadata.php"/>
-            </errorLevel>
-        </ArgumentTypeCoercion>
-    </issueHandlers>
-</psalm>

run-all.sh

@@ -1,21 +0,0 @@
-#!/bin/bash
-
-# This script is a small convenience wrapper for running the doctrine testsuite against a large bunch of databases.
-# Just create the phpunit.xmls as described in the array below and configure the specific files <php /> section
-# to connect to that database. Just omit a file if you don't have that database and the tests will be skipped.
-
-configs[1]="mysql.phpunit.xml" 
-configs[2]='postgres.phpunit.xml' 
-configs[3]='sqlite.phpunit.xml'
-configs[4]='oracle.phpunit.xml'
-configs[5]='db2.phpunit.xml'
-configs[6]='pdo-ibm.phpunit.xml'
-configs[7]='sqlsrv.phpunit.xml'
-
-for i in "${configs[@]}"; do
-    if [ -f "$i" ];
-    then
-        echo "RUNNING TESTS WITH CONFIG $i"
-        phpunit -c "$i" "$@" 
-    fi;
-done

src/AbstractQuery.php

@@ -18,7 +18,6 @@ use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\Mapping\MappingException as ORMMappingException;
 use Doctrine\ORM\Proxy\DefaultProxyClassNameResolver;
 use Doctrine\ORM\Query\Parameter;
-use Doctrine\ORM\Query\QueryException;
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\Mapping\MappingException;
 use LogicException;
@@ -83,7 +82,7 @@ abstract class AbstractQuery
      * The parameter map of this query.
      *
      * @var ArrayCollection|Parameter[]
-     * @psalm-var ArrayCollection<int, Parameter>
+     * @phpstan-var ArrayCollection<int, Parameter>
      */
     protected ArrayCollection $parameters;
 
@@ -95,14 +94,14 @@ abstract class AbstractQuery
     /**
      * The map of query hints.
      *
-     * @psalm-var array<string, mixed>
+     * @phpstan-var array<string, mixed>
      */
     protected array $hints = [];
 
     /**
      * The hydration mode.
      *
-     * @psalm-var string|AbstractQuery::HYDRATE_*
+     * @phpstan-var string|AbstractQuery::HYDRATE_*
      */
     protected string|int $hydrationMode = self::HYDRATE_OBJECT;
 
@@ -130,7 +129,7 @@ abstract class AbstractQuery
     /**
      * Second level query cache mode.
      *
-     * @psalm-var Cache::MODE_*|null
+     * @phpstan-var Cache::MODE_*|null
      */
     protected int|null $cacheMode = null;
 
@@ -217,14 +216,14 @@ abstract class AbstractQuery
         return $this;
     }
 
-    /** @psalm-return Cache::MODE_*|null */
+    /** @phpstan-return Cache::MODE_*|null */
     public function getCacheMode(): int|null
     {
         return $this->cacheMode;
     }
 
     /**
-     * @psalm-param Cache::MODE_* $cacheMode
+     * @phpstan-param Cache::MODE_* $cacheMode
      *
      * @return $this
      */
@@ -267,7 +266,7 @@ abstract class AbstractQuery
     /**
      * Get all defined parameters.
      *
-     * @psalm-return ArrayCollection<int, Parameter>
+     * @phpstan-return ArrayCollection<int, Parameter>
      */
     public function getParameters(): ArrayCollection
     {
@@ -286,7 +285,7 @@ abstract class AbstractQuery
         $key = Parameter::normalizeName($key);
 
         $filteredParameters = $this->parameters->filter(
-            static fn (Parameter $parameter): bool => $parameter->getName() === $key
+            static fn (Parameter $parameter): bool => $parameter->getName() === $key,
         );
 
         return ! $filteredParameters->isEmpty() ? $filteredParameters->first() : null;
@@ -296,14 +295,14 @@ abstract class AbstractQuery
      * Sets a collection of query parameters.
      *
      * @param ArrayCollection|mixed[] $parameters
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
+     * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
      *
      * @return $this
      */
     public function setParameters(ArrayCollection|array $parameters): static
     {
         if (is_array($parameters)) {
-            /** @psalm-var ArrayCollection<int, Parameter> $parameterCollection */
+            /** @phpstan-var ArrayCollection<int, Parameter> $parameterCollection */
             $parameterCollection = new ArrayCollection();
 
             foreach ($parameters as $key => $value) {
@@ -642,7 +641,7 @@ abstract class AbstractQuery
      * Change the default fetch mode of an association for this query.
      *
      * @param class-string $class
-     * @psalm-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
+     * @phpstan-param Mapping\ClassMetadata::FETCH_EAGER|Mapping\ClassMetadata::FETCH_LAZY $fetchMode
      */
     public function setFetchMode(string $class, string $assocName, int $fetchMode): static
     {
@@ -656,7 +655,7 @@ abstract class AbstractQuery
      *
      * @param string|int $hydrationMode Doctrine processing mode to be used during hydration process.
      *                                  One of the Query::HYDRATE_* constants.
-     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
+     * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
      *
      * @return $this
      */
@@ -670,7 +669,7 @@ abstract class AbstractQuery
     /**
      * Gets the hydration mode currently used by the query.
      *
-     * @psalm-return string|AbstractQuery::HYDRATE_*
+     * @phpstan-return string|AbstractQuery::HYDRATE_*
      */
     public function getHydrationMode(): string|int
     {
@@ -682,7 +681,7 @@ abstract class AbstractQuery
      *
      * Alias for execute(null, $hydrationMode = HYDRATE_OBJECT).
      *
-     * @psalm-param string|AbstractQuery::HYDRATE_* $hydrationMode
+     * @phpstan-param string|AbstractQuery::HYDRATE_* $hydrationMode
      */
     public function getResult(string|int $hydrationMode = self::HYDRATE_OBJECT): mixed
     {
@@ -728,7 +727,7 @@ abstract class AbstractQuery
     /**
      * Get exactly one result or null.
      *
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @throws NonUniqueResultException
      */
@@ -763,7 +762,7 @@ abstract class AbstractQuery
      * If the result is not unique, a NonUniqueResultException is thrown.
      * If there is no result, a NoResultException is thrown.
      *
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null $hydrationMode
      *
      * @throws NonUniqueResultException If the query result is not unique.
      * @throws NoResultException        If the query returned no result.
@@ -843,8 +842,8 @@ abstract class AbstractQuery
      * Executes the query and returns an iterable that can be used to incrementally
      * iterate over the result.
      *
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[] $parameters
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
+     * @phpstan-param ArrayCollection<int, Parameter>|mixed[] $parameters
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null    $hydrationMode
      *
      * @return iterable<mixed>
      */
@@ -865,10 +864,6 @@ abstract class AbstractQuery
             throw new LogicException('Uninitialized result set mapping.');
         }
 
-        if ($rsm->isMixed && count($rsm->scalarMappings) > 0) {
-            throw QueryException::iterateWithMixedResultNotAllowed();
-        }
-
         $stmt = $this->_doExecute();
 
         return $this->em->newHydrator($this->hydrationMode)->toIterable($stmt, $rsm, $this->hints);
@@ -877,8 +872,8 @@ abstract class AbstractQuery
     /**
      * Executes the query.
      *
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
+     * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      */
     public function execute(
         ArrayCollection|array|null $parameters = null,
@@ -894,8 +889,8 @@ abstract class AbstractQuery
     /**
      * Execute query ignoring second level cache.
      *
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
+     * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      */
     private function executeIgnoreQueryCache(
         ArrayCollection|array|null $parameters = null,
@@ -965,8 +960,8 @@ abstract class AbstractQuery
     /**
      * Load from second level cache or executes the query and put into cache.
      *
-     * @psalm-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
-     * @psalm-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
+     * @phpstan-param ArrayCollection<int, Parameter>|mixed[]|null $parameters
+     * @phpstan-param string|AbstractQuery::HYDRATE_*|null         $hydrationMode
      */
     private function executeUsingQueryCache(
         ArrayCollection|array|null $parameters = null,
@@ -1029,7 +1024,7 @@ abstract class AbstractQuery
      * automatically generated for you.
      *
      * @return string[] ($key, $hash)
-     * @psalm-return array{string, string} ($key, $hash)
+     * @phpstan-return array{string, string} ($key, $hash)
      */
     protected function getHydrationCacheId(): array
     {
@@ -1070,7 +1065,7 @@ abstract class AbstractQuery
     }
 
     /**
-     * Executes the query and returns a the resulting Statement object.
+     * Executes the query and returns the resulting Statement object.
      *
      * @return Result|int The executed database statement that holds
      *                    the results, or an integer indicating how

src/Cache/CollectionCacheKey.php

@@ -22,18 +22,21 @@ class CollectionCacheKey extends CacheKey
     public readonly array $ownerIdentifier;
 
     /**
+     * @param class-string         $entityClass     The owner entity class.
      * @param array<string, mixed> $ownerIdentifier The identifier of the owning entity.
-     * @param class-string         $entityClass     The owner entity class
      */
     public function __construct(
         public readonly string $entityClass,
         public readonly string $association,
         array $ownerIdentifier,
+        string $filterHash = '',
     ) {
         ksort($ownerIdentifier);
 
         $this->ownerIdentifier = $ownerIdentifier;
 
-        parent::__construct(str_replace('\\', '.', strtolower($entityClass)) . '_' . implode(' ', $ownerIdentifier) . '__' . $association);
+        $filterHash = $filterHash === '' ? '' : '_' . $filterHash;
+
+        parent::__construct(str_replace('\\', '.', strtolower($entityClass)) . '_' . implode(' ', $ownerIdentifier) . '__' . $association . $filterHash);
     }
 }

src/Cache/DefaultCache.php

@@ -25,7 +25,7 @@ class DefaultCache implements Cache
 
     /**
      * @var QueryCache[]
-     * @psalm-var array<string, QueryCache>
+     * @phpstan-var array<string, QueryCache>
      */
     private array $queryCaches = [];
 

src/Cache/DefaultQueryCache.php

@@ -16,6 +16,7 @@ use Doctrine\ORM\Mapping\ClassMetadata;
 use Doctrine\ORM\PersistentCollection;
 use Doctrine\ORM\Query;
 use Doctrine\ORM\Query\ResultSetMapping;
+use Doctrine\ORM\Query\SqlWalker;
 use Doctrine\ORM\UnitOfWork;
 
 use function array_map;
@@ -210,6 +211,10 @@ class DefaultQueryCache implements QueryCache
             throw FeatureNotImplemented::nonSelectStatements();
         }
 
+        if (($hints[SqlWalker::HINT_PARTIAL] ?? false) === true || ($hints[Query::HINT_FORCE_PARTIAL_LOAD] ?? false) === true) {
+            throw FeatureNotImplemented::partialEntities();
+        }
+
         if (! ($key->cacheMode & Cache::MODE_PUT)) {
             return false;
         }
@@ -226,7 +231,6 @@ class DefaultQueryCache implements QueryCache
         $region = $persister->getCacheRegion();
 
         $cm = $this->em->getClassMetadata($entityName);
-        assert($cm instanceof ClassMetadata);
 
         foreach ($result as $index => $entity) {
             $identifier = $this->uow->getEntityIdentifier($entity);
@@ -292,7 +296,7 @@ class DefaultQueryCache implements QueryCache
 
     /**
      * @return mixed[]|null
-     * @psalm-return array{targetEntity: class-string, type: mixed, list?: array[], identifier?: array}|null
+     * @phpstan-return array{targetEntity: class-string, type: mixed, list?: array[], identifier?: array}|null
      */
     private function storeAssociationCache(QueryCacheKey $key, AssociationMapping $assoc, mixed $assocValue): array|null
     {
@@ -343,7 +347,7 @@ class DefaultQueryCache implements QueryCache
         ];
     }
 
-    /** @psalm-return list<mixed>|object|null */
+    /** @phpstan-return list<mixed>|object|null */
     private function getAssociationValue(
         ResultSetMapping $rsm,
         string $assocAlias,
@@ -369,9 +373,9 @@ class DefaultQueryCache implements QueryCache
     }
 
     /**
-     * @psalm-param array<array-key, array{field: string, class: string}> $path
+     * @phpstan-param array<array-key, array{field: string, class: string}> $path
      *
-     * @psalm-return list<mixed>|object|null
+     * @phpstan-return list<mixed>|object|null
      */
     private function getAssociationPathValue(mixed $value, array $path): array|object|null
     {

src/Cache/EntityCacheEntry.php

@@ -11,8 +11,8 @@ use function array_map;
 class EntityCacheEntry implements CacheEntry
 {
     /**
-     * @param array<string,mixed> $data The entity map data
-     * @psalm-param class-string $class The entity class name
+     * @param class-string        $class The entity class name
+     * @param array<string,mixed> $data  The entity map data
      */
     public function __construct(
         public readonly string $class,

src/Cache/Exception/FeatureNotImplemented.php

@@ -20,4 +20,9 @@ class FeatureNotImplemented extends CacheException
     {
         return new self('Second-level cache query supports only select statements.');
     }
+
+    public static function partialEntities(): self
+    {
+        return new self('Second level cache does not support partial entities.');
+    }
 }