README

A lightweight, native PHP workflow orchestrator and visual designer for Laravel. This package allows you to model complex business processes visually using BPMN 2.0 and execute them as durable, stateful background jobs—without any external Java dependencies (like Camunda or Zeebe).

It bridges the gap between visual business diagrams and real-world execution by combining bpmn-js (for modeling) and durable-workflow (for resilient, suspendable background execution).

Status: v0.3.2-alpha. This package is actively being developed. The core execution engine, token tracking, and manual intervention layers are operational, but it is not yet recommended for production environments.

Key Features

No Heavy Infrastructure: Runs entirely on your existing Laravel queue system (database, Redis, SQS, etc.).

Durable Execution: Workflows are resilient. If a server crashes or restarts mid-process, the engine resumes exactly where it left off.

Embedded Visual Designer: A beautiful, responsive drag-and-drop designer powered by bpmn-js is built right into your Laravel app.

Event-Driven Architecture: Natively listen to Laravel Events to trigger workflows automatically using BPMN Message Start Events.

Advanced Routing & Scope: Full support for Parallel Gateways (AND splits/joins), Inline Sub-Processes, and Call Activities (reusable child processes).

Human-in-the-Loop: Pause execution indefinitely to wait for external human input (signals), then resume automatically.

State Projection: Separates background coroutines from UI tracking using isolated relational workflow_tokens, enabling real-time dashboards with zero parallel race conditions.

Technical Dependencies

PHP 8.3+

Illuminate Support (^12.0 || ^13.0): Native integration with the Laravel framework ecosystem.

Symfony Expression Language (^7.0): Used for evaluating sandbox-safe expressions in conditional routing.

Durable Workflow (^1.0): The robust PHP coroutine framework that provides suspendable workflow engines and queue orchestration.

bpmn-js: The frontend interactive modeling library, bundled natively via Vite.

Documentation

Usage Guide: Learn how to design workflows, scaffold activities, use element templates, and implement advanced nodes like Sub-Processes and Boundary Events.

Architecture & Under the Hood: Explore the engine's design, including the XML parser, the Strategy Pattern node handlers, and deterministic token tracking.

Installation

1. Require the Package

For local development, link the package to a host application by adding a path repository to your host's composer.json:

"repositories": [
    {
        "type": "path",
        "url": "../bpmn-engine",
        "options": {
            "symlink": true
        }
    }
],

Then require the package:

composer require "saccharine-app/bpmn-engine" "@dev"

2. Install and Initialize

The package provides an installation command to publish configurations, frontend assets, migrations, and run the database setup.

php artisan bpmn:install

Quickstart: The Interactive Demo

You can instantly scaffold an "Order Processing" workflow to see the engine in action:

php artisan bpmn:demo

This command generates a demo trigger and activity, registers them in your config, and seeds your database with a complete BPMN diagram. Navigate to /bpmn/workflows in your browser to view the generated diagram, and follow the terminal instructions to dispatch the event and watch the background worker execute the logic.

Acknowledgments

This package would not be possible without the incredible work of the open-source community:

bpmn-js by bpmn.io / Camunda: The gold standard for web-based BPMN 2.0 visualization.

durable-workflow: The elegant coroutine orchestration layer that makes suspendable, durable PHP processes a reality.

Symfony & Laravel: For providing the ultimate foundation of modern enterprise PHP development.

License

This package is open-source software licensed under the MIT License.

saccharine / bpmn-engine

Maintainers

Package info

Statistics

Security