Permission Manager Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require l5starter/permission-manager:5.4.x-dev
   

   Add to config/app.php:

   'providers' => [
       Spatie\Permission\PermissionServiceProvider::class,
       L5Starter\PermissionManager\PermissionManagerServiceProvider::class,
   ],
   

2. Publish Assets Run migrations and seeders:

   php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="migrations"
   php artisan migrate
   php artisan vendor:publish --provider="L5Starter\PermissionManager\PermissionManagerServiceProvider" --tag="seeder"
   php artisan db:seed --class=RolesTableSeeder
   

3. User Model Integration Add trait to app/User.php:

   use Spatie\Permission\Traits\HasRoles;
   use L5Starter\PermissionManager\Traits\HasPermissions; // If using custom permissions
   

4. First Use Case Assign a role to a user:

   $user = User::find(1);
   $user->assignRole('admin');
   

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

   • Assign Roles: $user->assignRole('editor')
   • Check Role: $user->hasRole('editor')
   • Remove Role: $user->removeRole('editor')
   • List Roles: $user->roles

2. Permission Management

   • Assign Permissions: $user->givePermissionTo('edit_articles')
   • Check Permission: $user->can('edit_articles')
   • Remove Permission: $user->revokePermissionTo('edit_articles')
   • List Permissions: $user->getAllPermissions()

3. Middleware Integration Use built-in middleware for route protection:

   Route::get('/admin', function () {
       // ...
   })->middleware(['role:admin', 'permission:edit_articles']);
   

4. Admin Panel Integration

   • Extend sidebar.blade.php (as shown in README) for UI navigation.
   • Use provided routes (admin.roles.index, admin.permissions.index) for CRUD operations.

5. Policy Integration Extend Laravel’s policies with permission checks:

   public function update(User $user, Article $article)
   {
       $this->authorize('edit_articles');
       // ...
   }
   

Advanced Patterns

• Dynamic Permissions: Create permissions on-the-fly:

  $permission = Permission::create(['name' => 'manage_users']);
  $user->givePermissionTo($permission);
  

• Role Hierarchies: Define parent-child relationships:

  $adminRole = Role::create(['name' => 'admin']);
  $editorRole = Role::create(['name' => 'editor']);
  $editorRole->setParent($adminRole);
  

• Gate Integration:

  Gate::define('edit_articles', function ($user) {
      return $user->hasPermissionTo('edit_articles');
  });
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts

   • If using Spatie’s permission package directly, avoid duplicate migrations. This package extends Spatie’s functionality, so ensure spatie/laravel-permission is not installed separately.

2. Seeder Overrides

   • The RolesTableSeeder may conflict with existing seeders. Review and merge logic if custom roles/permissions exist.

3. Route Caching

   • After adding middleware or routes, clear cached routes:

     php artisan route:clear
     

4. Permission Caching

   • Permission checks are cached by default. Clear cache if changes aren’t reflected:

     php artisan cache:clear
     

5. Namespace Collisions

   • Ensure L5Starter\PermissionManager doesn’t conflict with other PermissionManager classes in your project.

Debugging Tips

• Check User Roles/Permissions:

  dd($user->roles, $user->getAllPermissions());
  

• Log Middleware Failures: Add a throws block in middleware to log denied access:

  public function handle($request, Closure $next)
  {
      if (!auth()->user()->hasRole('admin')) {
          Log::warning('Unauthorized access attempt: ' . $request->path());
          abort(403);
      }
      return $next($request);
  }
  

Extension Points

1. Custom Permission Models Extend the Permission model or use traits to add custom logic:

   class CustomPermission extends \Spatie\Permission\Models\Permission
   {
       public function scopeActive($query)
       {
           return $query->where('is_active', true);
       }
   }
   

2. API Resources Create custom API resources for roles/permissions:

   namespace App\Http\Resources;
   use L5Starter\PermissionManager\Models\Role;
   use Illuminate\Http\Resources\Json\JsonResource;
   
   class RoleResource extends JsonResource
   {
       public function toArray($request)
       {
           return [
               'id' => $this->id,
               'name' => $this->name,
               'permissions' => $this->permissions->pluck('name'),
           ];
       }
   }
   

3. Event Listeners Listen for role/permission changes:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       'L5Starter\PermissionManager\Events\RoleAssigned' => [
           'App\Listeners\LogRoleAssignment',
       ],
   ];
   

4. Localization Override translations in resources/lang/en/l5starter.php:

   return [
       'roles' => 'Custom Role Name',
       'permissions' => 'Custom Permission Name',
   ];
   

5. Testing Use factories or seeders to set up test users with roles/permissions:

   $user = User::factory()->create();
   $user->assignRole('admin');
   $this->actingAs($user);