Users Roles Permissions Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cwsps154/users-roles-permissions
   

   Publish the package config and migrations:

   php artisan vendor:publish --provider="Cwsps154\UsersRolesPermissions\UsersRolesPermissionsServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Cwsps154\UsersRolesPermissions\UsersRolesPermissionsServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Register Filament Resources Add the following to app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->resources([
               \Cwsps154\UsersRolesPermissions\Resources\UserResource::class,
               \Cwsps154\UsersRolesPermissions\Resources\RoleResource::class,
               \Cwsps154\UsersRolesPermissions\Resources\PermissionResource::class,
           ]);
   }
   

3. First Use Case: Assign a Role to a User

   • Navigate to Filament Admin Panel → Users.
   • Select a user → Edit → Roles tab.
   • Check the desired role(s) and save.

Implementation Patterns

Core Workflows

1. Role-Based Access Control (RBAC)

   • Define permissions in PermissionResource (e.g., create-post, edit-user).
   • Assign permissions to roles in RoleResource (e.g., "Editor" role gets create-post).
   • Attach roles to users via UserResource.

2. Dynamic Policy Integration Use the package’s policies with Laravel’s built-in Gate system:

   // app/Providers/AuthServiceProvider.php
   public function boot()
   {
       Gate::define('update-post', function (User $user, Post $post) {
           return $user->hasPermissionTo('edit-post');
       });
   }
   

3. Middleware for Route Protection

   // app/Http/Kernel.php
   protected $routeMiddleware = [
       'role' => \Cwsps154\UsersRolesPermissions\Http\Middleware\CheckRole::class,
       'permission' => \Cwsps154\UsersRolesPermissions\Http\Middleware\CheckPermission::class,
   ];
   

   Apply in routes:

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

4. Bulk Operations

   • Use Filament’s bulk actions to assign roles/permissions to multiple users/roles at once.
   • Example: Select 10 users → Bulk Actions → Assign Role → "Editor".

Integration Tips

• Custom Fields: Extend resources with custom fields (e.g., add a department field to users):

  use Filament\Forms\Components\Select;
  
  public static function form(Form $form): Form
  {
      return $form->schema([
          Select::make('department')
              ->options(['HR', 'Engineering', 'Marketing'])
              ->required(),
          // ... existing fields
      ]);
  }
  

• API Access: Use the package’s API endpoints (if enabled) for headless integrations:

  php artisan make:filament-api-resource UserResource
  

• Seeding: Pre-populate roles/permissions via a seeder:

  // database/seeders/RolePermissionSeeder.php
  use Cwsps154\UsersRolesPermissions\Models\Role;
  use Cwsps154\UsersRolesPermissions\Models\Permission;
  
  public function run()
  {
      $adminRole = Role::create(['name' => 'admin']);
      Permission::create(['name' => 'manage-users'])->roles()->attach($adminRole);
  }
  

Gotchas and Tips

Pitfalls

1. Caching Issues

   • After modifying roles/permissions, clear Filament’s cache:

     php artisan filament:cache:clear
     

   • Or manually clear the filament_* tables in the database.

2. Permission Hierarchy Conflicts

   • If a user has both a role with create-post and another role with delete-post, the package does not automatically resolve conflicts. Explicitly define which permissions take precedence in your logic.

3. Migration Conflicts

   • If you’ve customized Laravel’s default users table (e.g., added department), ensure the package’s migrations don’t overwrite your changes. Run:

     php artisan migrate --pretend
     

     to check for conflicts before migrating.

4. Filament Widget Overrides

   • If you override the UserResource or RoleResource, ensure you extend the original class to retain package functionality:

     class CustomUserResource extends \Cwsps154\UsersRolesPermissions\Resources\UserResource
     {
         // Your customizations
     }
     

Debugging

• Permission Checks Failing:
  • Verify the name of permissions/roles matches exactly (case-sensitive).
  • Use Tinker to debug:

    php artisan tinker
    >>> $user = App\Models\User::first();
    >>> $user->hasPermissionTo('create-post'); // Should return true/false
    

• Role Assignment Not Saving:
  • Check if the pivot table (role_user) exists and has the correct columns (user_id, role_id).
  • Ensure the User model uses the correct belongsToMany relationship:

    public function roles()
    {
        return $this->belongsToMany(Role::class);
    }
    

Extension Points

1. Custom Permission Logic Override the hasPermissionTo method in your User model:

   public function hasPermissionTo($permission)
   {
       // Custom logic (e.g., check department + role)
       return parent::hasPermissionTo($permission) && $this->department === 'admin';
   }
   

2. Add Permission Groups Extend the PermissionResource to support groups (e.g., "Posts", "Users"):

   // app/Models/Permission.php
   public function groups()
   {
       return $this->belongsToMany(PermissionGroup::class);
   }
   

3. Audit Logging Use Laravel’s audit package (e.g., spatie/laravel-audit-log) to track role/permission changes:

   use Spatie\AuditLog\AuditLog;
   
   // In your RoleResource's update method
   AuditLog::log('updated role', $this->getUpdatedRoleData());
   

4. API Token Scopes Integrate with Laravel Sanctum/Passport to scope tokens by permissions:

   // app/Models/User.php
   public function getTokenScopes()
   {
       return $this->permissions->pluck('name');
   }