Merge remote-tracking branch 'origin/3.5.x' into 3.6.x

Author: greg0ire

UPGRADE.md

@@ -1,3 +1,32 @@
+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.6
 
 ## Deprecate specifying `nullable` on columns that end up being used in a primary key
@@ -40,6 +69,8 @@ root alias as key.
 
 # 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
@@ -93,6 +124,8 @@ 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.
@@ -113,6 +146,8 @@ 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.
@@ -129,6 +164,8 @@ 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.
@@ -155,6 +192,8 @@ using the `\Doctrine\ORM\Mapping\UniqueConstraint` and `\Doctrine\ORM\Mapping\In
 
 # 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.
@@ -178,6 +217,8 @@ Using array access on instances of the following classes is deprecated:
 
 # 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
@@ -203,6 +244,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
@@ -215,6 +259,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
 

phpstan-baseline.neon

@@ -3268,31 +3268,25 @@ parameters:
 			path: src/Tools/SchemaTool.php
 
 		-
-			message: '#^Parameter \#1 \$columnNames of method Doctrine\\DBAL\\Schema\\Table\:\:setPrimaryKey\(\) expects non\-empty\-list\<string\>, array\<string\> given\.$#'
-			identifier: argument.type
-			count: 1
-			path: src/Tools/SchemaTool.php
-
-		-
-			message: '#^Parameter \#1 \$value of static method Doctrine\\DBAL\\Schema\\Name\\Identifier\:\:unquoted\(\) expects non\-empty\-string, string given\.$#'
+			message: '#^Parameter \#2 \$columns of class Doctrine\\DBAL\\Schema\\Index constructor expects non\-empty\-list\<string\>, list\<string\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: src/Tools/SchemaTool.php
 
 		-
-			message: '#^Parameter \#2 \$columnNames of class Doctrine\\DBAL\\Schema\\PrimaryKeyConstraint constructor expects non\-empty\-list\<Doctrine\\DBAL\\Schema\\Name\\UnqualifiedName\>, list\<Doctrine\\DBAL\\Schema\\Name\\UnqualifiedName\> given\.$#'
+			message: '#^Parameter \#2 \$localColumnNames of method Doctrine\\DBAL\\Schema\\Table\:\:addForeignKeyConstraint\(\) expects non\-empty\-list\<string\>, list\<string\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: src/Tools/SchemaTool.php
 
 		-
-			message: '#^Parameter \#2 \$columns of class Doctrine\\DBAL\\Schema\\Index constructor expects non\-empty\-list\<string\>, list\<string\> given\.$#'
+			message: '#^Parameter \#2 \$primaryKeyColumns of method Doctrine\\ORM\\Tools\\SchemaTool\:\:addPrimaryKeyConstraint\(\) expects non\-empty\-array\<non\-empty\-string\>, list\<string\> given\.$#'
 			identifier: argument.type
-			count: 1
+			count: 2
 			path: src/Tools/SchemaTool.php
 
 		-
-			message: '#^Parameter \#2 \$localColumnNames of method Doctrine\\DBAL\\Schema\\Table\:\:addForeignKeyConstraint\(\) expects non\-empty\-list\<string\>, list\<string\> given\.$#'
+			message: '#^Parameter \#2 \$primaryKeyColumns of method Doctrine\\ORM\\Tools\\SchemaTool\:\:addPrimaryKeyConstraint\(\) expects non\-empty\-array\<non\-empty\-string\>, non\-empty\-list\<string\> given\.$#'
 			identifier: argument.type
 			count: 1
 			path: src/Tools/SchemaTool.php

phpstan-dbal3.neon

@@ -34,6 +34,14 @@ parameters:
             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

src/AbstractQuery.php

@@ -18,7 +18,6 @@
 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;
@@ -865,10 +864,6 @@ public function toIterable(
             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);

src/Internal/Hydration/AbstractHydrator.php

@@ -23,9 +23,11 @@
 use function array_map;
 use function array_merge;
 use function count;
+use function current;
 use function end;
 use function in_array;
 use function is_array;
+use function is_object;
 use function ksort;
 
 /**
@@ -126,8 +128,10 @@ final public function toIterable(Result $stmt, ResultSetMapping $resultSetMappin
                     } else {
                         yield from $result;
                     }
-                } else {
+                } elseif (is_object(current($result))) {
                     yield $result;
+                } else {
+                    yield array_merge(...$result);
                 }
             }
         } finally {

src/Mapping/Driver/DatabaseDriver.php

@@ -252,7 +252,14 @@ public function loadMetadataForClass(string $className, PersistenceClassMetadata
                         ];
                     }
                 } else {
-                    $associationMapping['mappedBy'] = $this->getFieldNameForColumn($manyTable->getName(), current(self::getReferencingColumnNames($myFk)), true);
+                    $associationMapping['mappedBy'] = $this->getFieldNameForColumn(
+                        // @phpstan-ignore function.alreadyNarrowedType (DBAL 3 compatibility)
+                        method_exists(Table::class, 'getObjectName')
+                            ? $manyTable->getObjectName()->toString()
+                            : $manyTable->getName(), // DBAL < 4.4
+                        current(self::getReferencingColumnNames($myFk)),
+                        true,
+                    );
                 }
 
                 $metadata->mapManyToMany($associationMapping);

src/Tools/SchemaTool.php

@@ -39,6 +39,7 @@
 use function array_flip;
 use function array_intersect_key;
 use function array_map;
+use function array_values;
 use function assert;
 use function class_exists;
 use function count;
@@ -47,6 +48,7 @@
 use function in_array;
 use function is_numeric;
 use function method_exists;
+use function preg_match;
 use function strtolower;
 
 /**
@@ -971,20 +973,26 @@ private function createSchemaForComparison(Schema $toSchema): Schema
         }
     }
 
-    /** @param string[] $primaryKeyColumns */
+    /** @param non-empty-array<non-empty-string> $primaryKeyColumns */
     private function addPrimaryKeyConstraint(Table $table, array $primaryKeyColumns): void
     {
-        if (class_exists(PrimaryKeyConstraint::class)) {
-            $primaryKeyColumnNames = [];
+        if (! class_exists(PrimaryKeyConstraint::class)) {
+            $table->setPrimaryKey(array_values($primaryKeyColumns));
 
-            foreach ($primaryKeyColumns as $primaryKeyColumn) {
+            return;
+        }
+
+        $primaryKeyColumnNames = [];
+
+        foreach ($primaryKeyColumns as $primaryKeyColumn) {
+            if (preg_match('/^"(.+)"$/', $primaryKeyColumn, $matches) === 1) {
+                $primaryKeyColumnNames[] = new UnqualifiedName(Identifier::quoted($matches[1]));
+            } else {
                 $primaryKeyColumnNames[] = new UnqualifiedName(Identifier::unquoted($primaryKeyColumn));
             }
-
-            $table->addPrimaryKeyConstraint(new PrimaryKeyConstraint(null, $primaryKeyColumnNames, true));
-        } else {
-            $table->setPrimaryKey($primaryKeyColumns);
         }
+
+        $table->addPrimaryKeyConstraint(new PrimaryKeyConstraint(null, $primaryKeyColumnNames, true));
     }
 
     /** @return string[] */