PHPackages                             kiurd/role-based-access-control - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. kiurd/role-based-access-control

ActiveLibrary[Authentication & Authorization](/categories/authentication)

kiurd/role-based-access-control
===============================

A 100% database-driven, automated role-permission system for Laravel with zero-code setup, auto-discovery, and complete REST API

v1.0.0(5mo ago)11MITPHPPHP ^8.0|^8.1|^8.2|^8.3

Since Nov 24Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/kiurd-gentleman/role-based-access-control)[ Packagist](https://packagist.org/packages/kiurd/role-based-access-control)[ Docs](https://github.com/imtiaz-kolpolok/role-based-access-control)[ RSS](/packages/kiurd-role-based-access-control/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (5)Versions (2)Used By (0)

Laravel Role-Based Access Control (RBAC)
========================================

[](#laravel-role-based-access-control-rbac)

A **100% database-driven**, automated role-permission system for Laravel with zero-code setup.

🚀 Key Features
--------------

[](#-key-features)

- **🎯 Zero-Code Setup**: No middleware in routes or controllers - everything is automatic
- **🔄 Global Auto-Enforcement**: Enable once, all routes are protected automatically
- **🛠️ Complete REST API**: Manage everything through API/UI without touching code
- **🔍 Auto-Discovery**: Automatically scan and sync permissions from your controllers
- **⚡ Dynamic Management**: Create roles, assign permissions, manage users - all in real-time
- **🔒 Multi-Guard Support**: Support for multiple authentication guards (web, api, etc.)
- **📊 Granular Permissions**: Module + Action based permission system
- **🎨 Admin-Friendly**: Build any admin UI with provided API endpoints

---

📖 Two Ways to Use This Package
------------------------------

[](#-two-ways-to-use-this-package)

### 1. **Zero-Code Dynamic Setup** (Recommended) ⚡

[](#1-zero-code-dynamic-setup-recommended-)

Perfect for projects where **admins manage permissions through a UI without touching code**.

👉 **[Read DYNAMIC\_SETUP.md](DYNAMIC_SETUP.md)** for the complete guide

**Quick Overview:**

```
# Just add this to .env
ENABLE_GLOBAL_PERMISSION_MIDDLEWARE=true
```

- ✅ **No middleware in routes** - Everything automatic
- ✅ **Complete REST API** - Build any admin UI
- ✅ **Database-driven** - Users control everything
- ✅ **Zero code changes** - Add controllers, sync, done!

### 2. **Traditional Manual Setup** 🔧

[](#2-traditional-manual-setup-)

For projects where you want **more control and explicit permission definitions**.

👉 Continue reading this README for traditional setup

---

Installation
------------

[](#installation)

### Step 1: Add Package to Your Project

[](#step-1-add-package-to-your-project)

Create a `packages` folder in your project root and clone this repository:

```
mkdir packages
cd packages
git clone https://github.com/imtiaz-kolpolok/role-based-access-control.git
```

### Step 2: Update composer.json

[](#step-2-update-composerjson)

Add the following to your `composer.json`:

```
{
    "require": {
        "kiurd/role-based-access-control": "dev-master"
    },
    "repositories": [
        {
            "type": "path",
            "url": "./packages/role-based-access-control"
        }
    ]
}
```

### Step 3: Install Dependencies

[](#step-3-install-dependencies)

```
composer update
```

### Step 4: Publish Configuration and Migrations

[](#step-4-publish-configuration-and-migrations)

```
php artisan vendor:publish --tag=role-permissions-config
php artisan vendor:publish --tag=role-permissions-migrations
php artisan migrate
```

### Step 5: Add Trait to User Model

[](#step-5-add-trait-to-user-model)

Add the `HasRolesAndPermissions` trait to your `User` model:

```
use Kiurd\RolePermissions\Traits\HasRolesAndPermissions;

class User extends Authenticatable
{
    use HasRolesAndPermissions;

    // ... rest of your model
}
```

Automated Permission Discovery
------------------------------

[](#automated-permission-discovery)

### Auto-Sync Permissions from Controllers

[](#auto-sync-permissions-from-controllers)

The package can automatically scan your controllers and create permissions:

```
# Preview what will be synced (recommended first)
php artisan permissions:sync --preview

# Sync from routes
php artisan permissions:sync --source=routes

# Sync from controllers directory
php artisan permissions:sync --source=controllers

# Sync with specific guard
php artisan permissions:sync --guard=api

# Sync from custom path
php artisan permissions:sync --source=controllers --path=/path/to/controllers
```

**How it works:**

- Scans your controllers and extracts public methods
- Converts controller names to module names (e.g., `UserController` → `users`)
- Maps methods to actions (e.g., `store` → `create`, `index` → `list`)
- Automatically creates modules, actions, and permissions in your database

### Method to Action Mapping

[](#method-to-action-mapping)

The package automatically maps controller methods to permission actions:

Controller MethodPermission Action`index()``list``show()``read``create()``create``store()``create``edit()``update``update()``update``destroy()``delete``delete()``delete`Other methods`snake_case` of method nameYou can customize this mapping in `config/role_permissions.php`.

Artisan Commands
----------------

[](#artisan-commands)

### Create a Role

[](#create-a-role)

```
php artisan role:create admin --description="Administrator role"
php artisan role:create editor --guard=api
```

### Assign Permission to Role

[](#assign-permission-to-role)

```
# Assign single permission (auto-creates module and action if needed)
php artisan role:assign-permission admin users create
php artisan role:assign-permission editor posts update --guard=web
```

### Assign All Permissions to Role

[](#assign-all-permissions-to-role)

Assign multiple permissions at once instead of one by one:

```
# Assign ALL permissions to a role
php artisan role:assign-all-permissions super-admin

# Assign all permissions for a specific module
php artisan role:assign-all-permissions manager --module=users

# Assign all permissions for a specific action across all modules
php artisan role:assign-all-permissions reader --action=read

# Combine filters: all 'create' permissions for 'users' module
php artisan role:assign-all-permissions editor --module=users --action=create

# Skip confirmation prompt
php artisan role:assign-all-permissions admin --force

# With specific guard
php artisan role:assign-all-permissions admin --guard=api
```

**Example Output:**

```
🎭 Role: manager

📋 Permissions to be assigned (4):
   📦 users
      • create
      • read
      • update
      • delete

🔍 Filters applied: Module: users

✅ Permissions assigned successfully!

+----------------------------+-------+
| Status                     | Count |
+----------------------------+-------+
| Newly assigned             | 4     |
| Already assigned           | 0     |
| Total permissions for role | 4     |
+----------------------------+-------+

```

### List All Permissions

[](#list-all-permissions)

```
# List all permissions
php artisan permissions:list

# Filter by role
php artisan permissions:list --role=admin

# Filter by module
php artisan permissions:list --module=users

# Filter by guard
php artisan permissions:list --guard=api
```

### View Relationships

[](#view-relationships)

#### Show User's Roles and Permissions

[](#show-users-roles-and-permissions)

Find out which roles and permissions are assigned to a specific user:

```
# By user ID
php artisan user:show 1

# By email
php artisan user:show john@example.com

# With specific guard
php artisan user:show 1 --guard=api
```

**Example Output:**

```
👤 User Information
   ID: 1
   Name: John Doe
   Email: john@example.com

🎭 Roles (2)
+----+---------+-------------------------+
| ID | Role    | Description             |
+----+---------+-------------------------+
| 1  | admin   | Administrator role      |
| 2  | editor  | Content editor          |
+----+---------+-------------------------+

🔐 Permissions (15)
   📦 users
      • create
      • read
      • update
      • delete
   📦 posts
      • create
      • update
   📦 products
      • read

✅ Summary:
   • 2 role(s)
   • 15 permission(s)
   • 3 module(s)

```

#### Show Role's Permissions and Users

[](#show-roles-permissions-and-users)

Find out which permissions belong to a role and which users have that role:

```
# By role name
php artisan role:show admin

# By role ID
php artisan role:show 1

# Include users with this role
php artisan role:show admin --with-users

# With specific guard
php artisan role:show admin --guard=web
```

**Example Output:**

```
🎭 Role Information
   ID: 1
   Name: admin
   Description: Administrator role
   Guard: web

🔐 Permissions (12)
   📦 users
      • create (ID: 1)
      • read (ID: 2)
      • update (ID: 3)
      • delete (ID: 4)
   📦 posts
      • create (ID: 5)
      • update (ID: 6)
      • delete (ID: 7)

👥 Users with this role (3)
+----+------------+---------------------+
| ID | Name       | Email               |
+----+------------+---------------------+
| 1  | John Doe   | john@example.com    |
| 2  | Jane Smith | jane@example.com    |
| 3  | Bob Wilson | bob@example.com     |
+----+------------+---------------------+

✅ Summary:
   • 12 permission(s)
   • 2 module(s)
   • 3 user(s)

```

#### Show Module's Permissions and Roles

[](#show-modules-permissions-and-roles)

Find out which actions (permissions) belong to a module and which roles have access:

```
# By module name
php artisan module:show users

# By module ID
php artisan module:show 1

# Include roles with access
php artisan module:show users --with-roles

# With specific guard
php artisan module:show users --guard=web
```

**Example Output:**

```
📦 Module Information
   ID: 1
   Name: users
   Description: User management module
   Guard: web

🔐 Available Actions (5)
+---------------+--------+------------------+
| Permission ID | Action | Description      |
+---------------+--------+------------------+
| 1             | create | Create operation |
| 2             | read   | Read operation   |
| 3             | update | Update operation |
| 4             | delete | Delete operation |
| 5             | list   | List operation   |
+---------------+--------+------------------+

🎭 Roles with access to this module (3)
   • admin → create, read, update, delete, list
   • editor → read, update
   • viewer → read, list

✅ Summary:
   • 5 action(s) available
   • 3 role(s) have access

```

Middleware Usage
----------------

[](#middleware-usage)

### 1. Auto-Discovery Middleware (Recommended)

[](#1-auto-discovery-middleware-recommended)

Automatically discovers and checks permissions based on the controller and method:

```
// In your routes or controller constructor
Route::middleware(['auth', 'permission.auto'])->group(function () {
    Route::resource('users', UserController::class);
});

// Or in controller constructor
public function __construct()
{
    $this->middleware('permission.auto');
}
```

**Auto-Create Permissions**: Enable in `.env` to automatically create permissions on first access:

```
AUTO_CREATE_PERMISSIONS=true
```

### 2. Manual Permission Middleware

[](#2-manual-permission-middleware)

Check specific module and action permissions:

```
// Simple permission check
Route::middleware(['auth', 'permission:users,create'])->group(function () {
    Route::post('/users', [UserController::class, 'store']);
});

// Method-based permission mapping
Route::middleware(['auth', 'permission.check:users,create:store|update:update|delete:destroy'])
    ->group(function () {
        Route::resource('users', UserController::class);
    });
```

Usage in Code
-------------

[](#usage-in-code)

### Check User Roles

[](#check-user-roles)

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

// Check multiple roles (OR logic)
if (auth()->user()->hasRole(['admin', 'editor'])) {
    // User has admin OR editor role
}

// Get user's first role
$role = auth()->user()->getRole();

// Get all user's roles
$roles = auth()->user()->roles;
```

### Assign Roles to Users

[](#assign-roles-to-users)

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

// Assign multiple roles
$user->assignRole(['admin', 'editor']);

// Assign with specific guard
$user->assignRole('admin', 'api');
```

### Check User Permissions

[](#check-user-permissions)

```
// Check if user has permission
if (auth()->user()->hasPermission('users', 'create')) {
    // User can create users
}

// Check with specific guard
if (auth()->user()->hasPermission('posts', 'delete', 'api')) {
    // User can delete posts via API
}

// Get all user permissions
$permissions = auth()->user()->getAllPermissions();
```

### Query Relationships Programmatically

[](#query-relationships-programmatically)

Besides artisan commands, you can also check relationships in your code:

```
use App\Models\User;
use Kiurd\RolePermissions\Models\Role;
use Kiurd\RolePermissions\Models\Module;

// Find which users have a specific role
$adminRole = Role::where('name', 'admin')->first();
$adminUsers = User::whereHas('roles', function($q) use ($adminRole) {
    $q->where('id', $adminRole->id);
})->get();

// Find which roles have permission for a specific module
$userModule = Module::where('name', 'users')->first();
$rolesWithAccess = Role::whereHas('permissions', function($q) use ($userModule) {
    $q->where('module_id', $userModule->id);
})->with(['permissions' => function($q) use ($userModule) {
    $q->where('module_id', $userModule->id)->with('action');
}])->get();

// Get all permissions for a specific module
$userModule = Module::where('name', 'users')->first();
$permissions = $userModule->permissions()->with('action')->get();

// Get all users with a specific permission
$permission = Permission::whereHas('module', function($q) {
    $q->where('name', 'users');
})->whereHas('action', function($q) {
    $q->where('name', 'delete');
})->first();

$usersWithPermission = User::whereHas('roles.permissions', function($q) use ($permission) {
    $q->where('permissions.id', $permission->id);
})->get();

// Check if a role has access to a specific module-action combination
$role = Role::where('name', 'editor')->first();
$hasAccess = $role->permissions()
    ->whereHas('module', function($q) {
        $q->where('name', 'posts');
    })
    ->whereHas('action', function($q) {
        $q->where('name', 'create');
    })
    ->exists();
```

Dynamic Permission Management
-----------------------------

[](#dynamic-permission-management)

### Using PermissionHelper

[](#using-permissionhelper)

```
use Kiurd\RolePermissions\Helpers\PermissionHelper;

// Create a single permission
$permission = PermissionHelper::createPermission('users', 'create');

// Create multiple permissions
$permissions = PermissionHelper::createPermissions([
    ['module' => 'users', 'action' => 'create'],
    ['module' => 'users', 'action' => 'update'],
    ['module' => 'posts', 'action' => 'delete'],
]);

// Create full CRUD permissions for a module
$permissions = PermissionHelper::createCrudPermissions('products');
// Creates: products.create, products.read, products.update, products.delete, products.list

// Assign permissions to a role
PermissionHelper::assignPermissionsToRole('admin', [
    ['module' => 'users', 'action' => 'create'],
    ['module' => 'users', 'action' => 'delete'],
]);

// Check if permission exists
if (PermissionHelper::permissionExists('users', 'create')) {
    // Permission exists
}

// Get all permissions for a module
$userPermissions = PermissionHelper::getModulePermissions('users');

// Delete a permission
PermissionHelper::deletePermission('users', 'create');
```

### Manual Permission Management

[](#manual-permission-management)

```
use Kiurd\RolePermissions\Models\Role;
use Kiurd\RolePermissions\Models\Module;
use Kiurd\RolePermissions\Models\Action;
use Kiurd\RolePermissions\Models\Permission;

// Create a module
$module = Module::create([
    'name' => 'products',
    'guard_name' => 'web',
    'description' => 'Product management'
]);

// Create an action
$action = Action::create([
    'name' => 'create',
    'guard_name' => 'web',
    'description' => 'Create operation'
]);

// Create a permission (module + action)
$permission = Permission::create([
    'module_id' => $module->id,
    'action_id' => $action->id,
    'guard_name' => 'web'
]);

// Create a role
$role = Role::create([
    'name' => 'product-manager',
    'guard_name' => 'web',
    'description' => 'Manages products'
]);

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

// Remove permission from role
$role->awayPermissionTo($permission);

// Sync permissions (replaces all existing)
$role->syncPermissions([$permission1, $permission2]);

// Assign role to user
$user->assignRole('product-manager');
```

Configuration
-------------

[](#configuration)

Edit `config/role_permissions.php` to customize:

```
return [
    // Enable auto-creation of permissions
    'auto_create_permissions' => env('AUTO_CREATE_PERMISSIONS', false),

    // Controller paths to scan
    'controller_paths' => [
        app_path('Http/Controllers'),
    ],

    // Controllers to exclude from scanning
    'excluded_controllers' => [
        'App\Http\Controllers\Controller',
    ],

    // Customize method to action mapping
    'method_action_map' => [
        'index' => 'list',
        'show' => 'read',
        'store' => 'create',
        // ... add your custom mappings
    ],
];
```

Example Workflow
----------------

[](#example-workflow)

### 1. Initial Setup

[](#1-initial-setup)

```
# Sync permissions from your controllers
php artisan permissions:sync --preview
php artisan permissions:sync

# Create roles
php artisan role:create admin
php artisan role:create editor
php artisan role:create viewer
```

### 2. Assign Permissions to Roles

[](#2-assign-permissions-to-roles)

```
# Give admin full access
php artisan role:assign-permission admin users create
php artisan role:assign-permission admin users read
php artisan role:assign-permission admin users update
php artisan role:assign-permission admin users delete

# Give editor limited access
php artisan role:assign-permission editor users read
php artisan role:assign-permission editor users update
```

### 3. Assign Roles to Users

[](#3-assign-roles-to-users)

```
// In your application code
$adminUser = User::find(1);
$adminUser->assignRole('admin');

$editorUser = User::find(2);
$editorUser->assignRole('editor');
```

### 4. Protect Your Routes

[](#4-protect-your-routes)

```
// Use auto-discovery middleware
Route::middleware(['auth', 'permission.auto'])->group(function () {
    Route::resource('users', UserController::class);
    Route::resource('posts', PostController::class);
    Route::resource('products', ProductController::class);
});
```

Database Schema
---------------

[](#database-schema)

The package creates the following tables:

- `roles` - Stores user roles
- `modules` - Stores resource modules (users, posts, etc.)
- `actions` - Stores actions (create, read, update, delete, etc.)
- `permissions` - Junction of modules and actions
- `role_permissions` - Assigns permissions to roles
- `user_roles` - Assigns roles to users

Multi-Guard Support
-------------------

[](#multi-guard-support)

The package supports multiple authentication guards:

```
// Assign role with specific guard
$user->assignRole('admin', 'api');

// Check permission with guard
$user->hasPermission('users', 'create', 'api');

// Sync permissions with guard
php artisan permissions:sync --guard=api
```

Best Practices
--------------

[](#best-practices)

1. **Run sync after adding new controllers**: Always sync permissions after creating new controllers or methods
2. **Use preview first**: Use `--preview` flag to see what will be synced before actually syncing
3. **Enable auto-create in development**: Set `AUTO_CREATE_PERMISSIONS=true` in development for rapid prototyping
4. **Disable auto-create in production**: Keep it `false` in production for security and performance
5. **Use auto-discovery middleware**: Use `permission.auto` middleware for automatic permission checking
6. **Create meaningful module names**: Structure your controllers with clear, meaningful names

Troubleshooting
---------------

[](#troubleshooting)

### Permissions not working

[](#permissions-not-working)

1. Make sure you've added the `HasRolesAndPermissions` trait to your User model
2. Run `php artisan permissions:sync` to sync permissions
3. Verify user has the correct role assigned
4. Check that the role has the required permissions

### Auto-create not working

[](#auto-create-not-working)

1. Ensure `AUTO_CREATE_PERMISSIONS=true` in your `.env`
2. Verify you're using the `permission.auto` middleware
3. Check file permissions on your database

License
-------

[](#license)

MIT License

Contributing
------------

[](#contributing)

Contributions are welcome! Please submit pull requests or open issues on GitHub.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance70

Regular maintenance activity

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

175d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/cb299a9f94774016df2d6a5a4dd9f88e37fd9a28329e595b729fccc2fe1ce309?d=identicon)[kiurd-gentleman](/maintainers/kiurd-gentleman)

---

Top Contributors

[![imtiaz-kolpolok](https://avatars.githubusercontent.com/u/190263447?v=4)](https://github.com/imtiaz-kolpolok "imtiaz-kolpolok (23 commits)")

---

Tags

access-controlaclauthorizationdynamic-permissionslaravellaravel-permissionslaravel-rolespermission-managementpermissionsrbacrole-based-access-controlroleslaravelauthorizationaclrolespermissionsrbacaccess-controllaravel-permissionslaravel-rolesrole-based-access-controlpermission-managementdynamic permissions

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kiurd-role-based-access-control/health.svg)

```
[![Health](https://phpackages.com/badges/kiurd-role-based-access-control/health.svg)](https://phpackages.com/packages/kiurd-role-based-access-control)
```

###  Alternatives

[hosseinhezami/laravel-permission-manager

Advanced permission manager for Laravel.

403.3k](/packages/hosseinhezami-laravel-permission-manager)[casbin/laravel-authz

An authorization library that supports access control models like ACL, RBAC, ABAC in Laravel.

324339.9k4](/packages/casbin-laravel-authz)[jeremykenedy/laravel-roles

A Powerful package for handling roles and permissions in Laravel. Supports Laravel 5.3 up to 12.

1.0k826.8k7](/packages/jeremykenedy-laravel-roles)[hasinhayder/tyro

Tyro - The ultimate Authentication, Authorization, and Role & Privilege Management solution for Laravel 12 & 13

6712.1k2](/packages/hasinhayder-tyro)[pktharindu/nova-permissions

Laravel Nova Grouped Permissions (ACL)

136387.1k](/packages/pktharindu-nova-permissions)[erag/laravel-role-permission

A simple and easy-to-install role and permission management package for Laravel, supporting versions 10.x and 11.x

404.2k](/packages/erag-laravel-role-permission)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)