Installation
Require the package, publish its config and migrations with the install command, and migrate. The service provider and the Workflows facade alias are auto-discovered, together with the providers of the Roundly packages it builds on — crypto (idempotency digests), enums and package-toolkit:
composer require roundly-consulting/workflows-for-laravel roundly-consulting/approvals-for-laravel
php artisan workflows:install # publishes config/workflows.php and the eight migrations
php artisan vendor:publish --tag="approvals-migrations" # approvals powers the approval step in the example below
php artisan migrateworkflows:install refuses to run when any of the package’s tables already exists. It prints the scheduler lines and the subject-registration hint. Migrations are publish-only (never auto-loaded) and forward-only.
approvals-for-laravel powers the approval step in the example below; leave it and its migrations out if you don’t need approvals. Without it, publishing a graph with an approval step fails adapter_missing.
1. Settle the key types before migrating
The polymorphic columns are sized at migration time. With bigint ids everywhere the defaults fit; with UUID or ULID keys, set them before php artisan migrate:
# Before php artisan migrate — bigint, uuid or ulid
WORKFLOWS_KEY_TYPE=bigint # user morphs: started_by, published_by, requested_by
WORKFLOWS_OWNER_KEY_TYPE= # owner morphs; blank = WORKFLOWS_KEY_TYPE
WORKFLOWS_SUBJECT_KEY_TYPE= # subject morphs; blank = WORKFLOWS_KEY_TYPE
WORKFLOWS_PRIMARY_KEY_TYPE=bigint # the package's own idsA model whose key does not fit the configured type is refused before any SQL with InvalidWorkflowsConfigurationException naming the key — PostgreSQL never answers with a raw “invalid input syntax”. workflows:doctor checks this too.
2. Schedule wake and prune
Delays, timeouts, retries, escalations and schedules wake on the scheduler. Nothing is scheduled automatically — without this line a delay never ends:
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('workflows:wake')->everyMinute()->withoutOverlapping(10)->onOneServer();
Schedule::command('workflows:prune')->daily();workflows:wake fires due timers, retries, wait timeouts, condition polls, escalations and schedule triggers, reclaims expired leases and re-pushes lost jobs. onOneServer() needs a cache store shared by every server (redis, database, memcached, dynamodb). Correctness never depends on it — every claim is a compare-and-set.
3. Run a queue worker
With workflows.queue.enabled on (the default) each step runs as a job — RunStepJob, ResumeStepJob, FireEscalationJob; ids only, tries = 1, dispatched after commit. The job timeout is engine.lease − 30 s (570 s by default): the queue connection’s retry_after must be longer than that, and the worker needs pcntl to enforce it. Laravel’s default database connection has retry_after 90 s, so a fresh app raises it — or lowers engine.lease if every step is short. workflows:doctor fails on a too-short retry_after and warns without pcntl. With the queue off, steps run inline in the request that starts or resumes them, through a trampoline (no recursion), bounded by limits.max_steps.
# A step job may run for up to 570 s (engine.lease − 30 s): retry_after must be longer.
DB_QUEUE_RETRY_AFTER=600 # Laravel's default database queue (90 s otherwise)
REDIS_QUEUE_RETRY_AFTER=600 # the redis queue
php artisan workflows:doctor # fails on a too-short retry_after4. Register a subject type and use the trait
A subject is the model an instance is about. Register each type once, in a service provider’s boot():
// AppServiceProvider::boot()
use RoundlyConsulting\Workflows\Facades\Workflows;
Workflows::subjects()->register(
Workflows::subject('purchase_request', PurchaseRequest::class)
->label('Purchase request')
->ownedBy('team')
->field('amount', 'decimal', 'Amount')
->field('requester', 'party', 'Requester'),
);use RoundlyConsulting\Workflows\Traits\HasWorkflows;
class PurchaseRequest extends Model
{
use HasWorkflows; // $request->workflows(), touch on update, cancel on delete
}5. Define, publish and start a workflow
use RoundlyConsulting\Workflows\Facades\Workflows;
use RoundlyConsulting\Workflows\Graph\Build\{Party, Trigger, When};
// Once, in a service provider: what a purchase request looks like to the engine.
Workflows::subjects()->register(
Workflows::subject('purchase_request', PurchaseRequest::class)
->label('Purchase request')
->ownedBy('team')
->field('amount', 'decimal', 'Amount')
->field('requester', 'party', 'Requester')
->field('approver', 'party', 'Approver'),
);
// The workflow itself is data: a JSON graph your users edit in a builder — or written in PHP.
$definition = Workflows::definitions()->create(key: 'purchase-approval', name: 'Purchase approval',
subjectType: 'purchase_request', owner: $team);
Workflows::definition('purchase-approval', $team)->edit(Workflows::graph() // or ->edit(json_decode($json, true))
->trigger('start', Trigger::manual())
->condition('check', When::field('subject.amount')->gt('500'))
->approval('approve', approvers: [Party::field('subject.approver')])
->end('done')
->connect('start', 'check')
->connect('check', 'approve', on: 'true')
->connect('check', 'done', on: 'false')
->connect('approve', 'done', on: ['approved', 'rejected', 'expired']));
Workflows::definition('purchase-approval', $team)->publish(by: $admin);
// Start it (this graph's trigger is `manual`) — with an `event` trigger the app event starts it instead.
$result = Workflows::start('purchase-approval', subject: $request, owner: $team)
->by($request->requester)
->idempotencyKey("submit:{$request->id}")
->dispatch();
$result->instance->status; // InstanceStatus::Running — a queue worker runs it on to the approval step, where it waitsPublish tags
| Tag | Publishes |
|---|---|
workflows-config | config/workflows.php |
workflows-migrations | The eight migrations, timestamped on publish. |
workflows-translations | lang/vendor/workflows/{en,sk} |
workflows-routes | The opt-in inbound webhook route file. |
php artisan vendor:publish --tag="workflows-config" # config/workflows.php
php artisan vendor:publish --tag="workflows-migrations" # the eight migrations, timestamped on publish
php artisan vendor:publish --tag="workflows-translations" # lang/vendor/workflows/{en,sk}
php artisan vendor:publish --tag="workflows-routes" # the opt-in inbound webhook route fileTables
| Table | Holds |
|---|---|
workflow_definitions | Named workflows per owner: key, name, subject type key, status, current version, webhook id. |
workflow_versions | Numbered graph snapshots: graph, trigger, actor, settings, checksum, review flags, publisher. |
workflow_instances | Runs: version, owner, subject, trigger, status, current node, failure, parent and depth. |
workflow_step_runs | The step log: one row per attempt of a visit, with input, output, outcome, error and lease. |
workflow_waits | Timers, events, condition polls, retries and timeouts the engine wakes on. |
workflow_escalations | The next pending escalation level of each waiting visit. |
workflow_idempotency_keys | Start and effect keys, stored as digests. |
workflow_dry_runs | Logged dry runs (only with ->log() or dry_run.log on). |
Table names are configurable (workflows.tables.*); every column is listed under Database.
Translations
English and Slovak ship under the workflows:: namespace — enums, exceptions, failures, fields, steps and validation. Step labels, validation messages, failure messages and enum labels all translate.
Check the setup
php artisan workflows:doctor # --json for CI and health checks, --strict to fail on warnings
php artisan about --only=workflows # step types, bridges, queue mode, key types, limits, webhooksphp artisan about shows a Workflows section: the number of step types, installed bridges, the queue mode, the four key types, the limits and whether the webhook route is on.
Upgrading to 1.4
One additive migration, 0009_add_failure_details_to_workflow_tables, adds two nullable json columns: workflow_step_runs.error_details and workflow_instances.failure_details. Re-publishing leaves your published migrations alone and adds only the new file:
php artisan vendor:publish --tag="workflows-migrations" # adds 0009_add_failure_details_to_workflow_tables
php artisan migrateUntil it runs, failures still record as before — the package writes the columns only when a step gives details — but a step that does give details would fail its write, so run the migration before you ship one. workflows:doctor warns (schema) while the columns are missing. Nothing else changes for existing code, except that InstanceResource failure and StepRunResource error now always carry a details key (null for every earlier failure), so a client comparing the whole object must expect it. Data you encoded into failure codes (my_code:<reason>:<id>) belongs in details now.
Upgrading to 1.3
No migration of this package. Two things to check:
- approvals-for-laravel ≥ 2.2. With approvals installed, Composer now requires 2.2 (conflict <2.2). Approvals 2.2 ships an additive migration, 0008_add_decision_guards_to_approvals_tables. Rounds without an approval step’s new exclude never write its columns, so it is only required before you publish a step with exclude.
- Notify steps now file inbox items under the instance owner. With notifications installed, notify steps and notify escalations pass the instance owner as the notifications context (workflows.bridges.notifications.context, default owner). Inbox filters by context — Notifications::inbox($user)->in($team) — now see workflow notifications, and items of an owned instance no longer collapse with context-less ones in the same window. To keep the 1.2 behaviour, set WORKFLOWS_NOTIFICATIONS_CONTEXT=off.
# with approvals-for-laravel installed: 2.2 is now required
composer update roundly-consulting/approvals-for-laravel
php artisan vendor:publish --tag="approvals-migrations" # adds 0008_add_decision_guards_to_approvals_tables
php artisan migrate
# keep notify steps context-less, as in 1.2
WORKFLOWS_NOTIFICATIONS_CONTEXT=offNew in 1.3.0, all opt-in: per-owner dynamic fields (see Subjects, owners and parties), an approval step’s exclude (see Bridges to other packages), paused owners (see The engine) and Workflows::owners()->export() (see Definitions and versions).
Upgrading to 1.2.1
1.2.1 fixes a fresh php artisan migrate with workflows.primary_key_type set to uuid or ulid on PostgreSQL: create_workflow_instances_table failed with SQLSTATE[42830] (no unique constraint matching the referenced table) because the parent_instance_id foreign key was created before the primary key it points at. bigint ids and MySQL were never affected.
Already published the migrations? Your copy in database/migrations is the broken one. Copy the fixed file over it, keep your file’s name, then migrate:
# overwrite your published copy, keep its file name
cp vendor/roundly-consulting/workflows-for-laravel/database/migrations/0003_create_workflow_instances_table.php database/migrations/<timestamp>_create_workflow_instances_table.php
php artisan migrateDon’t re-run vendor:publish --tag=workflows-migrations: your copy no longer matches the package file, so it would publish a second copy with a new timestamp. If you already moved the self-reference into its own Schema::table() call, keep it — the schema is the same.
Upgrading from 1.0.0
No migration and no config change. Check three things:
- The queue connection’s retry_after must be above the 570 s step job timeout (DB_QUEUE_RETRY_AFTER=600 for the database queue) — run workflows:doctor, which fails otherwise.
- Graphs with an approval step need approvals-for-laravel: require it and publish its migrations (approvals-migrations) before migrating.
- Workflows::emit() no longer throws when one matching definition refuses to start: the others still start and the refusal is listed in EmitResult::$failed. Code that caught that exception should read $result->failed instead.
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.