Merge pull request #11728 from greg0ire/4.0.x

Merge 3.4.x up into 4.0.x

Author: greg0ire

.github/ISSUE_TEMPLATE/BC_Break.md

@@ -111,7 +111,7 @@ jobs:
         dbal-version:
           - "default"
         postgres-version:
-          - "15"
+          - "17"
         extension:
           - pdo_pgsql
           - pgsql
@@ -337,7 +337,7 @@ jobs:
           path: "reports"
 
       - name: "Upload to Codecov"
-        uses: "codecov/codecov-action@v4"
+        uses: "codecov/codecov-action@v5"
         with:
           directory: reports
         env:

.github/ISSUE_TEMPLATE/Bug.md

@@ -3,8 +3,6 @@
 |           [![Build status][4.0 image]][4.0]            |           [![Build status][3.4 image]][3.4]            |           [![Build status][3.3 image]][3.3]            |           [![Build status][2.21 image]][2.21]            |           [![Build status][2.20 image]][2.20]            |
 | [![Coverage Status][4.0 coverage image]][4.0 coverage] | [![Coverage Status][3.4 coverage image]][3.4 coverage] | [![Coverage Status][3.3 coverage image]][3.3 coverage] | [![Coverage Status][2.21 coverage image]][2.21 coverage] | [![Coverage Status][2.20 coverage image]][2.20 coverage] |
 
-[<h1 align="center">🇺🇦 UKRAINE NEEDS YOUR HELP NOW!</h1>](https://www.doctrine-project.org/stop-war.html)
-
 Doctrine ORM is an object-relational mapper for PHP 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
 is the option to write database queries in a proprietary object oriented SQL dialect called Doctrine Query Language (DQL),

.github/ISSUE_TEMPLATE/Feature_Request.md

@@ -48,12 +48,27 @@ The properties `$indexes` and `$uniqueConstraints` have been removed since they
 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.4
+
+Using the same class several times in a discriminator map is deprecated.
+In 4.0, this will be an error.
+
 # Upgrade to 3.3
 
 ## 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
 
 ## Deprecate the `NotSupported` exception
@@ -787,7 +802,7 @@ Use `toIterable()` instead.
 
 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 
+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.
@@ -800,7 +815,7 @@ change in behavior.
 
 Progress on this is tracked at https://github.com/doctrine/orm/issues/11624 .
 
-## PARTIAL DQL syntax is undeprecated 
+## 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

.github/ISSUE_TEMPLATE/Support_Question.md

@@ -31,7 +31,7 @@
         "doctrine/inflector": "^1.4 || ^2.0",
         "doctrine/instantiator": "^1.3 || ^2",
         "doctrine/lexer": "^3",
-        "doctrine/persistence": "^3.3.1",
+        "doctrine/persistence": "^3.3.1 || ^4",
         "psr/cache": "^1 || ^2 || ^3",
         "symfony/console": "^5.4 || ^6.0 || ^7.0",
         "symfony/var-exporter": "^6.3.9 || ^7.0"

.github/workflows/continuous-integration.yml

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

README.md

@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

UPGRADE.md

@@ -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?".
 

composer.json

@@ -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:

docs/en/cookbook/aggregate-fields.rst

@@ -48,6 +48,8 @@
     </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>tests/*</exclude-pattern>
     </rule>
 

docs/en/reference/architecture.rst

@@ -125,6 +125,11 @@ parameters:
 			count: 1
 			path: src/Mapping/ClassMetadataFactory.php
 
+		-
+			message: "#^Expression on left side of \\?\\? is not nullable\\.$#"
+			count: 1
+			path: src/Mapping/Driver/AttributeDriver.php
+
 		-
 			message: "#^Method Doctrine\\\\ORM\\\\Mapping\\\\ToOneOwningSideMapping\\:\\:fromMappingArray\\(\\) should return static\\(Doctrine\\\\ORM\\\\Mapping\\\\ToOneOwningSideMapping\\) but returns Doctrine\\\\ORM\\\\Mapping\\\\ManyToOneAssociationMapping\\|Doctrine\\\\ORM\\\\Mapping\\\\OneToOneOwningSideMapping\\.$#"
 			count: 1

docs/en/reference/unitofwork.rst

@@ -293,15 +293,9 @@
       <code><![CDATA[$mapping]]></code>
       <code><![CDATA[$overrideMapping]]></code>
     </InvalidArgument>
-    <InvalidNullableReturnType>
-      <code><![CDATA[ReflectionClass|null]]></code>
-    </InvalidNullableReturnType>
     <InvalidPropertyAssignmentValue>
       <code><![CDATA[$definition]]></code>
     </InvalidPropertyAssignmentValue>
-    <NullableReturnStatement>
-      <code><![CDATA[$this->reflClass]]></code>
-    </NullableReturnStatement>
     <ParamNameMismatch>
       <code><![CDATA[$entity]]></code>
     </ParamNameMismatch>
@@ -448,6 +442,14 @@
       <code><![CDATA[new ReflectionClass($metadata->name)]]></code>
     </TypeDoesNotContainNull>
   </file>
+  <file src="src/Mapping/Driver/LoadMappingFileImplementation.php">
+    <LessSpecificImplementedReturnType>
+      <code><![CDATA[array]]></code>
+    </LessSpecificImplementedReturnType>
+    <MissingParamType>
+      <code><![CDATA[$file]]></code>
+    </MissingParamType>
+  </file>
   <file src="src/Mapping/Driver/SimplifiedXmlDriver.php">
     <MissingParamType>
       <code><![CDATA[$fileExtension]]></code>
@@ -500,6 +502,14 @@
       <code><![CDATA[$metadata]]></code>
     </MoreSpecificImplementedParamType>
   </file>
+  <file src="src/Mapping/GetReflectionClassImplementation.php">
+    <ImplementedReturnTypeMismatch>
+      <code><![CDATA[ReflectionClass]]></code>
+    </ImplementedReturnTypeMismatch>
+    <InvalidNullableReturnType>
+      <code><![CDATA[ReflectionClass]]></code>
+    </InvalidNullableReturnType>
+  </file>
   <file src="src/Mapping/ManyToManyInverseSideMapping.php">
     <PropertyNotSetInConstructor>
       <code><![CDATA[ManyToManyInverseSideMapping]]></code>

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

@@ -41,6 +41,7 @@
                 <referencedClass name="Doctrine\ORM\Tools\Console\Command\GenerateRepositoriesCommand"/>
                 <referencedClass name="Doctrine\ORM\Tools\Console\Helper\EntityManagerHelper"/>
                 <referencedClass name="Doctrine\ORM\Tools\Console\EntityManagerProvider\HelperSetManagerProvider"/>
+                <referencedClass name="Doctrine\Persistence\Mapping\StaticReflectionService"/>
             </errorLevel>
         </DeprecatedClass>
         <DocblockTypeContradiction>

phpcs.xml.dist

@@ -560,9 +560,9 @@ public function initializeObject(object $obj): void
     /**
      * {@inheritDoc}
      */
-    public function isUninitializedObject($obj): bool
+    public function isUninitializedObject($value): bool
     {
-        return $this->unitOfWork->isUninitializedObject($obj);
+        return $this->unitOfWork->isUninitializedObject($value);
     }
 
     public function getFilters(): FilterCollection

phpstan-baseline.neon

@@ -103,16 +103,14 @@ private function __construct()
      * The onFlush event occurs when the EntityManager#flush() operation is invoked,
      * after any changes to managed entities have been determined but before any
      * actual database operations are executed. The event is only raised if there is
-     * actually something to do for the underlying UnitOfWork. If nothing needs to be done,
-     * the onFlush event is not raised.
+     * actually something to do for the underlying UnitOfWork.
      */
     public const onFlush = 'onFlush';
 
     /**
      * The postFlush event occurs when the EntityManager#flush() operation is invoked and
      * after all actual database operations are executed successfully. The event is only raised if there is
-     * actually something to do for the underlying UnitOfWork. If nothing needs to be done,
-     * the postFlush event is not raised. The event won't be raised if an error occurs during the
+     * actually something to do for the underlying UnitOfWork. The event won't be raised if an error occurs during the
      * flush operation.
      */
     public const postFlush = 'postFlush';