feat(database): refine transaction callback API

Signed-off-by: memleakd <[email protected]>

Author: memleakd

system/Database/ConnectionInterface.php

@@ -115,6 +115,24 @@ public function query(string $sql, $binds = null);
      */
     public function simpleQuery(string $sql);
 
+    /**
+     * Register a callback to run after the outermost transaction commits.
+     *
+     * @param callable(): void $callback
+     *
+     * @return $this
+     */
+    public function afterCommit(callable $callback): static;
+
+    /**
+     * Register a callback to run after the outermost transaction rolls back.
+     *
+     * @param callable(): void $callback
+     *
+     * @return $this
+     */
+    public function afterRollback(callable $callback): static;
+
     /**
      * Returns an instance of the query builder for this connection.
      *

tests/system/Database/Live/TransactionCallbacksTest.php

@@ -70,6 +70,22 @@ public function testAfterCommitRunsAfterSuccessfulTransactionCommit(): void
         $this->assertSame(['committed'], $callbacks);
     }
 
+    public function testAfterCommitRunsAfterManualTransactionCommit(): void
+    {
+        $callbacks = [];
+
+        $this->db->transBegin();
+        $this->db->afterCommit(static function () use (&$callbacks): void {
+            $callbacks[] = 'committed';
+        });
+
+        $this->assertSame([], $callbacks);
+
+        $this->db->transCommit();
+
+        $this->assertSame(['committed'], $callbacks);
+    }
+
     public function testAfterCommitDoesNotRunAfterTransactionRollsBack(): void
     {
         $callbacks = [];
@@ -157,6 +173,22 @@ public function testAfterRollbackRunsAfterTransactionRollsBack(): void
         $this->assertSame(['rolled back'], $callbacks);
     }
 
+    public function testAfterRollbackRunsAfterManualTransactionRollback(): void
+    {
+        $callbacks = [];
+
+        $this->db->transBegin();
+        $this->db->afterRollback(static function () use (&$callbacks): void {
+            $callbacks[] = 'rolled back';
+        });
+
+        $this->assertSame([], $callbacks);
+
+        $this->db->transRollback();
+
+        $this->assertSame(['rolled back'], $callbacks);
+    }
+
     public function testAfterRollbackDoesNotRunAfterSuccessfulTransactionCommit(): void
     {
         $callbacks = [];

user_guide_src/source/changelogs/v4.8.0.rst

@@ -195,7 +195,7 @@ Testing
 Database
 ========
 
-- Added ``afterCommit()`` and ``afterRollback()`` transaction callbacks to database connections. These callbacks run after the outermost transaction commits or rolls back.
+- Added ``afterCommit()`` and ``afterRollback()`` transaction callbacks to database connections. These callbacks run after the outermost transaction commits or rolls back. See :ref:`transactions-transaction-callbacks`.
 - Added ``trustServerCertificate`` option to ``SQLSRV`` database connections in ``Config\Database``. Set it to ``true`` to trust the server certificate without CA validation when using encrypted connections.
 
 Query Builder

user_guide_src/source/database/transactions.rst

@@ -111,6 +111,8 @@ If you want an exception to be thrown when a query error occurs, you can use
 If a query error occurs, all the queries will be rolled backed, and a
 ``DatabaseException`` will be thrown.
 
+.. _transactions-transaction-callbacks:
+
 Running Code after Commit or Rollback
 =====================================
 
@@ -131,6 +133,16 @@ If the transaction commits, ``afterCommit()`` callbacks run and
 If no transaction is active, ``afterCommit()`` callbacks run immediately, while
 ``afterRollback()`` callbacks are not run.
 
+For example:
+
+.. literalinclude:: transactions/011.php
+
+.. note:: When ``afterCommit()`` is called outside an active transaction, it runs
+    immediately. This includes calls from Model ``beforeInsert`` or
+    ``beforeUpdate`` events when the calling code has not already started a
+    transaction, so the callback may run before the Model's insert or update
+    query is executed.
+
 This is useful for side effects that should only happen after committed data is
 visible, such as dispatching a queued job or sending a notification, and for
 cleanup that should only happen after a real rollback.
@@ -139,6 +151,10 @@ Callbacks run after the database transaction has already committed or rolled
 back. If a callback throws an exception, that exception bubbles to the caller,
 but the transaction outcome is not changed.
 
+.. warning:: When multiple callbacks are registered for the same transaction
+    outcome, they run in registration order. If one callback throws an exception,
+    the subsequent callbacks are not run.
+
 Rollback callbacks also run when CodeIgniter automatically rolls back an active
 transaction while handling a transaction failure or cleaning up an unfinished
 transaction.

user_guide_src/source/database/transactions/011.php

@@ -0,0 +1,5 @@
+<?php
+
+$this->db->afterCommit(static function (): void {
+    // Runs immediately because there is no active transaction.
+});