Download the PHP package chuimi/filament-impersonation without Composer

Filament Impersonation

Controlled and audited user impersonation plugin for Laravel and Filament applications.

Allows an authorized operator to temporarily authenticate as another user while preserving a mandatory audit trail of the real operator.

Requirements

• PHP >= 8.2
• Laravel >= 12
• Filament >= 5
• spatie/laravel-activitylog
• spatie/laravel-permission (optional — required only for role/permission-based authorization)

Installation

Publish the configuration file:

Minimal setup

Installing the package alone is not enough for the impersonation action to appear in the UI. The plugin must be registered in a panel and the action must be added to a resource explicitly.

The package does not auto-register in any Filament panel or inject the action into any resource. This is intentional — applications may have multiple panels and different authorization policies per context.

1. Install and publish config

2. Set required configuration

In config/filament-impersonation.php, configure at minimum guard, user_model, an authorization rule (operator_roles or can_impersonate), and protected_roles.

3. Register the plugin in your panel — required for the banner

4. Add the action to the users table — required for the trigger

5. Clear caches

For a detailed checklist including config examples, redirects, and manual verification steps see Integration guide — Minimal setup checklist.

Usage

Register the plugin in a Filament panel

Once registered, the impersonation banner is shown automatically at the bottom of the panel while any impersonation session is active.

Add the action to a resource or page

The action is hidden automatically when the current user cannot impersonate the record. It must be added manually to the resources or pages where impersonation should be available.

Enrich activity logs with impersonation context (opt-in)

Apply the trait to any Eloquent model that uses spatie/laravel-activitylog and should include impersonation context in its activity entries:

This trait is opt-in and must be added manually per model. The package does not apply impersonation context globally to all activity logs.

Security notes

• impersonation.started is mandatory and recorded before the user switch. If it cannot be written, impersonation does not start.
• Manual logout during impersonation does not restore the original operator.
• The stop route uses POST with CSRF protection via the web middleware stack. The banner renders the CSRF token automatically.

Full details in docs/SECURITY.md.

Documentation

License

MIT — see LICENSE.