erag / laravel-role-permission
A simple and easy-to-install role and permission management package for Laravel, supporting versions 10.x and 11.x
Requires
- php: >=8.0.0
- illuminate/database: ^8.12|^9.0|^10.0|^11.0
README
This package provides an effortless way to manage roles and permissions in your Laravel application. With automatic database configuration, one-command publishing, and easy integration, you can quickly set up robust role-based access control without hassle.
Getting Started
composer require erag/laravel-role-permission
Step 1: Add Trait to User Model
Before configuring the database and publishing the role-permission files, add the HasPermissionsTrait
to define in your User
model. This trait is essential for handling roles and permissions in your application.
HasPermissionsTrait
<?php namespace App\Models; use EragPermission\Traits\HasPermissionsTrait; use Illuminate\Database\Eloquent\Factories\HasFactory; use Illuminate\Foundation\Auth\User as Authenticatable; use Illuminate\Notifications\Notifiable; class User extends Authenticatable { use HasFactory, HasPermissionsTrait, Notifiable; }
Step 2: Database Configuration
Before proceeding with the setup, ensure that your database connection is properly configured in your .env
file. Example configuration:
DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=your_database_name DB_USERNAME=your_database_user DB_PASSWORD=your_database_password
Make sure to replace your_database_name
, your_database_user
, and your_database_password
with your actual database credentials.
Step 3: Automatic Database Setup
After configuring your database connection, the package will automatically set up your database by running the necessary migrations and seeders without any additional setup.
Step 4: Register the Service Provider
For Laravel v11.x
Ensure the service provider is registered in your /bootstrap/providers.php
file:
return [ // ... EragPermission\PermissionServiceProvider::class, ];
For Laravel v10.x
Ensure the service provider is registered in your config/app.php
file:
'providers' => [ // ... EragPermission\PermissionServiceProvider::class, ],
Step 5: Publish Role-Permission Files
Once the database is configured, publish the required migration and model files with a single command:
php artisan erag:publish-permission
This command will publish the required migrations:
php artisan erag:publish-permission --migrate
If you want to run the published migrations and seed the datbase you cann add --migrate
and --seed
respectively. Then the command will automatically run the migrations and the seeder to set up roles and permissions in your database.
php artisan erag:publish-permission --migrate --seed
Step 6: Using Role-Based Permissions
You can now easily check user permissions within your application logic:
if (auth()->user()->can('permission_name')) { // The user has the specified permission }
You can also use the helper method:
if (hasPermissions('post-create')) { dd('You are allowed to access'); } else { dd('You are not allowed to access'); }
OR
if (hasPermissions('post-create|post-edit')) { dd('You are allowed to access'); } else { dd('You are not allowed to access'); } if (hasPermissions('post-create,post-edit')) { dd('You are allowed to access'); } else { dd('You are not allowed to access'); }
To get all permissions:
getPermissions();
Using Role-Based Checks
if (hasRole('admin')) { dd('You are allowed to access'); } else { dd('You are not allowed to access'); }
To get all roles:
getRoles();
Step 7: Protecting Routes with Middleware
To protect routes based on roles and permissions, you can use the provided middleware. For example, to allow only users with the user
role and create-user
permission:
Route::group(['middleware' => ['role:user,user-create']], function () { // Protected routes go here }); Route::group(['middleware' => ['role:admin,post-create']], function () { // Protected routes go here });
Step 8: Displaying Content Based on Roles
You can also use Blade directives to display content based on the user's role:
@role('admin') {{ __('You are an admin') }} @endrole @role('user') {{ __('You are a user') }} @endrole
Step 9: Displaying Content Based on Permissions
You can also use Blade directives to display content based on the user's permissions:
@hasPermissions('post-create') {{ __('You can create a post') }} @endhasPermissions
OR
@hasPermissions('post-create|post-edit') {{ __('You can create a post') }} @endhasPermissions @hasPermissions('post-create,post-edit') {{ __('You can create a post') }} @endhasPermissions
Example Seeder for Roles and Permissions
Here's an example RolePermissionSeeder
that seeds roles, permissions, and users:
<?php namespace Database\Seeders; use App\Models\User; use EragPermission\Models\Role; use EragPermission\Models\Permission; use Illuminate\Database\Seeder; use Illuminate\Support\Facades\DB; use Illuminate\Support\Facades\Hash; class RolePermissionSeeder extends Seeder { /** * Run the database seeds. */ public function run(): void { DB::transaction(function () { $this->seedPermissions(); $this->seedRoles(); $this->seedUsers(); }); } private function seedPermissions(): void { $permissions = [ 'post-create', 'user-create', ]; foreach ($permissions as $permissionName) { Permission::firstOrCreate(['name' => $permissionName]); } } private function seedRoles(): void { $roles = [ 'admin' => ['post-create', 'post-edit', 'post-delete', 'post-update'], 'user' => ['user-create', 'user-edit', 'user-delete', 'user-update'], ]; foreach ($roles as $roleName => $permissionNames) { $role = Role::firstOrCreate(['name' => $roleName]); foreach ($permissionNames as $permissionName) { $permission = Permission::firstOrCreate(['name' => $permissionName]); $role->permissions()->syncWithoutDetaching($permission); $permission->roles()->syncWithoutDetaching($role); } } } private function seedUsers(): void { $users = [ [ 'name' => 'Admin', 'email' => 'admin@gmail.com', 'password' => Hash::make('admin'), 'roles' => ['admin'], 'permissions' => ['post-create', 'post-edit'], ], [ 'name' => 'User', 'email' => 'user@gmail.com', 'password' => Hash::make('user'), 'roles' => ['user'], 'permissions' => ['user-create', 'user-edit'], ], ]; foreach ($users as $userData) { $user = User::updateOrCreate( ['email' => $userData['email']], [ 'name' => $userData['name'], 'password' => $userData['password'], ] ); foreach ($userData['roles'] as $roleName) { $role = Role::where('name', $roleName)->first(); if ($role) { $user->roles()->syncWithoutDetaching($role); } } foreach ($userData['permissions'] as $permissionName) { $permission = Permission::where('name', $permissionName)->first(); if ($permission) { $user->permissions()->syncWithoutDetaching($permission); } } } } }
Contribution 🧑💻
We welcome contributions to this project. Please read our Contributing Guidelines before you start contributing.