PHPackages                             mhqady/flowra - 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. mhqady/flowra

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

mhqady/flowra
=============

Flowra is a flexible, database-driven workflow and state machine engine for Laravel. It supports workflows, typed states, transitions, guards, actions, scopes, and dynamic workflow loading, enabling complex business processes to evolve at runtime without redeploying code.

v0.1.10(2w ago)22611MITPHPPHP ^8.3CI passing

Since Sep 6Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/mhQady/flowra)[ Packagist](https://packagist.org/packages/mhqady/flowra)[ RSS](/packages/mhqady-flowra/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (8)Versions (14)Used By (0)

Flowra
======

[](#flowra)

Flowra is a database-driven workflow engine for Laravel applications. It lets you describe business processes as workflows composed of **typed states**, **transitions**, **guards**, **actions**, and **state groups**—all persisted in your database so processes can evolve without redeploying code.

The package provides artisan generators, migration stubs, rich Eloquent traits, and DTO helpers that make it simple to:

- **Attach workflows** to any Eloquent model.
- **Track current status** and historical registry of each workflow run.
- **Group states** to simplify querying and logic (e.g., "Draft" group containing "Initial" and "Pending").
- **Gate transitions** with custom Guard classes or closures.
- **Execute actions** automatically after a state change.
- **Bulk transitions** for processing multiple models efficiently.
- **Diagram export/import** (Mermaid & PlantUML) to visualize and scaffold workflows.
- **Fluent query scopes** that understand both specific states and state groups.

---

📦 Installation
--------------

[](#-installation)

Flowra supports Laravel 12 and 13 on PHP 8.3+.

```
composer require mhqady/flowra
```

### 1. Publish Assets

[](#1-publish-assets)

Publish the configuration, migrations, and stubs:

```
php artisan vendor:publish --tag=flowra-config
php artisan vendor:publish --tag=flowra-migrations
php artisan vendor:publish --tag=flowra-stubs
```

### 2. Run Migrations

[](#2-run-migrations)

Flowra uses two tables: `statuses` (current state) and `statuses_registry` (history).

```
php artisan migrate
```

---

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

[](#-quick-start)

### 1. Generate a Workflow

[](#1-generate-a-workflow)

Use the artisan command to scaffold a workflow and its states:

```
php artisan flowra:make-workflow "OrderWorkflow"
```

This creates:

- `app/Workflows/OrderWorkflow/OrderWorkflow.php`
- `app/Workflows/OrderWorkflow/OrderWorkflowStates.php`

### 2. Define States and Transitions

[](#2-define-states-and-transitions)

In `OrderWorkflowStates.php`, define your cases and optional groups:

```
enum OrderWorkflowStates: string
{
    use Flowra\Enums\BaseEnum;

    case PENDING = 'pending';
    case PROCESSING = 'processing';
    case COMPLETED = 'completed';

    public static function groups(): array
    {
        return [
            \Flowra\DTOs\StateGroup::make('active')->children(self::PENDING, self::PROCESSING),
        ];
    }
}
```

In `OrderWorkflow.php`, define the allowed transitions:

```
class OrderWorkflow extends BaseWorkflow
{
    public static function transitionsSchema(): array
    {
        return [
            Transition::make('process', OrderWorkflowStates::PENDING, OrderWorkflowStates::PROCESSING)
                ->guard(CheckStock::class)
                ->action(NotifyCustomer::class),
        ];
    }
}
```

### 3. Prepare Your Model

[](#3-prepare-your-model)

Add the `HasWorkflow` trait and implement `HasWorkflowContract`:

```
use Flowra\Contracts\HasWorkflowContract;
use Flowra\Traits\HasWorkflow;

class Order extends Model implements HasWorkflowContract
{
    use HasWorkflow;

    protected static array $workflows = [
        \App\Workflows\OrderWorkflow\OrderWorkflow::class,
    ];
}
```

---

✨ Key Concepts
--------------

[](#-key-concepts)

### Guards & Actions

[](#guards--actions)

- **Guards** (`Flowra\Contracts\GuardContract`) determine if a transition can proceed. If a guard returns `false`, an exception is thrown.
- **Actions** (`Flowra\Contracts\ActionContract`) run after the transition is successfully persisted.

Both can be:

- **Closures**: `->action(fn($t) => ...)`
- **Class Names**: `->guard(MyGuard::class)`
- **Instances**: `->action(new MyAction($param))`

### Dynamic Scopes

[](#dynamic-scopes)

Flowra automatically adds scopes to your model based on the registered workflows. If you have `OrderWorkflow`, you get:

```
// Find orders currently in 'pending' state
Order::whereOrderWorkflowCurrentStatus(OrderWorkflowStates::PENDING)->get();

// Find orders in 'active' group (includes pending and processing)
Order::whereOrderWorkflowCurrentStatus('active')->get();

// Eager load status to avoid N+1
Order::withOrderWorkflowStatus()->get();
```

### Dynamic Relations

[](#dynamic-relations)

Flowra automatically registers Laravel relations on your model for each workflow. If your workflow is `OrderWorkflow`, you can access:

```
// Returns the current Flowra\Models\Status for this workflow
$order->orderWorkflowStatus;

// Returns a collection of Flowra\Models\Registry (history) for this workflow
$order->orderWorkflowRegistry;
```

These are standard Eloquent relations, so you can eager load them or query through them:

```
$orders = Order::with('orderWorkflowStatus')->get();
```

---

🧰 Tooling & Commands
------------------------

[](#-tooling--commands)

- `flowra:make-workflow {name}` – Scaffolds workflow and state classes.
- `flowra:make-guard {name}` / `flowra:make-action {name}` – Generates guard or action classes.
- `flowra:list-workflow` – Lists all registered workflows.
- `flowra:export-workflow {class}` – Exports to Mermaid or PlantUML.
- `flowra:import-workflow {class} --path={file}` – Imports from Mermaid/PlantUML.
- `flowra:cache:warm` / `flowra:cache:clear` – Manage workflow definition cache.

---

🛠 Usage Examples
----------------

[](#-usage-examples)

### Applying Transitions

[](#applying-transitions)

```
$order = Order::find(1);

// Using magic property (key from transitionsSchema)
$order->orderWorkflow->process->apply();

// With metadata
$order->orderWorkflow->process
    ->appliedBy(auth()->id())
    ->comment('Starting the order')
    ->apply();
```

### Bulk Transitions

[](#bulk-transitions)

Process multiple models efficiently:

```
$orders = Order::where('status', 'pending')->get();

OrderWorkflow::applyMany($orders, 'process', appliedBy: auth()->id());
```

### State Jumps

[](#state-jumps)

Force a state change without a defined transition (e.g., for admin resets):

```
$order->orderWorkflow->jumpTo(OrderWorkflowStates::PENDING, 'admin_reset');
```

### History & Audit

[](#history--audit)

```
// Current status
$status = $order->orderWorkflow->status();

// Full transition history
$history = $order->orderWorkflow->registry();
```

---

Flowra makes complex business processes manageable, testable, and visible. Happy flowing!

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance92

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity48

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 ~28 days

Recently: every ~39 days

Total

11

Last Release

14d ago

PHP version history (2 changes)v0.1.0PHP ^8.4

v0.1.8PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/71000742?v=4)[Mohamed AlQady](/maintainers/mhQady)[@mhQady](https://github.com/mhQady)

---

Top Contributors

[![mhQady](https://avatars.githubusercontent.com/u/71000742?v=4)](https://github.com/mhQady "mhQady (27 commits)")

---

Tags

approval-workflowbpmnfinite-state-machinelaravelphpstate-machineworkflowworkflow-enginelaravellaravel-packageworkflowfinite-state machineworkflow enginestate-machinebusiness-processprocess-automationflowraHierarchical State Machine

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/mhqady-flowra/health.svg)

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M345](/packages/psalm-plugin-laravel)[erag/laravel-pwa

A simple and easy-to-use PWA (Progressive Web App) package for Laravel applications.

180124.1k](/packages/erag-laravel-pwa)[ringierimu/state-workflow

Laravel State Workflow provide tools for defining and managing workflows and activities with ease.

3470.2k](/packages/ringierimu-state-workflow)[tarfin-labs/event-machine

Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.

199.4k](/packages/tarfin-labs-event-machine)

PHPackages © 2026

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