README

A powerful wrapper around spatie/laravel-permission that manages permissions and roles through a simple configuration file.

Features

Config-Driven: Define permissions in config/permissions.php
Auto-CRUD Generation: Automatically generates CRUD permissions
Smart Syncing: Efficient database synchronization
Smart Translations: Automatic human-readable labels
Policy Trait: Simplify authorization with HasPermissionCheck

Note: This package wraps spatie/laravel-permission. For advanced features like blade directives, middleware usage, caching, and direct role/permission assignment, see the official Spatie documentation.

Installation

Install via Composer (Spatie Permission is included automatically):

composer require deifhelt/laravel-permissions-manager

Publish this package configuration:

php artisan vendor:publish --provider="Deifhelt\LaravelPermissionsManager\PermissionManagerServiceProvider"

This creates config/permissions.php (this package's permission definitions).

Publish Spatie Permission configuration and migrations:

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

This creates config/permission.php (Spatie's internal configuration) and migration files.

Clear config cache:

php artisan optimize:clear

Run migrations:

php artisan migrate

Add the HasRoles trait to your User model:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

Configuration

Standard CRUD Permissions

Define resources to auto-generate read, create, update, destroy permissions:

// config/permissions.php

'permissions' => [
    'users',
    'posts',
    'products',
],

This generates: read users, create users, update users, destroy users, etc.

Special Permissions

Add custom actions that don't fit the CRUD pattern:

'special_permissions' => [
    'users' => ['ban', 'impersonate'],
    'system' => ['view-logs', 'maintenance-mode'],
],

This generates: ban users, impersonate users, view-logs system, etc.

Super Admin (Bypass)

Define roles that bypass all permission checks (Super Admin). These roles are defined separately because they inherently have all permissions.

// config/permissions.php
'super_admin_role' => 'admin', // Can be a string or array: ['admin', 'root']

Note:

The permissions:sync command automatically creates these roles in the database for you.
Global Bypass: This package registers a Gate::before callback. This ensures that @can('any'), $user->can('any'), and Policies automatically return true for these users, even if they have 0 permissions in the database.

Roles

Define standard roles and assign their specific permissions:

'roles' => [
    // Manager - specific resources
    'manager' => [
        'users' => ['read', 'create', 'update'], // Specific actions
        'posts',                                  // All permissions for posts
    ],

    // Editor - explicit permission strings
    'editor' => [
        'read posts',
        'create posts',
        'update posts',
    ],
],

## Translations

Easily translate technical permissions (e.g., `create users`) into human-readable labels (e.g., "Crear Usuarios").

```bash
php artisan vendor:publish --tag=permissions-translations

Then use in your code:

use Deifhelt\LaravelPermissionsManager\Facades\Permissions;

```php
use Deifhelt\LaravelPermissionsManager\Facades\Permissions;

// Returns ['name' => 'create users', 'label' => 'Crear Usuarios']
$all = Permissions::getPermissionsWithLabels();

// Translate a single permission
echo Permissions::translate('create users');

See Translations Documentation for full details.

Note: The system automatically respects your config('app.locale') and any runtime locale changes.

Sync Permissions

After configuring your permissions and roles, sync them to the database:

php artisan permissions:sync

Alternative: Using Database Seeders

For automated deployments, CI/CD pipelines, or NativePHP applications where you can't run artisan commands interactively, use the included seeder:

use Deifhelt\LaravelPermissionsManager\Database\Seeders\RolesAndPermissionsSeeder;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        $this->call(RolesAndPermissionsSeeder::class);
    }
}

This is particularly useful for NativePHP desktop applications where the database is created on first run.

Using with Policies

Use the HasPermissionCheck trait to simplify policy authorization:

use Deifhelt\LaravelPermissionsManager\Traits\HasPermissionCheck;

class PostPolicy
{
    use HasPermissionCheck;

    public function viewAny(User $user): bool
    {
        return $this->checkPermission($user, 'read posts');
    }

    public function update(User $user, Post $post): bool
    {
        // Checks permission AND ownership (user_id)
        return $this->checkPermission($user, 'update posts', $post);
    }
}

Features:

Admin Bypass: Users with admin role automatically pass all checks
Permission Validation: Verifies user has required permission
Ownership Check: When passing a model, validates user_id matches

Documentation

Installation - Complete setup guide including Laravel 11/12 middleware
Configuration & Usage - Deep dive into permissions, roles, and commands
Translations - Translate permissions automatically
Policies - Security patterns and trait usage

License

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

deifhelt / laravel-permissions-manager

Maintainers

Details