PHPackages                             nextdeveloper/flow - 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. nextdeveloper/flow

ActiveLibrary

nextdeveloper/flow
==================

NextDeveloper Flow Package, generated by NextDeveloper Generator.

v1.3.6(1w ago)0163↑84%MITPHPPHP >=8.2.0

Since May 4Pushed 1w agoCompare

[ Source](https://github.com/nextdeveloper-nl/flow)[ Packagist](https://packagist.org/packages/nextdeveloper/flow)[ RSS](/packages/nextdeveloper-flow/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (7)Dependencies (6)Versions (29)Used By (0)

NextDeveloper Flow
==================

[](#nextdeveloper-flow)

A generic, reusable pipeline engine for the LEO platform. Any object — a CRM opportunity, a support ticket, a provisioning request — can be enrolled in a configurable workflow and moved through ordered stages without touching the original table.

---

Features
--------

[](#features)

- **Polymorphic** — attach a pipeline to any platform object via `object_type` / `object_id`
- **Multi-pipeline** — the same object can participate in multiple pipelines simultaneously
- **Custom fields** — define pipeline-scoped columns (EAV) with typed validation
- **Stage entry requirements** — enforce that specific fields are filled before a stage transition
- **Checklists** — per-stage task lists tracked individually per item
- **SLA tracking** — configurable day limits per stage with breach detection
- **Automations** — fire named platform events on stage transitions, item creation, or SLA breach
- **Audit trail** — immutable stage history for every item
- **Watchers** — subscribe users to item updates
- **Templates** — define reusable pipeline blueprints and clone them per account

---

Requirements
------------

[](#requirements)

- PHP >= 8.2
- Laravel >= 10
- NextDeveloper Commons
- NextDeveloper IAM
- NextDeveloper Events

---

Installation
------------

[](#installation)

Install via Composer:

```
composer require nextdeveloper/flow
```

Register the service provider (if not using auto-discovery):

```
// config/app.php
'providers' => [
    NextDeveloper\Flow\FlowServiceProvider::class,
],
```

Publish the config file:

```
php artisan vendor:publish --provider="NextDeveloper\Flow\FlowServiceProvider" --tag="config"
```

Run the migrations (managed at the application level — see your platform's migration set for `flow_*` tables).

---

Database Tables
---------------

[](#database-tables)

TablePurpose`flow_pipelines`Pipeline definitions`flow_stages`Ordered stages per pipeline`flow_columns`Custom field definitions per pipeline`flow_stage_required_columns`Fields required before entering a stage`flow_items`Polymorphic object ↔ stage links`flow_item_values`EAV values for custom columns per item`flow_stage_history`Immutable audit log of all stage transitions`flow_automations`Event rules triggered on stage transitions`flow_item_watchers`Users following an item---

Quick Start
-----------

[](#quick-start)

### 1. Create a pipeline

[](#1-create-a-pipeline)

```
use NextDeveloper\Flow\Services\PipelinesService;

$pipeline = PipelinesService::create([
    'name'        => 'Sales Pipeline',
    'object_type' => 'crm_opportunity',
    'is_active'   => true,
]);
```

### 2. Add stages

[](#2-add-stages)

```
use NextDeveloper\Flow\Services\StagesService;

StagesService::create([
    'flow_pipeline_id' => $pipeline->uuid,
    'name'             => 'Lead',
    'position'         => 0,
    'color'            => '#94a3b8',
    'probability'      => 10,
    'sla_days'         => 7,
]);

StagesService::create([
    'flow_pipeline_id' => $pipeline->uuid,
    'name'             => 'Won',
    'position'         => 3,
    'color'            => '#22c55e',
    'probability'      => 100,
    'is_won'           => true,
]);
```

### 3. Enroll an object

[](#3-enroll-an-object)

```
use NextDeveloper\Flow\Services\ItemsService;

$item = ItemsService::create([
    'flow_pipeline_id' => $pipeline->uuid,
    'flow_stage_id'    => $leadStage->uuid,
    'object_type'      => 'crm_opportunity',
    'object_id'        => $opportunity->id,
]);
// Initial stage history entry is recorded automatically.
```

### 4. Move to the next stage

[](#4-move-to-the-next-stage)

```
// The service validates required columns, resets the checklist,
// records history, fires automations and notifies watchers.
ItemsService::update($item->uuid, [
    'flow_stage_id' => $qualifiedStage->uuid,
]);
```

### 5. Set a custom field value

[](#5-set-a-custom-field-value)

```
use NextDeveloper\Flow\Services\ItemValuesService;

ItemValuesService::upsert(
    itemUuid:   $item->uuid,
    columnUuid: $contractValueColumn->uuid,
    value:      '42500'
);
```

### 6. Clone a template pipeline

[](#6-clone-a-template-pipeline)

```
$livePipeline = PipelinesService::cloneFromTemplate($templateUuid);
// Stages, columns, entry requirements and automations are all copied.
```

---

API Endpoints
-------------

[](#api-endpoints)

All endpoints are mounted under the `/flow` prefix. Every resource follows the same REST pattern:

```
GET    /flow/{resource}              List (supports filters & pagination)
GET    /flow/{resource}/{uuid}       Show
POST   /flow/{resource}              Create
PATCH  /flow/{resource}/{uuid}       Update
DELETE /flow/{resource}/{uuid}       Delete
POST   /flow/{resource}/{uuid}/do/{action}  Execute a named action

```

**Resources:** `pipelines`, `stages`, `items`, `columns`, `item-values`, `stage-required-columns`, `stage-history`, `automations`, `item-watchers`

Filter parameters are passed as query strings. Add `paginate=true` for paginated responses (`per_page` and `page` are also accepted).

For a full endpoint reference including request bodies and response shapes, see [docs/UI.md](docs/UI.md).

---

Stage Move Business Logic
-------------------------

[](#stage-move-business-logic)

When `flow_stage_id` is updated on an item the following happens automatically:

1. **Validate** — checks `flow_stage_required_columns` for the target stage. If any required column has no value in `flow_item_values`, the update is rejected with a `NotAllowedException` listing the missing column IDs.
2. **Reset checklist** — `checklist_state` is set to `null` so the new stage's checklist starts fresh.
3. **Timestamp** — `last_stage_changed_at` is set to now.
4. **History** — an entry is appended to `flow_stage_history`.
5. **Automations** — active `stage_exited` automations for the old stage and `stage_entered` automations for the new stage are fired via the Events system.
6. **Watchers** — a `item_stage_changed:NextDeveloper\Flow\Items` event is fired for any registered listeners to notify watchers.

---

Automation Triggers
-------------------

[](#automation-triggers)

TriggerWhen it fires`item_created`A new item is added to a pipeline`stage_entered`An item moves into a stage`stage_exited`An item moves out of a stage`sla_breached`An item has exceeded `sla_days` in its current stageSet `flow_stage_id` to `null` on an automation to make it fire for all stage transitions in the pipeline.

---

SLA Detection
-------------

[](#sla-detection)

Dispatch `CheckSlaBreachesJob` on a schedule (recommended: hourly) to detect and fire `sla_breached` automations:

```
// app/Console/Kernel.php
$schedule->job(new \NextDeveloper\Flow\Jobs\CheckSlaBreachesJob)->hourly();
```

The job finds all items where time in stage exceeds the stage's `sla_days` and fires the matching automations. Stages with `is_won = true` or `is_lost = true` are excluded.

---

Custom Field Types
------------------

[](#custom-field-types)

`field_type`Expected value format`text`Plain string`number`Numeric string, e.g. `"42500"``date`ISO 8601, e.g. `"2026-07-01"``boolean``"true"` or `"false"``select`One of the strings in column `options``multi_select`JSON array string, e.g. `'["High","Urgent"]'``json`Any valid JSON stringAll values are stored as `TEXT`. The `field_type` on `flow_columns` is the contract for how consumers should cast and validate them.

---

Configuration
-------------

[](#configuration)

After publishing, `config/flow.php` accepts global and per-model scope classes:

```
return [
    'scopes' => [
        'global'      => [],         // Applied to every flow model
        'flow_items'  => [],         // Applied to Items only
        // flow_pipelines, flow_stages, flow_columns, ...
    ],
];
```

To enable or disable the module's routes:

```
// config/leo.php
'allowed_routes' => [
    'flow' => true,
],
```

---

Documentation
-------------

[](#documentation)

FileContents[docs/Module.md](docs/Module.md)Architecture overview, data model, lifecycle queries[docs/UI.md](docs/UI.md)UI development guide — screens, API reference, interaction flows---

License
-------

[](#license)

MIT — see [LICENSE](LICENSE).

---

Support
-------

[](#support)

For questions, issues, or enterprise support:

**Email:**

Please include your platform version, PHP version, and a description of the issue.

---

Our Libraries
-------------

[](#our-libraries)

This library is part of the **NextDeveloper / PlusClouds open-source ecosystem**. Browse all available libraries and find the right building blocks for your next project:

---

Join the Community
------------------

[](#join-the-community)

We believe great software is built together. The PlusClouds developer community is a place where engineers share ideas, ask questions, showcase what they have built, and help shape the direction of these libraries. Whether you are integrating a single package or building an entire platform on top of our stack, you are very welcome here.

Come and join us — we would love to see what you build:

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance98

Actively maintained with recent releases

Popularity15

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

28

Last Release

10d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/95028646?v=4)[Harun Barış Bulut](/maintainers/yakari007)[@yakari007](https://github.com/yakari007)

---

Top Contributors

[![yakari007](https://avatars.githubusercontent.com/u/95028646?v=4)](https://github.com/yakari007 "yakari007 (31 commits)")

### Embed Badge

![Health badge](/badges/nextdeveloper-flow/health.svg)

```
[![Health](https://phpackages.com/badges/nextdeveloper-flow/health.svg)](https://phpackages.com/packages/nextdeveloper-flow)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k11](/packages/tempest-framework)[unopim/unopim

UnoPim Laravel PIM

10.1k2.2k](/packages/unopim-unopim)[concrete5/core

Concrete – an open source content management system.

20163.8k49](/packages/concrete5-core)

PHPackages © 2026

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