Download the PHP package maestrodimateo/laravel-workflow without Composer

Laravel Workflow

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

Publish the config and migrations:

Optionally publish the views to customize the admin UI:

Quick Start

1. Add the trait to your model

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

The workflow() helper is also available:

Facade API Reference

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

Model-bound methods

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

Static methods

These methods don't require for():

Role-based queries

These methods don't require for():

Eloquent scopes are also available directly:

Duration Tracking

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

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:

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:

Query scopes

Handling lock exceptions

Configure the default lock duration in .env:

Transition Actions

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

Built-in actions

Custom actions

Generate a new action with artisan:

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

Register it in your AppServiceProvider::boot():

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

Events

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

What happens during a transition

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:

Built-in variables

Custom variables

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

Programmatic import (seeders, commands)

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

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

Workflowable Trait

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

Relations

Methods

Scopes

Automatic Behavior

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

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

Or with Pest directly:

License

MIT. See LICENSE for details.

Credits

• Noel Mebale