Installation and setup.

Laravel Approval requires PHP 8.3 or 8.4 and Laravel 12 or 13.

The order matters during installation. Configuration values decide the table names and key types used by the published migrations.

1. Install the package

composer require byrcsc/laravel-approval

Laravel discovers the package and its Approval facade automatically.

2. Publish the configuration

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

This command writes config/approval.php.

Set the model used for requesters, approvers, and other actors:

APPROVAL_USER_MODEL=App\Models\User

Set the key type used by that model before publishing the migrations:

APPROVAL_USER_KEY_TYPE=uuid

The setting applies to requester, approver, delegate, actor, and uploader columns. Changing it after data exists requires an application migration.

The model under approval uses a separate approvable_id column. The approval.approvable_key_type setting controls its type. It takes the same values and defaults to int. Add the key to config/approval.php when your approvable models use another key type:

'approvable_key_type' => 'uuid',

3. Publish and run the migrations

php artisan vendor:publish --tag="approval-migrations"
php artisan migrate

The first migration creates eight related tables. The second creates approval_delegations for standing delegations and adds a delegation_id column to the assignments table. Publish the configuration first so both migrations use the table names and key types you selected.

If you change table names after migrating, create an application migration to rename the existing tables.

Upgrading from 1.0

An installation from 1.0 needs only the second migration. Publish and run the migrations the same way. Until the new migration has run, the rest of the package works as it did in 1.0. During that time, Approval::grantDelegation() throws an exception that names the commands to run.

The application still boots with a configuration file published for 1.0. Keys that the file lacks, such as table_names.delegations and model_classes, use their defaults.

4. Verify the installation

Run the status command:

php artisan approval:status

A new installation reports zero requests in every state. A successful response confirms that Laravel can resolve the package and query its tables.

php artisan about also lists a Laravel Approval section. It shows whether notifications are on, whether self-approval is allowed, both key types, and any custom model classes.

Optional settings

These environment variables control common behavior:

The workflows and stages, notifications, and SLAs and escalation pages explain the remaining settings when you need them.

Optional notification files

Publish these files only when you need to change notification text or email markup:

php artisan vendor:publish --tag="approval-translations"
php artisan vendor:publish --tag="approval-views"

See notification content for the published files and available placeholders.

Optional schedule

The package stores deadlines without a scheduler. Reminders and escalation require the approval:escalate command. Standing delegations that open or close in the future also need a scheduled command. Add the ones you use to routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('approval:escalate')->everyFifteenMinutes();
Schedule::command('approval:delegations')->everyFifteenMinutes();

What to read next

• Quick start to create a workflow and complete an approval.
• Workflows and stages to configure approval rules.
• Troubleshooting if the status command cannot read the package tables.