Download the PHP package juststeveking/workflow-engine without Composer

Workflow Engine

A signal-driven, step-based workflow engine for Laravel.

Most of the interesting logic in a Laravel application is not a single request. It is a process that unfolds over hours or days, and spends most of that time waiting on something it does not control. A payment provider. A human clicking a link in an email. A cron tick three days from now.

The usual approach is to bolt a few booleans onto a model and let the flow emerge from whatever code happens to fire next. It works for a week. Then the logic ends up smeared across a controller, two listeners, a webhook handler, and a scheduled command, and nobody can answer the only question support ever asks: where is this stuck, and why?

This package lets you model those processes as an ordered sequence of steps. Each step does one thing and then tells the engine what happens next: complete, pause and wait for a named signal, sleep for a while, jump somewhere else in the sequence, or fail. Instances are persisted as database rows, driven forward by queued jobs, and resumed by signals arriving from outside. There is one place that describes the process, and one durable row per run that can answer where it is.

The part I care most about is that the lifecycle is a declarative, enforced state machine rather than a diagram in a doc, so an instance cannot end up in an impossible state. That is the strongest guarantee here, and it has its own page: the state machine.

What it looks like

A workflow is an ordered list of steps. A step does one thing, then tells the engine what happens next:

Start it, and let it wait. No worker is held open, no request is blocked. The instance is a database row parked on a signal:

There are four complete, copy-pasteable workflows in examples/ if you would rather read code than prose.

The mental model

Seven nouns, and they fit on a napkin:

The important detail is what the engine does not do. It never runs your whole workflow in one call. It runs exactly one step, persists the result, and queues a job for the next one if there is more to do. Awaiting and sleeping steps stop entirely until a signal arrives or the wake time passes. Nothing is held open, so a workflow that waits three days costs you a database row and nothing else.

When to reach for it

Reach for it when there is waiting in the process, when you need to know exactly which step an instance is parked on and why it failed, or when you are about to stitch something together from listeners, scheduled jobs, and status columns.

Do not reach for it for a synchronous sequence with no waiting and no failure branching, for pure fan-out event handling (Laravel events are already good at that), or for a single background job that happens to have a few lines in it. A workflow engine earns its keep when the process is long-lived. Otherwise it is ceremony.

Installation

The service provider is auto-discovered and the package loads its own migrations:

If you want to customise the schema or the config, publish them first:

Two tables get created. workflow_instances holds one row per run. workflow_signals is an append-only log of every signal delivered, including buffered ones and timeouts. Configuration lives in config/workflow-engine.php; the configuration reference walks through every key.

Quickstart

1. Define your steps and a workflow

Read the two maxAttempts() values back to back and you can see the design decision in each step. Charging a card is not safe to repeat, so it gets one attempt. Provisioning an account is idempotent on our side, so it gets three. That choice belongs next to the code that makes it, which is why it lives on the step rather than in a config file.

2. Register the workflow

Typically in a service provider's boot():

3. Start an instance and drive it

4. Resume it when the signal arrives

That is the entire loop. Everything else is detail, and it lives in the docs.

Documentation

Full documentation is in docs/. Start here:

• The state machine, the enforced lifecycle and why an instance cannot reach an impossible state
• Concepts, the seven nouns and the aggregate
• Defining steps, the step contract, StepResult, and the context
• Control flow, branching with goto and delaying with sleep
• Signals, awaiting, early buffering, and webhook delivery
• Timeouts and retries
• Failure and compensation, saga rollback and resume
• Versioning, deploying safely with in-flight instances
• Events
• Running on the queue
• Console commands
• Concurrency guarantees
• Custom persistence
• Configuration
• Exceptions
• Testing

Architecture decisions are recorded in docs/adr/.

Requirements

• PHP ^8.3
• Laravel 12 or 13. The package depends on the individual illuminate/* components (bus, console, contracts, database, queue, support) rather than the whole laravel/framework
• A configured queue and a running worker for production use
• A database supporting transactions and row locking, which is any standard Laravel SQL driver

License

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