Merge 2.14.x into 3.0.x

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

@@ -372,7 +372,7 @@ Doctrine ORM currently supports two pessimistic lock modes:
  locks other concurrent requests that attempt to update or lock rows
  in write mode.
 
-You can use pessimistic locks in three different scenarios:
+You can use pessimistic locks in four different scenarios:
 
 
 1. Using
@@ -384,6 +384,10 @@ You can use pessimistic locks in three different scenarios:
  or
  ``EntityManager#lock($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
 3. Using
+ ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
+ or
+ ``EntityManager#refresh($entity, \Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``
+4. Using
  ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_WRITE)``
  or
  ``Query#setLockMode(\Doctrine\DBAL\LockMode::PESSIMISTIC_READ)``

lib/Doctrine/ORM/Decorator/EntityManagerDecorator.php

@@ -24,6 +24,9 @@
 use Doctrine\ORM\UnitOfWork;
 use Doctrine\Persistence\ObjectManagerDecorator;
 
+use function func_get_arg;
+use function func_num_args;
+
 /**
  * Base class for EntityManager decorators
  *
@@ -130,6 +133,17 @@ 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
+ {
+ $lockMode = null;
+
+ if (func_num_args() > 1) {
+ $lockMode = func_get_arg(1);
+ }
+
+ $this->wrapped->refresh($object, $lockMode);
+ }
+
  public function getEventManager(): EventManager
  {
  return $this->wrapped->getEventManager();

lib/Doctrine/ORM/EntityManager.php

@@ -500,14 +500,17 @@ public function remove(object $object): void
  * 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): void
+ public function refresh(object $object, LockMode|int|null $lockMode = null): void
  {
  $this->errorIfClosed();
 
- $this->unitOfWork->refresh($object);
+ $this->unitOfWork->refresh($object, $lockMode);
  }
 
  /**

lib/Doctrine/ORM/EntityManagerInterface.php

@@ -17,6 +17,7 @@
 use Doctrine\ORM\Query\ResultSetMapping;
 use Doctrine\Persistence\ObjectManager;
 
+/** @method void refresh(object $object, LockMode|int|null $lockMode = null) */
 interface EntityManagerInterface extends ObjectManager
 {
  /**

lib/Doctrine/ORM/UnitOfWork.php

@@ -64,6 +64,8 @@
 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;
@@ -1789,23 +1791,40 @@ private function doDetach(
  * any local, unpersisted changes.
  *
  * @throws InvalidArgumentException If the entity is not MANAGED.
+ * @throws TransactionRequiredException
  */
  public function refresh(object $entity): void
  {
  $visited = [];
 
- $this->doRefresh($entity, $visited);
+ $lockMode = null;
+
+ if (func_num_args() > 1) {
+ $lockMode = func_get_arg(1);
+ }
+
+ $this->doRefresh($entity, $visited, $lockMode);
  }
 
  /**
  * Executes a refresh operation on an entity.
  *
  * @psalm-param array<int, object> $visited The already visited entities during cascades.
+ * @psalm-param LockMode::*|null $lockMode
  *
  * @throws ORMInvalidArgumentException If the entity is not MANAGED.
+ * @throws TransactionRequiredException
  */
- private function doRefresh(object $entity, array &$visited): void
+ private function doRefresh(object $entity, array &$visited, LockMode|int|null $lockMode = null): void
  {
+ switch (true) {
+ case $lockMode === LockMode::PESSIMISTIC_READ:
+ case $lockMode === LockMode::PESSIMISTIC_WRITE:
+ if (! $this->em->getConnection()->isTransactionActive()) {
+ throw TransactionRequiredException::transactionRequired();
+ }
+ }
+
  $oid = spl_object_id($entity);
 
  if (isset($visited[$oid])) {
@@ -1823,17 +1842,19 @@ private function doRefresh(object $entity, array &$visited): void
  $this->getEntityPersister($class->name)->refresh(
  array_combine($class->getIdentifierFieldNames(), $this->entityIdentifiers[$oid]),
  $entity,
+ $lockMode,
  );
 
- $this->cascadeRefresh($entity, $visited);
+ $this->cascadeRefresh($entity, $visited, $lockMode);
  }
 
  /**
  * Cascades a refresh operation to associated entities.
  *
  * @psalm-param array<int, object> $visited
+ * @psalm-param LockMode::*|null $lockMode
  */
- private function cascadeRefresh(object $entity, array &$visited): void
+ private function cascadeRefresh(object $entity, array &$visited, LockMode|int|null $lockMode = null): void
  {
  $class = $this->em->getClassMetadata($entity::class);
 
@@ -1854,13 +1875,13 @@ private function cascadeRefresh(object $entity, array &$visited): void
  case $relatedEntities instanceof Collection:
  case is_array($relatedEntities):
  foreach ($relatedEntities as $relatedEntity) {
- $this->doRefresh($relatedEntity, $visited);
+ $this->doRefresh($relatedEntity, $visited, $lockMode);
  }
 
  break;
 
  case $relatedEntities !== null:
- $this->doRefresh($relatedEntities, $visited);
+ $this->doRefresh($relatedEntities, $visited, $lockMode);
  break;
 
  default:

psalm.xml

@@ -88,6 +88,9 @@
  <!-- 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/Tests/ORM/Functional/Locking/LockTest.php

@@ -144,6 +144,21 @@ public function testLockPessimisticWriteNoTransactionThrowsException(): void
  $this->_em->lock($article, LockMode::PESSIMISTIC_WRITE);
  }
 
+ /** @group locking */
+ public function testRefreshWithLockPessimisticWriteNoTransactionThrowsException(): void
+ {
+ $article = new CmsArticle();
+ $article->text = 'my article';
+ $article->topic = 'Hello';
+
+ $this->_em->persist($article);
+ $this->_em->flush();
+
+ $this->expectException(TransactionRequiredException::class);
+
+ $this->_em->refresh($article, LockMode::PESSIMISTIC_WRITE);
+ }
+
  /**
  * @group DDC-178
  * @group locking
@@ -180,6 +195,39 @@ public function testLockPessimisticWrite(): void
  self::assertStringContainsString($writeLockSql, $lastLoggedQuery);
  }
 
+ /** @group locking */
+ public function testRefreshWithLockPessimisticWrite(): void
+ {
+ $writeLockSql = $this->_em->getConnection()->getDatabasePlatform()->getWriteLockSQL();
+
+ if (! $writeLockSql) {
+ self::markTestSkipped('Database Driver has no Write Lock support.');
+ }
+
+ $article = new CmsArticle();
+ $article->text = 'my article';
+ $article->topic = 'Hello';
+
+ $this->_em->persist($article);
+ $this->_em->flush();
+
+ $this->_em->beginTransaction();
+ try {
+ $this->_em->refresh($article, LockMode::PESSIMISTIC_WRITE);
+ $this->_em->commit();
+ } catch (Exception) {
+ $this->_em->rollback();
+ }
+
+ $lastLoggedQuery = $this->getLastLoggedQuery()['sql'];
+ // DBAL 2 logs a commit as last query.
+ if ($lastLoggedQuery === '"COMMIT"') {
+ $lastLoggedQuery = $this->getLastLoggedQuery(1)['sql'];
+ }
+
+ self::assertStringContainsString($writeLockSql, $lastLoggedQuery);
+ }
+
  /** @group DDC-178 */
  public function testLockPessimisticRead(): void
  {