vandetho/symflow-laravel

A Symfony-compatible workflow engine for Laravel. State machines, Petri nets, guards, events, validation, weighted arcs, middleware, and YAML/JSON/PHP import/export.

dev-main 2026-04-24 07:36 UTC

Requires

• php: ^8.2
• illuminate/console: ^11.0|^12.0
• illuminate/contracts: ^11.0|^12.0
• illuminate/events: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• symfony/yaml: ^6.4|^7.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-laravel: ^3.0

MIT

• Vandeth Tho

• symfony
• workflow
• events
• laravel
• state-machine
• guards
• transitions
• petri-net

README

A Symfony-compatible workflow engine for Laravel. State machines, Petri nets, guards, events, weighted arcs, middleware, and YAML/JSON/PHP import/export.

Part of the SymFlow ecosystem. See also symflow for the TypeScript/Node.js version.

Installation

composer require vandetho/symflow-laravel
php artisan vendor:publish --tag=laraflow-config

Quick Start

Define a workflow in config/laraflow.php:

'workflows' => [
    'order' => [
        'type' => 'state_machine',
        'marking_store' => ['type' => 'property', 'property' => 'status'],
        'initial_marking' => ['draft'],
        'places' => ['draft', 'submitted', 'approved', 'rejected', 'fulfilled'],
        'transitions' => [
            'submit' => ['from' => 'draft', 'to' => 'submitted'],
            'approve' => ['from' => 'submitted', 'to' => 'approved'],
            'reject' => ['from' => 'submitted', 'to' => 'rejected'],
            'fulfill' => ['from' => 'approved', 'to' => 'fulfilled'],
        ],
    ],
],

Use the Eloquent trait:

use Laraflow\Eloquent\HasWorkflowTrait;

class Order extends Model
{
    use HasWorkflowTrait;

    protected function getDefaultWorkflowName(): string
    {
        return 'order';
    }
}

$order->applyTransition('submit');
$order->canTransition('approve'); // true/false

Or use the Facade:

use Laraflow\Facades\Laraflow;

$workflow = Laraflow::get('order');
$workflow->apply($order, 'submit');

Features

• Two workflow types -- state_machine and workflow (Petri net with parallel states)
• Symfony event order -- guard > leave > transition > enter > entered > completed > announce
• Subject-driven API -- mirrors Symfony's $workflow->apply($entity, 'submit') pattern
• Marking stores -- property and method stores, or implement your own
• Pluggable guards -- GuardEvaluatorInterface for custom authorization
• Weighted arcs -- consumeWeight / produceWeight for multi-token transitions
• Middleware -- wrap apply() with logging, transactions, metrics
• Validation -- 8 error types including BFS reachability analysis
• Pattern analysis -- AND-split, AND-join, OR-split, XOR detection
• Import/Export -- YAML (Symfony-compatible), JSON, PHP codegen, Mermaid, Graphviz DOT
• Eloquent trait -- HasWorkflowTrait for model integration
• Laravel events -- 7 event classes for the full transition lifecycle
• Artisan commands -- laraflow:validate, laraflow:mermaid, laraflow:dot

Documentation

Guide	Description
Getting Started	Installation, first workflow, Eloquent trait
Engine API	WorkflowEngine, guards, validation, pattern analysis
Subject API	Workflow facade, marking stores, config-driven workflows
Weighted Arcs	Multi-token transitions
Middleware	Lifecycle hooks, transactions, logging
Events	Symfony event order, Laravel event integration
Artisan Commands	validate, mermaid, dot
Persistence Formats	YAML, JSON, PHP, Mermaid, Graphviz

License

MIT