Refactor transactions

Nested transactions now are supported directly on Transaction by moving beginTransaction() to Executor instead of Link.

Added onCommit() and onRollback() event hooks to transactions.

Author: trowski

src/Executor.php

@@ -5,6 +5,7 @@
 /**
  * @template TResult of Result
  * @template TStatement of Statement
+ * @template TTransaction of Transaction
  */
 interface Executor extends TransientResource
 {
@@ -32,7 +33,7 @@ public function prepare(string $sql): Statement;
 
     /**
      * @param string $sql SQL query to prepare and execute.
-     * @param mixed[] $params Query parameters.
+     * @param array<int, mixed>|array<string, mixed> $params Query parameters.
      *
      * @return TResult
      *
@@ -43,7 +44,9 @@ public function prepare(string $sql): Statement;
     public function execute(string $sql, array $params = []): Result;
 
     /**
-     * Closes the executor. No further queries may be performed.
+     * Starts a transaction, returning an object where all queries are executed on a single connection.
+     *
+     * @return TTransaction
      */
-    public function close(): void;
+    public function beginTransaction(): Transaction;
 }

src/Link.php

@@ -7,18 +7,14 @@
  * @template TStatement of Statement
  * @template TTransaction of Transaction
  *
- * @extends Executor<TResult, TStatement>
+ * @extends Executor<TResult, TStatement, TTransaction>
  */
 interface Link extends Executor
 {
     /**
-     * Starts a transaction on a single connection.
+     * Sets the transaction isolation level for transactions began on this link.
      *
-     * @param TransactionIsolation $isolation Transaction isolation level.'
-     *
-     * @return TTransaction
+     * @see Executor::beginTransaction()
      */
-    public function beginTransaction(
-        TransactionIsolation $isolation = TransactionIsolationLevel::Committed,
-    ): Transaction;
+    public function setTransactionIsolation(TransactionIsolation $isolation): void;
 }

src/Transaction.php

@@ -5,7 +5,8 @@
 /**
  * @template TResult of Result
  * @template TStatement of Statement
- * @extends Executor<TResult, TStatement>
+ * @template TTransaction of Transaction
+ * @extends Executor<TResult, TStatement, TTransaction>
  */
 interface Transaction extends Executor
 {
@@ -16,6 +17,11 @@ public function getIsolationLevel(): TransactionIsolation;
      */
     public function isActive(): bool;
 
+    /**
+     * @return bool True if this transaction was created inside another transaction using a savepoint.
+     */
+    public function isNestedTransaction(): bool;
+
     /**
      * Commits the transaction and makes it inactive.
      *
@@ -31,29 +37,19 @@ public function commit(): void;
     public function rollback(): void;
 
     /**
-     * Creates a savepoint with the given identifier.
-     *
-     * @param non-empty-string $identifier Savepoint identifier.
+     * Attaches a callback which is invoked when the entire transaction is committed. If this transaction
+     * is a nested transaction, the callback will not be invoked until the top-level transaction is committed.
      *
-     * @throws TransactionError If the transaction has been committed or rolled back.
+     * @param \Closure():void $onCommit
      */
-    public function createSavepoint(string $identifier): void;
+    public function onCommit(\Closure $onCommit): void;
 
     /**
-     * Rolls back to the savepoint with the given identifier.
-     *
-     * @param non-empty-string $identifier Savepoint identifier.
+     * Attaches a callback which is invoked when the transaction is rolled back. If in a nested transaction, the
+     * callbacks may be invoked when rolling back to a savepoint or if the entire transaction is rolled back,
+     * regardless of if the savepoint was released prior.
      *
-     * @throws TransactionError If the transaction has been committed or rolled back.
-     */
-    public function rollbackTo(string $identifier): void;
-
-    /**
-     * Releases the savepoint with the given identifier.
-     *
-     * @param non-empty-string $identifier Savepoint identifier.
-     *
-     * @throws TransactionError If the transaction has been committed or rolled back.
+     * @param \Closure():void $onRollback
      */
-    public function releaseSavepoint(string $identifier): void;
+    public function onRollback(\Closure $onRollback): void;
 }