salvatorecervone / laravel-permission-toolkit

1.2.9 2026-09-28 15:05 UTC

Requires

• php: ^8.2
• illuminate/auth: ^10.0|^11.0|^12.0
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/routing: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0
• illuminate/view: ^10.0|^11.0|^12.0
• spatie/laravel-permission: ^5.0|^6.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• Salvatore Cervone

• acl
• laravel
• roles
• permissions
• rbac
• matrix
• spatie
• simulator
• laravel-package
• user-manager
• spatie-permission
• audit-log
• integrity-check

Published on Packagist.org on 2026-09-28 15:10 UTC

README

Supercharge your existing spatie/laravel-permission setup with an AWS IAM-style Diagnostic Simulator, an interactive standalone Role-Permission Matrix, a full User Access Manager, a Compliance Audit Trail, and a Database Integrity Doctor.

💡 Why this package?

spatie/laravel-permission is the undisputed industry standard for Laravel RBAC. However, in production applications, developers and security leads constantly hit five major limitations:

1. The "403 Black Box": When a user gets HTTP 403 Forbidden, debugging why is painful. Spatie doesn't explain if it was a missing role, direct permission, policy check, or guard mismatch.
2. Missing Standalone UI: Spatie provides no visual management panel unless you install an entire admin framework like Filament.
3. No Direct User Access UI: Assigning or reviewing roles and permissions for individual users requires manual Tinker commands or building custom admin forms.
4. No Compliance Audit Trail: Spatie doesn't record who assigned or revoked a role/permission, when, or from which IP.
5. Data Drift & Integrity Anomalies: Orphaned pivot records, unused permissions, and guard mismatches quietly pile up over years of development.

Laravel Permission Toolkit solves all of this without changing your database schema. It runs 100% seamlessly on top of your existing Spatie tables.

✨ Features

• 🔍 AWS IAM-Style Diagnostic Simulator & Reverse Lookup (permission:simulate & Web UI)
  Simulate and trace step-by-step why an authorization passed or failed (User identity ➔ Super Admin bypass ➔ Direct permissions ➔ Role inheritance ➔ Laravel Policy check), or run a Reverse Diagnostic Lookup to inspect every user who possesses a specific role or permission and trace their exact access path.
• 🔲 Interactive Role-Permission Matrix (/permission-manager/matrix)
  Spreadsheet-style pivot matrix with real-time AJAX toggling, inline role/permission creation & deletion, 1-click deep links (👥) to authorized users, and automatic Spatie cache invalidation.
• 👥 User Access Management & SoftDeletes Lifecycle (/permission-manager/users)
  List users with live search, filter by Role or Permission (with direct vs inherited indicators), filter by SoftDeletes status (Active vs Deactivated), and safely manage user deactivation, restoration, and force deletion with built-in self-protection guardrails.
• 📜 Security & Compliance Audit Trail (/permission-manager/audit-logs)
  Immutable activity log recording who created, deleted, assigned, or revoked roles and permissions with actor, target user, IP address, and timestamp.
• 🩺 Integrity Doctor (permission:doctor & /permission-manager/doctor)
  Scans your database for orphaned pivot records, empty roles, unused permissions, and Web vs API guard mismatches.
• 💾 JSON Export & Import (permission:export / permission:import)
  Effortlessly sync role-permission definitions between Local, Staging, and Production environments without manual DB dumps.
• 🌍 Bilingual Support (Italian 🇮🇹 & English 🇬🇧)
  Built-in full localization with a 1-click language switcher in the web panel header, publishable translation files (permission-toolkit-translations), and .env / session support.
• 🚀 Interactive Local Demo (Orchestra Workbench)
  Pre-packaged demo with realistic seeders, demo users, roles, and audit trail ready to launch in 1 command.

🚀 Try the Live Demo (Workbench)

To preview and test the complete visual panel locally:

git clone https://github.com/SalvatoreCervone/laravel-permission-toolkit.git
cd laravel-permission-toolkit
composer install
composer run serve

Open your browser at:

http://127.0.0.1:8000/permission-manager

Pre-seeded Demo Data:

• Mario Rossi: [e-mail] (Role: super-admin)
• Laura Bianchi: [e-mail] (Role: manager)
• Giuseppe Verdi: [e-mail] (Role: accountant + Direct Permission: reports.special-audit)
• Anna Neri: [e-mail] (Role: viewer)

📦 Installation in Your Application

1. Require the package via Composer

composer require salvatorecervone/laravel-permission-toolkit

2. Publish Configuration, Translations & (Optional) Audit Migration

# Publish configuration
php artisan vendor:publish --tag="permission-toolkit-config"

# (Optional) Publish translation language files (Italian & English)
php artisan vendor:publish --tag="permission-toolkit-translations"

# (Optional) Publish audit logs migration for security history
php artisan vendor:publish --tag="permission-toolkit-migrations"
php artisan migrate

🔐 Security & Access Control (Production-Ready)

By default in local and testing environments, any authenticated user can view the toolkit. In production, access is strictly forbidden unless authorized via a Gate or custom callback (matching Laravel Horizon/Telescope conventions):

Option A: Define the Gate in AuthServiceProvider

use Illuminate\Support\Facades\Gate;

Gate::define('viewPermissionToolkit', function ($user) {
    return $user->hasRole('super-admin');
});

Option B: Use the PermissionToolkit::auth Callback

use SalvatoreCervone\PermissionToolkit\PermissionToolkit;

PermissionToolkit::auth(function ($request) {
    return $request->user()?->can('manage-permissions');
});

🛡️ Built-in Guardrails:

• Super Admin Protection: Deleting roles configured as super_admin (super-admin / Super Admin) is strictly prohibited and returns 403 Forbidden.
• Self-Lockout Prevention: Authenticated users cannot delete a role they are currently assigned to.
• Multi-Guard Mismatch Guard: Toggling permissions with mismatched guards (web vs api) is validated before Spatie throws an exception.

🔲 Embeddable Blade Component

Want to embed the permission matrix directly inside your custom dashboard without using the standalone layout?

{{-- In any Blade view: --}}
<x-permission-toolkit-matrix />

{{-- Or filter by specific guard or module: --}}
<x-permission-toolkit-matrix guard="web" module="Invoices" />

📢 Domain Events & Webhook Integrations

The package dispatches real-time domain events for all state changes, allowing you to easily trigger webhooks, log to SIEM systems, or notify administrators:

Event	Dispatched When	Payload
SalvatoreCervone\PermissionToolkit\Events\PermissionToggled	Single or bulk matrix toggle	$role, $permission, $action (assigned|revoked), $causer
SalvatoreCervone\PermissionToolkit\Events\UserAccessUpdated	User roles/permissions updated	$user, $addedRoles, $removedRoles, $addedPerms, $removedPerms
SalvatoreCervone\PermissionToolkit\Events\RoleCreated	New role created	$role
SalvatoreCervone\PermissionToolkit\Events\RoleDeleted	Role deleted	$roleName, $roleId
SalvatoreCervone\PermissionToolkit\Events\PermissionCreated	New permission created	$permission
SalvatoreCervone\PermissionToolkit\Events\PermissionDeleted	Permission deleted	$permissionName, $permissionId
SalvatoreCervone\PermissionToolkit\Events\PermissionsExported	Permissions exported to JSON	$rolesCount, $permissionsCount
SalvatoreCervone\PermissionToolkit\Events\PermissionsImported	Permissions imported from JSON	$rolesCount, $permissionsCount, $fresh
SalvatoreCervone\PermissionToolkit\Events\AuditLogsPruned	Audit logs cleaned	$deletedCount, $days

Example listener in your application:

use SalvatoreCervone\PermissionToolkit\Events\PermissionToggled;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

Event::listen(PermissionToggled::class, function (PermissionToggled $event) {
    Log::notice("Permission [{$event->permission->name}] {$event->action} for role [{$event->role->name}]");
});

🌐 Web Panel Navigation & Features

Protected by ['web', 'auth', Authorize::class] middleware:

https://your-app.test/permission-manager

• Matrice Ruoli: /permission-manager/matrix
  • Bulk Actions: One-click mass assignment (✓) and revocation (✕) per role across entire modules.
  • Module Filter: Group permissions by feature (Users, Billing, Settings) and filter quickly.
  • 1-Click Web Export & Import: Download and upload role/permission JSON packages directly from the UI.
• Gestione Utenti: /permission-manager/users:
  • Priorità Utenti Attivi: Mostra sempre prima tutti gli utenti attivi (ATTIVO), relegando gli utenti disattivati (DISATTIVATO / Soft Deleted) in fondo.
  • Colonne e Visualizzazione Configurabili: Configura quali colonne mostrare al posto del solo name (es. ['cognome', 'nome'] o ['last_name', 'first_name']) via config('permission-toolkit.users.display_columns').
  • Ordinamento Automatico Multi-Colonna: Se configurato con ['cognome', 'nome'], la lista viene ordinata automaticamente per cognome e poi nome (mantenendo sempre gli attivi per primi), con supporto per header cliccabili e ordinamento custom (order_by).
  • Ricerca Intelligente: Ricerca testuale dinamica su tutte le colonne configurate (cognome, nome, name, email, username, ID numerici o UUID).
  • Password & Accessi: Gestione rapida permessi diretti, ruoli, e reset password con data scadenza.
• Diagnostic Simulator: /permission-manager/simulator (test interattivo con supporto per Gate globali, Policy e Spatie Teams)
• Audit Trail: /permission-manager/audit-logs (registro di conformità transazionale)
• Integrity Doctor: /permission-manager/doctor (diagnostica senza query N+1)
• 🌓 Dark / Light Mode: Seamless theme toggle in the header with persistent state.

🛠️ CLI Commands

# Diagnostic Simulator (AWS IAM style with Teams support)
php artisan permission:simulate 42 "invoices.create"
php artisan permission:simulate [e-mail] "update" --model="App\Models\Invoice" --id=15 --team=3

# Database Health Check (Optimized set-based queries)
php artisan permission:doctor

# Audit Trail Pruning (Pass --days=0 to keep indefinitely)
php artisan permission:audit-prune
php artisan permission:audit-prune --days=30

# Sync across environments (JSON Export & Import)
php artisan permission:export --file=permissions.json
php artisan permission:import --file=permissions.json --fresh

📄 License

The MIT License (MIT). Please see License File for more information.