Download the PHP package padosoft/laravel-flow without Composer

laravel-flow

DX-first workflow / saga / compensation engine for Laravel — with native dry-run, configurable compensation strategies, business-impact projection, opt-in persistence, and audit events. Built for Laravel teams that need dry-run, compensation, and persisted run telemetry inside the app they already operate.

laravel-flow is the third deliverable of the Padosoft v4.0 cycle (W5). It is a community Apache-2.0 package, standalone-agnostic (zero references to AskMyDocs / sister packages), and ships with the Padosoft AI vibe-coding pack so you can extend it with Claude Code or GitHub Copilot in minutes — not days.

Table of contents

• Why this package
• Design rationale
• Features at a glance
• Web admin UI
• Comparison vs alternatives
• Installation
• Quick start
• Usage examples
• Configuration reference
• Architecture
• AI vibe-coding pack
• Testing — Default + Live
• Roadmap
• Contributing
• Security
• License

Why this package

Laravel applications routinely need to orchestrate multi-step business workflows that mix:

• Validations (some safe to skip, some load-bearing).
• Simulations (project the impact of an operation without writing).
• Manual sign-off checkpoints (v0.3 approval gates can now pause, resume, or reject persisted runs; CLI approvals and signed webhook outbox delivery are available).
• Side-effecting writes (DB rows, queue jobs, vendor API calls).
• Compensation chains (when step N fails, undo step N-1 ... step 1).
• Audit trails (regulators want to see who did what, when, with which inputs, in which order).

The Laravel ecosystem has plenty of tools for some of these — Bus::chain() for sequence, jobs for async, transaction() for atomicity — but none of them ship with native dry-run, reverse-order saga compensation, and a single fluent surface that a junior dev can read in 30 seconds.

laravel-flow is that surface.

It is deliberately small. v0.1 is in-memory, synchronous, container-resolved. The current v0.2 foundation adds opt-in DB persistence for runs, steps, and audit rows plus queued dispatch, guarded retry metadata, database queue coverage, terminal-run replay, and opt-in parallel compensation for independent compensators. v0.3 has the approval pause primitive, hashed one-time approval-token issuance, persisted Flow::resume() / Flow::reject() APIs, CLI approvals, and signed webhook outbox delivery. The current v1.0 macro ships the package-side dashboard contracts (FlowDashboardReadModel read service, DashboardActionAuthorizer authorization hook with DenyAllAuthorizer default) so a separate companion app (padosoft-laravel-flow-dashboard, see docs/DASHBOARD_APP_SPEC.md) can build the operator UI on a stable headless surface.

Design rationale

Five non-negotiable choices that drove the API:

1. Dry-run is a first-class flag, not a convention

Every handler can declare ->withDryRun(true). When the engine runs in dry mode, it invokes dry-run-aware steps (so they can project impact) and skips the others, returning dry_run_skipped markers. There is no separate "preview" code path to maintain.

2. Compensation walks backwards by default

Saga semantics: when step N fails, the engine walks the previously-completed steps from N-1 back to 1, calling each registered FlowCompensator. There is no "compensate forward" or "best-effort cleanup" mode — predictable rollback every time.

When all compensators for a flow are independent and idempotent, set compensation_strategy=parallel to batch completed compensators through Laravel Concurrency. Reverse order stays the default because many saga rollbacks depend on undoing the newest side effect first. If the engine is constructed with an isolated/non-global container, or the configured Concurrency driver cannot run, parallel strategy falls back to in-process compensation through the injected container.

3. Handlers and compensators are container-resolved classes

step('persist', PersistPromotion::class) not step('persist', fn () => ...). Closures don't survive serialization (queued workers in v0.2), don't get DI, and don't surface in stack traces. Class-based handlers cost one extra file and pay back tenfold in observability.

4. The audit trail is event-driven

When audit_trail_enabled is enabled, normal-case step and compensation transitions dispatch the matching Laravel event, such as FlowStepStarted, FlowStepCompleted, FlowStepFailed, or FlowCompensated. When persistence is enabled, step events are dispatched only after the matching audit append succeeds, and compensation events are skipped if their audit append fails. The host application subscribes once and routes those events to the logger, DB, or metrics backend it already runs. Persisted flow_audit rows are written only for non-dry-run executions when both persistence and audit_trail_enabled are enabled. Dry-runs never write run, step, or audit rows.

5. Standalone-agnostic — zero AskMyDocs symbols

laravel-flow is a community package. It is not coupled to AskMyDocs, the sister patent-box-tracker, or any other Padosoft project. An architecture test enforces this on every CI run by walking src/ with RecursiveDirectoryIterator and asserting forbidden substrings never appear.

Features at a glance

• Fluent definition builder — Flow::define($name)->withInput([...])->step(...)->register().
• Native dry-run — Flow::dryRun($name, $input) simulates without persisting; supporting handlers project impact, others self-skip.
• Configurable saga compensation — compensateWith(Compensator::class) per step; default reverse-order rollback, plus opt-in parallel batching for independent compensators.
• Audit events and persisted audit rows — normal-case transitions dispatch matching FlowStep* / FlowCompensated events when audit_trail_enabled=true; persisted flow_audit rows are written only for non-dry-run executions with both persistence.enabled=true and audit_trail_enabled=true, and those rows are append-only during normal runtime but retention-prunable with flow:prune.
• Business-impact projection — handlers return businessImpact: [...] alongside output, surfaced on every step result.
• Opt-in persisted execution — flow_runs, flow_steps, and flow_audit migrations, Eloquent repositories, immutable run identity updates, correlation/idempotency keys, transaction-scoped step transitions, atomic step upserts, compensate-first runtime-abort recovery, sanitized listener/error storage, clock-aware audit timestamps, redacted JSON payload storage, and retention pruning.
• Queued dispatch foundation — Flow::dispatch($name, $input, $options) validates the flow and queues an after-commit RunFlowJob with a per-dispatch cache lock plus guarded Laravel-native tries/backoff metadata; sync and database queue paths have package coverage.
• Terminal-run replay — php artisan flow:replay {runId} creates a new persisted run linked to the original via replayed_from_run_id and warns when the current registered definition drifted from stored step metadata.
• Approval gate pause state — approvalGate($name) adds a built-in dry-run-aware step that marks the run paused, emits/persists FlowPaused, and, when persistence is enabled, issues a pending approval record.
• Persisted approval resume/reject API — Flow::resume($token, $payload, $actor) consumes the pending token only while the run is still paused, marks the approval gate succeeded, reconstructs persisted context, and continues downstream steps under a per-run shared cache lock; retries skip downstream steps that already have persisted success rows. Flow::reject($token, $payload, $actor) fails the gate and compensates prior completed steps. Custom persistence backends opt into this API by binding their approval backend to ApprovalRepository, implementing ApprovalDecisionRepository on that approval backend, returning a ConditionalRunRepository from FlowStore::runs(), and applying the package payload redactor consistently for approval decision JSON.
• Hashed approval-token foundation — ApprovalTokenManager issues expiring one-time approval records, persists only SHA-256 token hashes, and consumes approve/reject decisions with redacted actor metadata; the plain token is available only from the returned run at issuance time, while event/audit payloads carry non-secret metadata.
• Signed webhook outbox delivery — lifecycle rows for flow.completed, flow.failed, flow.paused, and flow.resumed are persisted with attempt counts and retry scheduling; php artisan flow:deliver-webhooks signs every payload with an X-Laravel-Flow-Signature header and reschedules transient failures up to a configured retry limit.
• Headless dashboard contracts — FlowDashboardReadModel exposes paginated listRuns, findRun, listApprovals, pendingApprovals, listWebhookOutbox, and aggregated kpis returning immutable DTOs; DashboardActionAuthorizer is the host-app authorization hook with DenyAllAuthorizer registered as the deny-by-default binding (AllowAllAuthorizer ships as an explicit dev opt-in). The companion app spec is at docs/DASHBOARD_APP_SPEC.md.
• Container-resolved handlers — full DI, type hints, and stack traces.
• Strict input validation — withInput(['a','b']) throws FlowInputException if a key is missing.
• Parallel compensation strategy — compensation_strategy=parallel batches completed compensators through Laravel Concurrency when compensators are safe to run without reverse-order dependencies.
• Testbench-friendly — TestCase + stubs ready to copy.
• 🚀 AI vibe-coding pack included — .claude/ directory with skills, rules, agents, commands, and the Padosoft Copilot review loop pre-wired.
• PHP 8.3 / 8.4 × Laravel 13 matrix on every CI run.

Web admin UI

A full-featured web admin panel for laravel-flow is available at padosoft/laravel-flow-admin.

Comparison vs alternatives

Legend: ✅ YES means the capability is first-class in the current product, ⚠️ PARTIAL means it is possible but manual, narrower, or provided through a different model, and ❌ NO means it is not available today.

Competitor snapshot checked against Durable Workflow, Symfony Workflow, Temporal, and AWS Step Functions documentation on 2026-05-05. laravel-flow is deliberately positioned as the lightest Laravel-native dependency in the table. If you already run Temporal or AWS Step Functions and need their queue/replay/redrive guarantees today, use them. If you want saga semantics, dry-run, business-impact projection, opt-in persistence, signed webhook delivery, headless dashboard contracts, and a companion web admin UI inside an existing Laravel app, this is the package.

Installation

Publish the config (optional — the engine works with defaults):

Publish the v0.2 persistence migrations only when you are opting into DB-backed storage:

The in-memory engine path still works without migrations. To persist runtime runs, enable LARAVEL_FLOW_PERSISTENCE_ENABLED=true; dry-runs remain simulation-only and do not write to the database.

Prune old terminal persistence records with the built-in retention command:

flow:prune deletes only terminal runs (succeeded, failed, compensated, aborted) with finished_at older than the cutoff. Matching flow_steps and flow_audit rows are deleted in the same batch transaction; running and pending rows are left untouched. Use LARAVEL_FLOW_RETENTION_DAYS=90 to make --days optional, and --force for non-interactive production runs.

Replay a terminal persisted run as a new linked run:

flow:replay reads the original persisted input and current registered definition, then creates a fresh persisted run with replayed_from_run_id pointing at the original. It does not mutate the original run and refuses to replay pending/running rows. If the stored step names/handlers differ from the current definition, the command warns and still uses the current definition. Redacted persisted input stays redacted during replay.

Requirements

• PHP 8.3+
• Laravel 13.x

Quick start

Usage examples

Correlation and idempotency

When persistence is enabled, correlationId and idempotencyKey are stored on flow_runs. Both values are trimmed, empty strings become null, and non-empty values are limited to 255 characters to match the published migrations. A later persisted execution with the same idempotency key returns the existing run state without executing handlers again. Dry-runs still avoid persistence writes.

Queue dispatch foundation

Flow::dispatch() validates the registered definition and required input before queuing RunFlowJob. The job dispatches after the current database transaction commits and takes a per-dispatch cache lock before execution; duplicate deliveries that find the lock held are released after the smaller of queue.lock_retry_seconds and queue.lock_seconds, while duplicates that arrive after the dispatch completed are acknowledged as no-ops. Configure queue.tries and queue.backoff_seconds to stamp Laravel-native retry metadata into the queued job payload for workers and Horizon. Because async Laravel workers retry the whole RunFlowJob from the beginning, policies that can re-run a flow are rejected until step-level retry semantics are available. The sync queue driver ignores worker retry metadata and remains allowed for local/test dispatches. The worker resolves the current FlowEngine and executes the same definition with the serialized input and execution options. Compensation still defaults to reverse-order rollback; set compensation_strategy=parallel only for flows whose compensators are independent and idempotent.

Approval gates

Approval resume/reject requires persistence and a shared cache store that supports Laravel atomic locks. Custom persistence backends must bind their approval backend to ApprovalRepository, implement ApprovalDecisionRepository on that approval backend for decided-token lookup, run-status-conditional consumes, and one-time pending-token reissue for downstream approval gates, return a ConditionalRunRepository from FlowStore::runs() for paused-run claims, keep the approval backend and FlowStore::runs() on the same durable storage boundary so conditional consumes and paused-run claims observe the same run state, and apply the package payload redactor consistently to approval decision JSON. Backends that delegate approval JSON redaction to laravel-flow can implement RedactorAwareApprovalRepository so Flow::resume() / Flow::reject() inject the same execution-frozen redactor used for step/run writes. The process-local array cache store is rejected for approval decisions because concurrent HTTP/API requests would not share the lock. The decision lock is keyed by run, so retries of older gate tokens serialize with a later gate resume on the same run. The plain token is returned only on the immediate paused run, while flow_approvals stores the current token hash, at most one previous hash for a reissued downstream-gate token, expiry, redacted decision payload, and redacted actor metadata. Custom approval repositories that support downstream token reissue must resolve both current and previous hashes in lookup, consume, and expiry paths so both handed-out tokens remain valid until expiry or decision. If a retry of an older approved token finds the run paused at a later approval gate, Laravel Flow can rotate that later gate's pending token hash once while it is still unexpired, keep the previous hash valid, refresh the paused-step expiry metadata, and return a fresh plain token on the current run. If the per-run lock is already held, old-token retries ask the caller to retry instead of returning a tokenless paused run or reissuing without owning the lock. Flow::resume() marks the approval gate succeeded and continues from the next unfinished step without rerunning prior or already-persisted downstream successes. If a duplicate resume sees that the run is already running, it returns the current persisted state instead of re-entering downstream handlers while another process may still own the side effect. Later steps receive the stored approval payload and stored approval actor metadata, so configured secret keys are redacted before handler context is reconstructed. Flow::reject() records the gate as failed and runs compensators for prior completed steps. Resume reconstructs context from persisted input and step outputs, so values redacted before storage remain redacted after resume.

Signed webhook outbox delivery

flow:deliver-webhooks processes pending rows from flow_webhook_outbox and sends signed HTTP POST payloads to laravel-flow.webhook.url. Each call can be retried with exponential backoff and a configurable attempt cap. Rows are marked delivered, pending (with a future available_at), or failed.

The command requires laravel-flow.webhook.enabled=true and a non-empty valid laravel-flow.webhook.url.

Compensation chain (saga rollback)

Dry-run / impact projection

Subscribing to the audit trail

Configuration reference

When persistence is enabled, synchronous FlowStep* listener or persistence failures are rethrown after the engine records best-effort recovery state and compensates completed steps. FlowCompensated listener failures are swallowed after the compensation audit row is durable so rollback is not interrupted. Wrap Flow::execute() in application-level exception handling anywhere infrastructure outages must be surfaced separately from business step failures.

Custom FlowStore implementations that need the same per-execution PayloadRedactor used by engine error-text sanitization should implement Padosoft\LaravelFlow\Contracts\RedactorAwareFlowStore. The engine calls withPayloadRedactor() once per persisted execution before writing run, step, and audit telemetry; implementations that keep transaction state on the store should return the same instance or a state-sharing decorator. PayloadRedactor decorators that wrap the package execution-scoped redactor should implement Padosoft\LaravelFlow\Contracts\CurrentPayloadRedactorProvider so multi-field repository writes can reuse one stable inner redactor without changing each JSON payload shape.

Architecture

Every box is one PHP class under src/. The engine path is still synchronous and in-memory by default; when persistence is enabled, runtime runs and steps are written to flow_runs and flow_steps for non-dry-run executions. Audit transitions are written to flow_audit only for non-dry-run executions while persistence and audit_trail_enabled are both enabled. Dry-runs never write audit rows. Flow::dispatch() queues an after-commit RunFlowJob with per-dispatch locking, database queue coverage, and guarded Laravel retry/backoff metadata. flow:replay creates new linked runs from terminal persisted input, and compensation_strategy=parallel batches independent compensators through Laravel Concurrency.

Public API surface (v1.0)

The package marks every class with @api (stable, SemVer-covered) or @internal (implementation detail, not covered by SemVer). Public surface:

• Facade: Padosoft\LaravelFlow\Facades\Flow.
• Engine + DTOs: FlowEngine, FlowDefinitionBuilder, FlowDefinition, FlowStep, FlowExecutionOptions, FlowRun, FlowStepResult, FlowContext, IssuedApprovalToken, ApprovalGate, ApprovalTokenManager, WebhookDeliveryClient, WebhookDeliveryResult.
• Hooks: FlowStepHandler, FlowCompensator interfaces.
• Events: every class under Padosoft\LaravelFlow\Events\*.
• Exceptions: every class under Padosoft\LaravelFlow\Exceptions\*.
• Extension contracts: every interface under Padosoft\LaravelFlow\Contracts\* (custom FlowStore, RunRepository, StepRunRepository, AuditRepository, ApprovalRepository, ApprovalDecisionRepository, ConditionalRunRepository, PayloadRedactor, CurrentPayloadRedactorProvider, RedactorAwareFlowStore, RedactorAwareApprovalRepository implementations).
• Dashboard contracts: FlowDashboardReadModel, the read DTOs in Padosoft\LaravelFlow\Dashboard\*, and DashboardActionAuthorizer + the DenyAllAuthorizer / AllowAllAuthorizer bindings.

The tests/Contract/PublicApiContractTest testsuite pins the v1.0 surface so a follow-up patch cannot silently rename or remove an @api class, method, or constant. Internal namespaces (Persistence, Models, Queue, Jobs, Console) may change in any minor release; route consumers through the public contracts instead. See docs/UPGRADE.md for the full SemVer policy and upgrade chain.

Companion dashboard

The package itself is headless — there is no embedded UI. The companion app padosoft/padosoft-laravel-flow-dashboard (separate repo) consumes the dashboard contracts via Composer path repository during development and from Packagist in production. The complete brief for an AI agent or human team building that app is at docs/DASHBOARD_APP_SPEC.md.

AI vibe-coding pack

🚀 Every Padosoft package ships with the same vibe-coding pack — drop the .claude/ directory into Claude Code or GitHub Copilot and you get:

• Skills under .claude/skills/ — reviewer-validated playbooks for copilot-pr-review-loop, pre-push-self-review, test-count-readme-sync, and more.
• Rules under .claude/rules/ — coding standards (type hints, early return, no debug in commits, code structure, naming conventions, PR workflow). For laravel-flow, repo-local rules define the Laravel 13 package baseline and PR workflow.
• Agents under .claude/agents/ — pre-wired sub-agent definitions (admin-interface-architect, playwright-enterprise-tester).
• Commands under .claude/commands/ — slash-command templates (/create-job, /domain-scaffold, /playwright-tester, /pagespeed-review).
• Instructions under .claude/instructions/ — runtime safety guardrails (testing-safety.md).

The pack is the same baseline used across all padosoft/* repos. It is opt-in: delete .claude/ if you don't use Claude Code or Copilot — nothing else depends on it.

Testing — Default + Live

The default phpunit invocation runs only the offline Unit + Architecture testsuites and never makes a network call:

The Live testsuite is opt-in and reserved for v0.2+ scenarios that need a real external dependency (queue worker, webhook receiver). Every Live test self-skips unless LARAVEL_FLOW_LIVE=1 is set:

CI runs Pint (style), PHPStan (level 6), and the Unit + Architecture suites through Composer scripts on the PHP 8.3 / 8.4 × Laravel 13 matrix for pushes to main and PRs targeting main or task/**. PHP 8.5 is intentionally not a hard gate until Laravel/Testbench dependency support is reliable enough for this package.

Roadmap

Contributing

See CONTRIBUTING.md. Community PRs target main; enterprise roadmap work uses the macro/subtask PR loop documented in AGENTS.md.

Security

Report vulnerabilities privately to [email protected] per SECURITY.md. Operational guarantees the package enforces:

• Approval tokens are SHA-256 hashed at rest. The plain token is returned only on the immediate FlowRun at issuance time and is never recoverable from flow_approvals. The dashboard contract takes a token hash, not the plain value, so authorization can run without the secret.
• JSON payload redaction. flow_runs.input/output/business_impact, flow_steps.input/output/business_impact, flow_audit.payload, and flow_approvals.payload/actor pass through the configured PayloadRedactor before storage. Default keys cover common secret-looking fields; the policy is configurable through laravel-flow.persistence.redaction. The dashboard read DTOs (RunDetail, ApprovalSummary) return whatever is stored — host apps that disable persistence.redaction.enabled MUST add their own redaction layer before rendering.
• Webhook payload signing. When webhook.secret is set, every outbox delivery carries X-Laravel-Flow-Signature: t=<unix>,v1=<hmac-sha256> so receivers can verify authenticity. Empty secret disables signing rather than emitting a bogus header.
• Dashboard authorization is deny-by-default. DashboardActionAuthorizer is bound to DenyAllAuthorizer. Production deployments MUST replace the binding with their own RBAC implementation. AllowAllAuthorizer is shipped explicitly for development and never registered automatically.
• Append-only audit at runtime. flow_audit rows cannot be updated or deleted via Eloquent save()/delete(). Bulk update() / delete() / forceDelete() are blocked by a custom Eloquent builder. The flow:prune retention command is the only supported deletion path and is documented as such.
• Run-level locking. Flow::resume() and Flow::reject() claim a per-run shared cache lock to serialize approval decisions. The process-local array cache store is rejected because it cannot synchronize across HTTP / queue workers.
• No secrets in logs or error messages. Engine text-redaction normalises common secret keys across snake_case / kebab-case / camelCase before persisting exception messages.

Enterprise notes

The package is designed to live inside a Laravel application's process and database, not in a separate workflow service. That keeps the operational footprint small (no dedicated workflow cluster) at the cost of cross-language workflows and managed multi-region failover. If you need either, evaluate a managed durable-workflow runtime instead — see docs/MIGRATION_DURABLE.md for the trade-off table.

For teams adopting laravel-flow:

• Use macro branches and subtask PRs documented in AGENTS.md. Every PR requires GitHub Copilot Code Review plus the local Composer-script gates (composer validate --strict --no-check-publish, composer format:test, composer analyse, composer test).
• Bind a custom DashboardActionAuthorizer before exposing the dashboard read model to operators. The default DenyAllAuthorizer is intentional.
• Schedule flow:prune to bound flow_audit and flow_webhook_outbox growth. Retention is the only supported audit-deletion path.
• Schedule flow:deliver-webhooks (e.g. once a minute) when webhook delivery is enabled. The command is idempotent and uses lease-based row claims with a compare-and-set guard, so multiple concurrent workers are safe.
• Configure queue.lock_store to a shared atomic cache (redis, memcached, database, dynamodb) before enabling queued dispatch with multiple workers. The array store is accepted only on the sync queue driver and is rejected for approval decisions.
• Read docs/UPGRADE.md before bumping major versions; v1.0 marked the public-vs-internal contract and SemVer policy.

License

Apache-2.0.

Built by Padosoft — part of the v4.0 ecosystem.