Download the PHP package dereuromark/cakephp-workflow without Composer

CakePHP Workflow Plugin

This branch is for CakePHP 5.2+. See version map for details.

State machine and workflow engine for CakePHP with PHP 8 Attributes, YAML/NEON config support, and admin UI.

[!TIP] Try the live demo: https://sandbox.dereuromark.de/workflow-sandbox

There is also a demo app with more details to experiment with

Requirements

• CakePHP 5.2+

Installation

For server-side diagram exports via /workflow/workflows/draw in svg / png formats, install GraphViz and make sure the dot binary is available on the host. Widget exports in app pages do not require GraphViz.

Load the plugin:

Run migrations:

The generic foreign_key column is polymorphic and defaults to integer; set the shared Polymorphic.type key to biginteger for large-id apps, or uuid / binaryuuid for non-integer keys. UUID / char primary keys are fully supported — no code changes needed. See Installation: Entity id type.

Configuration

Configure the plugin in your config/app.php:

The admin UI is fail-closed by default: you must provide Workflow.adminAccess to expose /admin/workflow/.... Manual admin actions also record actor and context metadata; when you still rely on legacy session auth, the admin logger falls back to Auth.User.id automatically.

Defining Workflows

Using PHP 8 Attributes (Recommended)

Create state classes in your namespace:

Using NEON or YAML

Install the optional parser you want:

• NEON: composer require nette/neon
• YAML: composer require symfony/yaml

Create workflow files in config/workflows/:

Using the Workflow

Add the behavior to your table:

Apply transitions:

See the documentation for the full API.

Embedding Workflow Diagrams In App Pages

For app-facing pages you often want a compact diagram preview, not the full admin screen.

Load Mermaid with the helper toolkit:

Render a compact workflow widget with:

• current-state highlighting
• optional current-state centering
• code toggle
• fullscreen modal
• client-side SVG export of the rendered Mermaid graph
• client-side PNG export derived from the rendered Mermaid graph
• Mermaid source export

For detailed helper options and canonical server-side draw exports, see the View Helper integration docs.

• exportFilename
• minWidth
• maxHeight
• modalMinWidth

SVG export uses a standalone serializer, so downloaded files get explicit dimensions from the rendered viewBox instead of keeping Mermaid's responsive width="100%" markup. This makes saved SVGs much more usable in external tools.

PNG export rasterizes that same standalone SVG into a canvas with a white background, which is useful for docs, tickets, and tools that do not render SVG cleanly.

Drift Safety

Changing a workflow while records exist can leave records in a state that no longer exists. This is handled out of the box, with no configuration:

• Graceful degradation: orphaned records never crash reads, display, or the admin UI — they render as a neutral "unknown" state, and transitioning one returns a clear blocked result.
• Detection: the admin Orphans view (/admin/workflow/orphans) and workflow validate --check-data list records whose state is no longer defined.
• Remediation: move them forward interactively, or headlessly:

See Drift Safety for details.

CLI Commands

Features

• PHP 8 Attributes or NEON/YAML definitions
• Guards, commands, and lifecycle callbacks
• Audit logging with user tracking
• Pessimistic locking for concurrent transitions
• Automatic timeouts
• Drift safety: orphaned records never crash, with detection and forward migration
• Admin UI with Mermaid.js diagrams
• CLI tools for management and validation

Documentation

Full documentation: https://dereuromark.github.io/cakephp-workflow/