feat: add transaction lifecycle callbacks

[memleakd]

Introduction

Hello! I’d like to propose a small database-layer primitive for transaction-aware side effects.

This came up as a concrete need in one of my CodeIgniter 4 projects, where jobs, notifications, events, cache invalidation, and cleanup should happen only after a transaction has actually committed or rolled back.

I kept the implementation intentionally narrow: no queue integration, event dispatcher behavior, outbox abstraction, or configuration surface. Since I am new to contributing here, please treat this as an initial proposal, and apologies in advance if this has already been discussed, rejected, or does not fit the current roadmap.

Description

This PR adds database transaction lifecycle callbacks to database connections:

• afterCommit() runs callbacks after the outermost transaction successfully commits.
• afterRollback() runs callbacks after the outermost transaction rolls back.
• Callbacks registered for the opposite outcome are discarded.
• afterCommit() runs immediately when no transaction is active.
• afterRollback() is a no-op when no transaction is active.
• Callback exceptions bubble to the caller after the database transaction has already reached its final state.

Motivation

Application code can currently perform side effects inside a transaction, but that can be unsafe when the transaction later rolls back. For example, an application may dispatch a queued job, send a notification, publish an event, clear a cache entry, or trigger an external integration before the data it depends on is actually committed.

This can lead to race conditions or inconsistent behavior, such as:

• A queued job runs before the committed row is visible.
• A notification is sent for data that later rolls back.
• A cache entry is invalidated even though the write did not persist.
• Cleanup code runs even though the transaction eventually commits.

By adding transaction lifecycle callbacks to the database layer, applications and future framework libraries can safely defer these side effects until after the outermost transaction commits or rolls back.

Use Cases

Common use cases include:

• Dispatching a queued job only after the database write it depends on has committed.
• Sending a notification only after a transaction succeeds.
• Publishing an application/domain event after committed data is visible.
• Invalidating or warming cache entries after a successful commit.
• Running cleanup logic only after a real rollback.
• Supporting future framework features that need transaction-aware side effects.

Behavior Notes

Callbacks are tied to the outermost transaction. Nested transaction callbacks do not run until the outermost transaction commits or rolls back.

Only callbacks for the final transaction outcome run: commit discards rollback callbacks, and rollback discards commit callbacks.

If a callback throws, the exception bubbles to the caller after the database transaction has already committed or rolled back, so the callback exception does not change the database outcome.

Testing

Added live database tests covering commit callbacks, rollback callbacks, nested transactions, callback exceptions, and automatic rollback behavior.

Checklist

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value (without duplication)
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide