Gestion Des Role Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require boxiweb/gestion-des-role
   

   Publish the package configuration (if available):

   php artisan vendor:publish --provider="Boxiweb\GestionDesRole\GestionDesRoleServiceProvider"
   

2. First Use Case Register a role and assign it to a user:

   use Boxiweb\GestionDesRole\Facades\GestionDesRole;
   
   // Create a role
   $role = GestionDesRole::createRole('admin', ['create_users', 'manage_content']);
   
   // Assign role to a user
   GestionDesRole::assignRoleToUser($role, $user);
   

3. Key Files to Review

   • config/gestion-des-role.php (if published)
   • src/Facades/GestionDesRole.php (main facade)
   • src/Models/Role.php (role model structure)

Implementation Patterns

Core Workflows

1. Role Management

   // Create a role with permissions
   $role = GestionDesRole::createRole('editor', ['edit_posts', 'publish']);
   
   // Update role permissions
   GestionDesRole::updateRolePermissions($role, ['edit_posts', 'delete_posts']);
   
   // Delete a role
   GestionDesRole::deleteRole($role);
   

2. User-Role Assignment

   // Assign multiple roles to a user
   GestionDesRole::assignRolesToUser($user, ['admin', 'moderator']);
   
   // Check if user has a role
   if (GestionDesRole::userHasRole($user, 'admin')) {
       // Grant access
   }
   
   // Revoke a role
   GestionDesRole::revokeRoleFromUser($user, 'moderator');
   

3. Permission Checks

   // Check if user has a specific permission
   if (GestionDesRole::userHasPermission($user, 'manage_content')) {
       // Allow action
   }
   
   // Get all permissions for a user
   $permissions = GestionDesRole::getUserPermissions($user);
   

Integration Tips

• Middleware for Role-Based Access

  use Boxiweb\GestionDesRole\Facades\GestionDesRole;
  
  public function handle($request, Closure $next)
  {
      if (!GestionDesRole::userHasRole(auth()->user(), 'admin')) {
          abort(403);
      }
      return $next($request);
  }
  

• Seeding Roles

  public function run()
  {
      $adminRole = GestionDesRole::createRole('admin', ['*']);
      $editorRole = GestionDesRole::createRole('editor', ['edit_posts']);
  
      $adminUser = User::where('email', 'admin@example.com')->first();
      GestionDesRole::assignRoleToUser($adminRole, $adminUser);
  }
  

• Dynamic Permission Assignment Useful for feature flags or conditional access:

  if ($user->isPremium()) {
      GestionDesRole::assignRoleToUser($premiumRole, $user);
  }
  

Gotchas and Tips

Pitfalls

1. No Built-in Migration The package does not include migrations. Ensure you create and run migrations for the roles and role_user tables manually:

   php artisan make:migration create_roles_table
   php artisan make:migration create_role_user_table
   

2. Permission Wildcards The package may not natively support wildcard permissions (e.g., * for all permissions). Validate permissions explicitly:

   // Instead of:
   GestionDesRole::userHasPermission($user, '*');
   
   // Use:
   $allPermissions = ['create_users', 'edit_users', 'delete_users'];
   $hasAll = collect($allPermissions)->every(fn($perm) => GestionDesRole::userHasPermission($user, $perm));
   

3. Facade Dependency The package relies heavily on the GestionDesRole facade. Avoid circular dependencies by injecting the facade or service container directly where needed.

Debugging Tips

• Check Role Existence

  if (!GestionDesRole::roleExists('admin')) {
      $role = GestionDesRole::createRole('admin', []);
  }
  

• Log Permission Errors

  try {
      if (GestionDesRole::userHasPermission($user, 'hidden_permission')) {
          // ...
      }
  } catch (\Exception $e) {
      Log::error("Permission check failed: " . $e->getMessage());
  }
  

Extension Points

1. Custom Role Providers Override the default role provider by binding your implementation in the service provider:

   $this->app->bind(
       \Boxiweb\GestionDesRole\Contracts\RoleProvider::class,
       \App\Providers\CustomRoleProvider::class
   );
   

2. Event Listeners Listen for role/permission changes:

   public function boot()
   {
       GestionDesRole::roleCreated(function ($role) {
           // Log or notify when a role is created
       });
   }
   

3. API Integration Expose role/permission endpoints via Laravel Sanctum or Passport:

   Route::middleware('auth:sanctum')->get('/user/permissions', function () {
       return GestionDesRole::getUserPermissions(auth()->user());
   });
   

Configuration Quirks

• Default Role Name The package may not enforce a default role (e.g., user). Define one in your config:

  'default_role' => 'user',
  

• Permission Caching If performance is critical, cache permission checks:

  Cache::remember("user_{$user->id}_permissions", now()->addHours(1), function () use ($user) {
      return GestionDesRole::getUserPermissions($user);
  });