Download the PHP package meius/laravel-transaction-orchestrator without Composer

Laravel Transaction Orchestrator

Declarative transactions and row-level locks for Laravel 11+ via PHP attributes. Annotate controller methods with #[Transactional] — get transactions with retries/backoff and HTTP-aware rollback. Annotate parameters with #[LockForUpdate] / #[SharedLock] — get row-locks directly during route model binding. Zero boilerplate.

Internally it uses the standard Laravel/Eloquent API: lockForUpdate() and sharedLock(). Support = whatever Laravel and your DB driver support.

Table of Contents

• Features
• Requirements & DB Support
• Installation
• Quick Start
• Attribute Reference
  • #[Transactional]
  • #[LockForUpdate] and #[SharedLock]
• Retries & Backoff
• HTTP-Aware Rollback
• Multiple Connections
• Nested Transactions
• Limitations
• License

Features

• #[Transactional] — wrap controller actions in a transaction, optionally with retries and backoff.
• Rollback policy based on HTTP response (4xx/5xx/specific codes).
• Exceptions that do not trigger rollback (noRollbackOn).
• #[LockForUpdate] / #[SharedLock] on action parameters — row-lock during route model binding.
• Zero config: service provider and router decoration auto-registered.

Requirements & DB Support

• PHP 8.2+
• Laravel 11+

Row lock support is fully delegated to Laravel/Eloquent:

• MySQL/MariaDB — FOR UPDATE / FOR SHARE (or LOCK IN SHARE MODE on older versions).
• PostgreSQL — FOR UPDATE / FOR SHARE (or FOR KEY SHARE depending on context).
• SQL Server — via hints (UPDLOCK, ROWLOCK), same as Laravel does.
• SQLite — no row-level lock for SELECT (effectively no-op).

If your driver/version doesn’t support the mode, behavior matches Laravel.

Installation

1. Composer Installation:
   Install the package using Composer:

2. Register the Service Provider:
   Manually register the service provider by adding it to your bootstrap/providers.php file:

Quick Start

Attribute Reference

Transactional

Purpose: run the controller method inside transaction(s).

Parameters & behavior:

• connection: null|string|string[].
  • null → default from config/database.php.
  • Normalized to array at runtime → $connections.
• retries: how many times to retry on transient DB errors (deadlock, lock timeout, disconnect, etc.).
• backoff: delay in ms before retry.
  • Single number = constant delay.
  • Array = per-attempt delay, last value repeats.
• noRollbackOn: list of exception FQCNs that do not trigger rollback.
• rollbackOnHttpError: rollback policy based on HTTP response: ROLLBACK_NONE, ROLLBACK_ON_4XX, ROLLBACK_ON_5XX, ROLLBACK_ON_4XX_5XX(default), or list of codes ([409, 422]).

Validation (constructor enforces):

• backoff as array → must be list<int>.
• rollbackOnHttpError as array → must be list<int>.
• noRollbackOn → must be Throwable subclasses.

Transaction outcome:

• Exceptions are not swallowed. Any unhandled exception → rollback (unless in noRollbackOn).
• If no exception: commit/rollback decided by the Response and policy.

LockForUpdate and SharedLock

Purpose: apply row-lock to action parameter during route model binding.

How it works:

• Before resolving the parameter, the router checks the attribute and applies the standard Eloquent lock (lockForUpdate() or sharedLock()) just once.
• Lock does not leak into other queries inside the method.
• SQL and semantics depend on your DB driver/version (see Requirements).

Example:

Retries & Backoff

• Enabled when retries > 0.
• Transient errors include common concurrency/connection issues.
• backoff in ms. Example [10, 30, 70] → values applied per attempt, last repeated.

With retries enabled, make operations idempotent (or dedupe-safe). The package does not enforce idempotency.

HTTP-Aware Rollback

Rollback can be triggered by response status without exceptions:

• Validation → 422 → rollback.
• Resource conflict → 409 → rollback.
• Any 5xx → rollback (default).

Customize via policy or code list:

Decision is made after action returns a Response, before sending body.

Multiple Connections

connection accepts an array:

• Opens a transaction for each connection.
• On error/rollback condition — all are rolled back.
• This is not 2PC (no cross-DB atomicity).

Nested Transactions

• If you call DB::transaction() inside, Laravel uses savepoints (if supported).
• Outer #[Transactional] decides final commit/rollback.
• Do not mix manual commit()/rollBack() with orchestrator — use DB::transaction().

Limitations

• Lock behavior depends on DB driver/version; package follows Laravel exactly.
• Locks apply only during route model binding. Queries inside method are unaffected.
• No 2PC across DBs.
• Retries ≠ idempotency: duplicate side effects are your responsibility.

License

This package is open-sourced software licensed under the MIT license.