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.

👉 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[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]

Applications own the business data.

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

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

v1.7 (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

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

v2.0

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

Future Exploration

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

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

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
• Event-driven architectures
• Enterprise workflow automation
• Laravel IAM / RBAC systems
• Workflow analytics and notification strategies

Feel free to reach out.

📩 Connect on LinkedIn
📧 apurbansinghdev@gmail.com

🤝 Contributing

PRs are welcome.

License

MIT License