PHPackages                             apurba-labs/laravel-approval-engine - 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. [Authentication & Authorization](/categories/authentication)
4. /
5. apurba-labs/laravel-approval-engine

ActiveLibrary[Authentication & Authorization](/categories/authentication)

apurba-labs/laravel-approval-engine
===================================

Batch-based approval workflow engine for Laravel

v1.8.2(6d ago)10491MITPHPPHP ^8.4

Since Mar 19Pushed 2mo agoCompare

[ Source](https://github.com/apurba-labs/laravel-approval-engine)[ Packagist](https://packagist.org/packages/apurba-labs/laravel-approval-engine)[ RSS](/packages/apurba-labs-laravel-approval-engine/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (3)Dependencies (21)Versions (21)Used By (0)

Laravel Approval Engine
=======================

[](#laravel-approval-engine)

[![Laravel](https://camo.githubusercontent.com/afe280ed5336d32590bb167f1a6223e8fa18cee7201d77bd523675721ac433a3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e782d7265643f6c6f676f3d6c61726176656c)](https://laravel.com/)[![PHP](https://camo.githubusercontent.com/b3dc90cb0374438e8ee57e57679045efe8f43f96aaad5e09d74b802a9c05f72d/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322d626c75653f6c6f676f3d706870)](https://www.php.net/)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](LICENSE)[![GitHub stars](https://camo.githubusercontent.com/d630b8cb3a34b69782a44f6f1cfb63411ed1e4db9c4f6f15921579f703cda8df/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f6170757262612d6c6162732f6c61726176656c2d617070726f76616c2d656e67696e653f7374796c653d736f6369616c)](https://github.com/apurba-labs/laravel-approval-engine/stargazers)

### Stop Email Spam. Start Smart Approvals.

[](#stop-email-spam-start-smart-approvals)

A modular, batch-based, multi-stage approval workflow engine for Laravel. Designed for **real-world enterprise workflows** -- it handles **high-volume enterprise requests** into actionable notification batches with email-based approvals and fully configurable stages..

Demo (Real Workflow)
--------------------

[](#demo-real-workflow)

👉 Create Request → Batch → Approval → Timeline → Done

🚧 Demo GIF coming soon (actively working on UI)

Meanwhile, you can test locally:

```
php artisan approval:demo
```

---

🏗️ Active Development (UI Layer)
--------------------------------

[](#️-active-development-ui-layer)

We are currently building the frontend components to provide a full "Plug & Play" experience.

ComponentStatusDescription🧾 **Workflow List**👷 In ProgressA management dashboard for all active batches.🧠 **Approval Timeline**🎨 DesigningA visual history of who approved/rejected and when.🔐 **IAM Dashboard**⚙️ Backend ReadyPowered by `laravel-iam` for scoped RBAC management.👉 **Note:** Screenshots and a full Demo GIF will be added in upcoming releases as the UI components are finalized.
------------------------------------------------------------------------------------------------------------------

[](#-note-screenshots-and-a-full-demo-gif-will-be-added-in-upcoming-releases-as-the-ui-components-are-finalized)

Why This Package? Solving "Approval Fatigue"
--------------------------------------------

[](#why-this-package-solving-approval-fatigue)

In most enterprise systems:

- **Email Spam:** 100 purchase requests = 100 separate emails to the Manager. 😓
- **Hardcoded Logic:** Approval steps are buried inside Controllers or Models.
- **No Escalation:** No built-in way to remind pending approvers or escalate.

**Laravel Approval Engine** solves this by separating the **Workflow Logic** from your **Business Models** and grouping requests into smart batches.

---

### Key Features

[](#key-features)

- **📦 Smart Batching:** Group 50 records into **1 single email/notification**.
- **⛓️ Multi-Stage Workflows:** Define paths like `Requisition -> HOS -> COO -> Finance`.
- **🔗 Secure Token-Based Approval:** Approve or Reject directly from email or Slack via expiring secure links.
- **🧩 Zero-Coupling:** Works with any Eloquent model without altering your schema.
- **⏳ Escalation Engine:** (v2.0) Automatic reminders and "Escalate to Higher Role" logic.
- **🚀 IAM Ready:** Integrates with [Laravel IAM](https://github.com/apurba-labs/laravel-iam) for scoped authority.

---

Engineering Philosophy
----------------------

[](#engineering-philosophy)

This package is built on a simple belief:

> **Workflow logic should not live inside controllers or models.**

Modern systems require:

- Separation of concerns
- Scalable architecture
- Configurable business logic

Instead of hardcoding approval flows, this engine provides:

- ✅ **Modular workflow design** (plug & play modules)
- ✅ **Headless architecture** (UI-agnostic, API-first)
- ✅ **Database-driven configuration** (no redeploy needed)
- ✅ **IAM-based authorization** (not role hardcoding)

This allows teams to evolve workflows without rewriting core logic.

---

Architectural Maturity
----------------------

[](#architectural-maturity)

The PHP ecosystem is evolving beyond framework defaults toward **clean, scalable architecture**.

Recent industry trends emphasize:

- Moving from **fat controllers → Action & DTO-based architecture**
- Designing **configurable, database-driven systems**
- Building **enterprise-grade workflow engines and scoring systems**
- Reducing dependency on external SaaS by building **in-house solutions**
- Improving **observability, auditability, and system transparency**

At Apurba Labs, this is not a trend — it’s the foundation.

Our systems are designed to:

- Be **modular and extensible**
- Support **complex business logic (workflows, approvals, IAM)**
- Operate in **high-scale, event-driven environments**
- Remain **framework-agnostic and future-proof**

---

How This Project Aligns
-----------------------

[](#how-this-project-aligns)

Laravel Approval Engine is built following modern architectural principles:

- ✅ Action-driven workflow execution (no fat controllers)
- ✅ IAM-based authorization (permission-first, not role-only)
- ✅ Modular workflow modules (plug & play architecture)
- ✅ Database-driven workflow configuration
- ✅ Full auditability of approval lifecycle
- ✅ Batch-based processing for high-volume systems

This makes the engine suitable for **enterprise-grade applications and SaaS platforms**.

---

Example Use Cases
-----------------

[](#example-use-cases)

- 🧾 Requisition Approval (HOS → COO)
- 💰 Invoice Approval (Manager → Finance → CFO)
- 🛒 Purchase Workflow
- 🧑‍💼 Leave Approval System

---

How It Works
------------

[](#how-it-works)

 ```
graph TD
    A[Create Request] --> B[Batch Created]
    B --> C[Email Sent]
    C --> D[User Clicks Link]
    D --> E[Approve / Reject]
    E --> F[Next Stage]
    F --> G[Workflow Completed]
```

      Loading ---

⏱ Escalation & Reminder Flow
--------------------------------

[](#-escalation--reminder-flow)

 ```
graph TD
    A[Batch Sent] --> B[Wait]
    B --> C{Approved?}
    C -- No --> D[Reminder]
    D --> E{Still Pending?}
    E -- Yes --> F[Escalate]
```

      Loading ---

Quick Start (2 Minutes)
-----------------------

[](#quick-start-2-minutes)

```
git clone https://github.com/apurba-labs/laravel-approval-engine

cd laravel-approval-engine/example/laravel-demo

composer install
cp .env.example .env
php artisan key:generate

php artisan migrate
php artisan approval:demo
```

👉 Output:

```
✔ Sample data created
✔ Batch generated
✔ Approval link generated
```

Demo Screenshot
---------------

[](#demo-screenshot)

[![Workflow](./docs/demo.png)](./docs/demo.png)

---

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

[](#installation)

```
composer require apurba-labs/laravel-approval-engine
```

---

Setup
-----

[](#setup)

```
php artisan vendor:publish --tag=approval-config
php artisan migrate
php artisan db:seed --class="ApurbaLabs\ApprovalEngine\Database\Seeders\WorkflowDatabaseSeeder"
```

---

Create Workflow Module
----------------------

[](#create-workflow-module)

```
php artisan make:workflow-module Requisition
```

### Example: Define Module

[](#example-define-module)

```
class RequisitionModule extends BaseWorkflowModule
{
    public function model(): string
    {
        return \App\Models\Requisition::class;
    }

    /**
     * Validate records before they enter a batch.
     * Useful for checking data integrity or custom business rules.
     */
    public function validate(array $data): void
    {
        // Default: No validation required
        validator($data, [
            'total_amount' => 'required|numeric|min:1',
            'user_id' => 'required|exists:users,id',
        ])->validate();
    }

    public function approvedColumn(): string
    {
        return 'approved_at';
    }

    /**
     * Default status column name.
     * Override this in the child class if it differs.
     */
    public function statusColumn(): string
    {
        return 'status';
    }

    /**
     * Default priorities: check for 'user', then 'creator'.
     * Individual modules can override this.
     */
    public function ownerRelations(): array
    {
        return ['user', 'creator'];
    }

    /**
     * Allow developers to add extra relations (like 'items' or 'department').
     */
    protected function customRelations(): array
    {
        return [];
    }

    public function selectColumns(): array
    {
         return [
            'id',
            'user_id',
            'reference_id',
            'stage',
            'stage_status',
            'status',
            'approved_at',
        ];
    }

    public function displayColumns(): array
    {
        return [
            'reference_id' => 'Reference',
            'user.name' => 'Requested By',
        ];
    }
    public function relationModels(): array
    {
        return [
            'user' => \ApurbaLabs\ApprovalEngine\Tests\Support\Models\User::class,
            //'admin' => \App\Models\Admin::class,
        ];
    }
}
```

---

🔐 Token-Based Approval API
--------------------------

[](#-token-based-approval-api)

```
Approve workflows securely without login using expiring tokens.

POST /api/v1/approvals/token/approve

Example Request:

{
  "token": "secure-token-here"
}

Behavior
- Validates token (expiry + usage)
- Resolves workflow + approver
- Executes approval via engine
- Marks token as used

👉 Perfect for:

- Email approvals
- Slack / Teams integrations
- External systems
```

---

RBAC Integration (laravel-iam)
------------------------------

[](#rbac-integration-laravel-iam)

```
This engine works seamlessly with:
👉 Role-based access control (RBAC)
👉 Permission-based approval resolution

Example:

$user->can('approval.approve');
```

---

Architecture (Clean & Headless)
-----------------------------------

[](#architecture-clean--headless)

 ```
graph TD

    A[Adapters API CLI Queue] --> B[Workflow Manager]

    B --> C[Workflow Engine]

    C --> D[Workflow Domain Models]
    C --> E[Rule Resolver]
    C --> F[Stage Navigator]

    C --> G[Workflow Events]

    G --> H[Listeners]

    H --> I[Notification Service]

    I --> J[Notification Dispatcher]

    J --> K[Queue Jobs]

    K --> L[Email Slack Teams]

    M[Approval Token Service]

```

      Loading Applications own the business data.

The Approval Engine only orchestrates workflow state, approval progression, events, notifications, and audit history.

---

Commands
--------

[](#commands)

```
php artisan approval:send-batch
php artisan approval:status

```

---

Why This Engine is Different
----------------------------

[](#why-this-engine-is-different)

```
Unlike traditional Laravel packages:

- ❌ No fat controllers
- ❌ No hardcoded approval flows
- ❌ No framework-specific business logic
- ❌ No tenant assumptions
- ❌ No tight coupling with models

Instead:

- ✅ Headless workflow engine
- ✅ Event-driven lifecycle
- ✅ Module-based architecture
- ✅ Plugin system for extensibility
- ✅ Token-based approvals
- ✅ Smart notification batching
- ✅ IAM-friendly (works with any RBAC solution)
- ✅ Application-agnostic design
- ✅ Enterprise-ready audit trail

The engine focuses on workflow orchestration only.

Tenancy, billing, user management, dashboards, and application-specific concerns belong to the consuming application.
```

---

Roadmap
-------

[](#roadmap)

### v1.7 (Current ✅)

[](#v17-current-)

- ✅ Headless workflow engine
- ✅ Multi-stage approval lifecycle
- ✅ Event-driven architecture
- ✅ Token-based approvals
- ✅ Smart notification batching
- ✅ Plugin system
- ✅ Module registry
- ✅ IAM integration support
- ✅ Clean architecture boundaries

### v1.8

[](#v18)

- 🔜 SLA and escalation policies
- 🔜 Approval delegation
- 🔜 Enhanced notification channels (Slack, Teams, Webhooks)
- 🔜 Workflow analytics and metrics
- 🔜 Reminder and follow-up automation

### v2.0

[](#v20)

- 🔜 Visual workflow designer
- 🔜 Dynamic rule builder
- 🔜 Workflow versioning
- 🔜 Advanced audit and compliance tools
- 🔜 Enterprise reporting and analytics

### Future Exploration

[](#future-exploration)

- 🔜 Plugin marketplace
- 🔜 BPMN import/export
- 🔜 Workflow simulation and testing tools
- 🔜 AI-assisted workflow recommendations

---

### Out of Scope

[](#out-of-scope)

The following are intentionally outside the scope of Laravel Approval Engine:

- Multi-tenant SaaS platforms
- Billing and subscriptions
- User onboarding systems
- CRM / ERP functionality
- Dashboard applications

These concerns belong to the consuming application.

⭐ Support the Project
---------------------

[](#-support-the-project)

If this package has helped you streamline your enterprise workflows, please consider supporting it:

- **Star the Repo** – It helps other developers find this tool.
- **Share with your Team** – Spread the word to your fellow Laravel developers.
- **Contribute** – Submit a PR or open an issue to help make it even better.

---

💼 Consulting & Implementation
---------------------------------

[](#-consulting--implementation)

This engine is actively used as the foundation for scalable approval systems.

If you need help designing or integrating:

- Workflow engines
- Approval pipelines
- Event-driven architectures
- Enterprise workflow automation
- Laravel IAM / RBAC systems
- Workflow analytics and notification strategies

Feel free to reach out.

📩 **[Connect on LinkedIn](https://www.linkedin.com/in/apurba-narayan-singh/)**
📧 ****

---

🤝 Contributing
--------------

[](#-contributing)

PRs are welcome.

---

License
-------

[](#license)

MIT License

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance92

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity61

Established project with proven stability

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

Recently: every ~16 days

Total

15

Last Release

6d ago

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

v1.5.0PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/cf451535411e28149e4b7f65d90625f54be2dc4f9a37bd119eee6204d3f73566?d=identicon)[apurbasingh](/maintainers/apurbasingh)

---

Tags

laravelworkflowrbactask automationapproval-workflowapproval-enginebatch-approvalmulti-stage-approvalenterprise-workflownotification-batchingsaas-readyprocess-approval

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/apurba-labs-laravel-approval-engine/health.svg)

```
[![Health](https://phpackages.com/badges/apurba-labs-laravel-approval-engine/health.svg)](https://phpackages.com/packages/apurba-labs-laravel-approval-engine)
```

###  Alternatives

[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k4.3M155](/packages/bezhansalleh-filament-shield)[directorytree/ldaprecord-laravel

LDAP Authentication & Management for Laravel.

5732.5M22](/packages/directorytree-ldaprecord-laravel)[hasinhayder/tyro

Tyro - The ultimate Authentication, Authorization, and Role & Privilege Management solution for Laravel 12 & 13

6796.8k7](/packages/hasinhayder-tyro)[masterix21/laravel-licensing

Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts.

1614.1k4](/packages/masterix21-laravel-licensing)

PHPackages © 2026

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