Filament Multi Guard Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require iotronlab/filament-multi-guard
   

   Ensure you're using Filament v2 (not v3, as noted in the README).

2. Publish Config:

   php artisan vendor:publish --provider="Iotronlab\FilamentMultiGuard\FilamentMultiGuardServiceProvider" --tag="filament-multi-guard-config"
   

   This generates config/filament-multi-guard.php.

3. Register Guards: Define guards in config/filament-multi-guard.php:

   'guards' => [
       'admin' => [
           'guard' => 'web',
           'middleware' => ['web', 'auth:sanctum'],
           'resources' => ['posts', 'users'],
           'pages' => ['dashboard', 'profile'],
       ],
       'client' => [
           'guard' => 'web',
           'middleware' => ['web', 'auth:client'],
           'resources' => ['client-posts'],
           'pages' => ['client-dashboard'],
       ],
   ],
   

4. First Use Case: Register the package in AppServiceProvider:

   use Iotronlab\FilamentMultiGuard\Facades\FilamentMultiGuard;
   
   public function boot()
   {
       FilamentMultiGuard::register();
   }
   

   Now, Filament will automatically route resources/pages to their respective guards.

Implementation Patterns

Workflows

1. Guard-Specific Routing:

   • Use guard() method in policies or middleware to enforce context:

     if (FilamentMultiGuard::guard() === 'client') {
         // Client-specific logic
     }
     

2. Dynamic Resource Registration:

   • Register resources dynamically in a service provider:

     FilamentMultiGuard::registerResource('posts', PostResource::class, 'admin');
     

3. Middleware Integration:

   • Apply guard-specific middleware to Filament routes:

     FilamentMultiGuard::middleware(['verified'])->forGuards(['client']);
     

4. Widget Isolation:

   • Assign widgets to specific guards in config/filament.php:

     'widgets' => [
         'stats' => [
             'guard' => 'admin',
         ],
     ],
     

5. Authentication Fallbacks:

   • Handle unauthorized access gracefully:

     FilamentMultiGuard::fallbackGuard('admin'); // Fallback to 'admin' if guard not found
     

Integration Tips

• Laravel Sanctum/Passport: Use auth:sanctum or auth:api in guard middleware for API-based auth.
• Custom Guards: Extend the Guard class to add logic (e.g., role-based access):

  FilamentMultiGuard::extend('admin', function () {
      return new CustomAdminGuard();
  });
  

• Testing: Mock guards in tests:

  FilamentMultiGuard::shouldReceive('guard')->andReturn('client');
  

Gotchas and Tips

Pitfalls

1. Filament v3 Incompatibility: The package only works with Filament v2. Migrate to Filament v3’s native multi-tenant support if upgrading.

2. Middleware Order: Ensure guard middleware runs after Filament’s auth middleware to avoid conflicts:

   // config/filament.php
   'middleware' => [
       \Filament\Panel::class,
       'web',
       \Iotronlab\FilamentMultiGuard\Middleware\GuardMiddleware::class, // Must come last
   ],
   

3. Resource/Policy Conflicts: Avoid naming collisions (e.g., posts resource in both admin and client guards). Use namespacing:

   'resources' => [
       'admin/posts',
       'client/posts',
   ],
   

4. Caching Issues: Clear Filament’s route cache after adding/removing guards:

   php artisan filament:cache-reset
   

Debugging

• Check Guard Context: Log the current guard in middleware:

  \Log::info('Current guard:', ['guard' => FilamentMultiGuard::guard()]);
  

• Route Debugging: Use php artisan route:list to verify guard-specific routes are registered.

Extension Points

1. Custom Guard Logic: Override the Guard class to add logic (e.g., tenant resolution):

   FilamentMultiGuard::macro('resolveTenant', function () {
       return Tenant::findOrFail(request('tenant'));
   });
   

2. Dynamic Guard Registration: Register guards programmatically in a service provider:

   FilamentMultiGuard::registerGuard('tenant', [
       'guard' => 'web',
       'middleware' => ['web', 'tenant'],
   ]);
   

3. Fallback Guards: Configure fallback guards for unmatched routes:

   'fallback_guard' => 'admin',
   

4. Guard-Specific Views: Override Filament views per guard using view.guard namespace:

   // resources/views/vendor/filament/guard/admin/partials/header.blade.php