Filament Impersonate Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require stechstudio/filament-impersonate
   

2. Add to UserResource table actions (e.g., app/Filament/Resources/UserResource.php):

   use STS\FilamentImpersonate\Actions\Impersonate;
   
   public static function table(Table $table): Table
   {
       return $table
           ->columns([...])
           ->actions([
               Impersonate::make(),
           ]);
   }
   

3. Add to EditUser header actions (e.g., app/Filament/Resources/UserResource/Pages/EditUser.php):

   protected function getHeaderActions(): array
   {
       return [
           Impersonate::make()->record($this->getRecord()),
       ];
   }
   

4. Add the impersonation banner (if using non-Filament layouts):

   <x-impersonate::banner />
   

First Use Case

Debugging as a user:

• Navigate to the UserResource table.
• Click the impersonate icon next to a user.
• Verify the impersonation banner appears and you’re logged in as the target user.

Implementation Patterns

Core Workflows

1. Table Actions:

   • Use Impersonate::make() in table() for list views.
   • Customize with guard() or redirectTo():

     Impersonate::make()
         ->guard('custom-guard')
         ->redirectTo(route('dashboard'));
     

2. Page Actions:

   • Use Impersonate::make()->record($record) in getHeaderActions() for edit/create forms.
   • Example:

     Impersonate::make()->record($this->record)->withoutSpa();
     

3. Programmatic Impersonation:

   • Use the facade for logic outside Filament:

     if (Impersonation::isImpersonating()) {
         Impersonation::leave();
     }
     

4. Authorization:

   • Add canImpersonate() to the impersonator model (e.g., User):

     public function canImpersonate(): bool
     {
         return $this->is_admin;
     }
     

   • Add canBeImpersonated() to the target model:

     public function canBeImpersonated(): bool
     {
         return !$this->is_super_admin;
     }
     

Integration Tips

• SPA Mode: Use ->withoutSpa() if redirecting to non-Livewire pages.
• Events: Listen for EnterImpersonation/LeaveImpersonation:

  use STS\FilamentImpersonate\Events\EnterImpersonation;
  
  EnterImpersonation::dispatch($impersonator, $impersonated);
  

• Translations: Supports 16+ languages (e.g., zh_CN, ms). Override via config/filament-impersonate.php.

Gotchas and Tips

Pitfalls

1. 403 Errors in List Views:

   • If using InteractsWithPageTable, add a guard clause to UserPolicy::viewAny():

     public function viewAny(User $user): bool
     {
         if (Impersonation::isImpersonating()) return true;
         return $user->canAccessFilament();
     }
     

   • Why: Livewire re-renders before redirect, triggering policy checks.

2. Soft-Deleted Users:

   • By default, impersonation blocks soft-deleted users. Override in .env:

     FILAMENT_IMPERSONATE_ALLOW_SOFT_DELETED=true
     

3. Octane Compatibility:

   • Uses native session manipulation (no custom guards). Test under Swoole/FrankenPHP.

4. Missing Record in Page Actions:

   • Always pass $this->getRecord() to Impersonate::make() in EditUser.

Debugging

• Failed Impersonation:

  • Check Filament notifications and Laravel logs (Log::warning).
  • Verify guards match (guard() parameter or panel config).

• Banner Not Showing:

  • Ensure <x-impersonate::banner /> is in non-Filament layouts.
  • Clear cached views (php artisan view:clear).

Extension Points

1. Custom Banner:

   • Override the blade component (resources/views/vendor/filament-impersonate/banner.blade.php).
   • Customize style/display name:

     <x-impersonate::banner style="light" :display="auth()->user()->email" />
     

2. Custom Events:

   • Extend EnterImpersonation/LeaveImpersonation for analytics or logging.

3. Guard-Specific Logic:

   • Use guard() to handle multi-guard apps:

     Impersonate::make()->guard('api');
     

Pro Tips

• Test Impersonation:
  • Use Impersonation::enter($from, $to) in tests:

    $this->actingAs($admin)
         ->call('POST', '/impersonate', ['user_id' => $user->id]);
    

• Audit Logs:
  • Log impersonation events via LeaveImpersonation listeners.
• Performance:
  • Cache canImpersonate()/canBeImpersonated() results if models are large.