Filament Shield Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bezhansalleh/filament-shield
   

   Publish the config and migrations:

   php artisan vendor:publish --provider="BezhanSalleh\FilamentShield\FilamentShieldServiceProvider"
   php artisan migrate
   

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

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               \BezhanSalleh\FilamentShield\FilamentShieldPlugin::make(),
           ]);
   }
   

3. First Use Case:

   • Navigate to Filament Dashboard > Shield to manage roles, permissions, and users.
   • Assign a role to a user via the User Management section (e.g., admin, editor).

Where to Look First

• Documentation: Filament Shield Docs (check for Filament 4/5 compatibility).
• Example Config: config/filament-shield.php (customize default roles/permissions).
• Migrations: database/migrations/..._create_permission_tables.php (if extending tables).

Implementation Patterns

Core Workflows

1. Role-Permission Assignment:

   • Use the Shield > Roles tab to define permissions (e.g., create posts, manage users).
   • Attach permissions to roles via the Permissions tab (drag-and-drop or bulk actions).

2. User Role Management:

   • Edit a user in Filament > Users and assign roles via the Shield widget.
   • Gate access programmatically:

     use BezhanSalleh\FilamentShield\Enums\PermissionGroup;
     use BezhanSalleh\FilamentShield\Enums\PermissionName;
     
     if (auth()->user()->can(PermissionName::MANAGE_USERS)) {
         // Allow action
     }
     

3. Policy Integration:

   • Extend existing policies (e.g., PostPolicy) to use Shield permissions:

     public function create(User $user)
     {
         return $user->can(PermissionName::CREATE_POSTS);
     }
     

Integration Tips

• Filament Resources: Disable actions conditionally:

  public static function getPages(): array
  {
      return [
          'index' => fn() => auth()->user()->can(PermissionName::VIEW_POSTS),
          'create' => fn() => auth()->user()->can(PermissionName::CREATE_POSTS),
      ];
  }
  

• Middleware: Use Can middleware for API routes:

  Route::get('/admin/posts', [PostController::class, 'index'])
      ->middleware(['auth', new Can(PermissionName::VIEW_POSTS)]);
  

• Custom Groups: Define permission groups in config/filament-shield.php:

  'groups' => [
      'posts' => [
          'create_posts',
          'edit_posts',
          'delete_posts',
      ],
  ],
  

Gotchas and Tips

Pitfalls

1. Permission Caching:

   • Clear cached permissions after bulk updates:

     php artisan cache:clear
     

   • Or use auth()->user()->syncPermissions() manually.

2. Filament Version Mismatch:

   • Ensure filament-shield matches your Filament version (4.x vs. 5.x). Check the release notes.

3. Overlapping Roles:

   • Avoid granting conflicting permissions (e.g., edit_posts and delete_posts to non-admin roles). Use role hierarchies in Shield.

4. Migration Conflicts:

   • If extending spatie/laravel-permission tables, run:

     php artisan permission:table
     

     before migrating.

Debugging

• Permission Checks: Log user permissions for debugging:

  \Log::info('User permissions:', auth()->user()->getAllPermissions()->toArray());
  

• Widget Visibility: Hide the Shield widget for non-admins:

  \BezhanSalleh\FilamentShield\FilamentShieldPlugin::make()
      ->visible(fn() => auth()->user()->can(PermissionName::MANAGE_ROLES)),
  

Extension Points

1. Custom Permission Models: Extend HasPermissions trait to add fields:

   use BezhanSalleh\FilamentShield\Traits\HasPermissions;
   
   class User extends Authenticatable
   {
       use HasPermissions;
   
       protected $casts = [
           'permissions' => 'array',
           'role' => 'string',
       ];
   }
   

2. Dynamic Permissions: Fetch permissions from an external API:

   public function boot()
   {
       \BezhanSalleh\FilamentShield\Permission::created(fn($permission) => $this->syncExternalPermission($permission));
   }
   

3. Localization: Translate permission names/groups in resources/lang/en/permissions.php:

   return [
       'create_posts' => 'Create Posts',
   ];
   

Pro Tips

• Bulk Actions: Use the Shield > Roles bulk select to assign permissions to multiple roles at once.

• Audit Logging: Combine with spatie/laravel-activitylog to track permission changes:

  \Spatie\Activitylog\Models\Activity::create([
      'log_name' => 'permission_updated',
      'properties' => ['permission' => $permission->name],
  ]);
  

• Testing: Mock permissions in tests:

  $user = User::factory()->create();
  $user->givePermissionTo('edit_posts');
  $this->actingAs($user);