PHPackages                             fawzy/laravel-roles-permissions - 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. fawzy/laravel-roles-permissions

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

fawzy/laravel-roles-permissions
===============================

A powerful, flexible, and easy-to-use roles and permissions package for Laravel applications with built-in API support

v1.0.0(6mo ago)13MITPHPPHP ^8.1

Since Nov 2Pushed 6mo agoCompare

[ Source](https://github.com/ahmedfawzy23/laravel-roles-permissions)[ Packagist](https://packagist.org/packages/fawzy/laravel-roles-permissions)[ Docs](https://github.com/ahmedfawzy23/laravel-roles-permissions)[ RSS](/packages/fawzy-laravel-roles-permissions/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (6)Versions (2)Used By (0)

Laravel Roles & Permissions Package
=======================================

[](#laravel-roles--permissions-package)

[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)[![Laravel](https://camo.githubusercontent.com/42cfba12244453656c2836687fcf763e35dc2ae3487b327e5831fc942c723cfb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e7825323025374325323031312e782d7265642e737667)](https://camo.githubusercontent.com/42cfba12244453656c2836687fcf763e35dc2ae3487b327e5831fc942c723cfb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d31302e7825323025374325323031312e782d7265642e737667)[![PHP](https://camo.githubusercontent.com/7663c9d53dc13cedaf0660a8745a7e77d2dd711257f36aa86ebce12a0600ef42/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e312d626c75652e737667)](https://camo.githubusercontent.com/7663c9d53dc13cedaf0660a8745a7e77d2dd711257f36aa86ebce12a0600ef42/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e312d626c75652e737667)

A powerful, flexible, and easy-to-use roles and permissions package for Laravel applications with built-in API support.

Features
--------

[](#features)

✨ **Core Features**

- Multiple roles per user
- Multiple permissions per user and role
- Direct user permissions (bypass roles)
- Role and permission hierarchies
- Easy-to-use fluent API

🔒 **Security**

- Middleware for route protection
- Blade directives for view authorization
- API endpoints for role/permission management
- Built-in authorization checks

⚡ **Performance**

- Efficient database queries
- Relationship eager loading
- Configurable caching support

🎨 **Developer Experience**

- Simple and intuitive syntax
- Comprehensive documentation
- RESTful API included
- Laravel auto-discovery support

Table of Contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
    - [Basic Usage](#basic-usage)
    - [Roles](#roles)
    - [Permissions](#permissions)
    - [Checking Permissions](#checking-permissions)
    - [Middleware](#middleware)
    - [Blade Directives](#blade-directives)
    - [API Endpoints](#api-endpoints)
- [Advanced Usage](#advanced-usage)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x or 11.x

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

[](#installation)

Install the package via Composer:

```
composer require fawzy/roles-permissions
```

Publish all package assets (config, migrations, routes, factories, seeders, Postman collection):

```
php artisan vendor:publish --provider="Fawzy\RolesPermissions\Providers\RolesPermissionsServiceProvider"
```

Or publish specific assets by tag:

```
# Publish config only
php artisan vendor:publish --tag=roles-permissions-config

# Publish migrations only
php artisan vendor:publish --tag=roles-permissions-migrations

# Publish routes only
php artisan vendor:publish --tag=roles-permissions-routes

# Publish Postman Collection only
php artisan vendor:publish --tag=permissions-postman

# Publish factories only
php artisan vendor:publish --tag=roles-permissions-factories

# Publish seeders only
php artisan vendor:publish --tag=roles-permissions-seeders
```

Run the migrations:

```
php artisan migrate
```

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

[](#configuration)

Add the `HasRoles` trait to your User model:

```
use Fawzy\RolesPermissions\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

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

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

#### Creating Roles and Permissions

[](#creating-roles-and-permissions)

```
use Fawzy\RolesPermissions\Models\Role;
use Fawzy\RolesPermissions\Models\Permission;

// Create a role
$admin = Role::create([
    'name' => 'Administrator',
    'slug' => 'admin',
    'description' => 'Full system access'
]);

// Create a permission
$editPosts = Permission::create([
    'name' => 'Edit Posts',
    'slug' => 'edit-posts',
    'description' => 'Can edit blog posts'
]);
```

### Roles

[](#roles)

#### Assigning Roles to Users

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

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

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

// Sync roles (removes all existing roles and adds new ones)
$user->syncRoles(['admin', 'editor']);

// Remove role
$user->removeRole('admin');
$user->removeRole(['admin', 'editor']);
```

#### Checking User Roles

[](#checking-user-roles)

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

// Check multiple roles (OR condition)
if ($user->hasAnyRole(['admin', 'editor'])) {
    // User has at least one of these roles
}

// Check multiple roles (AND condition)
if ($user->hasAllRoles(['admin', 'editor'])) {
    // User has all these roles
}

// Get all user roles
$roles = $user->roles;
```

### Permissions

[](#permissions)

#### Assigning Permissions

[](#assigning-permissions)

```
// Assign permission to role
$role->givePermissionTo('edit-posts');
$role->givePermissionTo($permission);

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

// Sync permissions
$user->syncPermissions(['edit-posts', 'delete-posts']);

// Revoke permission
$role->revokePermissionTo('edit-posts');
$user->revokePermissionTo('delete-posts');
```

#### Checking Permissions

[](#checking-permissions)

```
// Check if user has permission (checks both direct and role permissions)
if ($user->hasPermission('edit-posts')) {
    // User can edit posts
}

// Check if user has direct permission (bypasses roles)
if ($user->hasDirectPermission('edit-posts')) {
    // User has direct permission
}

// Check if user has permission through role
if ($user->hasPermissionViaRole('edit-posts')) {
    // User has permission through a role
}

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

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

// Get all permissions (direct + role permissions)
$permissions = $user->getAllPermissions();
```

### Middleware

[](#middleware)

Protect your routes using middleware:

```
// Single role
Route::get('/admin', function () {
    return 'Admin Dashboard';
})->middleware('role:admin');

// Multiple roles (OR condition)
Route::get('/dashboard', function () {
    return 'Dashboard';
})->middleware('role:admin|editor|viewer');

// Single permission
Route::get('/posts/edit', function () {
    return 'Edit Posts';
})->middleware('permission:edit-posts');

// Multiple permissions (OR condition)
Route::get('/posts', function () {
    return 'Posts';
})->middleware('permission:edit-posts|view-posts');

// Combine multiple middleware
Route::middleware(['auth', 'role:admin', 'permission:edit-posts'])
    ->group(function () {
        Route::get('/posts/edit', [PostController::class, 'edit']);
    });
```

### Blade Directives

[](#blade-directives)

Use directives in your Blade templates:

```
{{-- Check role --}}
@role('admin')
    Admin Panel
@endrole

@hasrole('admin')
    Admin Action
@endhasrole

{{-- Check permission --}}
@permission('edit-posts')
    Edit Posts
@endpermission

@haspermission('delete-posts')
    Delete Post
@endhaspermission

{{-- Multiple checks --}}
@role('admin')
    @permission('edit-posts')
        Admin Edit
    @endpermission
@endrole
```

### API Endpoints

[](#api-endpoints)

The package includes RESTful API endpoints for managing roles and permissions:

#### Roles

[](#roles-1)

```
# Get all roles
GET /roles-permissions/roles-permissions/roles

# Create role
POST /roles-permissions/roles-permissions/roles
{
    "name": "Editor",
    "slug": "editor",
    "description": "Can edit content"
}

# Get specific role
GET /roles-permissions/roles-permissions/roles/{roleId}

# Update role
PUT /roles-permissions/roles-permissions/roles/{roleId}
{
    "name": "Senior Editor",
    "description": "Senior content editor"
}

# Delete role
DELETE /roles-permissions/roles-permissions/roles/{roleId}

# Assign permissions to role
POST /roles-permissions/roles-permissions/roles/{roleId}/permissions/assign
{
    "permissions": [1, 2, 3]
}

# Revoke permissions from role
POST /roles-permissions/roles-permissions/roles/{roleId}/permissions/revoke
{
    "permissions": [1, 2]
}
```

#### Permissions

[](#permissions-1)

```
# Get all permissions
GET /roles-permissions/roles-permissions/permissions

# Create permission
POST /roles-permissions/roles-permissions/permissions
{
    "name": "Delete Posts",
    "slug": "delete-posts",
    "description": "Can delete blog posts"
}

# Get specific permission
GET /roles-permissions/roles-permissions/permissions/{permissionId}

# Update permission
PUT /roles-permissions/roles-permissions/permissions/{permissionId}
{
    "name": "Delete All Posts",
    "description": "Can delete any post"
}

# Delete permission
DELETE /roles-permissions/roles-permissions/permissions/{permissionId}
```

#### User Roles & Permissions

[](#user-roles--permissions)

```
# Get user roles
GET /roles-permissions/roles-permissions/users/{userId}/roles

# Assign roles to user
POST /roles-permissions/roles-permissions/users/{userId}/roles/assign
{
    "roles": [1, 2]
}

# Remove roles from user
POST /roles-permissions/roles-permissions/users/{userId}/roles/remove
{
    "roles": [1]
}

# Sync user roles
POST /roles-permissions/roles-permissions/users/{userId}/roles/sync
{
    "roles": [2, 3]
}

# Check if user has role
GET /roles-permissions/roles-permissions/users/{userId}/roles/check/{roleSlug}

# Get user permissions
GET /roles-permissions/roles-permissions/users/{userId}/permissions

# Assign permissions to user
POST /roles-permissions/roles-permissions/users/{userId}/permissions/assign
{
    "permissions": [1, 2, 3]
}

# Revoke permissions from user
POST /roles-permissions/roles-permissions/users/{userId}/permissions/revoke
{
    "permissions": [1]
}

# Check if user has permission
GET /roles-permissions/roles-permissions/users/{userId}/permissions/check/{permissionSlug}
```

#### API Response Format

[](#api-response-format)

All API responses follow this structure:

**Success Response:**

```
{
    "success": true,
    "message": "Operation completed successfully",
    "data": {
        // Response data
    }
}
```

**Error Response:**

```
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "field": ["Error message"]
    }
}
```

#### Protecting API Routes

[](#protecting-api-routes)

You can protect API routes using middleware:

```
Route::middleware(['auth:sanctum', 'role:admin'])->group(function () {
    Route::post('/roles-permissions/roles-permissions/roles', [RoleController::class, 'store']);
    Route::put('/roles-permissions/roles-permissions/roles/{role}', [RoleController::class, 'update']);
    Route::delete('/roles-permissions/roles-permissions/roles/{role}', [RoleController::class, 'destroy']);
});
```

Advanced Usage
--------------

[](#advanced-usage)

### Custom Role and Permission Models

[](#custom-role-and-permission-models)

You can extend the base models:

```
namespace App\Models;

use Fawzy\RolesPermissions\Models\Role as BaseRole;

class Role extends BaseRole
{
    // Add your custom methods and properties

    public function scopeActive($query)
    {
        return $query->where('active', true);
    }
}
```

Update your config file:

```
// config/roles-permissions.php
return [
    'models' => [
        'role' => App\Models\Role::class,
        'permission' => App\Models\Permission::class,
    ],
];
```

### Seeding Roles and Permissions

[](#seeding-roles-and-permissions)

You can use the built-in seeder or publish it to customize.

Run built-in seeder directly:

```
php artisan db:seed --class="Fawzy\\RolesPermissions\\Database\\Seeders\\RolesPermissionsSeeder"
```

Or publish the seeder to your application and customize it:

```
php artisan vendor:publish --tag=roles-permissions-seeders
```

Factories are also publishable if you want to tweak how sample data is generated:

```
php artisan vendor:publish --tag=roles-permissions-factories
```

Create a seeder:

```
php artisan make:seeder RolesAndPermissionsSeeder
```

```
use Fawzy\RolesPermissions\Models\Role;
use Fawzy\RolesPermissions\Models\Permission;

class RolesAndPermissionsSeeder extends Seeder
{
    public function run()
    {
        // Create permissions
        $permissions = [
            ['name' => 'View Posts', 'slug' => 'view-posts'],
            ['name' => 'Create Posts', 'slug' => 'create-posts'],
            ['name' => 'Edit Posts', 'slug' => 'edit-posts'],
            ['name' => 'Delete Posts', 'slug' => 'delete-posts'],
        ];

        foreach ($permissions as $permission) {
            Permission::create($permission);
        }

        // Create roles
        $admin = Role::create([
            'name' => 'Administrator',
            'slug' => 'admin',
            'description' => 'Full access'
        ]);

        $editor = Role::create([
            'name' => 'Editor',
            'slug' => 'editor',
            'description' => 'Can manage content'
        ]);

        // Assign permissions to roles
        $admin->givePermissionTo(Permission::all());
        $editor->givePermissionTo(['view-posts', 'edit-posts', 'create-posts']);
    }
}
```

### Using in Controllers

[](#using-in-controllers)

```
namespace App\Http\Controllers;

class PostController extends Controller
{
    public function edit(Post $post)
    {
        if (!auth()->user()->hasPermission('edit-posts')) {
            abort(403, 'Unauthorized action.');
        }

        return view('posts.edit', compact('post'));
    }

    public function destroy(Post $post)
    {
        $this->authorize('delete', $post);

        if (auth()->user()->hasPermission('delete-posts')) {
            $post->delete();
            return redirect()->route('posts.index')
                ->with('success', 'Post deleted successfully');
        }

        abort(403);
    }
}
```

### Using with Laravel Policies

[](#using-with-laravel-policies)

```
namespace App\Policies;

use App\Models\User;
use App\Models\Post;

class PostPolicy
{
    public function update(User $user, Post $post)
    {
        return $user->hasPermission('edit-posts') || $post->user_id === $user->id;
    }

    public function delete(User $user, Post $post)
    {
        return $user->hasPermission('delete-posts') ||
               ($user->hasRole('editor') && $post->user_id === $user->id);
    }

    public function viewAny(User $user)
    {
        return $user->hasPermission('view-posts');
    }
}
```

### Caching Permissions

[](#caching-permissions)

Enable caching in your config file:

```
// config/roles-permissions.php
return [
    'cache' => [
        'enabled' => true,
        'expiration_time' => 60 * 24, // 24 hours in minutes
        'key_prefix' => 'roles_permissions.',
    ],
];
```

### Working with Multiple Guards

[](#working-with-multiple-guards)

If you're using multiple authentication guards:

```
// Check role for specific guard
$admin = auth('admin')->user();
if ($admin->hasRole('super-admin')) {
    // Admin has super-admin role
}

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

### Querying Users by Role or Permission

[](#querying-users-by-role-or-permission)

```
// Get all users with a specific role
$admins = User::whereHas('roles', function ($query) {
    $query->where('slug', 'admin');
})->get();

// Get all users with a specific permission
$editors = User::whereHas('permissions', function ($query) {
    $query->where('slug', 'edit-posts');
})->orWhereHas('roles.permissions', function ($query) {
    $query->where('slug', 'edit-posts');
})->get();

// Get users without a specific role
$nonAdmins = User::whereDoesntHave('roles', function ($query) {
    $query->where('slug', 'admin');
})->get();
```

Testing
-------

[](#testing)

The package includes a test suite. Run tests with:

```
composer test
```

### Writing Tests

[](#writing-tests)

Example test for your application:

```
namespace Tests\Feature;

use Tests\TestCase;
use App\Models\User;
use Fawzy\RolesPermissions\Models\Role;
use Fawzy\RolesPermissions\Models\Permission;

class RolesPermissionsTest extends TestCase
{
    public function test_user_can_be_assigned_role()
    {
        $user = User::factory()->create();
        $role = Role::create(['name' => 'Admin', 'slug' => 'admin']);

        $user->assignRole('admin');

        $this->assertTrue($user->hasRole('admin'));
    }

    public function test_user_can_access_protected_route_with_role()
    {
        $user = User::factory()->create();
        $role = Role::create(['name' => 'Admin', 'slug' => 'admin']);
        $user->assignRole('admin');

        $response = $this->actingAs($user)
            ->get('/admin');

        $response->assertStatus(200);
    }

    public function test_user_cannot_access_route_without_permission()
    {
        $user = User::factory()->create();

        $response = $this->actingAs($user)
            ->get('/posts/edit');

        $response->assertStatus(403);
    }
}
```

Common Use Cases
----------------

[](#common-use-cases)

### E-commerce Application

[](#e-commerce-application)

```
// Create roles
$admin = Role::create(['name' => 'Admin', 'slug' => 'admin']);
$seller = Role::create(['name' => 'Seller', 'slug' => 'seller']);
$customer = Role::create(['name' => 'Customer', 'slug' => 'customer']);

// Create permissions
$manageProducts = Permission::create(['name' => 'Manage Products', 'slug' => 'manage-products']);
$viewOrders = Permission::create(['name' => 'View Orders', 'slug' => 'view-orders']);
$placeOrders = Permission::create(['name' => 'Place Orders', 'slug' => 'place-orders']);

// Assign permissions
$admin->givePermissionTo(Permission::all());
$seller->givePermissionTo(['manage-products', 'view-orders']);
$customer->givePermissionTo('place-orders');
```

### Blog/CMS Application

[](#blogcms-application)

```
// Create roles
$superAdmin = Role::create(['name' => 'Super Admin', 'slug' => 'super-admin']);
$editor = Role::create(['name' => 'Editor', 'slug' => 'editor']);
$author = Role::create(['name' => 'Author', 'slug' => 'author']);
$contributor = Role::create(['name' => 'Contributor', 'slug' => 'contributor']);

// Create permissions
$permissions = [
    'publish-posts' => 'Publish Posts',
    'edit-posts' => 'Edit Posts',
    'delete-posts' => 'Delete Posts',
    'create-posts' => 'Create Posts',
    'manage-users' => 'Manage Users',
];

foreach ($permissions as $slug => $name) {
    Permission::create(['name' => $name, 'slug' => $slug]);
}

// Assign permissions
$superAdmin->givePermissionTo(Permission::all());
$editor->givePermissionTo(['publish-posts', 'edit-posts', 'delete-posts', 'create-posts']);
$author->givePermissionTo(['create-posts', 'edit-posts']);
$contributor->givePermissionTo('create-posts');
```

### Multi-tenant SaaS Application

[](#multi-tenant-saas-application)

```
// Workspace-specific roles
$workspaceOwner = Role::create(['name' => 'Workspace Owner', 'slug' => 'workspace-owner']);
$workspaceAdmin = Role::create(['name' => 'Workspace Admin', 'slug' => 'workspace-admin']);
$workspaceMember = Role::create(['name' => 'Workspace Member', 'slug' => 'workspace-member']);

// Workspace permissions
$manageWorkspace = Permission::create(['name' => 'Manage Workspace', 'slug' => 'manage-workspace']);
$inviteMembers = Permission::create(['name' => 'Invite Members', 'slug' => 'invite-members']);
$viewAnalytics = Permission::create(['name' => 'View Analytics', 'slug' => 'view-analytics']);

$workspaceOwner->givePermissionTo([$manageWorkspace, $inviteMembers, $viewAnalytics]);
$workspaceAdmin->givePermissionTo([$inviteMembers, $viewAnalytics]);
```

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

[](#troubleshooting)

### Common Issues

[](#common-issues)

**Issue: Middleware not working**

Make sure middleware is registered. Check `app/Http/Kernel.php`:

```
protected $middlewareAliases = [
    // ...
    'role' => \Fawzy\RolesPermissions\Middleware\RoleMiddleware::class,
    'permission' => \Fawzy\RolesPermissions\Middleware\PermissionMiddleware::class,
];
```

**Issue: Trait not found**

Ensure you've added the `HasRoles` trait to your User model:

```
use Fawzy\RolesPermissions\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}
```

**Issue: Tables not created**

Run migrations:

```
php artisan migrate
```

If migrations aren't running, publish them first:

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

**Issue: API routes not working**

Clear route cache:

```
php artisan route:clear
php artisan cache:clear
php artisan config:clear
```

Performance Tips
----------------

[](#performance-tips)

1. **Eager Load Relationships**

    ```
    $users = User::with(['roles', 'permissions'])->get();
    ```
2. **Use Specific Checks**

    ```
    // Faster - checks direct permissions only
    if ($user->hasDirectPermission('edit-posts')) {
        // ...
    }

    // Slower - checks both direct and role permissions
    if ($user->hasPermission('edit-posts')) {
        // ...
    }
    ```
3. **Cache Results**

    ```
    $permissions = Cache::remember('user_'.$user->id.'_permissions', 3600, function () use ($user) {
        return $user->getAllPermissions();
    });
    ```
4. **Use Database Indexing**

    ```
    // Add indexes in your migrations
    $table->index('slug');
    $table->index(['user_id', 'role_id']);
    ```

Security Best Practices
-----------------------

[](#security-best-practices)

1. **Never trust user input for roles/permissions**

    ```
    // Bad
    $user->assignRole($request->input('role'));

    // Good
    if (in_array($request->input('role'), ['editor', 'author'])) {
        $user->assignRole($request->input('role'));
    }
    ```
2. **Always validate in backend**

    ```
    // Don't rely only on frontend checks
    public function update(Request $request, Post $post)
    {
        if (!auth()->user()->hasPermission('edit-posts')) {
            abort(403);
        }
        // Update post
    }
    ```
3. **Use middleware for routes**

    ```
    Route::middleware(['auth', 'role:admin'])->group(function () {
        // Protected routes
    });
    ```
4. **Implement rate limiting for API**

    ```
    Route::middleware(['throttle:60,1'])->group(function () {
        // API routes
    });
    ```

API Authentication
------------------

[](#api-authentication)

For API endpoints, use Laravel Sanctum or Passport:

### Using Laravel Sanctum

[](#using-laravel-sanctum)

```
composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
```

Update `app/Http/Kernel.php`:

```
'api' => [
    \Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,
    'throttle:api',
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],
```

Protect your API routes:

```
Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('roles', RoleController::class);
    Route::apiResource('permissions', PermissionController::class);
});
```

### Example API Usage with Authentication

[](#example-api-usage-with-authentication)

```
// Login and get token
fetch('/roles-permissions/login', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        email: 'user@example.com',
        password: 'password'
    })
})
.then(response => response.json())
.then(data => {
    const token = data.token;

    // Use token for authenticated requests
    fetch('/roles-permissions/roles-permissions/roles', {
        headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json',
        }
    })
    .then(response => response.json())
    .then(roles => console.log(roles));
});
```

Migration from Other Packages
-----------------------------

[](#migration-from-other-packages)

### From Spatie Laravel Permission

[](#from-spatie-laravel-permission)

The API is similar, making migration straightforward:

```
// Spatie
$user->assignRole('admin');
$user->givePermissionTo('edit posts');

// This package
$user->assignRole('admin');
$user->givePermissionTo('edit-posts');
```

Key differences:

- Permission slugs use kebab-case by default
- Additional API endpoints included
- Slightly different method names for some operations

Changelog
---------

[](#changelog)

### Version 1.0.0 (2024-10-31)

[](#version-100-2024-10-31)

- Initial release
- Core roles and permissions functionality
- Middleware support
- Blade directives
- RESTful API endpoints
- Laravel 10.x and 11.x support

Roadmap
-------

[](#roadmap)

- Permission groups/categories
- Role hierarchy
- Team/workspace-based permissions
- GUI for role/permission management
- Import/Export roles and permissions
- Permission wildcards (e.g., posts.\*)
- Temporary permissions with expiration
- Audit logging

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

[](#contributing)

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Coding Standards

[](#coding-standards)

- Follow PSR-12 coding standards
- Write tests for new features
- Update documentation as needed
- Keep backward compatibility in mind

### Running Tests

[](#running-tests)

```
composer install
composer test
```

Support
-------

[](#support)

- **Issues**: [GitHub Issues](https://github.com/ahmedfawzy23/roles-permissions/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ahmedfawzy23/roles-permissions/discussions)
- **Email**:

Credits
-------

[](#credits)

- **Author**: Ahmed Fawzy
- **Contributors**: [All Contributors](https://github.com/ahmedfawzy23/roles-permissions/contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

---

Quick Links
-----------

[](#quick-links)

- [GitHub Repository](https://github.com/ahmedfawzy23/roles-permissions)
- [Issue Tracker](https://github.com/ahmedfawzy23/roles-permissions/issues)
- [Packagist](https://packagist.org/packages/fawzy/roles-permissions)

---

Made with ❤️ for the Laravel community

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance67

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity44

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

192d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b6cb57e4d9db869238d467de5aa0d7ebca9fed1e7d7dc3b586f2a97b022e141f?d=identicon)[ahmedfawzy23](/maintainers/ahmedfawzy23)

---

Top Contributors

[![ahmedfawzy23](https://avatars.githubusercontent.com/u/96644839?v=4)](https://github.com/ahmedfawzy23 "ahmedfawzy23 (7 commits)")

---

Tags

apilaravelsecurityauthorizationaclrolespermissionsrbacaccess-control

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fawzy-laravel-roles-permissions/health.svg)

```
[![Health](https://phpackages.com/badges/fawzy-laravel-roles-permissions/health.svg)](https://phpackages.com/packages/fawzy-laravel-roles-permissions)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k89.8M1.0k](/packages/spatie-laravel-permission)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[hasinhayder/tyro

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

6712.1k2](/packages/hasinhayder-tyro)[casbin/laravel-authz

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

324339.9k4](/packages/casbin-laravel-authz)[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)[hosseinhezami/laravel-permission-manager

Advanced permission manager for Laravel.

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

PHPackages © 2026

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