Download the PHP package wezlo/filament-approval without Composer

Filament Approval Workflow Engine

A configurable approval workflow package for Filament. Attach approval chains to any Eloquent model with single, sequential, or parallel approvers, SLA timers, escalation rules, delegation, and a full audit trail.

Requirements

• Filament 4+

Features

• Polymorphic design -- attach approvals to any model via a trait
• Single, sequential, and parallel approval chains
• Configurable approval flows with a Filament resource UI
• Approve, reject, comment, and delegate actions
• SLA timers with auto-escalation (notify, auto-approve, reassign, reject)
• Delegation -- approvers can delegate to another user
• Full audit trail of every action
• Pluggable approver resolvers (specific users, roles, custom callbacks)
• Filament database notifications (requested, approved, rejected, escalated, SLA warning)
• Dashboard widgets (pending approvals table with clickable rows, analytics stats)
• Approval status badge column for resource tables
• Approvals relation manager (full history with slide-over detail view)
• Infolist section for current approval status at a glance
• Per-panel plugin configuration (user model, resolvers, navigation group)
• Scheduled command for SLA processing
• Publishable config and views

Installation

Publish and run migrations:

Ensure you have a notifications table (required for Filament database notifications):

Register the plugin in your Panel Provider:

You can override resolvers, user model, and navigation group per-panel:

Resolution order: plugin override (per-panel) > config file (global) > default fallback.

You can also disable the flow resource or widgets per-panel:

Publish the config (optional):

Quick Start

1. Add the trait to your model

This gives you:

2. Add approval actions to your resource page

This adds five context-aware actions to the page header:

• Submit for Approval -- visible when no pending approval
• Approve -- visible to assigned/delegated approvers who haven't acted
• Reject -- same visibility, requires a comment
• Comment -- visible to assigned approvers during a pending approval
• Delegate -- visible to assigned approvers, lets them delegate to another user

3. Add the status column to your table

Displays a colored badge: Pending (warning), Approved (success), Rejected (danger), Cancelled (gray).

4. Add approval history to your resource

Relation Manager -- full approval history tab on View/Edit pages:

This adds an "Approvals" tab showing all approval instances. Clicking "View" on any row opens a slide-over with:

• Approval details (flow, status, submitter, dates)
• Step progress (each step with status, approvers, received/required count, SLA)
• Full audit trail (every action with who, what, when, comment)

Infolist Section -- current approval at a glance on View pages:

Shows a collapsible section with:

• Current status badge, flow name, submitter, dates
• Current step details (name, pending approvers, progress, SLA deadline with overdue highlighting)
• Recent activity timeline (collapsible)

The section auto-hides when there's no approval on the record.

5. Create an approval flow

Navigate to the Approvals > Approval Flows resource in your Filament panel. Create a flow with:

• Name -- e.g. "Purchase Order Approval"
• Applies To -- dropdown auto-populated with models that use HasApprovals and are registered as resources in the current panel. Leave blank to apply to any model.
• Steps -- ordered list with:
  • Step name
  • Type: Single / Sequential / Parallel
  • Approver type: dropdown of resolvers configured on the plugin (e.g. Specific Users, Users by Role, or your custom resolvers)
  • Approver config: dynamic fields based on the selected resolver (user picker, role selector, etc.)
  • Required approvals (visible for Parallel type, with "Require N of M" hint)
  • SLA hours (optional)
  • Escalation action (visible when SLA is set)

Approval Flow Types

Single

One approver, one approval required. The simplest flow.

Sequential

Multiple steps executed in order. Step 2 doesn't activate until step 1 is approved. A rejection at any step rejects the entire approval and skips remaining steps.

Parallel

Multiple approvers on a single step. Configure required_approvals to set how many must approve (e.g., 2-of-3). The step completes when the threshold is met.

Approver Resolvers

Resolvers determine who can approve each step. Three are included:

UserResolver

Assigns specific users by ID:

RoleResolver

Assigns all users with a given Spatie role. When multi-tenancy is enabled, approvers are scoped to the approvable model's tenant:

CallbackResolver

Register named callbacks in your service provider for custom logic:

Then select "Custom Callback" as the approver type in the flow builder.

Custom Resolvers

Implement the ApproverResolver contract:

Register it in config/filament-approval.php:

SLA & Escalation

Configure SLA on any step in the flow builder:

• SLA (hours) -- deadline after the step is activated
• Escalation action -- what happens when the SLA is breached:
  • Send Reminder -- notifies approvers again
  • Auto-Approve -- automatically approves the step
  • Auto-Reject -- automatically rejects the entire approval
  • Reassign -- reassigns to different approvers (configure via escalation config)

The approval:process-sla command runs every minute (configurable) and:

1. Sends SLA warnings at 75% of the deadline (configurable threshold)
2. Processes escalations when the deadline is breached

The command is auto-scheduled by the package. To disable:

Delegation

Any assigned approver can delegate their approval authority to another user. The delegate can then approve or reject on their behalf. Delegations are recorded in the audit trail.

Submission Policy

By default, any authenticated user can submit any record for approval, and re-submission is allowed after approval or rejection. Override these methods on your model to customize:

One-time approval (no re-submission)

Restrict who can submit

Combine both

The canBeSubmittedForApproval() method combines all checks (pending status + resubmission policy + user authorization) and is used by the Submit action's visibility logic.

Audit Trail

Every action is recorded in the approval_actions table:

• Submitted
• Approved (with optional comment)
• Rejected (with required comment)
• Commented
• Delegated (with target user and reason)
• Escalated (with escalation action taken)

Access the audit trail:

Notifications

The package sends Filament database notifications for:

• Approval Requested -- sent to each assigned approver when a step activates
• Approval Approved -- sent to the submitter when the full approval completes
• Approval Rejected -- sent to the submitter when rejected
• SLA Warning -- sent to approvers when approaching the deadline
• Escalated -- sent to approvers when the SLA is breached

Dashboard Widgets

The plugin registers two widgets:

PendingApprovalsWidget

A table showing the current user's pending approvals with step name, record reference, time waiting, and SLA status. Overdue items are highlighted in red.

ApprovalAnalyticsWidget

Stats overview with:

• Pending approvals count
• Approved in last 30 days
• Rejected in last 30 days
• Overdue steps count

Disable widgets:

Disable the flow resource:

Blade Components

The package includes Blade components for custom views:

Publish views:

Events & Model Callbacks

There are two ways to react to approval lifecycle events: Laravel events (for decoupled listeners) and model callbacks (for logic that belongs on the model itself).

Laravel Events

Listen to these events via event listeners or subscribers:

Each event carries the relevant Approval or ApprovalStepInstance model.

Model Lifecycle Callbacks

Override these methods on any model using HasApprovals to react directly on the model:

All callbacks are optional -- only override the ones you need. They are called after the action has been persisted to the database.

Programmatic Usage

Use the ApprovalEngine service directly:

Multi-Tenancy

Multi-tenancy is disabled by default. When enabled, approval flows are scoped per tenant and the tenant column is added to the approval_flows migration.

Enable it in config/filament-approval.php:

When scope_approvers is true, the RoleResolver will only return users that share the same tenant as the approvable model.

Important: Configure multi-tenancy before running migrations. The tenant column is only added to the approval_flows table when multi_tenancy.enabled is true.

Configuration

Translations

The package ships with English and Arabic translations. All UI strings (labels, messages, notifications, enum values) are fully translated.

Publish translations to customize:

This copies the language files to lang/vendor/filament-approval/. The translation file is organized by section:

• status.* -- Approval statuses (Pending, Approved, Rejected, Cancelled)
• step_type.* -- Step types (Single, Sequential, Parallel)
• action_type.* -- Audit trail actions (Submitted, Approved, Delegated, etc.)
• escalation.* -- Escalation actions (Send Reminder, Auto-Approve, etc.)
• flow.* -- Flow builder form labels
• actions.* -- Approval action buttons and modals
• notifications.* -- Database notification titles and bodies
• widgets.* -- Dashboard widget labels
• relation_manager.* -- Relation manager labels
• infolist.* -- Infolist section labels

To add a new language, create lang/vendor/filament-approval/{locale}/approval.php with the same structure.

Custom Theme

If you have a custom Filament theme, add the package views to your @source directive:

Testing

License

MIT