Saga

Ejecuta procesos de varios pasos y, si uno falla a la mitad, deshace los anteriores con su compensación — en orden inverso. El patrón saga, para cuando una operación toca varios servicios y no hay una transacción de base de datos que los abarque a todos.

Un núcleo independiente de framework (solo PHP) con un puente opcional para Laravel (bitácora en Eloquent, eventos, facade).

use Webrek\Saga\Laravel\Facades\Saga;
use Webrek\Saga\SagaContext;

$resultado = Saga::for('checkout', ['order_id' => 42])
    ->step('cobrar',
        fn (SagaContext $c) => $c->set('cargo', $pago->charge($c['order_id'])),
        compensate: fn (SagaContext $c) => $pago->refund($c['cargo']))
    ->step('apartar',
        fn (SagaContext $c) => $inventario->reserve($c['order_id']),
        compensate: fn (SagaContext $c) => $inventario->release($c['order_id']))
    ->step('enviar',
        fn (SagaContext $c) => $envios->create($c['order_id']))   // si esto falla…
    ->run();

// …se libera el inventario y se reembolsa el cargo, automáticamente.
$resultado->isCompleted();   // false
$resultado->status;          // SagaStatus::Compensated

Completa el cuarteto de resiliencia de webrek: entrada (idempotency) · salida (outbox) · dependencias (circuit-breaker) · y coordinación (este).

Instalación

composer require webrek/saga

En Laravel, el service provider se descubre solo. Publica la migración de la bitácora:

php artisan vendor:publish --tag=saga-migrations
php artisan migrate
php artisan vendor:publish --tag=saga-config   # opcional

Cómo corre

Los pasos se ejecutan en orden. Un SagaContext (un saco de datos) se pasa a cada paso: lo que un paso escribe, el siguiente —y las compensaciones— lo leen.

Si un paso lanza una excepción, los pasos ya completados se compensan en orden inverso y la saga termina con uno de tres estados:

Estado	Significado
Completed	Todos los pasos corrieron bien.
Compensated	Un paso falló y todo lo anterior se deshizo limpiamente.
CompensationFailed	Un paso falló y una compensación también — quedó a medias, requiere intervención manual.

El resultado nunca traga la excepción original ($resultado->failure), y los estados CompensationFailed son justo los que conviene vigilar ($resultado->needsAttention()).

La bitácora (Laravel)

Cada corrida se registra en la tabla sagas: nombre, estado, pasos completados, contexto, paso que falló y errores de compensación. Es tu rastro de auditoría y, sobre todo, la forma de encontrar las sagas cuya compensación falló. Cada corrida también dispara un evento (SagaCompleted, SagaCompensated, SagaCompensationFailed).

Desactívala con 'journal' => false en la configuración.

Sin Laravel

use Webrek\Saga\{Saga, SagaRunner, SagaContext};

$saga = new Saga(new SagaRunner);   // sin eventos ni bitácora
$resultado = $saga->for('checkout', ['order_id' => 42])
    ->step('cobrar', $accion, compensate: $compensacion)
    ->run();

Para eventos o persistencia propios, implementa Webrek\Saga\Contracts\EventDispatcher y Webrek\Saga\Contracts\SagaStore y pásalos al SagaRunner.

Alcance

Es una saga de orquestación síncrona, en proceso: corre dentro de tu petición o tu job. No es un two-phase commit ni reintenta pasos por sí sola — si necesitas reintentos, combínalo con la cola de Laravel o con webrek/laravel-circuit-breaker dentro de un paso. Las compensaciones deben ser idempotentes.

Pruebas

composer test

La suite del núcleo (tests/Unit) corre sin framework; la de Laravel (tests/Feature) ejercita la bitácora de Eloquent.

Contribuir

Consulta CONTRIBUTING.md. Corre make check antes de abrir un pull request.

Seguridad

Reporta vulnerabilidades a través del formulario de avisos de seguridad, no como issues públicos. Consulta SECURITY.md.

Licencia

Licencia MIT (MIT). Consulta LICENSE.