feat: rewrite AR transaction to using EntityManager

src/ActiveRecord.php

@@ -4,13 +4,11 @@
 
 namespace Cycle\ActiveRecord;
 
+use Cycle\ActiveRecord\Exception\Transaction\TransactionException;
 use Cycle\ActiveRecord\Internal\TransactionFacade;
 use Cycle\ActiveRecord\Query\ActiveQuery;
-use Cycle\ORM\EntityManager;
-use Cycle\ORM\EntityManagerInterface;
 use Cycle\ORM\ORMInterface;
 use Cycle\ORM\RepositoryInterface;
-use Cycle\ORM\Transaction\StateInterface;
 
 /**
  * A base class for entities that are managed by the ORM.
@@ -72,11 +70,22 @@ final public static function findAll(array $scope = []): iterable
 
     /**
      * Execute a callback within a single transaction.
-     * Only {@see ActiveRecord} methods will be registered in the transaction and run on the callback completion.
+     *
+     * All the ActiveRecord write operations within the callback will be registered
+     * using the Entity Manager without being executed until the end of the callback.
+     *
+     * @template TResult
+     * @param callable(): TResult $callback
+     * @return TResult
+     *
+     * @throws TransactionException
+     * @throws \Throwable
      */
-    public static function transact(callable $callback, TransactionMode $mode = TransactionMode::OpenNew): void
-    {
-        TransactionFacade::transact($callback, $mode);
+    public static function transact(
+        callable $callback,
+        TransactionMode $mode = TransactionMode::OpenNew,
+    ): mixed {
+        return TransactionFacade::transact($callback, $mode);
     }
 
     /**
@@ -96,81 +105,62 @@ public static function getRepository(): RepositoryInterface
 
     /**
      * Persist the entity.
-     *
-     * @throws \Throwable
      */
-    final public function save(bool $cascade = true): StateInterface
+    final public function save(bool $cascade = true): bool
     {
-        /** @var EntityManager $entityManager */
-        $entityManager = Facade::getEntityManager();
-        $entityManager->persist($this, $cascade);
-
-        return $entityManager->run(throwException: false);
+        $transacting = TransactionFacade::getEntityManager();
+        if ($transacting === null) {
+            return Facade::getEntityManager()
+                ->persist($this, $cascade)
+                ->run(false)
+                ->isSuccess();
+        }
+
+        $transacting->persist($this, $cascade);
+        return true;
     }
 
     /**
      * Persist the entity and throw an exception if an error occurs.
+     * The exception will be thrown if the action is happening not in a {@see self::transcat()} scope.
      *
      * @throws \Throwable
      */
-    final public function saveOrFail(bool $cascade = true): StateInterface
-    {
-        /** @var EntityManager $entityManager */
-        $entityManager = Facade::getEntityManager();
-        $entityManager->persist($this, $cascade);
-
-        return $entityManager->run();
-    }
-
-    /**
-     * Prepare the entity for persistence.
-     *
-     * @note This function is experimental and may be removed in the future.
-     */
-    final public function persist(bool $cascade = true): EntityManagerInterface
+    final public function saveOrFail(bool $cascade = true): void
     {
-        return Facade::getEntityManager()->persist($this, $cascade);
+        TransactionFacade::getEntityManager()?->persist($this, $cascade) ?? Facade::getEntityManager()
+            ->persist($this, $cascade)
+            ->run();
     }
 
     /**
      * Delete the entity.
-     *
-     * @throws \Throwable
      */
-    final public function delete(bool $cascade = true): StateInterface
+    final public function delete(bool $cascade = true): bool
     {
-        /** @var EntityManager $entityManager */
-        $entityManager = Facade::getEntityManager();
-        $entityManager->delete($this, $cascade);
-
-        return $entityManager->run(throwException: false);
+        $transacting = TransactionFacade::getEntityManager();
+        if ($transacting === null) {
+            return Facade::getEntityManager()
+                ->delete($this, $cascade)
+                ->run(false)
+                ->isSuccess();
+        }
+
+        $transacting->delete($this, $cascade);
+        return true;
     }
 
     /**
      * Delete the entity and throw an exception if an error occurs.
+     * The exception will be thrown if the action is happening not in a {@see self::transcat()} scope.
      *
      * @throws \Throwable
      */
-    final public function deleteOrFail(bool $cascade = true): StateInterface
+    final public function deleteOrFail(bool $cascade = true): void
     {
-        /** @var EntityManager $entityManager */
-        $entityManager = Facade::getEntityManager();
-        $entityManager->delete($this, $cascade);
-
-        return $entityManager->run();
-    }
-
-    /**
-     * Prepare the entity for deletion.
-     *
-     * @note This function is experimental and may be removed in the future.
-     */
-    final public function remove(bool $cascade = true): EntityManagerInterface
-    {
-        /** @var EntityManager $entityManager */
-        $entityManager = Facade::getEntityManager();
-
-        return $entityManager->delete($this, $cascade);
+        TransactionFacade::getEntityManager()?->delete($this, $cascade) ?? Facade::getEntityManager()
+            ->delete($this, $cascade)
+            ->run();
     }
 
     private static function getOrm(): ORMInterface

src/Exception/Transaction/TransactionException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cycle\ActiveRecord\Exception\Transaction;
+
+use Cycle\ActiveRecord\Exception\ActiveRecordException;
+
+class TransactionException extends \RuntimeException implements ActiveRecordException {}

src/Internal/TransactionFacade.php

@@ -4,43 +4,50 @@
 
 namespace Cycle\ActiveRecord\Internal;
 
-use Cycle\ActiveRecord\Exception\TransactionDesyncException;
+use Cycle\ActiveRecord\Exception\Transaction\TransactionException;
 use Cycle\ActiveRecord\Facade;
 use Cycle\ActiveRecord\TransactionMode;
+use Cycle\ORM\EntityManagerInterface;
 use Cycle\ORM\Transaction\Runner;
-use Cycle\ORM\Transaction\StateInterface;
-use Cycle\ORM\Transaction\UnitOfWork;
 
 final class TransactionFacade
 {
-    private static ?UnitOfWork $uow = null;
+    private static ?EntityManagerInterface $em = null;
 
-    public static function getUoW(): ?UnitOfWork
+    public static function getEntityManager(): ?EntityManagerInterface
     {
-        return self::$uow;
+        return self::$em;
     }
 
+    /**
+     * @template TResult
+     * @param callable(): TResult $callback
+     * @return TResult
+     *
+     * @throws TransactionException
+     * @throws \Throwable
+     */
     public static function transact(
-        callable $callable,
+        callable $callback,
         TransactionMode $mode = TransactionMode::OpenNew,
-    ): StateInterface {
-        $previous = self::$uow;
-        self::$uow = $uow = new UnitOfWork(
-            Facade::getOrm(),
-            match ($mode) {
-                TransactionMode::Ignore => Runner::outerTransaction(strict: false),
-                TransactionMode::Continue => Runner::outerTransaction(strict: true),
-                TransactionMode::OpenNew => Runner::innerTransaction(),
-            },
+    ): mixed {
+        $runner = match ($mode) {
+            TransactionMode::Ignore => Runner::outerTransaction(strict: false),
+            TransactionMode::Current => Runner::outerTransaction(strict: true),
+            TransactionMode::OpenNew => Runner::innerTransaction(),
+        };
+
+        self::$em === null or throw new TransactionException(
+            'A transaction is already in progress.',
         );
+        self::$em = Facade::getEntityManager();
+
         try {
-            $callable();
-            return $uow->run();
+            $result = $callback();
+            self::$em->run(true, $runner);
+            return $result;
         } finally {
-            self::$uow === $uow or throw new TransactionDesyncException(
-                'A transaction was started outside of the previous transaction scope.',
-            );
-            self::$uow = $previous;
+            self::$em = null;
         }
     }
 }

src/TransactionMode.php

@@ -17,7 +17,7 @@ enum TransactionMode
      *
      * @see \Cycle\ORM\Transaction\Runner::innerTransaction() with strict mode.
      */
-    case Continue;
+    case Current;
     /**
      * A new transaction will be open for each used driver connection and will close they on finish.
      *

tests/app/Repository/RepositoryWithActiveQuery.php

@@ -15,7 +15,6 @@
  */
 final class RepositoryWithActiveQuery extends ActiveRepository
 {
-    #[\Override]
     public function __construct()
     {
         parent::__construct(User::class);

tests/src/Functional/ActiveRecordTest.php

@@ -4,8 +4,11 @@
 
 namespace Cycle\Tests\Functional;
 
-use Cycle\ActiveRecord\Facade;
+use Cycle\ActiveRecord\ActiveRecord;
+use Cycle\ActiveRecord\Exception\Transaction\TransactionException;
+use Cycle\ActiveRecord\TransactionMode;
 use Cycle\App\Entity\User;
+use Cycle\ORM\Exception\RunnerException;
 use Cycle\ORM\Select\Repository;
 use PHPUnit\Framework\Attributes\Test;
 
@@ -69,7 +72,7 @@ public function it_saves_entity(): void
     {
         $user = new User('Alex');
 
-        self::assertTrue($user->save()->isSuccess());
+        self::assertTrue($user->save());
         self::assertCount(3, User::findAll());
 
         $result = $this->selectEntity(User::class, cleanHeap: true)->wherePK($user->id)->fetchOne();
@@ -85,13 +88,13 @@ public function it_triggers_exception_when_tries_to_save_entity_using_save_or_fa
     {
         $user = new User('John');
 
-        $this::expectException(\Throwable::class);
+        self::expectException(\Throwable::class);
 
         // pgsql-response: SQLSTATE[23505]: Unique violation: 7 ERROR:  duplicate key value violates unique constraint "user_index_name_663d5b6bf1e34
         // sqlite-response: SQLSTATE[23000]: Integrity constraint violation: 19 UNIQUE constraint failed: user.name
         // mysql-response: SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'John' for key 'user.user_index_name_663d5bc589edb'
 
-        $this::expectExceptionMessage('SQLSTATE');
+        self::expectExceptionMessage('SQLSTATE');
 
         $entityManager = $user->saveOrFail();
 
@@ -103,16 +106,15 @@ public function it_triggers_exception_when_tries_to_save_entity_using_save_or_fa
      * @throws \Throwable
      */
     #[Test]
-    public function it_persists_multiple_entities(): void
+    public function it_persists_multiple_entities_in_single_transaction(): void
     {
-        $userOne = new User('Foo');
-        $userOne->persist();
+        ActiveRecord::transact(static function () use (&$userOne, &$userTwo) {
+            $userOne = new User('Foo');
+            $userOne->saveOrFail();
 
-        $userTwo = new User('Bar');
-        $userTwo->persist();
-
-        $entityManager = Facade::getEntityManager();
-        $entityManager->run();
+            $userTwo = new User('Bar');
+            $userTwo->saveOrFail();
+        });
 
         self::assertCount(4, User::findAll());
 
@@ -132,28 +134,27 @@ public function it_deletes_entity(): void
         $user = User::findByPK(1);
         self::assertNotNull($user);
 
-        self::assertTrue($user->delete()->isSuccess());
+        self::assertTrue($user->delete());
         self::assertCount(1, User::findAll());
     }
 
     /**
      * @throws \Throwable
      */
     #[Test]
-    public function it_deletes_multiple_entities_using_remove_method(): void
+    public function it_deletes_multiple_entities_in_single_transaction(): void
     {
+        self::assertCount(2, User::findAll());
+
         /** @var User $userOne */
         $userOne = User::findByPK(1);
         /** @var User $userTwo */
         $userTwo = User::findByPK(2);
 
-        $userOne->remove();
-        $userTwo->remove();
-
-        self::assertCount(2, User::findAll());
-
-        $entityManager = Facade::getEntityManager();
-        self::assertTrue($entityManager->run()->isSuccess());
+        ActiveRecord::transact(static function () use ($userOne, $userTwo) {
+            $userOne->delete();
+            $userTwo->delete();
+        });
 
         self::assertCount(0, User::findAll());
     }
@@ -165,4 +166,35 @@ public function it_gets_default_repository_of_entity(): void
 
         self::assertInstanceOf(Repository::class, $repository);
     }
+
+    #[Test]
+    public function it_runs_transaction_without_actions(): void
+    {
+        $result = ActiveRecord::transact(static function () {
+            return 'foo';
+        });
+
+        self::assertSame('foo', $result);
+    }
+
+    #[Test]
+    public function it_runs_transaction_in_current_transaction_mode_without_opened_transaction(): void
+    {
+        self::expectException(RunnerException::class);
+
+        ActiveRecord::transact(static function () {
+            $user = User::findByPK(1);
+            $user->delete();
+        }, TransactionMode::Current);
+    }
+
+    #[Test]
+    public function it_runs_transaction_in_transaction(): void
+    {
+        self::expectException(TransactionException::class);
+
+        ActiveRecord::transact(static function () {
+            return ActiveRecord::transact(fn () => true);
+        }, TransactionMode::Current);
+    }
 }