Download the PHP package discovery-ukraine/saga-lara-flow without Composer

Saga Lara Flow is a workflow management engine with an integrated Saga pattern, built on top of Laravel Queues.

It lets you write a long-running, durable business process as a single deterministic PHP method: each step runs, is recorded, and survives worker restarts through exception-based suspension and replay. When a step fails partway through, registered compensations roll back the completed work in reverse order.

It is inspired by Durable Workflow (formerly Laravel Workflow), but it is not a replacement for it. Saga Lara Flow positions itself as a lighter, native-Laravel alternative: no Fibers, generators, or promises — just queues, an event log, and Eloquent.

📚 Full documentation: sagalaraflow.dev

If ReserveStock or ShipOrder fails, RefundCard (and any other registered compensation) runs automatically, in reverse order.

Table of contents

• Installation
• Configuration
• Your first workflow
• Actions
• Sagas & compensations
• Signals
• Retry on signal
• Side effects
• Parallel actions
• Optional actions
• Child workflows
• Tags & querying
• Expiration & monitoring
• Queues, locks & idempotency
• Synchronous execution
• Versioning long-running workflows
• Octane & multi-tenancy
• Determinism rules
• Events
• Artisan commands
• Testing your workflows

Installation

Install the package via Composer:

Run the migrations:

The engine's migrations ship with the package, so migrate picks them up directly — no publish step. Future versions add their migrations the same way: composer update then php artisan migrate.

Always migrate after an upgrade. The engine writes its newest columns for every action it schedules, so upgrading without php artisan migrate breaks ordinary workflow execution with an unknown-column error — not just the newest feature. See UPGRADING.md.

Optionally publish the config file:

Customize the schema through config — database.table_prefix, database.connection, and the swappable models.* — rather than by editing the migration. (The migration runs automatically; do not also vendor:publish it, or migrate would try to run both the published copy and the package's own.)

Requirements: PHP ^8.5, Laravel 13 (illuminate/*: ^13). The package registers its service provider and the SagaFlow facade automatically.

Configuration

Every setting lives in config/saga-lara-flow.php. The most common ones:

• Dedicated database connection. database.connection (env SAGA_LARA_FLOW_DB_CONNECTION) keeps the engine's tables on their own connection; null uses the app default. database.table_prefix (default saga_) prefixes every table, and is capped at 24 bytes — it rides along in every index name, and PostgreSQL truncates an identifier past 63 bytes while MySQL refuses one past 64 characters.
• Swappable models. Every row model under models.* can be pointed at your own subclass.
• Queue. queue.connection / queue.queue control where workflow and action jobs run; queue.after_commit dispatches after the surrounding DB transaction commits.
• Locks. locks.* configure the WithoutOverlapping middleware that serializes concurrent drives of a single run. workflow_ttl_seconds / action_ttl_seconds / block_seconds are in seconds. See Queues, locks & idempotency.
• Monitor. monitor.expiration.defaults set implicit deadlines (seconds) for run / action / signal — null means no default. See Expiration & monitoring.
• Sagas / parallel / children. Default compensation, failure, and close policies.
• Tenancy. tenancy.* hooks, named by class so config:cache works — see Octane & multi-tenancy.

Your first workflow

Generate a workflow and an action:

A workflow is a class extending Workflow with a deterministic handle(). A workflow author never news an action — they schedule it through the DSL, and the engine runs, records, and replays it for you:

An action is a unit of work with native Laravel dependency injection:

Start it:

Actions

action(string $actionClass, mixed ...$arguments) returns an ActionBuilder; run() executes it and returns the action's result. Arguments passed here are forwarded to the action's handle() after its injected dependencies.

Retries and timeouts use native Laravel queue semantics — declare them on the action:

A per-step deadline (independent of the queue timeout) is set on the builder:

run() throws when the action ultimately fails, so a workflow can react to it:

Two things about when this throws:

• It surfaces on replay, not the instant the action fails. In queued mode the action runs in its own job, off the handle() stack, and retries per $tries. Once it ultimately fails the engine re-drives handle() from the top and the failed step replays as a throw — that is where your try/catch catches it. In sync mode the step runs inline and run() re-throws the action's raw exception (not ActionFailedException), so catch the concrete type you expect.
• Use try/catch for local branching — "if ChargeCard fails, try PayPal instead". For a cross-cutting "report whenever any workflow fails", listen to the FlowFailed event (Events) instead: it fires once on the terminal transition — on both the direct-fail and the fail-after-compensation paths, and regardless of sync/queued. If you do report from inside a catch in handle(), re-throw afterwards so the engine still fails and compensates the run; swallowing the exception lets handle() run on past a step that has no result.

⚠️ Never catch DiscoveryUkraine\SagaLaraFlow\Exceptions\Internal\FlowSuspended (or any InternalFlowControl) — those are the engine's suspend/replay signals, not errors. Business exceptions (ActionFailedException, FlowExpiredException, ChildWorkflowFailedException, …) all extend FlowException and are safe to catch; the two internal signals live under …\Exceptions\Internal\ and are the only things a broad catch (\Throwable $e) must re-throw: if ($this->isFlowControl($e)) { throw $e; }.

Sagas & compensations

The Saga pattern trades distributed transactions for compensating actions: each step registers how to undo itself, and on failure the engine rolls completed steps back in reverse order.

Action-level compensation (the primary style) attaches an undo to each step:

Compensation can also be a closure:

Grouped sagas via saga() express a compensation boundary explicitly and give you group-level policies:

CompensationFailurePolicy::Stop (default) halts the rollback on the first failed compensation; Continue presses on. Precedence for policies is action > group > config. If a compensation itself fails under Stop, a CompensationFailedException surfaces.

Signals

Signals let external code push data or decisions into a running workflow. Inside handle(), awaitSignal() blocks the workflow (by suspending it) until the named signal arrives, then returns its payload:

A timeout turns an unanswered wait into a catchable exception:

A deadline does not enforce itself: the package has no durable timers, so an unanswered wait only times out once the expiration sweep notices — see Expiration & monitoring below. Until then the wait stays open, however long the deadline has been past.

Deliver a signal from anywhere via the handle:

A signal is accepted only by a run that can still consume one — Pending, Running or Waiting. signal() throws CannotSignalTerminalFlowException on a finished run and CannotSignalCancellingFlowException on one that is rolling back; both extend CannotSignalFlowException. A refusal writes nothing.

No $runId? Find the run by workflow and tag, then signal it. Use signalable() (alias active()), not running() — a flow parked on awaitSignal() is Waiting, not Running:

Retry on signal

A step that fails hard takes the whole run with it: the saga rolls back and completed work is undone. retryOnSignal() parks such a step instead — the run waits, nothing rolls back, and when the named signal arrives only that step runs again:

Deliver balance-refilled the way you deliver any other signal and ChargeCard runs again, alone; earlier steps stay completed and un-compensated. The layers stack: Laravel's $tries first, then retryOnSignal(), then continueOnFailure(), then hard failure and compensation. When the budget is spent, the wait times out, or the policy refuses the failure, the step fails exactly as it would have without the policy — same ActionFailedException, same rollback.

A policy worth naming goes in a class instead, and the call site takes the object:

Nothing about the policy is persisted — it is rebuilt by handle() on every replay — and it decides whether to park, not whether to wake: an already-parked step spends its cycle when the signal arrives. The predicate must stay a pure function of its RetryContext; writing to the run it is deciding for raises RetryPolicyReentryException.

A retry consumes no new sequence: the step reuses its own ordinal and action_runs row, so downstream steps land identically whether it retried or not. saga()->step() mirrors the method.

saga-flow:list annotates a parked run with the signal it needs, saga-flow:show gains a Retry column, and two events (ActionAwaitingRetry, ActionRetried) cover the lifecycle.

Side effects

Anything non-deterministic (random values, now(), a UUID, an external read) must be wrapped in sideEffect() so replay reuses the recorded value instead of computing a new one:

The first execution records the value; every later replay of the run returns the same stored value. A factory is not called once the run is rolling back: the seam reads the run's status from the connection that wrote it and ends the pass first, so host code does not run outside a plan that is already being unwound. The same holds for a child workflow started at a new ordinal. See Statuses.

Parallel actions

parallel() runs several actions concurrently (as queued jobs, or inline under runSync) and returns their results as a list:

->waitAllThenFail() lets every step settle before the block fails; failFast() (the config default, ParallelFailurePolicy::FailFast) short-circuits on the first hard failure. Steps in a parallel block can carry their own compensations and optionalAction().

Optional actions

An optional action never fails the flow — its failure is swallowed and a fallback is returned:

You can also mark it declaratively with #[ContinueOnFailure] on the action class.

Child workflows

A workflow can start another workflow and await its result. The child inherits the parent's connection, queue, and tenant context:

Close policies: Abandon (default — leave the child running), Cancel (cancel it), Fail (fail it). A failing child throws ChildWorkflowFailedException (or ChildWorkflowCancelledException) unless you call ->continueParentOnFailure(). The default close policy is configurable (children.default_close_policy) or per class via #[ChildPolicy].

child() is also the only seam that runs another workflow from inside handle(). SagaFlow::create(...) there takes no ordinal, so the run it starts is recognized by nothing, and the next replay starts another one.

Tags & querying

Attach searchable key/value tags at creation, from inside the workflow, or from outside through a FlowHandle:

Tag keys written from outside should not collide with keys the workflow writes in handle(): a workflow $this->tag('x', ...) re-runs on every replay and would overwrite the host value.

Query runs with the fluent, type-safe FlowQuery:

Status shortcuts: running(), waiting(), completed(), failed(), plus active() / signalable() (Pending, Running, or Waiting) for finding a run to deliver a signal to.

Terminals: get(), first(), count(), paginate(), handles(), and builder() (the raw Eloquent builder for ordering/limits).

Expiration & monitoring

Runs, actions, and signal waits can carry deadlines — either explicitly (->expiresAt(...), ->timeoutAfter(...)) or via the configured defaults in monitor.expiration.defaults. Something has to notice an expired deadline; there are two ways to drive that sweep:

Scheduler (recommended). Run the monitor on a schedule:

Queue looping (opt-in). Drive the sweep off the queue worker's idle loop by enabling monitor.queue_looping.enabled (throttled by throttle_seconds). Useful when you have no cron but always-on workers.

If neither is running, no deadline is ever enforced — queue:work alone does not check them. And because the sweep is the only writer of "this deadline passed", deadlines are approximate: a signal delivered after its deadline but before the next sweep is still accepted. Both points are expanded in Expiration & monitoring.

For runs whose progress was lost to a dropped job (rather than a deadline), the doctor can re-dispatch missing actions (repair.redispatch_lost_actions) and re-wake stuck waits (repair.wake_stuck_flows) — enable repair.enabled and either schedule saga-flow:repair or loop it off the worker (repair.queue_looping.enabled), or kick a single run manually with saga-flow:kick {run} / SagaFlow::kick($id). A kick refills the repair budget that repair.max_attempts caps and sends the sequential step the run is parked on its own job back, so the cap holds the automatic pass off rather than ending the run's recovery. Each config key is documented in Expiration & monitoring.

None of these drives a run that is rolling back or finished — a pass begins only for a run that may still start work, so a deadline is enforced once and each compensation on the rollback it planned runs once. A pass already replaying when the rollback commits starts nothing further either: its next step is refused at the claim, and a child workflow or side effect at an ordinal it has not reached before ends the pass instead. The plan that is unwound is drawn once the run is already rolling back, so a step whose owed attempt completed while an earlier plan was being drawn is compensated too. See Statuses.

Queues, locks & idempotency

Every workflow and action runs as a queued job on the configured connection/queue. A run is driven by replaying handle() from the recorded history; each operation is identified by a deterministic (flow_run_id, sequence) pair, so a step that has completed and recorded its result is never repeated — it is reused from history. The WithoutOverlapping locks (locks.*, TTLs and waits in seconds) serialize concurrent drives of the same run so two workers can't advance it at once.

This is not automatic end-to-end idempotency. The reuse guarantee covers recorded steps only — it does not make the work inside an action idempotent. If a job hangs, is retried, or dies after performing its external effect (charging a card, calling an API) but before recording its result, that effect can happen more than once. End-to-end idempotency depends on your action code: use an idempotency key, prefer upserts, or check whether the effect already happened. The (flow_run_id, sequence) pair makes a stable idempotency key to hand downstream. See Queues, locks & idempotency.

Synchronous execution

runSync() drives the whole workflow in-process, using the same single replay loop as the queued path — handy for tests, tinkering, or short workflows:

The queued and synchronous paths are guaranteed to reach the same final database state.

Never call it inside a DB::transaction() of your own. The steps run while your transaction is open, so a rollback afterwards discards every row of the run while the work those rows describe is already done. The same holds for signal(), cancel() and compensate(); only the queued run() is safe. See Queues, locks & idempotency.

Versioning long-running workflows

A workflow may be suspended for days while its code keeps shipping. To change a running workflow's logic without breaking in-flight runs, keep versions in separate classes/directories (App\Workflows\V1\CheckoutWorkflow, App\Workflows\V2\CheckoutWorkflow) and pin a version at creation:

Read the pinned version inside handle() with $this->version(); existing runs keep replaying against the class they were created with.

Octane & multi-tenancy

The engine runs each workflow/action handle() in the tenant the run was created for and reverts afterwards, so nothing leaks between runs on a shared Octane or queue worker.

• Capture at creation. SagaFlow::create(...) snapshots the current tenant via the tenancy.capture hook onto flow_runs.tenancy_context. Child runs inherit the parent's context.
• Auto-restore is opt-in. Off by default (tenancy.auto). When on, the engine calls tenancy.restore before handle() and reverts in a finally (via tenancy.end, or by restoring the previous context). Override per class with #[Tenancy(auto: true)] (precedence: attribute > config).
• Manual discovery. Even with auto off, read the run's tenant inside handle(): SagaFlow::tenancyContext() returns ['tenant' => '…'] or null.

Each hook is an invokable class name or a [Class::class, 'method'] pair, resolved from the container — write the class with its full namespace, since the config file imports nothing. A hook that cannot be called throws InvalidTenancyHookException; only null turns one off. A closure works too, but php artisan config:cache refuses a config that holds one.

See the multi-tenancy docs for a full stancl/tenancy integration example.

Determinism rules

handle() is replayed from the start on every resume, so it must be deterministic:

• ✅ Do call actions, child workflows, signals, and parallel blocks through the DSL — their results are recorded and reused on replay.
• ✅ Do wrap any nondeterminism (now(), random, UUIDs, direct DB/HTTP reads) in sideEffect().
• ❌ Don't branch on ambient state that can change between replays (wall-clock time, rand(), external reads) outside a sideEffect().
• ❌ Don't raise the engine's own business exceptions (ActionFailedException, AwaitSignalTimeoutException, …) yourself — a rollback is planned by replaying handle(), and only a seam that read the run's history may end that replay with one.
• ❌ Don't catch the engine's control-flow exceptions (FlowSuspended) as if they were errors.

Break a rule and the history contract guard raises HistoryContractMismatchException when the replay diverges from the recorded history.

Events

The engine mirrors its flow_events log onto Laravel events you can listen to — e.g. FlowStarted, FlowCompleted, FlowFailed, FlowWaiting, FlowCancelled, ActionCompleted, ActionFailed, CompensationCompleted, ChildWorkflowCompleted, SideEffectRecorded, and more (see src/Events). Register listeners as usual:

FlowCancelled carries an optional ?string $reason, populated when you call $handle->cancel('reason here').

Two events have no flow_events counterpart. A worker that finishes a step whose row has moved on has its outcome refused, and ActionOutcomeRejected / CompensationOutcomeRejected carry what it produced — the value the step returned, in the form the row would have stored, or the throw the engine deliberately does not rethrow. The work is done and nothing local records it, so the payload reaches somewhere you chose rather than nowhere. See Events.

Artisan commands

These are CLI only — the package exposes no HTTP routes.

Testing your workflows

Under test, the queued paths must run against a real database queue driven with queue:work --stop-when-empty — the sync driver bypasses the suspend/replay machinery and won't exercise the engine faithfully. runSync() is fine for asserting final state directly:

For queued assertions, set the queue to the database connection, dispatch with ->run(), then drain the queue before asserting. The package's own suite (tests/) is a working reference.

When should I use Durable Workflow instead?

Saga Lara Flow is intentionally a lighter, Laravel-native package. It is focused on queues, Eloquent, an event log, replay, signals, child workflows, and first-class Saga compensations inside a single Laravel application.

If you need a more complete workflow engine — SDK-neutral or polyglot workers, standalone/external workers, Fiber-based execution, strict workflow-definition fingerprinting, worker compatibility fleets, sticky execution, durable timers, schedules, control-plane APIs, rich projections/observability, search attributes, memos, history export/import, replay verification, external payload storage, history budgets, or Temporal/Cadence-style operations — you should evaluate Durable Workflow instead.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Andriy Karpishyn
• All Contributors

License

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