Add $lockMode parameter to EntityManager::refresh()

UPGRADE.md

@@ -1,5 +1,10 @@
 # Upgrade to 3.0
 
+## BC BREAK: Changed `EntityManagerInterface#refresh($entity)`, `EntityManagerDecorator#refresh($entity)` and `UnitOfWork#refresh($entity)` signatures
+
+The new signatures of these methods add an optional `LockMode|int|null $lockMode`
+param with default `null` value (no lock).
+
 ## BC Break: Removed AnnotationDriver
 
 The annotation driver and anything related to annotation has been removed.

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -24,9 +24,6 @@
 use Doctrine\ORM\UnitOfWork;
 use Doctrine\Persistence\ObjectManagerDecorator;
 
-use function func_get_arg;
-use function func_num_args;
-
 /**
  * Base class for EntityManager decorators
  *
@@ -133,14 +130,8 @@ public function find(string $className, mixed $id, LockMode|int|null $lockMode =
  return $this->wrapped->find($className, $id, $lockMode, $lockVersion);
  }
 
- public function refresh(object $object): void
+ public function refresh(object $object, LockMode|int|null $lockMode = null): void
  {
- $lockMode = null;
-
- if (func_num_args() > 1) {
- $lockMode = func_get_arg(1);
- }
-
  $this->wrapped->refresh($object, $lockMode);
  }
 

lib/Doctrine/ORM/EntityManager.php

@@ -496,16 +496,6 @@ public function remove(object $object): void
  $this->unitOfWork->remove($object);
  }
 
- /**
- * Refreshes the persistent state of an entity from the database,
- * overriding any local changes that have not yet been persisted.
- *
- * @psalm-param LockMode::*|null $lockMode
- *
- * @throws ORMInvalidArgumentException
- * @throws ORMException
- * @throws TransactionRequiredException
- */
  public function refresh(object $object, LockMode|int|null $lockMode = null): void
  {
  $this->errorIfClosed();

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -17,7 +17,6 @@
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\ObjectManager;
 
-/** @method void refresh(object $object, LockMode|int|null $lockMode = null) */
 interface EntityManagerInterface extends ObjectManager
 {
  /**
@@ -133,6 +132,21 @@ public function createQueryBuilder(): QueryBuilder;
  */
  public function find(string $className, mixed $id, LockMode|int|null $lockMode = null, int|null $lockVersion = null): object|null;
 
+ /**
+ * Refreshes the persistent state of an object from the database,
+ * overriding any local changes that have not yet been persisted.
+ *
+ * @param LockMode|int|null $lockMode One of the \Doctrine\DBAL\LockMode::* constants
+ * or NULL if no specific lock mode should be used
+ * during the search.
+ * @psalm-param LockMode::*|null $lockMode
+ *
+ * @throws ORMInvalidArgumentException
+ * @throws ORMException
+ * @throws TransactionRequiredException
+ */
+ public function refresh(object $object, LockMode|int|null $lockMode = null): void;
+
  /**
  * Gets a reference to the entity identified by the given type and identifier
  * without actually loading it, if the entity is not yet loaded.

lib/Doctrine/ORM/UnitOfWork.php

@@ -64,8 +64,6 @@
 use function assert;
 use function count;
 use function current;
-use function func_get_arg;
-use function func_num_args;
 use function get_debug_type;
 use function implode;
 use function in_array;
@@ -1790,19 +1788,15 @@ private function doDetach(
  * Refreshes the state of the given entity from the database, overwriting
  * any local, unpersisted changes.
  *
+ * @psalm-param LockMode::*|null $lockMode
+ *
  * @throws InvalidArgumentException If the entity is not MANAGED.
  * @throws TransactionRequiredException
  */
- public function refresh(object $entity): void
+ public function refresh(object $entity, LockMode|int|null $lockMode = null): void
  {
  $visited = [];
 
- $lockMode = null;
-
- if (func_num_args() > 1) {
- $lockMode = func_get_arg(1);
- }
-
  $this->doRefresh($entity, $visited, $lockMode);
  }
 

psalm.xml

@@ -88,9 +88,6 @@
  <!-- Persistence 2 compatibility -->
  <referencedFunction name="Doctrine\Persistence\ObjectManager::clear"/>
 
- <!-- Remove on 3.0.x -->
- <referencedFunction name="Doctrine\Persistence\ObjectManager::refresh"/>
-
  <!-- See https://github.com/doctrine/orm/issues/8850 -->
  <referencedFunction name="Doctrine\DBAL\Connection::lastInsertId"/>
 

tests/Doctrine/Performance/Mock/NonProxyLoadingEntityManager.php

@@ -201,9 +201,9 @@ public function detach(object $object): void
  $this->realEntityManager->detach($object);
  }
 
- public function refresh(object $object): void
+ public function refresh(object $object, LockMode|int|null $lockMode = null): void
  {
- $this->realEntityManager->refresh($object);
+ $this->realEntityManager->refresh($object, $lockMode);
  }
 
  public function flush(): void