Quickstart Guide
Get up and running with saccharine/bpmn in under five minutes. This guide walks through installing the package, running migrations, seeding the demo workflows, and tracing a live process instance from trigger to completion.
Requirements
- PHP:
^8.4 - Laravel Framework:
^13.0 - Orchestration Core:
durable-workflow/workflow^2.0 - Expression Parser:
symfony/expression-language^8.1 - Database: MySQL 8+, MariaDB 10.3+, PostgreSQL 13+, or SQLite 3.35+
- Queue Driver: Database, Redis, or SQS (a background worker running
php artisan queue:workis required to advance durable workflows)
1. Installation
Install the package via Composer:
composer require saccharine/bpmn
Publish the package configuration and pre-compiled bpmn-js frontend assets, then run your database migrations:
php artisan bpmn:install
php artisan migrate
bpmn:installpublishesconfig/saccharine-bpmn.php(saccharine-bpmn-config) and the compiled browser assets topublic/vendor/saccharine/bpmn(saccharine-bpmn-assets).php artisan migratecreates both thedurable-workflowv2 runtime tables and the package'sprocess_*tables (loaded automatically byBpmnServiceProvider).
2. Seed the Demo Workflows
The package ships with BpmnDemoSeeder, which compiles four example BPMN 2.0 process definitions into your database:
php artisan db:seed --class='Saccharine\Bpmn\Database\Seeders\BpmnDemoSeeder'
This populates:
1. Demo: Order Processing (order-processing): Triggered automatically when a DemoOrder model is created (demo_order_created). Routes orders >= $1000 to a Manager Review User Task before sending a confirmation via the built-in Saccharine\Bpmn\Workflows\Activities\SendNotificationActivity (bpmn_send_notification).
2. Demo: Parallel Fulfillment (parallel-fulfillment): Demonstrates AND split/join execution across concurrent branches.
3. Demo: SLA Escalation & Error Boundaries (sla-escalation): Demonstrates a PT24H Timer Boundary Event on a User Task and an Error Boundary Event on a Service Task.
4. Demo: Parent Pipeline with Call Activity (parent-pipeline): Demonstrates an inline subProcess followed by a callActivity invoking another published process definition.
(Optional) If you use Filament v5, you can also publish a DemoOrderResource CRUD table and sample activity class to trigger orders directly from your admin panel:
php artisan bpmn:publish-filament-stubs
3. Running the Engine
Open two terminal windows in your project directory:
Terminal A: Start a Queue Worker
Start your standard Laravel queue worker to execute workflow steps:
php artisan queue:work
Terminal B: Trigger a Test Order
Create a DemoOrder record using the built-in test command:
# Triggers an order requiring human review (total >= 1000)
php artisan bpmn:test-order --amount=1500 [email protected]
Because DemoOrder uses the TriggersBpmnProcesses trait, creating the record dispatches ModelEventTrigger (demo_order_created), which ProcessTriggerListener intercepts to launch an instance of order-processing.
In Terminal A, BpmnConsoleLogListener streams live execution transitions:
[BPMN:ENGINE] [#1] (Start_OrderPlaced) Process started from node [Start_OrderPlaced].
[BPMN:GATEWAY] [#1] (Gateway_VIP) Evaluated conditions. Routing token -> [Task_ManualReview].
[BPMN:HIBERNATE] [#1] (Task_ManualReview) User Task [Manager Review] reached. Workflow hibernating in database awaiting signal.
4. Inspecting & Resuming in the Live Cockpit
Open the standalone process dashboard in your browser:
http://your-app.test/bpmn/processes/instances
Note: The default web prefix is
bpmn/processes, configurable viaprefix.webinconfig/saccharine-bpmn.php. If you have registeredBpmnFilamentPlugin::make()in a Filament v5 panel, instances are also available at/admin/bpmn/processes/instances.
Completing the Hibernated User Task
- Locate the running Demo: Order Processing instance and click Live Cockpit (
/bpmn/processes/instances/1/track). - Inspect the diagram overlay:
- Completed nodes (
.bpmn-history-completed) are highlighted in slate blue. - Active waiting nodes (
.bpmn-active-token) pulse in green.
- Completed nodes (
- Click the pulsing Manager Review node on the canvas to open the task approval modal.
- Choose Approve & Continue, enter review notes, and click Submit & Resume.
- In Terminal A, watch your queue worker immediately wake the hibernated Fiber, pass through the merge gateway, run
SendNotificationActivity(logging the confirmation message), and complete at the End Event.
CLI Scaffolding & Control Reference
Once you have verified the demo workflow, use the Artisan CLI to scaffold your own components or control running instances:
# Scaffold a Service Task Activity and register it in config/saccharine-bpmn.php
php artisan bpmn:make-activity SendInvoiceActivity
# Scaffold a custom BpmnTriggerableEvent and register its alias
php artisan bpmn:make-trigger CustomerOnboardedEvent
# Scaffold a Camunda-compatible Element Template JSON file in resources/bpmn/templates/
php artisan bpmn:make-template "Charge Credit Card" --key="charge_card"
# List and control running process instances
php artisan bpmn:instance list
php artisan bpmn:instance suspend {id}
php artisan bpmn:instance resume {id}
php artisan bpmn:instance halt {id}