Merge branch '2.11.x' into 3.0.x

* 2.11.x:
  Added runtime deprecation to `UnitOfWork::commit()` and `clear()` (#9327)
  Document return type of getEntityState() (#9328)
  Fix broken type declaration (#9330)
  Enable some previously disabled PHPCS rules (#9324)

Author: derrabus

lib/Doctrine/ORM/UnitOfWork.php

@@ -325,6 +325,15 @@ public function __construct(EntityManagerInterface $em)
      */
     public function commit(object|array|null $entity = null): void
     {
+        if ($entity !== null) {
+            Deprecation::triggerIfCalledFromOutside(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/issues/8459',
+                'Calling %s() with any arguments to commit specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                __METHOD__
+            );
+        }
+
         $connection = $this->em->getConnection();
 
         if ($connection instanceof PrimaryReadReplicaConnection) {
@@ -928,8 +937,6 @@ private function computeAssociationChanges(array $assoc, mixed $value): void
                     // so the exception will be raised from the DBAL layer (constraint violation).
                     throw ORMInvalidArgumentException::detachedEntityFoundThroughRelationship($assoc, $entry);
 
-                    break;
-
                 default:
                     // MANAGED associated entities are already taken into account
                     // during changeset calculation anyway, since they are in the identity map.
@@ -1503,6 +1510,9 @@ public function addToIdentityMap(object $entity): bool
      *                         This parameter can be set to improve performance of entity state detection
      *                         by potentially avoiding a database lookup if the distinction between NEW and DETACHED
      *                         is either known or does not matter for the caller of the method.
+     * @psalm-param self::STATE_*|null $assume
+     *
+     * @psalm-return self::STATE_*
      */
     public function getEntityState(object $entity, ?int $assume = null): int
     {
@@ -2418,6 +2428,13 @@ public function clear(?string $entityName = null): void
             $this->eagerLoadingEntities           =
             $this->orphanRemovals                 = [];
         } else {
+            Deprecation::triggerIfCalledFromOutside(
+                'doctrine/orm',
+                'https://github.com/doctrine/orm/issues/8460',
+                'Calling %s() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine ORM 3.0.',
+                __METHOD__
+            );
+
             $this->clearIdentityMapForEntityName($entityName);
             $this->clearEntityInsertionsForEntityName($entityName);
         }

phpcs.xml.dist

@@ -128,11 +128,6 @@
         <exclude-pattern>lib/Doctrine/ORM/Cache/DefaultQueryCache.php</exclude-pattern>
     </rule>
 
-    <rule ref="SlevomatCodingStandard.Commenting.UselessInheritDocComment.UselessInheritDocComment">
-        <!-- Workaround for https://github.com/slevomat/coding-standard/issues/1233 -->
-        <exclude-pattern>lib/Doctrine/ORM/Mapping/ReflectionEmbeddedProperty.php</exclude-pattern>
-    </rule>
-
     <rule ref="SlevomatCodingStandard.Classes.SuperfluousInterfaceNaming">
         <exclude-pattern>lib/Doctrine/ORM/EntityManagerInterface.php</exclude-pattern>
     </rule>
@@ -258,14 +253,6 @@
         <exclude-pattern>tests/Doctrine/Tests/ORM/Functional/Ticket/DDC1843Test.php</exclude-pattern>
     </rule>
 
-    <rule ref="PSR2.ControlStructures.SwitchDeclaration.TerminatingComment">
-        <!--
-            Remove when upgrading to squizlabs/php_codesniffer 3.6.0
-            https://github.com/squizlabs/PHP_CodeSniffer/pull/3186
-        -->
-        <exclude-pattern>lib/Doctrine/ORM/Query/Parser.php</exclude-pattern>
-    </rule>
-
     <rule ref="Generic.CodeAnalysis.EmptyStatement.DetectedElse">
         <!-- The missing code needs to be implemented someday -->
         <exclude-pattern>lib/Doctrine/ORM/Id/TableGenerator.php</exclude-pattern>

phpstan-baseline.neon

@@ -1565,11 +1565,6 @@ parameters:
 			count: 1
 			path: lib/Doctrine/ORM/UnitOfWork.php
 
-		-
-			message: "#^Unreachable statement \\- code above always terminates\\.$#"
-			count: 1
-			path: lib/Doctrine/ORM/UnitOfWork.php
-
 		-
 			message: "#^Access to an undefined property Doctrine\\\\Persistence\\\\Mapping\\\\ClassMetadata\\:\\:\\$name\\.$#"
 			count: 1

psalm-baseline.xml

@@ -3012,6 +3012,9 @@
       <code>$entity</code>
       <code>$entity</code>
     </PossiblyNullArgument>
+    <RedundantConditionGivenDocblockType occurrences="1">
+      <code>$state === UnitOfWork::STATE_DETACHED</code>
+    </RedundantConditionGivenDocblockType>
   </file>
   <file src="lib/Doctrine/ORM/Tools/Pagination/CountOutputWalker.php">
     <MoreSpecificImplementedParamType occurrences="1">

tests/Doctrine/Tests/ORM/UnitOfWorkTest.php

@@ -7,6 +7,7 @@
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\EventManager;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Doctrine\ORM\EntityNotFoundException;
 use Doctrine\ORM\Events;
 use Doctrine\ORM\Mapping\ClassMetadata;
@@ -50,6 +51,8 @@
  */
 class UnitOfWorkTest extends OrmTestCase
 {
+    use VerifyDeprecations;
+
     /**
      * SUT
      *
@@ -226,6 +229,9 @@ public function testChangeTrackingNotifyIndividualCommit(): void
 
         $this->_unitOfWork->persist($entity);
         $this->_unitOfWork->persist($entity2);
+
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8459');
+
         $this->_unitOfWork->commit($entity);
         $this->_unitOfWork->commit();
 
@@ -389,6 +395,8 @@ public function testPersistedEntityAndClearManager(): void
         $this->_unitOfWork->persist($entity2);
         self::assertTrue($this->_unitOfWork->isInIdentityMap($entity2));
 
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8460');
+
         $this->_unitOfWork->clear(Country::class);
         self::assertTrue($this->_unitOfWork->isInIdentityMap($entity1));
         self::assertFalse($this->_unitOfWork->isInIdentityMap($entity2));
@@ -410,6 +418,8 @@ public function testEntityChangeSetIsNotClearedAfterFlushOnSingleEntity(): void
         $this->_unitOfWork->persist($entity1);
         $this->_unitOfWork->persist($entity2);
 
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8459');
+
         $this->_unitOfWork->commit($entity1);
         self::assertEmpty($this->_unitOfWork->getEntityChangeSet($entity1));
         self::assertCount(1, $this->_unitOfWork->getEntityChangeSet($entity2));
@@ -432,6 +442,8 @@ public function testEntityChangeSetIsNotClearedAfterFlushOnArrayOfEntities(): vo
         $this->_unitOfWork->persist($entity2);
         $this->_unitOfWork->persist($entity3);
 
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/orm/issues/8459');
+
         $this->_unitOfWork->commit([$entity1, $entity3]);
 
         self::assertEmpty($this->_unitOfWork->getEntityChangeSet($entity1));