Distributed Transactions: The Saga Pattern in Laravel 🎻

#laravel #php #microservices #architecture

The Distributed Transaction Dilemma

When you build a modular monolith or a microservice architecture, your business logic spans across multiple distinct domains or external services. Consider an e-commerce platform processing a new order. The system must perform three distinct actions: reserve inventory, process a Stripe payment, and generate a shipping label. In a traditional monolith sharing a single database, this is trivial: you wrap all three operations in a single DB::transaction(). If the shipping label fails, the database automatically rolls back the inventory reservation.

But what happens when Inventory, Billing, and Shipping are isolated microservices, or rely on slow external APIs? You cannot wrap HTTP calls to Stripe and FedEx inside an ACID relational database transaction. If you reserve the inventory and charge the credit card, but the shipping service crashes, you have a massive data inconsistency. The customer was billed, but the item will never ship. This is the nightmare of Distributed Transactions.

At Smart Tech Devs, we prevent distributed data corruption by implementing the Saga Pattern. A Saga is a sequence of local transactions. Each local transaction updates the database and publishes a message or event to trigger the next local transaction. Most importantly, if any local transaction fails, the Saga executes a series of Compensating Transactions that undo the changes made by the preceding steps.

Choreography vs. Orchestration

There are two ways to implement a Saga: Choreography (events bouncing between services, like a dance) and Orchestration (a central controller directing the services, like a maestro). For complex enterprise logic in Laravel, we heavily favor Orchestration because it provides a single source of truth for the transaction's state, making it vastly easier to debug and monitor.

Phase 1: Architecting the Saga Steps

We begin by defining a strict contract. Every step in our Saga must have two actions: an execute() method to perform the work, and a compensate() method to logically undo that work.


namespace App\Sagas\Contracts;

interface SagaStep
{
    public function execute(array $payload): array;
    
    /**
     * The compensation must be completely idempotent.
     * It might be called multiple times in a network failure scenario.
     */
    public function compensate(array $payload): void;
}

Now, let's implement the Billing step. If the execution charges the card, the compensation must issue a refund.


namespace App\Sagas\Steps;

use App\Sagas\Contracts\SagaStep;
use App\Services\StripeService;

class ProcessPaymentStep implements SagaStep
{
    public function __construct(private StripeService $stripe) {}

    public function execute(array $payload): array
    {
        $charge = $this->stripe->charge($payload['user_id'], $payload['amount']);
        
        // Pass the charge ID forward so the compensation step knows what to refund
        $payload['charge_id'] = $charge->id;
        return $payload;
    }

    public function compensate(array $payload): void
    {
        if (isset($payload['charge_id'])) {
            $this->stripe->refund($payload['charge_id']);
        }
    }
}

Phase 2: Building the Orchestrator

The Orchestrator is the heart of the pattern. It iterates through an array of defined steps. If a step throws an exception, it stops moving forward, reverses the array of completed steps, and meticulously executes their compensation logic in reverse order.


namespace App\Sagas;

use Exception;
use Illuminate\Support\Facades\Log;

class SagaOrchestrator
{
    private array $completedSteps = [];

    public function __construct(private array $steps) {}

    public function execute(array $initialPayload): bool
    {
        $payload = $initialPayload;

        foreach ($this->steps as $step) {
            try {
                // 1. Attempt to execute the current step
                $payload = $step->execute($payload);
                
                // 2. Track successful steps for potential rollback
                $this->completedSteps[] = clone $step;

            } catch (Exception $e) {
                // 3. A step failed! Halt execution and begin compensation.
                Log::error("Saga step failed. Initiating compensation.", ['exception' => $e]);
                $this->compensate($payload);
                return false;
            }
        }

        return true; // The entire distributed transaction succeeded
    }

    private function compensate(array $payload): void
    {
        // Reverse the completed steps to undo them in Last-In-First-Out (LIFO) order
        $stepsToRollback = array_reverse($this->completedSteps);

        foreach ($stepsToRollback as $step) {
            try {
                $step->compensate($payload);
            } catch (Exception $e) {
                // Compensation failure is a critical architectural alert.
                // This typically requires manual human intervention.
                Log::critical("CRITICAL: Saga compensation failed!", [
                    'step' => get_class($step),
                    'payload' => $payload,
                    'exception' => $e
                ]);
            }
        }
    }
}

Phase 3: Executing the Order Saga

With our architecture in place, the previously terrifying process of distributed order processing becomes a clean, readable, and highly resilient workflow inside our controller or job.


namespace App\Http\Controllers;

use App\Sagas\SagaOrchestrator;
use App\Sagas\Steps\ReserveInventoryStep;
use App\Sagas\Steps\ProcessPaymentStep;
use App\Sagas\Steps\GenerateShippingLabelStep;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        $orchestrator = new SagaOrchestrator([
            app(ReserveInventoryStep::class),
            app(ProcessPaymentStep::class),
            app(GenerateShippingLabelStep::class)
        ]);

        $success = $orchestrator->execute([
            'order_id' => $request->order_id,
            'user_id' => $request->user()->id,
            'amount' => 150.00,
            'items' => $request->items
        ]);

        if (!$success) {
            return response()->json(['error' => 'Order failed. You have not been charged.'], 500);
        }

        return response()->json(['message' => 'Order successfully processed!']);
    }
}

The Engineering ROI and Eventual Consistency

Adopting the Saga Pattern fundamentally shifts how you design enterprise backends. You stop trying to force impossible physical database locks across the internet, and instead embrace logical rollbacks and Eventual Consistency. By wrapping your third-party API calls and microservice interactions in an orchestrated Saga, you guarantee that your application will never leave a customer in a "half-processed" state. If the shipping API goes down during Black Friday, the orchestration seamlessly catches it, issues an automated refund via the compensation step, un-reserves the inventory, and gracefully informs the user, maintaining absolute data integrity across your entire distributed ecosystem.