Rbac Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require admin-platform/rbac
   

   Add to config/app.php under providers:

   AdminPlatform\Rbac\RbacServiceProvider::class,
   

2. Publish Config & Migrations

   php artisan vendor:publish --provider="AdminPlatform\Rbac\RbacServiceProvider" --tag="rbac-config"
   php artisan vendor:publish --provider="AdminPlatform\Rbac\RbacServiceProvider" --tag="rbac-migrations"
   php artisan migrate
   

3. First Use Case: Assigning a Role

   use AdminPlatform\Rbac\Models\Role;
   
   // Create a role
   $adminRole = Role::create(['name' => 'admin', 'guard_name' => 'web']);
   
   // Assign to a user
   $user->roles()->attach($adminRole);
   

4. Check Permissions

   if ($user->can('access_dashboard')) {
       // Grant access
   }
   

Implementation Patterns

Role Hierarchy Management

• Define Hierarchy via parent_id in the roles table:

  $superAdmin = Role::create(['name' => 'super_admin']);
  $admin = Role::create(['name' => 'admin', 'parent_id' => $superAdmin->id]);
  

• Check Hierarchical Permissions:

  if ($user->can('edit_users', true)) { // `true` enables hierarchy checks
      // Logic for hierarchical access
  }
  

Permission Assignment

• Bulk Assign Permissions to a role:

  $role->permissions()->sync(['create_post', 'edit_post']);
  

• Dynamic Permission Checks in middleware:

  public function handle($request, Closure $next)
  {
      if (!$request->user()->can('manage_users')) {
          abort(403);
      }
      return $next($request);
  }
  

Integration with Policies

• Extend Policies to use RBAC:

  use AdminPlatform\Rbac\Traits\HasRbac;
  
  class PostPolicy
  {
      use HasRbac;
  
      public function update(User $user, Post $post)
      {
          return $user->can('edit_post');
      }
  }
  

API Resource Protection

• Gate Middleware for API Routes:

  Route::middleware(['auth:sanctum', 'rbac'])->group(function () {
      Route::get('/admin/dashboard', [DashboardController::class, 'index']);
  });
  

Gotchas and Tips

Pitfalls

1. Guard Name Mismatch

   • Ensure guard_name in roles matches your auth guard (e.g., web, api). Defaults to web if omitted.
   • Fix: Update roles with correct guard:

     Role::where('guard_name', 'null')->update(['guard_name' => 'web']);
     

2. Circular Hierarchy

   • Avoid loops in role inheritance (e.g., Role A → Role B → Role A).
   • Fix: Validate hierarchy before saving:

     if ($role->isAncestorOf($parentRole)) {
         throw new \Exception("Circular hierarchy detected.");
     }
     

3. Permission Caching

   • Permissions are cached by default. Clear cache after bulk updates:

     php artisan cache:clear
     

   • Tip: Disable caching in config/rbac.php for testing:

     'cache_permissions' => env('RBAC_CACHE_PERMISSIONS', false),
     

Debugging

• Log Permission Checks Add to config/rbac.php:

  'debug' => env('RBAC_DEBUG', false),
  

  Check logs for denied permission attempts.

• Dump User Permissions

  dd($user->getAllPermissions());
  

Extension Points

1. Custom Permission Providers Override AdminPlatform\Rbac\Contracts\PermissionProvider to fetch permissions from external sources (e.g., database views).

2. Event Listeners Listen for role/permission changes:

   Role::created(function ($role) {
       // Trigger notifications or sync services
   });
   

3. Custom Guards Extend AdminPlatform\Rbac\RbacGuard for non-standard auth setups.

Performance Tips

• Index Database Columns Add indexes to roles and role_permission tables for large datasets:

  Schema::table('roles', function (Blueprint $table) {
      $table->index('guard_name');
      $table->index('parent_id');
  });
  

• Lazy-Load Permissions Use with(['permissions']) sparingly; eager-load only when necessary:

  $role = Role::with('permissions')->find($id);