README

Advanced Laravel Permission Package with enhanced features beyond traditional role-permission systems.

Features

🚀 Advanced Features

Hierarchical Roles - Parent-child role relationships
Dynamic Permissions - Runtime permission creation and management
Resource-based Permissions - Fine-grained control over specific resources
Time-based Permissions - Temporary permissions with expiration
Permission Inheritance - Automatic permission inheritance through role hierarchy
Permission Groups - Organize permissions into logical groups
Audit Trail - Complete tracking of permission changes
Bulk Operations - Efficient bulk assignment/revocation
Cache Management - Intelligent caching with automatic invalidation
Multi-tenancy Support - Team/organization-based permissions

🎯 User-Friendly Features

GUI Dashboard - Web interface for permission management
Import/Export - JSON/CSV import/export functionality
Permission Templates - Pre-defined permission sets
Role Cloning - Duplicate roles with all permissions
Permission Suggestions - AI-powered permission recommendations
Conflict Detection - Automatic detection of permission conflicts

🔧 Developer Features

Fluent API - Intuitive method chaining
Middleware Support - Easy route protection
Blade Directives - Template-level permission checks
Artisan Commands - CLI management tools
Event System - Hooks for custom logic
Database Agnostic - Works with any Laravel-supported database

Requirements

PHP 8.1+
Laravel 10.0+

Installation

Install the package via composer:

composer require openbackend/laravel-permission

Publish and run the migrations:

php artisan vendor:publish --provider="OpenBackend\LaravelPermission\PermissionServiceProvider" --tag="migrations"
php artisan migrate

Publish the config file:

php artisan vendor:publish --provider="OpenBackend\LaravelPermission\PermissionServiceProvider" --tag="config"

Quick Start

1. Add the Trait to Your User Model

<?php

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use OpenBackend\LaravelPermission\Traits\HasRolesAndPermissions;

class User extends Authenticatable
{
    use HasRolesAndPermissions;
    
    // ... your model code
}

2. Create Roles and Permissions

use OpenBackend\LaravelPermission\Models\Role;
use OpenBackend\LaravelPermission\Models\Permission;

// Create permissions
$editPosts = Permission::create(['name' => 'edit posts', 'group' => 'posts']);
$deletePosts = Permission::create(['name' => 'delete posts', 'group' => 'posts']);

// Create role with permissions
$role = Role::create(['name' => 'writer'])
    ->givePermissionTo($editPosts, $deletePosts);

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

3. Check Permissions

// Check if user has permission
if ($user->can('edit posts')) {
    // User can edit posts
}

// Check multiple permissions
if ($user->hasAnyPermission(['edit posts', 'delete posts'])) {
    // User has at least one permission
}

// Check all permissions
if ($user->hasAllPermissions(['edit posts', 'delete posts'])) {
    // User has all permissions
}

Advanced Usage

Hierarchical Roles

// Create parent role
$admin = Role::create(['name' => 'admin']);

// Create child role
$moderator = Role::create(['name' => 'moderator', 'parent_id' => $admin->id]);

// Child roles inherit parent permissions automatically
$admin->givePermissionTo('manage users');
$moderator->hasPermissionTo('manage users'); // true (inherited)

Time-based Permissions

// Give temporary permission
$user->givePermissionTo('access premium', [
    'expires_at' => now()->addDays(30)
]);

// Check if permission is still valid
if ($user->hasValidPermission('access premium')) {
    // Permission is still active
}

Resource-based Permissions

// Create resource-specific permission
$permission = Permission::create([
    'name' => 'edit',
    'resource_type' => 'App\Models\Post',
    'resource_id' => 1
]);

// Assign to user
$user->givePermissionTo($permission);

// Check resource permission
if ($user->can('edit', $post)) {
    // User can edit this specific post
}

Middleware Protection

// In your routes/web.php
Route::group(['middleware' => ['permission:edit posts']], function () {
    Route::get('/posts/{post}/edit', [PostController::class, 'edit']);
});

// Multiple permissions (any)
Route::group(['middleware' => ['permission:edit posts|delete posts']], function () {
    // Routes
});

// Multiple permissions (all)
Route::group(['middleware' => ['permission:edit posts,delete posts']], function () {
    // Routes
});

// Role-based middleware
Route::group(['middleware' => ['role:admin']], function () {
    // Admin only routes
});

Blade Directives

@can('edit posts')
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcan

@role('admin')
    <a href="{{ route('admin.dashboard') }}">Admin Dashboard</a>
@endrole

@hasanypermission('edit posts|delete posts')
    <div class="post-actions">
        <!-- Action buttons -->
    </div>
@endhasanypermission

@hasallpermissions('edit posts,delete posts')
    <button>Full Post Control</button>
@endhasallpermissions

Artisan Commands

# Create permission
php artisan permission:create "edit posts" --group=posts

# Create role
php artisan role:create admin --permissions="edit posts,delete posts"

# Assign role to user
php artisan permission:assign-role admin --user=1

# Show user permissions
php artisan permission:show-user 1

# Import permissions from JSON
php artisan permission:import permissions.json

# Export permissions to JSON
php artisan permission:export

# Cache permissions
php artisan permission:cache

# Clear permission cache
php artisan permission:clear-cache

API Reference

User Methods

// Role assignment
$user->assignRole('admin');
$user->assignRole(['admin', 'editor']);
$user->assignRole($roleObject);

// Role removal
$user->removeRole('admin');
$user->syncRoles(['admin', 'editor']);

// Permission assignment
$user->givePermissionTo('edit posts');
$user->revokePermissionTo('edit posts');
$user->syncPermissions(['edit posts', 'delete posts']);

// Checking permissions
$user->hasPermissionTo('edit posts');
$user->hasAnyPermission(['edit posts', 'delete posts']);
$user->hasAllPermissions(['edit posts', 'delete posts']);

// Checking roles
$user->hasRole('admin');
$user->hasAnyRole(['admin', 'editor']);
$user->hasAllRoles(['admin', 'editor']);

// Getting permissions/roles
$user->getAllPermissions();
$user->getDirectPermissions();
$user->getPermissionsViaRoles();
$user->getRoleNames();

Role Methods

// Permission management
$role->givePermissionTo('edit posts');
$role->revokePermissionTo('edit posts');
$role->syncPermissions(['edit posts', 'delete posts']);

// Hierarchy
$role->setParent($parentRole);
$role->getChildren();
$role->getAncestors();
$role->getDescendants();

// Bulk operations
Role::bulkCreate(['admin', 'editor', 'viewer']);
$role->bulkAssignPermissions(['edit posts', 'delete posts']);

Configuration

The config file allows you to customize:

Table names
Model classes
Cache settings
Middleware options
Hierarchy settings
And more...

Testing

composer test

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

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

Credits

License

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

Support

📧 Email: contact@openbackend.dev
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
🌐 Website: openbackend.dev

openbackend / laravel-permission

Maintainers

Details