Download the PHP package fzengin19/laravel-approval without Composer

A comprehensive approval system package for PHP 8.3+ and Laravel 10+. It provides a flexible way to manage approval statuses for your models. Developed with a TDD approach, with reliable code and high test coverage.

✨ Features

• 🚀 Easy Integration: Integrate your models with approval system by just adding a trait.
• ⚙️ Flexible Configuration: Two different modes (insert/upsert) and customizable settings.
• 💡 Configurable Initial State: Define a default status for models that haven't been through an approval process yet.
• 🧠 Smart Rejection Handling: Normalizes unknown rejection reasons to other while preserving the original text in the comment.
• 🔍 Global Scope: Automatically show only approved records with configurable behavior.
• 🔔 Comprehensive Event System: 6 events with clear before/after transition timing and causedBy payloads.
• 📊 Statistics Service: Built-in statistics calculation with percentages and model-specific data.
• 🎭 Facade Support: Static API for easy usage with full IDE support.
• 🖥️ Artisan Commands: View statistics via CLI with table formatting.
• 🔧 Repository Pattern: Clean data access layer with insert/upsert modes.
• 🛡️ Validation System: Input validation with business rule enforcement.
• 🌐 Webhook Support: Configurable webhook endpoints for external integrations.
• 🎯 Model-specific Configuration: Override settings per model with inheritance.
• 🔄 Auto Pending: Automatically set models to pending status on creation.
• 🔗 Polymorphic Approval Audit Trail: Approval records keep a polymorphic causer relation to the configured user model.
• ✨ Modern PHP: Utilizes PHP 8.3+ features and enums for type-safe statuses.
• 📈 Performance Optimized: Indexed database fields and efficient queries.

🚀 Quick Start

1. Installation

2. Publish and Migrate

3. Add Trait to Your Model

4. Start Using

That's it. Your model now has full approval functionality.

📦 Installation

Requirements

• PHP 8.3 or higher
• Laravel 10 or higher

Install via Composer

Publish Configuration

Run Migrations

⚙️ Configuration

The published config file (config/approvals.php) contains comprehensive configuration options. Here are the key sections:

allow_custom_reasons is kept for backward compatibility in the config shape, but unknown reasons are still normalized to other.

Note: Approval statuses are managed by the LaravelApproval\Enums\ApprovalStatus enum:

• ApprovalStatus::PENDING
• ApprovalStatus::APPROVED
• ApprovalStatus::REJECTED

📖 Usage Guide

Basic Operations

Query Scopes

Modes

Insert Mode (Default)

Creates a new approval record for each status change. Ideal for history tracking and audit trails.

Configure in your config/approvals.php:

Usage:

Upsert Mode

Updates existing approval record. Ideal for keeping single record and current status only.

Configure in your config/approvals.php:

Usage:

Note: Mode can be configured per model in the config file.

Smart Rejection Handling

The reject() method stores configured reasons directly and normalizes unknown reasons to other:

Validation Rules:

• reason field: maximum 255 characters (string field limit)
• comment field: no length limit (TEXT field)

Global Scope

auto_scope and show_only_approved_by_default do different jobs:

• auto_scope is the global master switch that registers the package scope on approvable models.
• show_only_approved_by_default controls whether that scope filters a given model down to approved records by default.

When both are enabled, only approved records are visible by default:

The scope is registered for approvable models only when approvals.default.auto_scope is enabled:

If auto_scope is disabled, you can still apply the scope manually when needed:

Auto Pending

Automatically set to pending status when model is created. Configure in your config/approvals.php:

Usage:

Model-Specific Configuration

Override default settings for specific models in your config/approvals.php. Only specify the settings you want to override:

🔔 Events

Listen to events on status changes. The package provides 6 different events with rich context:

Available Events

Before persistence:

• LaravelApproval\Events\ModelApproving
• LaravelApproval\Events\ModelRejecting

After persistence:

• LaravelApproval\Events\ModelApproved
• LaravelApproval\Events\ModelRejected
• LaravelApproval\Events\ModelSettingPending
• LaravelApproval\Events\ModelPending

ModelSettingPending is dispatched after the pending approval record is saved and immediately before ModelPending.

Event Usage

Event Configuration

Configure events globally or per model in your config/approvals.php:

Configurable actions can be invokable classes:

Closures are not config-cache-safe, so use class strings here instead.

Event Properties

Event payloads are intentionally not identical across all six events:

• All events expose model, causedBy, context, and metadata.
• Post-save events expose approval: ModelApproved, ModelRejected, ModelSettingPending, and ModelPending.
• Rejection events expose reason: ModelRejecting and ModelRejected.
• Comment-bearing events expose comment: approving, approved, rejecting, rejected, setting pending, and pending.

🎭 Facade Usage

🖥️ Artisan Commands

Command Output Examples

All Models Statistics: +-------------------+-------+----------+--------+----------+-------------+ | Model | Total | Approved | Pending| Rejected | Approved % | +-------------------+-------+----------+--------+----------+-------------+ | App\Models\Post | 100 | 75 | 15 | 10 | 75.00% | | App\Models\Comment| 50 | 40 | 5 | 5 | 80.00% | +-------------------+-------+----------+--------+----------+-------------+

Single Model Statistics: +----------+-------+------------+ | Metric | Count | Percentage | +----------+-------+------------+ | Total | 100 | 100% | | Approved | 75 | 75.00% | | Pending | 15 | 15.00% | | Rejected | 10 | 10.00% | +----------+-------+------------+ bash composer test

tests/ ├── ArchTest.php # Architecture tests ├── Commands/ # Artisan command tests ├── Core/ # Core service tests ├── Events/ # Event class tests ├── Exceptions/ # Exception tests ├── Facades/ # Facade tests ├── Integration/ # Integration tests ├── Listeners/ # Listener tests ├── Models/ # Model tests ├── Services/ # Service tests ├── Traits/ # Trait tests ├── ExampleTest.php └── TestCase.php

## 📝 Changelog

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## 🤝 Contributing

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

## 🔒 Security Vulnerabilities

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

## 👨‍💻 Credits

- [Fatih Zengin](https://github.com/fzengin19)
- [All Contributors](../../contributors)

## 📄 License

This package is licensed under the MIT License. See [LICENSE.md](LICENSE.md) for details.