README

This package focuses exclusively on permissions functionality while leveraging the role management capabilities of Litepie/Roles.

Features

• 🔐 Permission model with Eloquent relationships
• 🎭 HasPermissions trait for models
• 🛡️ Permission-based middleware
• 🎨 Blade directives for permission checks
• ⚡ Artisan commands for permission management
• 📢 Events and listeners for permission operations
• 🧪 Comprehensive test suite
• 💾 Database caching for performance
• 🔄 Multi-guard support

Installation

You can install the package via composer:

composer require litepie/permissions

First, install and configure the Litepie/Roles package as this package extends its functionality:

composer require litepie/roles

Publish and run the migrations:

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

Publish the config file (optional):

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

Quick Start

1. Add the HasPermissions trait

Add the HasPermissions trait to your User model:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Litepie\Roles\Traits\HasRoles;
use Litepie\Permissions\Traits\HasPermissions;

class User extends Authenticatable
{
    use HasRoles, HasPermissions;

    // ...
}

2. Create Permissions

use Litepie\Permissions\Models\Permission;

// Create a permission
$permission = Permission::create(['name' => 'edit articles']);

// Or use the artisan command
php artisan permissions:create "edit articles"

3. Assign Permissions

// Assign permission directly to user
$user->givePermissionTo('edit articles');

// Assign permission to role (requires Litepie/Roles)
$role = Role::create(['name' => 'editor']);
$role->givePermissionTo('edit articles');
$user->assignRole('editor');

4. Check Permissions

// Check if user has permission
$user->hasPermissionTo('edit articles');
$user->can('edit articles'); // Using Laravel's built-in authorization

// Check via role
$user->hasPermissionTo('edit articles'); // Returns true if user has role with this permission

Usage

Creating Permissions

use Litepie\Permissions\Models\Permission;

// Create single permission
$permission = Permission::create(['name' => 'edit articles']);

// Create with guard
$permission = Permission::create([
    'name' => 'edit articles',
    'guard_name' => 'admin'
]);

Assigning Permissions

// Assign to user
$user->givePermissionTo('edit articles');
$user->givePermissionTo(['edit articles', 'delete articles']);

// Assign to role
$role->givePermissionTo('edit articles');

// Sync permissions (remove all others)
$user->syncPermissions(['edit articles', 'publish articles']);

Checking Permissions

// Check single permission
$user->hasPermissionTo('edit articles');
$user->can('edit articles');

// Check any permission
$user->hasAnyPermission(['edit articles', 'publish articles']);

// Check all permissions
$user->hasAllPermissions(['edit articles', 'publish articles']);

// Check direct permission (not via role)
$user->hasDirectPermission('edit articles');

Removing Permissions

// Remove single permission
$user->revokePermissionTo('edit articles');

// Remove multiple permissions
$user->revokePermissionTo(['edit articles', 'delete articles']);

// Remove all permissions
$user->revokePermissionTo($user->permissions);

Middleware

Register the permission middleware in your bootstrap/app.php (Laravel 11+):

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'permission' => \Litepie\Permissions\Middleware\PermissionMiddleware::class,
    ]);
})

Or in app/Http/Kernel.php (Laravel 10 and below):

protected $middlewareAliases = [
    // ...
    'permission' => \Litepie\Permissions\Middleware\PermissionMiddleware::class,
];

Use in routes:

Route::group(['middleware' => ['permission:edit articles']], function () {
    // Routes that require 'edit articles' permission
});

Route::get('/articles', function () {
    // This route requires 'edit articles' OR 'publish articles' permission
})->middleware('permission:edit articles|publish articles');

Blade Directives

@permission('edit articles')
    <a href="/articles/create">Create Article</a>
@endpermission

@haspermission('edit articles')
    I have permission to edit articles!
@endhaspermission

@hasanypermission(['edit articles', 'publish articles'])
    I have at least one of these permissions!
@endhasanypermission

@hasallpermissions(['edit articles', 'publish articles'])
    I have all of these permissions!
@endhasallpermissions

Artisan Commands

# Create a permission
php artisan permissions:create "edit articles"

# Create permission with guard
php artisan permissions:create "edit articles" --guard=admin

# List all permissions
php artisan permissions:list

# Show permission details
php artisan permissions:show "edit articles"

# Delete a permission
php artisan permissions:delete "edit articles"

Eloquent Scopes

// Get users with specific permission
$users = User::permission('edit articles')->get();

// Get users without specific permission  
$users = User::withoutPermission('edit articles')->get();

Cache

The package uses Laravel's cache to improve performance. You can clear the permission cache:

// Clear permission cache
app()[\Litepie\Permissions\PermissionRegistrar::class]->forgetCachedPermissions();

// Or use artisan command
php artisan permissions:cache-reset

Events

The package fires several events:

• Litepie\Permissions\Events\PermissionAttached - When permission is given to model
• Litepie\Permissions\Events\PermissionDetached - When permission is revoked from model

use Litepie\Permissions\Events\PermissionAttached;

Event::listen(PermissionAttached::class, function ($event) {
    // $event->model - The model that received the permission
    // $event->permission - The permission that was attached
});

Configuration

The config file allows you to customize:

return [
    'models' => [
        'permission' => Litepie\Permissions\Models\Permission::class,
    ],

    'table_names' => [
        'permissions' => 'permissions',
        'model_has_permissions' => 'model_has_permissions',
    ],

    'column_names' => [
        'permission_pivot_key' => null, // default 'permission_id'
        'model_morph_key' => 'model_id',
    ],

    'cache' => [
        'expiration_time' => \DateInterval::createFromDateString('24 hours'),
        'key' => 'litepie.permissions.cache',
        'store' => 'default',
    ],

    'display_permission_in_exception' => false,
];

Requirements

This package extends Litepie/Roles, so you need to install and configure that package first.

• PHP 8.1+
• Laravel 10.0+
• Litepie/Roles ^1.0

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Litepie Team
• Inspired by Spatie Laravel Permission
• All Contributors

License

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