README

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)

👉 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)

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

Component	Status	Description
🧾 Workflow List	👷 In Progress	A management dashboard for all active batches.
🧠 Approval Timeline	🎨 Designing	A visual history of who approved/rejected and when.
🔐 IAM Dashboard	⚙️ Backend Ready	Powered 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.

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

📦 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 for scoped authority.

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

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

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

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

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]

⏱ 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]

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

Installation

composer require apurba-labs/laravel-approval-engine

Setup

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

Create Workflow Module

php artisan make:workflow-module Requisition

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

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)

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

Example:

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

Architecture (Clean & Headless)

graph TD
    A[Adapters: API / CLI / Queue] --> B[Workflow Manager]
    B --> C[Workflow Engine]
    C --> D[Domain Models]
    C --> E[Rule Resolver]
    C --> F[Stage Navigator]
    C --> G[Events]

    G --> H[Listeners]
    H --> I[Notifications]
    I --> J[Batch Processor]

    B --> K[Token Service]

Commands

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

Why This Engine is Different

Unlike traditional Laravel packages:

- ❌ No fat controllers
- ❌ No hardcoded approval flows
- ❌ No tight coupling with models

Instead:

- ✅ Headless workflow engine
- ✅ Event-driven lifecycle
- ✅ Token-based approvals
- ✅ Smart batching (enterprise-grade)
- ✅ IAM-ready (RBAC, multi-tenant future)

Roadmap

### v1.4 (Current 🚧)

✅ Workflow engine \
✅ IAM integration \
🔜 Filament UI \
🔜 Rule Builder (no-code)

### v2.0

🔜 Slack / Teams integration \
🔜 Advanced analytics

### v3.0 (SaaS)
🔜 Multi-tenant system \
🔜 API platform
🔜 Dashboard (Next.js)

⭐ 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

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

If you need help designing or integrating:

Workflow engines
Approval pipelines
Multi-tenant SaaS systems

Feel free to reach out.

📩 Connect on LinkedIn
📧 apurbansinghdev@gmail.com

🤝 Contributing

PRs are welcome.

License

MIT License

apurba-labs / laravel-approval-engine

Maintainers

Package info

Statistics

Security