README

A powerful Laravel package that implements the Saga Pattern for managing long-running processes and distributed transactions with automatic compensation logic.

Features

🚀 Easy to Use: Simple, intuitive API for defining and executing sagas
🔄 Automatic Compensation: Built-in rollback mechanism when steps fail
📊 Step-by-Step Execution: Sequential execution with progress tracking
🎯 Event-Driven: Rich event system for monitoring saga lifecycle
💾 Persistent State: Database storage for saga state and context
⚡ Retry Logic: Configurable retry attempts for failed sagas
📝 Comprehensive Logging: Detailed logging for debugging and monitoring
🧪 Fully Tested: Comprehensive test suite included

Installation

You can install the package via composer:

composer require eng-mmustafa/laravel-saga-workflow

Publish and run migrations

php artisan vendor:publish --tag="saga-migrations"
php artisan migrate

Publish configuration file (optional)

php artisan vendor:publish --tag="saga-config"

Quick Start

1. Create a Step

First, create a step by extending the AbstractStep class:

<?php

namespace App\Sagas\Steps;

use EngMMustafa\LaravelSagaWorkflow\Core\AbstractStep;

class CreateOrderStep extends AbstractStep
{
    public function handle(array $context): array
    {
        // Your business logic here
        $orderId = $this->createOrder($context['customer_id'], $context['items']);
        
        $this->logInfo('Order created successfully', ['order_id' => $orderId]);
        
        return array_merge($context, ['order_id' => $orderId]);
    }

    protected function doCompensate(array $context): void
    {
        // Compensation logic - rollback the order creation
        if (isset($context['order_id'])) {
            $this->cancelOrder($context['order_id']);
            $this->logInfo('Order cancelled during compensation');
        }
    }

    private function createOrder(int $customerId, array $items): int
    {
        // Your order creation logic
        return Order::create([
            'customer_id' => $customerId,
            'items' => $items,
            'status' => 'pending'
        ])->id;
    }

    private function cancelOrder(int $orderId): void
    {
        Order::find($orderId)?->update(['status' => 'cancelled']);
    }
}

2. Create a Saga

Create a saga by extending the AbstractSaga class:

<?php

namespace App\Sagas;

use EngMMustafa\LaravelSagaWorkflow\Core\AbstractSaga;
use App\Sagas\Steps\CreateOrderStep;
use App\Sagas\Steps\ProcessPaymentStep;
use App\Sagas\Steps\UpdateInventoryStep;
use App\Sagas\Steps\SendConfirmationStep;

class OrderProcessingSaga extends AbstractSaga
{
    protected function defineName(): string
    {
        return 'OrderProcessing';
    }

    protected function defineSteps(): void
    {
        $this->addStep(new CreateOrderStep())
             ->addStep(new ProcessPaymentStep())
             ->addStep(new UpdateInventoryStep())
             ->addStep(new SendConfirmationStep());
    }
}

3. Execute the Saga

Execute your saga using the SagaManager:

<?php

namespace App\Http\Controllers;

use App\Sagas\OrderProcessingSaga;
use EngMMustafa\LaravelSagaWorkflow\Core\SagaManager;
use EngMMustafa\LaravelSagaWorkflow\Exceptions\SagaExecutionException;

class OrderController extends Controller
{
    public function __construct(
        private SagaManager $sagaManager
    ) {}

    public function processOrder(Request $request)
    {
        try {
            // Create saga with initial context
            $saga = new OrderProcessingSaga(context: [
                'customer_id' => $request->customer_id,
                'items' => $request->items,
                'payment_method' => $request->payment_method
            ]);

            // Execute the saga
            $result = $this->sagaManager->execute($saga);

            return response()->json([
                'success' => true,
                'saga_id' => $saga->getId(),
                'result' => $result
            ]);

        } catch (SagaExecutionException $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage(),
                'saga_id' => $e->getSagaId()
            ], 422);
        }
    }

    public function getSagaStatus(string $sagaId)
    {
        $status = $this->sagaManager->getStatus($sagaId);
        
        if (!$status) {
            return response()->json(['error' => 'Saga not found'], 404);
        }

        return response()->json($status);
    }
}

Advanced Usage

Custom Step Configuration

You can create more sophisticated steps with custom configuration:

class PaymentStep extends AbstractStep
{
    public function __construct(
        private PaymentService $paymentService,
        private string $provider = 'stripe'
    ) {
        parent::__construct('ProcessPayment');
    }

    public function handle(array $context): array
    {
        $paymentResult = $this->paymentService->charge(
            $context['amount'],
            $context['payment_method'],
            $this->provider
        );

        if (!$paymentResult->successful) {
            throw new PaymentFailedException('Payment processing failed');
        }

        return array_merge($context, [
            'payment_id' => $paymentResult->id,
            'transaction_id' => $paymentResult->transaction_id
        ]);
    }

    protected function doCompensate(array $context): void
    {
        if (isset($context['payment_id'])) {
            $this->paymentService->refund($context['payment_id']);
        }
    }
}

Event Listeners

Listen to saga events for monitoring and logging:

<?php

namespace App\Listeners;

use EngMMustafa\LaravelSagaWorkflow\Events\SagaStarted;
use EngMMustafa\LaravelSagaWorkflow\Events\SagaCompleted;
use EngMMustafa\LaravelSagaWorkflow\Events\SagaFailed;
use Illuminate\Support\Facades\Log;

class SagaEventListener
{
    public function handleSagaStarted(SagaStarted $event): void
    {
        Log::info('Saga started', [
            'saga_id' => $event->getSagaId(),
            'saga_name' => $event->getSagaName()
        ]);
    }

    public function handleSagaCompleted(SagaCompleted $event): void
    {
        Log::info('Saga completed successfully', [
            'saga_id' => $event->getSagaId(),
            'execution_time' => $event->getTotalExecutionTimeInSeconds()
        ]);
    }

    public function handleSagaFailed(SagaFailed $event): void
    {
        Log::error('Saga failed', [
            'saga_id' => $event->getSagaId(),
            'failed_step' => $event->getFailedStepName(),
            'error' => $event->getErrorMessage()
        ]);
    }
}

protected $listen = [
    SagaStarted::class => [SagaEventListener::class . '@handleSagaStarted'],
    SagaCompleted::class => [SagaEventListener::class . '@handleSagaCompleted'],
    SagaFailed::class => [SagaEventListener::class . '@handleSagaFailed'],
];

Retry Failed Sagas

public function retrySaga(string $sagaId)
{
    try {
        // Recreate the saga instance
        $saga = new OrderProcessingSaga();
        
        // Retry the saga
        $result = $this->sagaManager->retry($sagaId, $saga);
        
        return response()->json(['success' => true, 'result' => $result]);
        
    } catch (SagaExecutionException $e) {
        return response()->json(['error' => $e->getMessage()], 422);
    }
}

Queue Integration

You can easily integrate sagas with Laravel queues:

<?php

namespace App\Jobs;

use App\Sagas\OrderProcessingSaga;
use EngMMustafa\LaravelSagaWorkflow\Core\SagaManager;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class ProcessOrderSaga implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(
        private array $orderData
    ) {}

    public function handle(SagaManager $sagaManager): void
    {
        $saga = new OrderProcessingSaga(context: $this->orderData);
        $sagaManager->execute($saga);
    }
}

Configuration

The package comes with a comprehensive configuration file. Here are the key options:

return [
    'defaults' => [
        'max_retries' => 3,
        'retryable' => true,
        'timeout' => 300,
    ],
    
    'logging' => [
        'enabled' => true,
        'channel' => 'default',
        'log_steps' => true,
        'log_compensation' => true,
    ],
    
    'events' => [
        'enabled' => true,
        'queue_listeners' => false,
    ],
    
    'cleanup' => [
        'enabled' => true,
        'completed_retention_days' => 30,
        'failed_retention_days' => 90,
    ],
];

Available Events

The package dispatches the following events:

SagaStarted - When saga execution begins
SagaStepCompleted - When a step completes successfully
SagaStepFailed - When a step fails
SagaCompleted - When saga completes successfully
SagaFailed - When saga fails and compensation begins

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email eng.mmustafa@example.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see CHANGELOG for more information what has changed recently.# laravel-saga-workflow

eng-mmustafa / laravel-saga-workflow

Maintainers

Details