PHPackages                             nganthoiba/laravel-dynamic-workflow - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. nganthoiba/laravel-dynamic-workflow

ActiveLibrary[Utility & Helpers](/categories/utility)

nganthoiba/laravel-dynamic-workflow
===================================

A dynamic graph-based workflow engine and visual designer for Laravel.

v1.1.6(1w ago)056↓46.4%MITBladePHP ^8.2

Since May 13Pushed 6d agoCompare

[ Source](https://github.com/Nganthoiba/laravel-dynamic-workflow)[ Packagist](https://packagist.org/packages/nganthoiba/laravel-dynamic-workflow)[ RSS](/packages/nganthoiba-laravel-dynamic-workflow/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (6)Versions (26)Used By (0)

Laravel Dynamic Workflow
========================

[](#laravel-dynamic-workflow)

A powerful, dynamic graph-based workflow engine and visual designer for Laravel.

This package enables you to design complex business processes visually and execute them with a robust runtime engine. It supports dynamic routing, conditional branching, role-based authorization, and full audit tracking—all without modifying application source code.

✨ Features
----------

[](#-features)

- **Visual Designer**: Drag-and-drop workflow builder powered by LogicFlow.
- **Dynamic Routing**: Modify approval chains and logic on the fly.
- **Conditional Branching**: Intelligent runtime routing based on data or user input.
- **Task Management**: Built-in Inbox/Outbox for user tasks.
- **Role-Based**: Seamless integration with your existing role/permission system.
- **Audit Trails**: Complete history of every action and decision.
- **Enterprise Ready**: Designed for adaptability in complex regulatory environments.

---

⚡ Why Dynamic Workflows?
------------------------

[](#-why-dynamic-workflows)

In real-world enterprise systems, business rules are rarely fixed. Organizational policies evolve, approval authorities change, and routing rules become more complex over time.

For example, a **Purchase Order** process might evolve from a simple `Employee → Manager` flow to a multi-stage `Employee → Assistant Manager → Manager → Finance Director → Admin` chain. Traditional hardcoded systems require code changes and redeployments for every such evolution.

This package enables administrators to:

- **Insert/Remove** intermediate approval steps.
- **Modify** routing conditions dynamically.
- **Redesign** approval hierarchies visually.
- **Adapt** processes without touching the application source code.

---

🚀 Quick Start
-------------

[](#-quick-start)

Get a workflow up and running in minutes.

### 1. Install & Setup

[](#1-install--setup)

```
composer require nganthoiba/laravel-dynamic-workflow
php artisan vendor:publish --provider="Workflow\Providers\WorkflowServiceProvider"
php artisan migrate
```

#### Selective Publishing (Tags)

[](#selective-publishing-tags)

If you only want to publish specific parts of the package, use the `--tag` flag:

TagDescription`workflow-config`Main configuration file (`workflow.php`).`workflow-conditions-config`Logical branching fields (`workflow_conditions.php`).`workflow-views`All management UI views (Inbox, Designer, etc.).`workflow-step-views`Runtime action views for workflow steps.`workflow-assets`Required JS/CSS for the designer.`workflow-migrations`Database schema files.`workflow-models`Core models (optionally published to `app/Models/Workflow`).### 2. Register Your Models

[](#2-register-your-models)

Define which models can trigger workflows in `config/workflow.php`:

```
'workflow_models' => [
    'purchase_order' => [
        'label' => 'Purchase Order',
        'class' => \App\Models\PurchaseOrder::class,
    ],
],
```

### 3. Design & Bind

[](#3-design--bind)

1. Go to `/workflow/processes` and create your first process.
2. Use the **Designer** to draw your workflow (Start → Step → End).
3. Go to `/workflow-bindings` to map your model (e.g., `PurchaseOrder`) and event (e.g., `created`) to the process.

**That's it!** Creating a `PurchaseOrder` will now automatically launch your workflow.

---

⚙️ Configuration & Logic
----------------------------

[](#️-configuration--logic)

The package uses two main configuration files to manage workflow behavior.

### 1. General Settings (`config/workflow.php`)

[](#1-general-settings-configworkflowphp)

Define your business models, roles, and supported events.

```
'workflow_models' => [
    'purchase_order' => [
        'label' => 'Purchase Order',
        'class' => \App\Models\PurchaseOrder::class,
    ],
],

'models' => [
    'role' => \App\Models\Role::class,
    'user' => \App\Models\User::class,
],
```

### 2. Condition Fields (`config/workflow_conditions.php`)

[](#2-condition-fields-configworkflow_conditionsphp)

Define the fields available for logical branching in the designer.

KeyTypeDescription`key``string`The identifier (e.g., `amount`) the engine looks for.`label``string`The human-readable name shown in the designer.`type``string``number`, `string`, `date`, or `enum`.#### Field Schema Details

[](#field-schema-details)

PropertyRequiredDescription`operators_json`**Yes**List of allowed operators (e.g., `=`, `!=`, `>`, ` 'department',
    'label' => 'Department',
    'type' => 'enum',
    'operators_json' => ['=', '!='],
    'options_json' => [
        ['value' => 'sales', 'label' => 'Sales Dept'],
        ['value' => 'hr', 'label' => 'Human Resources'],
    ],
],
```

Important

**Data Sources**: Logic can evaluate both **Database Attributes** (like `order_amount`) and **Form Inputs** (like `action_result`). The `action_result` parameter is specifically used to record user decisions.

---

🧩 Core Concepts
---------------

[](#-core-concepts)

The workflow engine operates on a **Graph-Based Architecture**.

### Node Types

[](#node-types)

- **Start Node**: The entry point. Every process must have exactly one.
- **Step Node**: A business task assigned to a role.
- **Condition Node**: Logical branching ($True/False$).
- **End Node**: The termination point.

### State Management

[](#state-management)

1. **Instances (`workflow_instances`)**: Tracks the current active step and overall status (IN\_PROGRESS, COMPLETED, etc.).
2. **History (`workflow_instance_steps`)**: A full audit trail of every performed task, including who did it and when.

### 🧠 Condition Intelligence

[](#-condition-intelligence)

The engine supports intelligent runtime routing using **Condition Nodes**. These nodes evaluate logic based on two primary data sources:

- **Blade Views (Form Inputs)**: Data passed from the task form (e.g., ``).
- **Model Attributes (Database)**: Fields directly from the associated Eloquent model (e.g., `total_amount`).

Tip

**Why `action_result` Matters**: Even if not used in a condition, passing `action_result` (e.g., `approve`, `reject`, `revert`) ensures that the precise decision is recorded in the task history audit trail.

---

🎨 Visual Designer
-----------------

[](#-visual-designer)

Manage your workflows through an interactive UI at `/workflow/processes`.

### 1. Designing the Flow

[](#1-designing-the-flow)

Click **Designer** on any process to launch the canvas.

- **Drag & Drop**: Pull nodes from the sidebar onto the grid.
- **Connect**: Drag from the blue anchor points to create transitions.
- **Configure**: Click any node to open the properties panel (set names, actions, or roles).

### 🧰 Designer Toolbox

[](#-designer-toolbox)

- 🟢 **Start Node**: Entry point of the workflow process.
- 🔵 **Step Node**: Executable business task assigned to roles.
- 🟡 **Condition Node**: Performs logical evaluation for branching.
- 🔴 **End Node**: Termination point.

### 🎮 Canvas Controls

[](#-canvas-controls)

- **Resize Nodes**: Select a node and use the handles to scale its boundaries.
- **Context Menu**: Hover over a node to reveal **Edit** and **Delete** shortcuts.
- **Zoom & Pan**: Use the header controls to scale the viewport.

### 2. Event Triggers (UI Binding)

[](#2-event-triggers-ui-binding)

Map your models to workflows without code at `/workflow-bindings`.

- **Target**: The workflow process to launch.
- **Trigger**: The Eloquent event (defaults to `created`).
- **Priority**: Execution order if multiple bindings exist.

---

📥 Task Management
-----------------

[](#-task-management)

### Inbox (`/workflow/inbox`)

[](#inbox-workflowinbox)

- View and execute pending tasks.
- Only users with authorized roles can see specific tasks.

### Outbox (`/workflow/outbox`)

[](#outbox-workflowoutbox)

- Track your completed tasks and audit your decisions.

---

🔄 Starting a Workflow
---------------------

[](#-starting-a-workflow)

### Automatic Mode (Recommended)

[](#automatic-mode-recommended)

By default, the package globally listens for the **created** event on all registered models. If you register a binding in the UI (`/workflow-bindings`), the engine will automatically start the workflow when a model is created.

### Manual Mode

[](#manual-mode)

Start workflows programmatically:

```
$service = app(WorkflowInstanceService::class);
$instance = $service->start($process, $order);
$service->proceed($instance, $request->all());
```

---

⚡ Workflow Actions (Hooks)
--------------------------

[](#-workflow-actions-hooks)

Workflow actions define executable business behavior. Each step in the visual designer references a `workflow_action` hook which determines the Blade form view and its backend execution class.

### 1. Registering Actions

[](#1-registering-actions)

Define your actions in `config/workflow.php`. The `view` refers to the Blade file used for the task form, and `action` refers to the class that handles the submitted data.

```
'workflow_actions' => [
    // Custom business actions
    'initiate_purchase_order' => [
        'label' => 'Initiate Purchase Order',
        'view' => 'initiate_purchase_order',
        'action' => \App\Workflow\Actions\InitiatePurchaseOrderAction::class,
    ],

    // Common utility actions
    'approve_and_forward' => [
        'label' => 'Approve and Forward',
        'view' => 'approve_and_forward',
        'action' => \App\Workflow\Actions\ApproveAndForwardAction::class,
    ],
    'approve' => [
        'label' => 'Approve',
        'view' => 'approve',
        'action' => \App\Workflow\Actions\ApproveAction::class,
    ],
],
```

Note: the **action** can be null if there is nothing to do at the backend.

### 2. Implementation

[](#2-implementation)

#### A. The Action Class

[](#a-the-action-class)

Action classes must implement `Workflow\Core\Contracts\StepActionInterface`. The `execute` method receives the submitted form data, the target model, and the task step.

```
class ApproveOrderAction implements StepActionInterface {
    public function validate(array $data): array {
        return validator($data, [
            'remarks' => 'nullable|string|max:500',
            'action_result' => 'nullable|string',
        ])->validate();
    }

    public function execute(array $data, Model $model, WorkflowInstanceStep $step): void {
        // Logic to update your model based on the user's decision
        $model->update([
            'status' => ($data['action_result'] == 'reject' ? 'rejected' : 'approved'),
            'remark' => $data['remarks'] ?? null,
        ]);
    }
}
```

#### B. The Blade View

[](#b-the-blade-view)

Every task form **must** extend the package's layout. Data passed from these fields will be automatically handled by the action class.

```
@extends('vendor.workflow.task_layout')

@section('form_fields')

        Remarks

@endsection

@section('form_actions')
    Reject
    Revert
    Approve & Forward
@endsection
```

---

🛠️ Technical Reference
----------------------

[](#️-technical-reference)

### Database Schema

[](#database-schema)

The package uses several tables to store definitions and execution data:

- `processes`: Stores high-level definitions (name, unique code, and the LogicFlow graph JSON).
- `steps`: Individual nodes within a workflow (start, end, task steps, and condition gates).
- `step_transitions`: The directed edges (arrows) connecting steps, including logical branch types (True/False).
- `workflow_instances`: Tracks the lifecycle of an active execution and its polymorphic link to a business model.
- `workflow_instance_steps`: The full audit trail of executed tasks, actions taken, and user comments.
- `workflow_bindings`: Mapping of Eloquent events to automatic workflow triggers.

### Model Requirements

[](#model-requirements)

Any model used in a workflow **must** have a `status` column. This is used by the engine to track and display badge states.

### Summary Views

[](#summary-views)

When a user opens a task, they see a summary of the business object (e.g., a Purchase Order). You can explicitly map models to their specific summary views in `config/workflow.php`:

```
'reference_views' => [
    \App\Models\PurchaseOrder::class => 'workflow.reference.purchase_order',
],
```

If no explicit mapping is provided, the engine falls back to a **default convention** based on the model's snake\_case class name (e.g., `App\Models\PurchaseOrder` looks for `resources/views/workflow/reference/purchase_order.blade.php`).

### Advanced: Send Back (REVERT)

[](#advanced-send-back-revert)

Enable automatic backtracking by adding a button with `value="REVERT"`. Unlike explicit backward arrows, the **REVERT** action is a built-in engine mechanism:

1. **Scan History**: The engine scans the `workflow_instance_steps` for the most recent completed human task.
2. **Re-open Task**: It closes the current task and creates a new pending task for that previous performer.
3. **Audit Trail**: The action is recorded as `REVERT` in the audit logs.

Note

If you are on the first step of a workflow, the "Send Back" action will be ignored as there is no previous state to return to.

---

### 🏛️ Separation of Concerns

[](#️-separation-of-concerns)

This package is designed to separate **Workflow Orchestration** from **Business Logic**:

- **Workflow Engine**: Manages routing, authorization, state transitions, and audit trails.
- **Application Logic**: Defines the business models, task views (Blade), and executable actions (Hooks).

This separation allows your business processes to evolve and scale without cluttering your core application code with complex state machine logic.

🚀 Future Roadmap
----------------

[](#-future-roadmap)

- Workflow versioning & templates.
- Separate APIs for use in frontend like ReactJs

🤝 Contributing & License
----------------------------

[](#-contributing--license)

Contributions are welcome!

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance98

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

25

Last Release

8d ago

PHP version history (2 changes)v1.0.0PHP ^8.1

v1.0.1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/4373d0c332133de4fb6320c94f8423e8912f28e417ca4e4d7734f4f39572d7be?d=identicon)[Nganthoiba Khangenbam](/maintainers/Nganthoiba%20Khangenbam)

---

Top Contributors

[![Nganthoiba](https://avatars.githubusercontent.com/u/14937846?v=4)](https://github.com/Nganthoiba "Nganthoiba (68 commits)")

### Embed Badge

![Health badge](/badges/nganthoiba-laravel-dynamic-workflow/health.svg)

```
[![Health](https://phpackages.com/badges/nganthoiba-laravel-dynamic-workflow/health.svg)](https://phpackages.com/packages/nganthoiba-laravel-dynamic-workflow)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[pressbooks/pressbooks

Pressbooks is an open source book publishing tool built on a WordPress multisite platform. Pressbooks outputs books in multiple formats, including PDF, EPUB, web, and a variety of XML flavours, using a theming/templating system, driven by CSS.

45344.0k1](/packages/pressbooks-pressbooks)[api-platform/laravel

API Platform support for Laravel

59156.3k10](/packages/api-platform-laravel)[fleetbase/core-api

Core Framework and Resources for Fleetbase API

1232.2k16](/packages/fleetbase-core-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)