Orchestrating Chaos: The Saga Pattern in Laravel ⚙️

#laravel #php #architecture #microservices

The Distributed Transaction Nightmare

In a traditional monolithic Laravel application, executing a complex business workflow is simple because everything shares a single database. If a customer submits an e-commerce order, you can deduct the inventory, charge the credit card, and create the shipping label inside a single DB::transaction() block. If the credit card API fails on step two, Laravel automatically rolls back the inventory deduction on step one. The database maintains absolute consistency.

When you transition to a Microservices Architecture, this safety net is completely destroyed. The "Inventory Service", the "Billing Service", and the "Shipping Service" all have their own isolated databases. You can no longer use a standard SQL transaction to wrap the workflow. If the Billing Service charges the card, but the Shipping Service subsequently crashes, how do you undo the credit card charge? You cannot simply issue a MySQL ROLLBACK command across the network.

At Smart Tech Devs, we guarantee absolute data consistency across our distributed microservices by abandoning the traditional Two-Phase Commit (2PC) and implementing the Saga Pattern. A Saga is a sequence of local transactions where each service publishes an event to trigger the next step. If any step fails, the Saga automatically executes a series of Compensating Transactions to undo the preceding work.

Philosophy: Orchestration vs. Choreography

There are two ways to implement a Saga:

Choreography: Every service listens to events and acts independently, like dancers reacting to music. (Service A emits OrderCreated, Service B listens and emits InventoryReserved). This is fast but becomes impossible to monitor in complex workflows.
Orchestration: A central "Manager" service commands the other services, like a conductor leading an orchestra. We heavily favor Orchestration for enterprise billing and checkout flows because it provides a single source of truth for the transaction's state.

Phase 1: Architecting the Saga Orchestrator

Let's build an OrderSagaOrchestrator in Laravel. This class acts as a state machine. It will sequentially command the Inventory, Billing, and Shipping microservices using our Message Broker (e.g., Kafka or RabbitMQ) and wait for their asynchronous responses.

First, we define the state transitions of the Saga in the database.


use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('order_sagas', function (Blueprint $table) {
            $table->uuid('id')->primary();
            $table->uuid('order_id');
            // States: pending, inventory_reserved, billed, completed, compensating, failed
            $table->string('status')->default('pending'); 
            $table->json('payload'); // Stores data passed between services
            $table->timestamps();
        });
    }
};

Phase 2: The Orchestration Logic

When an order is placed, we instantiate the Saga and trigger the first step. The Orchestrator does not do the work itself; it dispatches specific commands to the isolated microservices via the message broker.


namespace App\Sagas;

use App\Models\OrderSaga;
use Illuminate\Support\Facades\Log;
use Junges\Kafka\Facades\Kafka;

class CheckoutSagaOrchestrator
{
    public function startSaga(string $orderId, array $payload): void
    {
        $saga = OrderSaga::create([
            'order_id' => $orderId,
            'status' => 'pending',
            'payload' => $payload
        ]);

        $this->reserveInventory($saga);
    }

    // --- STEP 1: INVENTORY ---
    private function reserveInventory(OrderSaga $saga): void
    {
        // We command the external Inventory Microservice via Kafka
        Kafka::publishOn('inventory-commands')
            ->withBody(['saga_id' => $saga->id, 'items' => $saga->payload['items']])
            ->send();
    }

    public function handleInventoryReserved(string $sagaId): void
    {
        $saga = OrderSaga::findOrFail($sagaId);
        $saga->update(['status' => 'inventory_reserved']);
        
        // Step 1 succeeded. Proceed to Step 2.
        $this->processBilling($saga);
    }

    public function handleInventoryFailed(string $sagaId, string $reason): void
    {
        $saga = OrderSaga::findOrFail($sagaId);
        $saga->update(['status' => 'failed']);
        Log::error("Saga Failed at Inventory: {$reason}");
        // No compensation needed, nothing was committed yet.
    }

    // --- STEP 2: BILLING ---
    private function processBilling(OrderSaga $saga): void
    {
        Kafka::publishOn('billing-commands')
            ->withBody(['saga_id' => $saga->id, 'amount' => $saga->payload['total']])
            ->send();
    }

    public function handleBillingSucceeded(string $sagaId): void
    {
        $saga = OrderSaga::findOrFail($sagaId);
        $saga->update(['status' => 'billed']);
        
        // Step 2 succeeded. Proceed to Step 3.
        $this->createShippingLabel($saga);
    }
}

Phase 3: Architecting Compensating Transactions (The Rollback)

What happens if the Billing step fails? The customer's card is declined. However, the Inventory Service has already permanently reserved the items in its isolated database during Step 1. We must execute a Compensating Transaction to undo that specific step.


// Inside CheckoutSagaOrchestrator...

    public function handleBillingFailed(string $sagaId, string $reason): void
    {
        $saga = OrderSaga::findOrFail($sagaId);
        $saga->update(['status' => 'compensating']);
        Log::warning("Saga Failed at Billing. Initiating Rollback. Reason: {$reason}");

        // We must command the Inventory Service to UNDO the reservation
        $this->compensateInventory($saga);
    }

    private function compensateInventory(OrderSaga $saga): void
    {
        Kafka::publishOn('inventory-compensations')
            ->withBody(['saga_id' => $saga->id, 'items' => $saga->payload['items']])
            ->send();
    }

    public function handleInventoryCompensationCompleted(string $sagaId): void
    {
        $saga = OrderSaga::findOrFail($sagaId);
        $saga->update(['status' => 'failed']);
        Log::info("Saga successfully rolled back and safely aborted.");
    }

The Engineering ROI and Eventual Consistency

Architecting the Saga pattern requires a massive paradigm shift in how your engineering team views data integrity. You must accept that your distributed system will be Eventually Consistent. For a few milliseconds, the inventory might be reserved while the billing is pending, but the Saga guarantees that the system will mathematically resolve itself into a consistent final state—either fully completed or perfectly rolled back.

By implementing a centralized Orchestrator, you achieve ultimate visibility into complex enterprise workflows. When a transaction stalls, you can query the order_sagas table and instantly see exactly which microservice is holding up the process. This pattern allows your independent microservices to maintain complete database autonomy while ensuring your platform's most critical financial and operational workflows are bulletproof and deeply resilient to network failures.

DEV Community