Download the PHP package maestrodimateo/laravel-workflow without Composer
On this page you can find all versions of the php package maestrodimateo/laravel-workflow. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download maestrodimateo/laravel-workflow
More information about maestrodimateo/laravel-workflow
Files in maestrodimateo/laravel-workflow
Package laravel-workflow
Short Description Workflow engine for Laravel applications
License MIT
Informations about the package laravel-workflow
Laravel Workflow
A visual, configurable workflow engine for Laravel. Define circuits (workflows), baskets (steps) and transitions, then move any Eloquent model through them with a clean Facade API.
Ships with a built-in visual admin interface to design your workflows by drag-and-drop.
Table of contents
- Features
- Requirements
- Installation
- Quick start
- Key concepts
- Facade API
- The Workflowable trait
- Multi-circuit
- Resource locking
- Transition actions
- Transition conditions
- Duration tracking
- Message templates
- Events
- Export & Import
- Admin interface
- Configuration
- Testing
- License
Features
| Category | Description |
|---|---|
| Visual designer | Drag-and-drop baskets, draw transitions, configure actions & conditions |
| Facade & helper | Workflow::for($model)->transition($id) or workflow($model)->transition($id) |
| Multi-circuit | A model can belong to multiple workflows simultaneously |
| Resource locking | Prevent concurrent access with lock() / unlock() |
| Role-based access | Allowed roles per circuit and per basket |
| Transition actions | Email, webhook, log, required documents, custom actions on each transition |
| Transition conditions | Gate a transition on the model's state (server-side + UI) |
| Duration tracking | Automatic timing between steps |
| Full history | Every transition is logged: who, when, how long, why |
| Message templates | WYSIWYG editor with variable interpolation |
| Export / Import | Share workflows as JSON + PNG image export |
| Dark mode | Light and dark themes |
| No CDN | Vendored assets, served same-origin, works offline |
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 is automatically placed in the DRAFT basket of every circuit targeting it.
2. Open the visual designer
Navigate to /workflow/admin. From there you can:
- Create a circuit targeting your model
- Add baskets (steps) with colors and roles
- Draw transitions by dragging from one basket to another
- Configure actions and conditions on each transition
3. Transition models in your code
The workflow() helper is also available:
Key concepts
The package is built around three concepts:
| Concept | Description | Example |
|---|---|---|
| Circuit | A complete workflow targeting an Eloquent model | "Invoice approval" |
| Basket | A step in the circuit, with a status, color and roles | "Pending review" |
| Transition | A directed link between two baskets, carrying actions and conditions | Draft → Review |
Facade API
All methods are available via Workflow:: or workflow()->.
Model-bound methods
Always prefixed with Workflow::for($model):
Navigation:
| Method | Returns | Description |
|---|---|---|
in($circuit) |
WorkflowManager |
Scope to a specific circuit |
currentStatus() |
?Basket |
Current basket of the model |
nextBaskets() |
Collection |
Baskets reachable from the current one |
availableTransitions() |
array |
Next baskets with open (bool) and blockedBy (reasons) |
allStatuses() |
array |
Current basket in every circuit |
circuits() |
Collection |
All circuits the model belongs to |
Actions:
| Method | Returns | Description |
|---|---|---|
transition($id, $comment) |
bool |
Move the model to the target basket |
lock($minutes) |
WorkflowLock |
Lock the model for exclusive access |
unlock($force) |
void |
Release the lock |
Queries:
| Method | Returns | Description |
|---|---|---|
history() |
Collection |
Full transition history |
totalDuration() |
int |
Total processing time in seconds |
durationInStatus($status) |
int |
Time spent in a specific status (seconds) |
isLocked() |
bool |
Is the model locked? |
isLockedByMe() |
bool |
Locked by the current user? |
lockedBy() |
?string |
User ID holding the lock |
lockExpiration() |
?Carbon |
When the lock expires |
requiredDocuments($basketId) |
array |
Documents required for a transition |
requirements() |
array |
All requirements for all next transitions |
Static methods
No for() needed:
| Method | Returns | Description |
|---|---|---|
importFromJson($path) |
Circuit |
Import a circuit from an exported JSON file |
registerAction($class) |
void |
Register a custom transition action |
getRegisteredActions() |
array |
List all registered action classes |
registerCondition($class) |
void |
Register a custom transition condition |
getRegisteredConditions() |
array |
List all registered condition classes |
Role-based queries
Equivalent Eloquent scopes:
The Workflowable trait
The trait adds relations, methods and scopes directly on your model.
Relations
Methods
Scopes
Automatic behavior
When a model is created, it is attached to the DRAFT basket of every circuit targeting its class:
Multi-circuit
A model can belong to multiple circuits at the same time.
Use in() to scope operations:
See all statuses at once:
Resource locking
Prevent multiple operators from working on the same model simultaneously.
Usage
Handling lock exceptions
Configuration
Transition actions
Actions execute automatically when a transition occurs. They are configured visually in the designer.
Built-in actions
| Action | Key | Config | Execution |
|---|---|---|---|
| Send email | send_email |
Select a message from the circuit | Queued (after commit) |
| Webhook | webhook |
Target URL | Queued (after commit) |
| Log | log |
Optional message | After commit |
| Require documents | require_document |
List of documents (type + label) | In transaction |
Execution modes
Every transition() is wrapped in a DB transaction. Actions run in one of three modes:
| Mode | Interface | When to use |
|---|---|---|
| In transaction (default) | — | Validations, atomic DB writes. An exception rolls back the transition. |
| After commit | AfterCommitAction |
Fast, non-rollbackable side effects (log, cache). |
| Queued | QueueableAction |
Slow or external side effects (email, HTTP, APIs). The request returns immediately. |
Creating a custom action
This creates app/Workflow/Actions/GeneratePdfAction.php:
Register it in your AppServiceProvider::boot():
The action immediately appears in the designer's "Add action" menu on any transition.
After-commit action
For non-rollbackable external side effects:
Queued action
For slow side effects — the request returns immediately:
What you get for free:
- Race-free dispatch — the job is sent via
DB::afterCommit(), so the worker never sees an intermediate state - Fresh state — the model is re-fetched from the DB when the job runs
- Automatic retries — handled by the Laravel queue worker like any other job
Global configuration:
With
QUEUE_CONNECTION=sync, queued actions run inline. Switching toredisordatabaseis enough to offload them — no code change needed.A
QueueableActionalready runs after commit — no need to also implementAfterCommitAction.
Transition conditions
Gate a transition on the model's own state. Conditions are evaluated in two places with the same result:
- Server-side — the transition is rejected with a rollback
- Your UI —
availableTransitions()tells you which transitions are open or blocked
Built-in: attribute condition (no code)
In the designer, open a transition and add Condition → Model attribute. Pick a field, an operator and a value.
| Operator | Meaning |
|---|---|
= != |
Equals / not equals |
< <= > >= |
Comparisons |
in not_in |
Value in a comma-separated list |
empty not_empty |
Attribute is blank / present |
contains |
String contains |
Example: only allow Draft → Approved when amount <= 1000.
Custom condition
For anything the attribute editor can't express:
Register it in config/workflow.php:
Application side
Conditions must be read-only (no side effects).
Duration tracking
Every transition automatically records the time spent in the previous step.
Human-readable formats: 45s, 12min, 2h 35min, 3d 4h.
Message templates
Messages are created at the circuit level and used in transition actions (send_email).
The WYSIWYG editor supports variable interpolation:
Built-in variables
| Variable | Description |
|---|---|
{{ model_id }} |
Model identifier |
{{ model_type }} |
Model class name |
{{ from_status }} / {{ from_name }} |
Source basket |
{{ to_status }} / {{ to_name }} |
Target basket |
{{ circuit_name }} |
Circuit name |
{{ date }} / {{ heure }} / {{ datetime }} |
Current date/time |
{{ user }} |
User performing the transition |
Custom variables
Events
A TransitionEvent is fired after every transition:
What happens during a transition
Export & Import
From the admin UI
- Export JSON — download the full circuit definition
- Export PNG — download a high-resolution image of the workflow diagram
- Import — select a
.jsonfile to recreate a circuit
Via API
Programmatic import (seeders, commands)
Creates the full circuit (baskets, transitions, messages) inside a DB transaction.
Returns the Circuit instance with all relations loaded.
Throws \InvalidArgumentException if the file is invalid.
Admin interface
The visual designer is available at /workflow/admin.
| Feature | Details |
|---|---|
| Circuits | Create, edit, delete, assign roles |
| Canvas | Drag-and-drop baskets, panning, auto-layout |
| Linking | Click the output port then click the target basket |
| Transitions | Click a link to configure label, actions, conditions |
| Baskets | Delete / Backspace to remove the selected basket |
| Messages | WYSIWYG editor with variables |
| Export / Import | JSON + PNG export, JSON import |
| Zoom | Scroll wheel + controls |
| Theme | Light / dark |
Front-end assets
Libraries (compiled Tailwind, Alpine.js, Quill) are vendored under resources/dist/ and served same-origin — no CDN. The UI works offline and under a strict CSP.
Only maintainers editing the Blade views need Node:
Configuration
Testing
License
MIT. See LICENSE.
Credits
All versions of laravel-workflow with dependencies
illuminate/database Version ^12.0|^13.0
illuminate/support Version ^12.0|^13.0
illuminate/events Version ^12.0|^13.0
symfony/html-sanitizer Version ^7.0