Filament Spatie Roles Permissions Laravel Package

Getting Started

Minimal Setup

1. Installation Run:

   composer require althinect/filament-spatie-roles-permissions
   

   Then publish the config:

   php artisan vendor:publish --tag="filament-spatie-roles-permissions-config"
   

2. Register Resources Add the provider and resources to app/Providers/Filament/AdminPanelProvider.php:

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

3. First Use Case Access /admin/roles and /admin/permissions in your Filament admin panel to manage roles and permissions via a clean UI. Assign permissions to roles directly from the RoleResource page.

Implementation Patterns

Core Workflows

1. Role-Permission Assignment

   • Use the RoleResource to assign permissions to roles via a many-to-many relationship table.
   • Example: Assign edit-posts to the Editor role by checking the box in the Permissions tab.

2. Permission Generation

   • Generate permissions via Artisan:

     php artisan make:permission edit-posts --model=Post
     php artisan make:permission delete-posts --model=Post
     

   • These will appear in the PermissionResource automatically.

3. Team-Aware Permissions (Optional)

   • Enable tenancy-aware teams in config/permission.php:

     'teams' => true,
     

   • Use the TeamResource (if included) to scope permissions to teams.

4. Policy Integration

   • Define policies for models (e.g., PostPolicy) and link them to permissions:

     public function abilities(User $user): array
     {
         return [
             'edit' => $user->hasPermissionTo('edit-posts'),
             'delete' => $user->hasPermissionTo('delete-posts'),
         ];
     }
     

   • Sync policies with permissions via:

     php artisan permission:policy-sync
     

5. Bulk Actions

   • Use the PermissionResource to bulk-create permissions or assign them to multiple roles.

Integration Tips

• Customize Columns/Tables Override the default table columns in app/Filament/Resources/RoleResource.php:

  public static function table(Table $table): Table
  {
      return $table
          ->columns([
              TextColumn::make('name'),
              TextColumn::make('permissions_count')->counts('permissions'),
          ]);
  }
  

• Filtering Add filters to the PermissionResource to search by model or action:

  public static function getFilters(): array
  {
      return [
          SelectFilter::make('model')
              ->options(Permission::getAvailableModels())
              ->label('Model'),
      ];
  }
  

• Middleware for Access Control Use Filament’s built-in middleware to restrict access:

  public static function getPages(): array
  {
      return [
          'index' => fn () => redirect('/admin/dashboard')->unless(fn () => auth()->user()->hasPermissionTo('manage-roles')),
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Config Overrides

   • Running vendor:publish overwrites existing config. Backup config/filament-spatie-roles-permissions.php before updating.

2. Permission Caching

   • Clear cached permissions after bulk updates:

     php artisan cache:clear
     php artisan config:clear
     

3. Team Permissions Quirks

   • If teams is enabled in config/permission.php, ensure the team_id column exists in the model_has_permissions table. Run migrations if needed:

     php artisan migrate
     

4. Policy Sync Conflicts

   • The permission:policy-sync command overwrites existing policies. Review generated policies before running:

     php artisan permission:policy-sync --dry-run
     

5. Filament Version Compatibility

   • The package may lag behind Filament major versions. Check the GitHub issues for compatibility notes.

Debugging Tips

1. Permission Not Showing?

   • Verify the permission exists in the database (permissions table).
   • Check if the permission is cached:

     \Spatie\Permission\Permission::cachePermissions();
     

2. Role Assignment Issues

   • Ensure the role_id column exists in the users table (or your pivot table). Run:

     php artisan migrate
     

3. Team Scoping Problems

   • If using teams, ensure the team_id is set on the user or role. Debug with:

     dd(auth()->user()->currentTeam);
     

Extension Points

1. Custom Permission Models Extend the default Permission model by publishing and modifying the migration:

   php artisan vendor:publish --tag="spatie-permission-migrations"
   

2. Add Custom Fields to Roles Extend the Role model and update the RoleResource:

   public static function form(Form $form): Form
   {
       return $form->schema([
           TextInput::make('name'),
           SelectInput::make('department')
               ->options(['HR', 'Engineering', 'Marketing']),
       ]);
   }
   

3. Override Resource Classes Create a custom resource class (e.g., app/Filament/Resources/CustomRoleResource.php) and register it in AdminPanelProvider:

   ->resources([
       \App\Filament\Resources\CustomRoleResource::class,
   ]);
   

4. Localization Translate labels/placeholders by publishing the language files:

   php artisan vendor:publish --tag="filament-spatie-roles-permissions-lang"