README

A comprehensive and flexible Laravel package for advanced permission management. This package provides a robust system for managing roles, permissions, groups, and entity-specific abilities.

Core Functionality:

Role-Based Access Control (RBAC): Define custom roles with specific permission sets. Roles can be assigned to users to manage access levels efficiently.
Permission System: Implement fine-grained permissions using a code-based system (e.g., posts.create, users.edit). Permissions are global entities that can be assigned to roles and groups. Supports wildcard permissions for flexible access patterns.
Group Management: Organize users into groups. Groups can have their own permission sets, allowing for efficient permission management when multiple users need the same access level.
Entity-Specific Abilities: Grant or deny permissions for specific model instances (e.g., allowing a user to edit a particular post but not others). This provides the most granular level of access control.
Caching & Performance: Intelligent caching system to optimize permission checks, reducing database queries and improving application performance.
Audit Logging: Optional comprehensive audit trail that logs all permission-related actions including role assignments and permission changes.
Laravel Integration: Seamlessly integrates with Laravel's built-in authorization system, including Policies, Blade directives, and middleware for route protection.

Key Features

✅ Roles & Permissions: Flexible role system with granular permissions
✅ Groups: Organize users into groups with shared permissions
✅ Abilities: Entity-specific permissions for individual models
✅ Smart Caching: Caching system to optimize permission checks
✅ Audit Logging: Complete action logging (optional)
✅ Blade Directives: Blade directives for permission checks in views
✅ Policies: Integration with Laravel's Policy system
✅ Middleware: Middleware for route protection
✅ Artisan Commands: CLI tools for management
✅ Events: Event system for permission changes (RoleAssigned, RoleRemoved, AbilityGranted, AbilityRevoked)
✅ Validation: Automatic validation of permission codes
✅ Performance: Optimized queries with eager loading

Requirements

PHP >= 8.1
Laravel 8.x, 9.x, 10.x, 11.x or 12.x

Installation

1. Install the Package

composer require squareetlabs/laravel-simple-permissions

2. Publish Configuration and Migrations

php artisan vendor:publish --provider="Squareetlabs\LaravelSimplePermissions\SimplePermissionsServiceProvider"

This will publish:

config/simple-permissions.php - Configuration file
Database migrations

3. Configure the User Model

Add the HasPermissions trait to your User model:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Squareetlabs\LaravelSimplePermissions\Traits\HasPermissions;

class User extends Model
{
    use HasPermissions;
    
    // ... rest of your code
}

4. Run Migrations

⚠️ IMPORTANT: Always do backups before running migrations.

php artisan migrate

Note

If you wish to use custom foreign keys and table names, modify config/simple-permissions.php before running migrations.

5. Optional Configuration

Enable Caching

To improve performance, enable caching in .env:

SIMPLE_PERMISSIONS_CACHE_ENABLED=true
SIMPLE_PERMISSIONS_CACHE_DRIVER=redis
SIMPLE_PERMISSIONS_CACHE_TTL=3600

Enable Audit Logging

To log all permission actions:

SIMPLE_PERMISSIONS_AUDIT_ENABLED=true
SIMPLE_PERMISSIONS_AUDIT_LOG_CHANNEL=stack

Configuration

The configuration file config/simple-permissions.php contains all options:

Custom Models

'models' => [
    'user' => App\Models\User::class,
    // ... other models
],

Cache

'cache' => [
    'enabled' => env('SIMPLE_PERMISSIONS_CACHE_ENABLED', true),
    'driver' => env('SIMPLE_PERMISSIONS_CACHE_DRIVER', 'redis'),
    'ttl' => env('SIMPLE_PERMISSIONS_CACHE_TTL', 3600),
    'prefix' => 'simple_permissions',
    'tags' => true,
],

Basic Usage

Creating Roles and Permissions

use Squareetlabs\LaravelSimplePermissions\Support\Facades\SimplePermissions;

// Create permissions
$viewPost = SimplePermissions::model('permission')::create(['code' => 'posts.view', 'name' => 'View Posts']);
$createPost = SimplePermissions::model('permission')::create(['code' => 'posts.create', 'name' => 'Create Posts']);

// Create role
$adminRole = SimplePermissions::model('role')::create(['code' => 'admin', 'name' => 'Administrator']);

// Assign permissions to role
$adminRole->permissions()->attach([$viewPost->id, $createPost->id]);

Assigning Roles to Users

// Assign role to user
$user->assignRole('admin');

// Remove role from user
$user->removeRole('admin');

// Sync roles (replaces all existing roles)
$user->syncRoles(['admin', 'editor']);

Checking Permissions

// Check if user has a permission (direct or via role/group)
if ($user->hasPermission('posts.create')) {
    // User can create posts
}

// Check if user has a role
if ($user->hasRole('admin')) {
    // User is admin
}

// Check specific ability on an entity
if ($user->hasAbility('edit', $post)) {
    // User can edit this specific post
}

Users

The HasPermissions trait provides the following methods:

// Check if user has a role (or roles)
// $require = true: all roles are required
// $require = false: at least one of the roles
$user->hasRole('admin', $require = false)
$user->hasRole(['admin', 'editor'], $require = false)

// Check if user has a permission (or permissions)
// $require = true: all permissions are required
// $require = false: at least one of the permissions
$user->hasPermission('posts.create', $require = false)
$user->hasPermission(['posts.create', 'posts.edit'], $require = false)

// Check if user has an ability on an entity
$user->hasAbility('posts.edit', $post)

// Allow ability for user on an entity
$user->allowAbility('posts.edit', $post)

// Forbid ability for user on an entity
$user->forbidAbility('posts.edit', $post)

// Remove ability from user
$user->removeAbility('posts.edit', $post)

Roles & Permissions

Wildcard Permissions

You can use wildcards for permissions:

posts.* - All permissions starting with posts.
* - All permissions (if enabled in config)

Checking Permissions

// Check multiple permissions (OR)
if ($user->hasPermission(['posts.create', 'posts.edit'], false)) {
    // User can create OR edit posts
}

// Check multiple permissions (AND)
if ($user->hasPermission(['posts.create', 'posts.edit'], true)) {
    // User can create AND edit posts
}

Abilities

Abilities allow specific permissions for individual entities.

Creating and Assigning Abilities

You can use helper methods for easier ability management:

// Allow user to edit a specific post
$user->allowAbility('posts.edit', $post);

// Forbid user to edit a specific post
$user->forbidAbility('posts.edit', $post);

// Remove ability from user
$user->removeAbility('posts.edit', $post);

Or use the direct approach:

use Squareetlabs\LaravelSimplePermissions\Support\Facades\SimplePermissions;

// Create a permission first
$permission = SimplePermissions::model('permission')::create(['code' => 'posts.edit']);

// Create an ability for a specific entity
$ability = SimplePermissions::model('ability')::create([
    'permission_id' => $permission->id,
    'title' => 'Edit Post #1',
    'entity_id' => $post->id,
    'entity_type' => get_class($post),
]);

// Allow user to edit a specific post
$ability->users()->attach($user, ['forbidden' => false]);

// Forbid user to edit a specific post
$ability->users()->attach($user, ['forbidden' => true]);

// Remove ability from user
$ability->users()->detach($user);

Checking an Ability

if ($user->hasAbility('posts.edit', $post)) {
    // User can edit this specific post
}

Groups

Groups allow organizing users with shared permissions.

Creating and Managing Groups

use Squareetlabs\LaravelSimplePermissions\Support\Facades\SimplePermissions;

// Create group
$group = SimplePermissions::model('group')::create(['code' => 'moderators', 'name' => 'Moderators']);

// Assign permissions to group
$permission = SimplePermissions::model('permission')::where('code', 'posts.moderate')->first();
$group->permissions()->attach($permission);

// Add users to group
$group->users()->attach($user);

// Remove users from group
$group->users()->detach($user);

Middleware

The package provides middleware for route protection.

Usage in Routes

// Check role
Route::middleware(['role:admin'])->group(function () {
    Route::get('/admin', [AdminController::class, 'index']);
});

// Check permission
Route::middleware(['permission:posts.create'])->group(function () {
    Route::post('/posts', [PostController::class, 'store']);
});

// Check ability
// Format: ability:action,entity_class,route_parameter_name
Route::middleware(['ability:edit,App\Models\Post,post_id'])->group(function () {
    Route::put('/posts/{post_id}', [PostController::class, 'update']);
});

OR Operations

// User must have admin OR root
Route::middleware(['role:admin|root'])->group(function () {
    // ...
});

Blade Directives

The package includes Blade directives for permission checks in views:

{{-- Check role --}}
@role('admin')
    <button>Admin Panel</button>
@endrole

{{-- Check permission --}}
@permission('posts.create')
    <a href="{{ route('posts.create') }}">New Post</a>
@endpermission

{{-- Check ability --}}
@ability('edit', $post)
    <button>Edit Post</button>
@endability

Policies

The package integrates with Laravel's Policy system.

Generate a Policy

php artisan permissions:policy PostPolicy --model=Post

Using the Policy

// In a controller
if ($user->can('view', $post)) {
    // User can view the post
}

// In a view
@can('update', $post)
    <button>Edit</button>
@endcan

Events

The package dispatches events when permissions change, allowing you to hook into these actions:

Available Events

RoleAssigned: Dispatched when a role is assigned to a user
RoleRemoved: Dispatched when a role is removed from a user
AbilityGranted: Dispatched when an ability is granted to a user
AbilityRevoked: Dispatched when an ability is revoked from a user

Listening to Events

use Squareetlabs\LaravelSimplePermissions\Events\RoleAssigned;
use Squareetlabs\LaravelSimplePermissions\Events\AbilityGranted;

// In your EventServiceProvider
protected $listen = [
    RoleAssigned::class => [
        // Your listeners here
    ],
    AbilityGranted::class => [
        // Your listeners here
    ],
];

Example Listener

use Squareetlabs\LaravelSimplePermissions\Events\RoleAssigned;

class LogRoleAssignment
{
    public function handle(RoleAssigned $event)
    {
        // Log the role assignment
        Log::info("User {$event->user->id} was assigned role {$event->role->code}");
    }
}

Artisan Commands

The package includes several useful commands:

Management

// List all roles
php artisan permissions:roles

// Show role details
php artisan permissions:show-role {role}

// List all permissions
php artisan permissions:list

// Sync permissions from configuration
php artisan permissions:sync

// Export permissions
php artisan permissions:export --format=json

// Import permissions
php artisan permissions:import --file=permissions.json

// Clear permissions cache
php artisan permissions:clear-cache

// Generate a policy
php artisan permissions:policy PostPolicy --model=Post

squareetlabs / laravel-simple-permissions

Maintainers

Details

README

Key Features

Requirements

Installation

1. Install the Package

2. Publish Configuration and Migrations

3. Configure the User Model

4. Run Migrations

5. Optional Configuration

Enable Caching

Enable Audit Logging

Configuration

Custom Models

Cache

Basic Usage

Creating Roles and Permissions

Assigning Roles to Users

Checking Permissions

Users

Roles & Permissions

Wildcard Permissions

Checking Permissions

Abilities

Creating and Assigning Abilities

Checking an Ability

Groups

Creating and Managing Groups

Middleware

Usage in Routes

OR Operations

Blade Directives

Policies

Generate a Policy

Using the Policy

Events

Available Events

Listening to Events

Example Listener

Artisan Commands

Management