Documentation

Complete guide to building flexible approval workflows in your Laravel application.

Features

• Multiple Workflow Versions: Define and evolve workflows over time without breaking existing instances
• Dynamic Assignment: Assign tasks to users, roles (Spatie Permission integration), or managers
• Flexible Modes: Support for 'any' (one person approves) or 'all' (consensus required) modes
• SLA Monitoring: Built-in support for task deadlines and breach recording
• Delegation: Automatic redirection of tasks based on user availability (vacation/out-of-office)
• Audit Trail: Detailed event logging (started, assigned, acted, breached, completed) for every action
• Conditional Transitions: Override default flow based on actions (approve/reject/changes_requested)
• Team / Department Scoping: Optionally scope workflows, tasks, and approvers by team_id
• UI & API Agnostic: No controllers, routes, views, or APIs are enforced. Each application decides how workflows are exposed

Installation

Requirements

• PHP 8.2 or higher (PHP 8.4+ recommended)
• Laravel 12.x
• Composer
• Spatie Laravel Permission (optional, for role-based assignment)

Step 1: Install via Composer

composer require putheakhem/approval-workflow

Step 2: Publish Configuration

php artisan vendor:publish --tag=approval-workflow-config

This publishes the configuration file to config/approval-workflow.php

Step 3: Publish Migrations

php artisan vendor:publish --tag=approval-workflow-migrations

Step 4: Run Migrations

php artisan migrate

Configuration

The configuration file is published to config/approval-workflow.php

return [
    // Enable SLA checking command
    'sla_command' => env('APPROVAL_WORKFLOW_SLA_COMMAND', false),
    
    // Default SLA hours for approval steps
    'default_sla_hours' => 24,
    
    // Team scoping
    'enable_team_scoping' => true,
];

Basic Usage

Make a Model Approvable

Use the HasWorkflow trait on any Eloquent model:

use PutheaKhem\ApprovalWorkflow\Concerns\HasWorkflow;

class Term extends Model
{
    use HasWorkflow;
}

Workflow Definitions

Define workflows using PHP arrays or JSON format with versioning support:

[
    'steps' => [
        ['key' => 'start', 'type' => 'start', 'next' => 'review'],
        [
            'key' => 'review',
            'type' => 'approval',
            'mode' => 'any',
            'sla_hours' => 24,
            'assignment' => [
                'type' => 'role',
                'roles' => ['reviewer'],
            ],
            'next' => 'end',
        ],
        ['key' => 'end', 'type' => 'end'],
    ],
    'transitions' => [
        ['from' => 'review', 'on' => 'reject', 'to' => 'end'],
    ],
]

Starting Workflows

Initialize a workflow instance for your subject model:

$instance = $service->startWorkflow(
    workflowKey: 'service-approval',
    context: [
        'team_id' => 1,
        'requester_id' => auth()->id(),
    ],
    teamId: 1,
    startedBy: auth()->id(),
);

Approving & Rejecting Tasks

Approve

use PutheaKhem\ApprovalWorkflow\Services\ApprovalService;

$approval = app(ApprovalService::class);

$approval->approve(
    instance: $instance,
    taskId: $taskId,
    userId: auth()->id(),
    notes: 'Approved with conditions'
);

Reject

$approval->reject(
    instance: $instance,
    taskId: $taskId,
    userId: auth()->id(),
    notes: 'Missing required documents'
);

Request Changes

$approval->requestChanges(
    instance: $instance,
    taskId: $taskId,
    userId: auth()->id(),
    notes: 'Please provide additional details'
);

API Reference

Complete list of available services and methods.

Events

The package emits the following domain events:

Audit Trail

All workflow actions are recorded in the workflow_events table for transparency and compliance.

SLA Support

Enable SLA checking to monitor approval deadlines.

Enable SLA Command

APPROVAL_WORKFLOW_SLA_COMMAND=true

Run SLA Check

php artisan workflow:check-sla

Schedule in Kernel

// In routes/console.php or app/Console/Kernel.php
Schedule::command('workflow:check-sla')->hourly();