SymFlow for Laravel

A Symfony-compatible workflow engine for Laravel. State machines, Petri nets, guards, events, weighted arcs, middleware, and YAML/JSON/PHP/Mermaid/Graphviz/SVG 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
• Structured guard results -- return GuardResult::deny($reason, $code) so blockers carry a human-readable reason
• Blockable Guard event -- listeners can veto a transition via $event->setBlocked(true, reason, code)
• Listener scoping & priority -- on() accepts an optional transition name and priority for declarative ordering
• Listener error modes -- ListenerErrorMode::Throw / Collect / Swallow controls how listener exceptions surface
• 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, SVG (auto-layout, dark/light theme)
• Eloquent trait -- HasWorkflowTrait for model integration
• Laravel events -- 7 event classes for the full transition lifecycle
• Artisan commands -- laraflow:validate, laraflow:mermaid, laraflow:dot

Examples

End-to-end Laravel apps built on symflow-laravel:

Documentation

License

MIT