README

A visual, configurable workflow engine for Laravel. Define circuits (workflow definitions), baskets (steps), and transitions — then move any Eloquent model through them with a clean Facade API.

Comes with a built-in visual admin interface to design your workflows by drag-and-drop.

Features

• Visual workflow designer — drag-and-drop baskets, draw transitions, configure actions
• Facade & helper — Workflow::for($model)->transition($basketId) or workflow($model)->transition($basketId)
• Multi-circuit — a model can belong to multiple workflows, scoped with in($circuit)
• Resource locking — prevent concurrent access with lock() / unlock()
• Role-based access — define allowed roles per circuit and per basket
• Transition actions — attach actions (email, webhook, log, require documents, custom) to transitions
• Duration tracking — automatic timing between steps with human-readable formatting
• Full history — every transition is logged with who, when, how long, and why
• Message templates — WYSIWYG editor with variable interpolation
• Export / Import — share workflows as JSON files + PNG image export
• Dark mode — the admin UI supports light and dark themes
• Zero build step — the admin UI uses Alpine.js + Tailwind CDN, no npm required

Requirements

• PHP 8.3+
• Laravel 12 or 13

Installation

composer require maestrodimateo/laravel-workflow

Publish the config and migrations:

php artisan vendor:publish --tag=workflow-config
php artisan vendor:publish --tag=workflow-migrations
php artisan migrate

Optionally publish the views to customize the admin UI:

php artisan vendor:publish --tag=workflow-views

Quick Start

1. Add the trait to your model

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Model;
use Maestrodimateo\Workflow\Traits\Workflowable;

class Invoice extends Model
{
    use HasUuids, Workflowable;
}

When an Invoice is created, it's automatically placed in the DRAFT basket of the circuit targeting it.

2. Open the visual designer

Navigate to /workflow/admin in your browser. From there you can:

• Create a circuit (workflow) targeting your model
• Add baskets (steps) with colors and roles
• Draw transitions (links) between baskets by dragging from one to another
• Configure actions on each transition (send email, call webhook, etc.)

3. Transition models in your code

use Maestrodimateo\Workflow\Facades\Workflow;

// Get current status
$basket = Workflow::for($invoice)->currentStatus();
echo $basket->name;   // "Brouillon"
echo $basket->status; // "DRAFT"

// See available next steps
$options = Workflow::for($invoice)->nextBaskets();

// Transition
Workflow::for($invoice)->transition(
    $nextBasket->id,
    'Approved by manager',  // optional comment
);

The workflow() helper is also available:

workflow($invoice)->currentStatus();
workflow($invoice)->transition($basketId);

Facade API Reference

All methods are available via Workflow:: or workflow()->.

Model-bound methods

These methods require Workflow::for($model) first:

$wf = Workflow::for($model);

Static methods

These methods don't require for():

Role-based queries

These methods don't require for():

// Circuits accessible to a role
Workflow::circuitsForRole('manager');
Workflow::circuitsForRoles(['admin', 'manager']);

// Baskets accessible to a role (optionally scoped to a circuit)
Workflow::basketsForRole('validator');
Workflow::basketsForRole('validator', $circuitId);
Workflow::basketsForRoles(['admin', 'operator'], $circuitId);

Eloquent scopes are also available directly:

use Maestrodimateo\Workflow\Models\Circuit;
use Maestrodimateo\Workflow\Models\Basket;

Circuit::forRole('admin')->get();
Basket::forRoles(['admin', 'manager'])->get();

$basket->hasRole('validator'); // true/false
$circuit->hasRole('admin');    // true/false

Duration Tracking

Every transition automatically records the time spent in the previous step:

$history = Workflow::for($invoice)->history();

foreach ($history as $entry) {
    echo $entry->previous_status;  // "DRAFT"
    echo $entry->next_status;      // "REVIEW"
    echo $entry->duration_seconds; // 3600
    echo $entry->duration_human;   // "1h"
    echo $entry->done_by;          // User ID
    echo $entry->comment;          // "Sent for review"
}

// Total time
$seconds = Workflow::for($invoice)->totalDuration();

// Time in a specific step
$reviewTime = Workflow::for($invoice)->durationInStatus('REVIEW');

Human-readable formats: 45s, 12min, 2h 35min, 3j 4h.

Multi-Circuit Support

A model can belong to multiple circuits simultaneously. Use in() to scope operations:

// Scope to a specific circuit
Workflow::for($invoice)->in($approvalCircuit)->currentStatus();
Workflow::for($invoice)->in($complianceCircuit)->transition($basketId);
Workflow::for($invoice)->in('circuit-uuid')->history();

// See status in ALL circuits at once
$statuses = Workflow::for($invoice)->allStatuses();
// [
//     'circuit-a-id' => ['circuit' => Circuit, 'basket' => Basket],
//     'circuit-b-id' => ['circuit' => Circuit, 'basket' => Basket],
// ]

// List circuits the model belongs to
$circuits = Workflow::for($invoice)->circuits();

When a model is created, it's automatically attached to the DRAFT basket of every circuit targeting its class.

Resource Locking

Prevent multiple operators from working on the same model simultaneously:

// Lock the model (default: 30 minutes)
Workflow::for($invoice)->lock();
Workflow::for($invoice)->lock(60); // 1 hour

// Check lock status
Workflow::for($invoice)->isLocked();       // true
Workflow::for($invoice)->isLockedByMe();   // true
Workflow::for($invoice)->lockedBy();       // "user-uuid"
Workflow::for($invoice)->lockExpiration(); // Carbon instance

// Transition (auto-checks the lock)
Workflow::for($invoice)->transition($basketId);
// → OK if you hold the lock (lock is released after transition)
// → ModelLockedException if locked by someone else

// Release manually
Workflow::for($invoice)->unlock();

// Admin force unlock
Workflow::for($invoice)->unlock(force: true);

Query scopes

// Available models (not locked or lock expired)
Invoice::fromBasket($reviewBasket)->unlocked()->get();

// Models I'm working on
Invoice::lockedBy(auth()->id())->get();

Handling lock exceptions

use Maestrodimateo\Workflow\Exceptions\ModelLockedException;

try {
    Workflow::for($invoice)->transition($basketId);
} catch (ModelLockedException $e) {
    return back()->withErrors([
        'lock' => $e->getMessage(),
        // "Ce dossier est verrouillé par [user] jusqu'à [14:30]."
    ]);
}

Configure the default lock duration in .env:

WORKFLOW_LOCK_DURATION=30  # minutes

Transition Actions

Actions are executed automatically when a specific transition occurs. They are configured visually in the admin UI.

Built-in actions

Transaction behavior

Every transition() is wrapped in a single DB transaction (model move, history insert, lock release). Each action runs in one of three modes depending on which marker interface it implements:

• In transaction (default) — the action runs inside the transition transaction. A thrown exception rolls back the entire transition. Use this for validations (e.g., require_document) or DB writes that must be atomic with the transition.
• After commit (AfterCommitAction) — the action runs inline once the transition has been committed to the database. Use this for fast non-rollbackable side effects (logging, in-memory cache invalidation) where queueing would be overkill.
• Queued (QueueableAction) — the action is wrapped in a job and dispatched after commit, executed by a queue worker. Use this for slow or external side effects (HTTP calls, email, third-party APIs) so the request returns immediately and transient failures can be retried by the worker.

SendEmailAction and WebhookAction implement QueueableAction. LogTransitionAction implements AfterCommitAction. RequireDocumentAction runs inline — its throw must be able to abort the transition.

Custom actions

Generate a new action with artisan:

php artisan make:workflow-action GeneratePdfAction

This creates app/Workflow/Actions/GeneratePdfAction.php:

use Maestrodimateo\Workflow\Contracts\TransitionAction;

class GeneratePdfAction implements TransitionAction
{
    public static function key(): string { return 'generate_pdf'; }
    public static function label(): string { return 'Generate Pdf'; }

    public function execute(Model $model, Basket $from, Basket $to, array $config = []): void
    {
        // Your logic here
    }
}

Register it in your AppServiceProvider::boot():

Workflow::registerAction(GeneratePdfAction::class);

The action immediately appears in the admin UI's "Add action" menu on any transition.

Opting an action out of the transaction

If your custom action produces an external side effect that cannot be rolled back (HTTP call, email, push notification, third-party SDK), add the AfterCommitAction marker so it only runs once the transition is safely committed:

use Maestrodimateo\Workflow\Contracts\AfterCommitAction;
use Maestrodimateo\Workflow\Contracts\TransitionAction;

class NotifySlackAction implements TransitionAction, AfterCommitAction
{
    public static function key(): string { return 'notify_slack'; }
    public static function label(): string { return 'Notify Slack'; }

    public function execute(Model $model, Basket $from, Basket $to, array $config = []): void
    {
        Http::post($config['webhook_url'], [
            'model' => $model->getKey(),
            'to'    => $to->status,
        ]);
    }
}

Validation-style actions (those that may throw to abort the transition) should NOT implement AfterCommitAction — their exception needs to roll back the transition, which is only possible from inside the transaction.

Running an action on a queue

For slow side effects (HTTP calls, email, third-party APIs), implement QueueableAction instead. The action is wrapped in a job and dispatched after commit, so the request returns immediately and the worker picks it up:

use Maestrodimateo\Workflow\Contracts\QueueableAction;
use Maestrodimateo\Workflow\Contracts\TransitionAction;

class NotifySlackAction implements TransitionAction, QueueableAction
{
    public static function key(): string { return 'notify_slack'; }
    public static function label(): string { return 'Notify Slack'; }

    // Return null to use the package default (workflow.actions_queue.queue),
    // then Laravel's default queue.
    public static function queue(): ?string { return 'notifications'; }

    // Same fallback chain for the queue connection.
    public static function connection(): ?string { return null; }

    public function execute(Model $model, Basket $from, Basket $to, array $config = []): void
    {
        Http::post($config['webhook_url'], [
            'model' => $model->getKey(),
            'to'    => $to->status,
        ]);
    }
}

What you get for free:

• Race-free dispatch — the job is sent inside DB::afterCommit(), so the worker can never read the transition's rows before they're visible.
• Fresh state on the worker — the subject, source and target baskets are serialized by reference (SerializesModels) and re-fetched from the DB when the job runs.
• Automatic retries — Laravel's queue worker handles retries, backoff, and failed-jobs storage like any other job.

Override the queue and connection globally via .env:

WORKFLOW_ACTIONS_QUEUE=workflow
WORKFLOW_ACTIONS_QUEUE_CONNECTION=redis

With QUEUE_CONNECTION=sync (the Laravel default), queueable actions run inline on the request — useful for local development without a running worker. Switching to redis, database, or sqs is enough to move them off the request lifecycle; no code change required.

A QueueableAction already runs after commit — you don't need to also implement AfterCommitAction.

Events

A TransitionEvent is fired after every transition. Add your own listeners:

// In your EventServiceProvider
protected $listen = [
    \Maestrodimateo\Workflow\Events\TransitionEvent::class => [
        \App\Listeners\NotifySlack::class,
        \App\Listeners\SyncWithExternalSystem::class,
    ],
];

public function handle(TransitionEvent $event): void
{
    $event->currentBasket; // Source basket
    $event->nextBasket;    // Target basket
    $event->model;         // The transitioned model
    $event->comment;       // Transition comment
}

What happens during a transition

1. Lock guard — throws ModelLockedException if locked by another user
2. DB transaction opens
   a. Model detached from current basket, attached to next
   b. In-transaction actions executed (e.g. require_document — may throw and rollback)
   c. TransitionEvent fired → HistoryListener records history with duration
   d. Lock released
3. DB transaction commits
4. After-commit actions executed inline (log, any AfterCommitAction)
5. Queueable actions dispatched to the queue (send_email, webhook, any QueueableAction)
6. Your custom listeners run

Message Templates

Messages are created at the circuit level and can be used in transition actions (e.g., send_email).

The WYSIWYG editor supports variable interpolation:

Bonjour, la demande {{ reference }} a été transférée de {{ from_name }}
vers {{ to_name }} par {{ user }} le {{ datetime }}.

Built-in variables

Custom variables

// config/workflow.php
'message_variables' => [
    'reference' => fn ($model) => $model->reference,
    'montant'   => fn ($model) => number_format($model->amount, 2, ',', ' ') . ' €',
],

Export / Import

In the admin UI

• Export JSON — download the full circuit definition as a .json file
• Export PNG — download a high-resolution image of the workflow diagram
• Import — select a .json file to recreate a circuit with all its configuration

Via API

GET  /workflow/admin/api/circuits/{circuit}/export
POST /workflow/admin/api/circuits/import  # multipart form, field: "file"

Programmatic import (seeders, commands)

Import a previously exported JSON file directly from code — no HTTP request needed:

use Maestrodimateo\Workflow\Facades\Workflow;

// In a seeder
Workflow::importFromJson(database_path('seeders/workflow-invoices.json'));

// Or via the manager directly
app(\Maestrodimateo\Workflow\WorkflowManager::class)::importFromJson($path);

The method creates the full circuit (baskets, transitions, messages) inside a database transaction and returns the newly created Circuit instance with all relations loaded.

Throws \InvalidArgumentException if the file is missing or has an invalid format.

Configuration

// config/workflow.php
return [
    'routes' => [
        'prefix'           => 'workflow',
        'middleware'        => ['api'],
        'admin_middleware'  => ['web'],
    ],
    'auth_identifier' => 'id',
    'message_variables' => [],
    'actions' => [],
    'actions_queue' => [
        'queue' => env('WORKFLOW_ACTIONS_QUEUE'),           // null → Laravel's default queue
        'connection' => env('WORKFLOW_ACTIONS_QUEUE_CONNECTION'), // null → Laravel's default connection
    ],
    'lock' => [
        'duration_minutes' => 30,
    ],
];

Workflowable Trait

The Workflowable trait adds relations, methods, and scopes directly on your model instance. Everything below is available without using the Facade.

Relations

$invoice->baskets;        // Collection<Basket> — all baskets the model is/has been in
$invoice->histories;      // Collection<History> — all transition history entries
$invoice->workflowLock;   // WorkflowLock|null — the active lock on this model

Methods

// Current status (last basket attached)
$invoice->currentStatus();                // ?Basket — across all circuits
$invoice->currentStatus($circuit);        // ?Basket — in a specific circuit
$invoice->currentStatus('circuit-uuid');   // same with a string ID

// Inspect the current basket
$invoice->currentStatus()->status;        // "REVIEW"
$invoice->currentStatus()->name;          // "Under Review"
$invoice->currentStatus()->color;         // "#2563eb"
$invoice->currentStatus()->roles;         // ["manager", "validator"]
$invoice->currentStatus()->hasRole('manager'); // true

// Access the circuit
$invoice->currentStatus()->circuit->name; // "Invoice Approval"

// Navigate the workflow graph
$invoice->currentStatus()->next;          // Collection<Basket> — possible next steps
$invoice->currentStatus()->previous;      // Collection<Basket> — where it came from

// History with duration tracking
$invoice->histories->each(function ($h) {
    $h->previous_status;   // "DRAFT"
    $h->next_status;       // "REVIEW"
    $h->comment;           // "Sent for review"
    $h->done_by;           // "user-uuid"
    $h->duration_seconds;  // 3600
    $h->duration_human;    // "1h"
    $h->created_at;        // Carbon
});

// Lock info
$invoice->workflowLock?->locked_by;      // "user-uuid" or null
$invoice->workflowLock?->expires_at;     // Carbon or null
$invoice->workflowLock?->isActive();     // true if not expired

Scopes

// Models currently in a specific basket
Invoice::fromBasket($reviewBasket)->get();

// Available models (not locked or lock expired)
Invoice::unlocked()->get();

// Models locked by a specific user
Invoice::lockedBy(auth()->id())->get();

// Combine scopes
Invoice::fromBasket($reviewBasket)->unlocked()->get();

Automatic Behavior

When a model is created, it's automatically attached to the DRAFT basket of every circuit targeting its class:

$invoice = Invoice::create(['number' => 'INV-001']);

$invoice->currentStatus()->status; // "DRAFT" — automatic
$invoice->baskets->count();        // 1 (or more if multiple circuits)

Admin Interface

The visual designer at /workflow/admin provides:

• Circuit management — create, edit, delete circuits with role assignment
• Drag-and-drop canvas — position baskets freely, auto-layout button
• Visual linking — click output port, then click target basket to create transitions
• Transition config — click a link to add label and actions
• Message editor — WYSIWYG editor with variable interpolation
• Export / Import — JSON + PNG export, JSON import
• Zoom — scroll wheel + controls
• Dark mode — toggle between light and dark themes
• No build step — works out of the box, powered by Alpine.js + Tailwind CDN

Testing

composer test

Or with Pest directly:

./vendor/bin/pest

License

MIT. See LICENSE for details.

Credits

• Noel Mebale