Filament Impersonate

https://github.com/stechstudio/filament-impersonate
Admin
A Filament plugin that allows administrators to easily impersonate users, providing a seamless way...
Tokens:56,677
Snippets:518
Trust Score:7.6
Update:1 week ago
Show doc for...
Tokens:
Raw
### Customized action.php translation file

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Example content for resources/lang/en/action.php after publishing translations. Customizes the 'failed' message to 'Could not start impersonation. Check your permissions.'

```php
return [
    'label' => 'Impersonate',
    'failed' => 'Could not start impersonation. Check your permissions.',
];
```

--------------------------------

### enter(Authenticatable $from, Authenticatable $to, ?string $guardName = null): bool

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Starts impersonation of the target user by the source user. Returns true on success, false on failure.

```APIDOC
## enter(Authenticatable $from, Authenticatable $to, ?string $guardName = null): bool

### Description
Starts impersonation of the target user by the source user.

### Method
enter

### Parameters
- **$from** (Authenticatable) - Required - The user who is impersonating.
- **$to** (Authenticatable) - Required - The user to be impersonated.
- **$guardName** (?string) - Optional - The guard name to use.

### Return Value
- **bool** - True if impersonation started successfully, false otherwise.

### Example
```php
use STS\FilamentImpersonate\Facades\Impersonation;
use App\Models\User;

$admin = auth()->user();
$customer = User::find(42);

if (Impersonation::enter($admin, $customer)) {
    // Now auth()->user() returns $customer
    return redirect('/customer/dashboard');
} else {
    return back()->with('error', 'Impersonation failed');
}
```
```

--------------------------------

### Install with Composer

Source: https://github.com/stechstudio/filament-impersonate/blob/master/README.md

Install the package via Composer.

```bash
composer require stechstudio/filament-impersonate
```

--------------------------------

### Custom Routes and Controllers for Impersonation

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Defines two routes: one to start impersonation via POST /admin/impersonate and another to leave impersonation via GET /leave-impersonation. The first checks permissions and calls enter(), the second calls leave() and redirects.

```php
use STS\FilamentImpersonate\Facades\Impersonation;
use App\Models\User;

Route::post('/admin/impersonate', function () {
    $adminUser = auth()->user();
    $targetUser = User::find(request('user_id'));

    if (!$targetUser || !$adminUser->canImpersonate()) {
        return response('Forbidden', 403);
    }

    if (Impersonation::enter($adminUser, $targetUser)) {
        return redirect(route('dashboard'));
    }

    return back()->with('error', 'Failed to impersonate');
})->middleware('auth', 'admin');

Route::get('/leave-impersonation', function () {
    if (!Impersonation::isImpersonating()) {
        return redirect('/');
    }

    Impersonation::leave();
    return redirect('/admin');
})->name('leave-impersonation');
```

--------------------------------

### Programmatic Impersonation with Impersonation::enter()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Starts impersonation by passing the admin user and target customer to enter(). On success, auth()->user() returns the customer; otherwise, it returns back with an error.

```php
use STS\FilamentImpersonate\Facades\Impersonation;
use App\Models\User;

$admin = auth()->user();
$customer = User::find(42);

// Start impersonation
if (Impersonation::enter($admin, $customer)) {
    // Now auth()->user() returns $customer
    return redirect('/customer/dashboard');
} else {
    // Handle failure
    return back()->with('error', 'Impersonation failed');
}
```

--------------------------------

### Get Impersonator Information with getImpersonatorId() and getImpersonator()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Retrieves the impersonator's ID and the impersonator model instance. The example then echoes the impersonator's name.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

$impersonatorId = Impersonation::getImpersonatorId();
$impersonator = Impersonation::getImpersonator();

echo "Impersonating as: " . $impersonator->name;
```

--------------------------------

### canImpersonate() example implementation

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Example implementation of canImpersonate() that returns the is_admin property. If false, the impersonation action is hidden.

```php
class User extends Model
{
    public function canImpersonate(): bool
    {
        // If this returns false, the action is hidden
        return $this->is_admin;
    }
}
```

--------------------------------

### canBeImpersonated() example implementation

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Example implementation of canBeImpersonated() that prevents impersonating service accounts by returning false for them.

```php
class User extends Model
{
    public function canBeImpersonated(): bool
    {
        // Prevent impersonating service accounts
        if ($this->is_service_account) {
            return false;
        }
        return true;
    }
}
```

--------------------------------

### getGuard() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Example of calling getGuard() after setting a guard via the guard() method. Outputs 'admin'.

```php
$action = Impersonate::make()->guard('admin');
echo $action->getGuard();  // 'admin'
```

--------------------------------

### getBackTo() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Example of calling getBackTo() after setting a back URL via the backTo() method. Outputs '/users'.

```php
$action = Impersonate::make()->backTo('/users');
echo $action->getBackTo();  // '/users'
```

--------------------------------

### ImpersonateManager::enter()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Starts an impersonation session from one authenticatable user to another. Returns false on failure instead of throwing an exception.

```APIDOC
## ImpersonateManager::enter()

### Description
Starts an impersonation session from one authenticatable user to another. Returns false on failure instead of throwing an exception.

### Method
`enter`

### Signature
```php
public function enter(Authenticatable $from, Authenticatable $to, ?string $guardName = null): bool
```

### Parameters
- **$from** (Authenticatable) - Required - The user to impersonate from.
- **$to** (Authenticatable) - Required - The user to impersonate.
- **$guardName** (?string) - Optional - The guard name to use.

### Return Value
- **bool** - Returns `true` on success, `false` on failure.

### Failure Conditions
- Any exception occurs during impersonation setup
- Session manipulation fails
- Auth guard is not session-based

### Recovery Example
```php
if (!Impersonation::enter($admin, $user, $guardName)) {
    Log::error('Impersonation failed for user', ['user_id' => $user->id]);
    return back()->with('error', 'Failed to start impersonation');
}
```
```

--------------------------------

### clear(): void

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Clears any impersonation state. Returns nothing.

```APIDOC
## clear(): void

### Description
Clears any impersonation state.

### Method
clear

### Parameters
None

### Return Value
- **void** - No return value.
```

--------------------------------

### Send notifications on impersonation start

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Listens to EnterImpersonation to send database notifications to both the impersonator and the impersonated user, informing them that impersonation has started.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;

Event::listen(EnterImpersonation::class, function (EnterImpersonation $event) {
    // Notify the impersonator
    Notification::make()
        ->title('Impersonation started')
        ->body("You are now impersonating {$event->impersonated->name}")
        ->sendToDatabase($event->impersonator);

    // Alert the impersonated user
    Notification::make()
        ->title('Your account is being accessed')
        ->body("Admin {$event->impersonator->name} is accessing your account")
        ->sendToDatabase($event->impersonated);
});
```

--------------------------------

### Multi-Guard Authentication Configuration Example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/FilamentImpersonateServiceProvider.md

Example configuration for multiple authentication guards in config/auth.php. The service provider supports multiple guards, ensuring impersonation in one guard does not affect others and password hash clearing is specific to affected guards.

```php
// config/auth.php
'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'admin' => [
        'driver' => 'session',
        'provider' => 'admins',
    ],
    'storefront' => [
        'driver' => 'session',
        'provider' => 'customers',
    ],
]
```

--------------------------------

### getRedirectTo() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Example of calling getRedirectTo() after setting a redirect URL via the redirectTo() method. Outputs '/app/dashboard'.

```php
$action = Impersonate::make()->redirectTo('/app/dashboard');
echo $action->getRedirectTo();  // '/app/dashboard'
```

--------------------------------

### getRedirectSpa() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Example of calling getRedirectSpa() after setting the SPA setting via the spa() method. Outputs false.

```php
$action = Impersonate::make()->spa(false);
echo $action->getRedirectSpa();  // false
```

--------------------------------

### Example of throwing and correct guard usage

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Shows that using auth()->guard('api') (TokenGuard) throws the RuntimeException, while auth()->guard('web') (SessionGuard) is correct.

```php
// This throws:
auth()->guard('api')  // TokenGuard, not SessionGuard

// Correct:
auth()->guard('web')  // SessionGuard
```

--------------------------------

### Multi-guard impersonation scenario

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Example scenario showing that impersonation continues unaffected when an unrelated guard logs in.

```php
// Scenario: Admin impersonating a user (guard: 'web')
// Customer logs in on storefront (guard: 'storefront')
// Result: Impersonation continues unaffected
```

--------------------------------

### Prefixed Leave Route Example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/endpoints.md

Example of the leave route when a route prefix is configured.

```http
GET /api/admin/filament-impersonate/leave
```

--------------------------------

### leave(): bool

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Ends the current impersonation session. Returns true on success, false on failure.

```APIDOC
## leave(): bool

### Description
Ends the current impersonation session.

### Method
leave

### Parameters
None

### Return Value
- **bool** - True if impersonation ended successfully, false otherwise.

### Example
```php
use STS\FilamentImpersonate\Facades\Impersonation;

if (Impersonation::isImpersonating()) {
    if (Impersonation::leave()) {
        return redirect('/admin');
    }
}
```
```

--------------------------------

### ImpersonateManager::enter() method signature

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Returns false on failure instead of throwing. Use this method to start impersonation; check the boolean return value to handle failures.

```php
public function enter(Authenticatable $from, Authenticatable $to, ?string $guardName = null): bool
```

--------------------------------

### Example: User model authorization methods

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Example methods on the User model that the action checks before allowing impersonation. canImpersonate() returns true for admins, canBeImpersonated() returns false for internal emails.

```php
// In your User model
class User extends Model
{
    public function canImpersonate()
    {
        return $this->is_admin;
    }

    public function canBeImpersonated()
    {
        return !str_ends_with($this->email, '@internal.com');
    }
}

// The action will check these before allowing impersonation
```

--------------------------------

### backTo() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Sets the return URL to a named route. The closure receives no parameters.

```php
Impersonate::make()
    ->backTo(route('filament.admin.resources.users.index'))
```

--------------------------------

### Listening to EnterImpersonation event

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Example listener for the EnterImpersonation event that logs impersonation details and queues a notification email.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Log;

Event::listen(EnterImpersonation::class, function (EnterImpersonation $event) {
    Log::channel('security')->info('Impersonation started', [
        'impersonator_id' => $event->impersonator->id,
        'impersonator_email' => $event->impersonator->email,
        'impersonated_id' => $event->impersonated->id,
        'impersonated_email' => $event->impersonated->email,
        'timestamp' => now(),
        'ip' => request()->ip(),
    ]);

    // Send notification email
    Mail::to($event->impersonator->email)
        ->queue(new ImpersonationStartedNotification($event->impersonated));
});
```

--------------------------------

### ImpersonateManager::enter()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/INDEX.md

Starts impersonating a user. This method is part of the ImpersonateManager component.

```APIDOC
## ImpersonateManager::enter()

### Description
Starts impersonating a user.

### Method
`enter()`

### Parameters
None

### Returns
Void or result of entering impersonation.
```

--------------------------------

### Configure route_prefix in config file

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/configuration.md

Config file entry for route_prefix, reads from FILAMENT_IMPERSONATE_ROUTE_PREFIX with default null. With prefix 'admin/api', the leave route becomes GET /admin/api/filament-impersonate/leave; without prefix, GET /filament-impersonate/leave.

```php
// config/filament-impersonate.php
'route_prefix' => env('FILAMENT_IMPERSONATE_ROUTE_PREFIX', null),
```

--------------------------------

### Example: calling impersonate()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Shows how to call the impersonate method, usually done automatically by Filament when the action is clicked. The variable $success receives the return value.

```php
// Usually called automatically by Filament when action is clicked
$success = $action->impersonate($userToImpersonate);
```

--------------------------------

### Use Impersonation facade with type hints

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Imports the Impersonation facade for IDE autocomplete and type checking. The facade provides PHPDoc type hints for all delegated methods, enabling accurate autocomplete in modern IDEs.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

// IDE will provide autocomplete for all methods
Impersonation::isImpersonating();
```

--------------------------------

### Leave Impersonation with Impersonation::leave()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Checks if impersonating and then calls leave() to end the impersonation. Redirects to '/admin' on success.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

if (Impersonation::isImpersonating()) {
    if (Impersonation::leave()) {
        return redirect('/admin');
    }
}
```

--------------------------------

### Config File (config/filament-impersonate.php) Example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/configuration.md

PHP configuration file for Filament Impersonate, mapping environment variables to config keys. Includes banner styles for light and dark themes. Publish this file (optional) to customize settings.

```php
<?php
return [
    'redirect_to' => env('FILAMENT_IMPERSONATE_REDIRECT', '/'),

    'leave_middleware' => env('FILAMENT_IMPERSONATE_LEAVE_MIDDLEWARE', 'web'),

    'route_prefix' => env('FILAMENT_IMPERSONATE_ROUTE_PREFIX', null),

    'allow_soft_deleted' => env('FILAMENT_IMPERSONATE_ALLOW_SOFT_DELETED', false),

    'banner' => [
        'render_hook' => env('FILAMENT_IMPERSONATE_BANNER_RENDER_HOOK', 'panels::body.start'),
        'style' => env('FILAMENT_IMPERSONATE_BANNER_STYLE', 'dark'),
        'fixed' => env('FILAMENT_IMPERSONATE_BANNER_FIXED', true),
        'position' => env('FILAMENT_IMPERSONATE_BANNER_POSITION', 'top'),
        'styles' => [
            'light' => [
                'text' => '#1f2937',
                'background' => '#f3f4f6',
                'border' => '#e8eaec',
            ],
            'dark' => [
                'text' => '#f3f4f6',
                'background' => '#1f2937',
                'border' => '#374151',
            ],
        ]
    ],
];
```

--------------------------------

### Event Listening for EnterImpersonation

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Listens to the EnterImpersonation event and logs impersonation details to the security channel, including impersonator and impersonated emails and the request IP.

```php
use STS\FilamentImpersonate\Facades\Impersonation;
use STS\FilamentImpersonate\Events\EnterImpersonation;

Event::listen(EnterImpersonation::class, function (EnterImpersonation $event) {
    Log::channel('security')->info('Impersonation started', [
        'impersonator' => $event->impersonator->email,
        'impersonated' => $event->impersonated->email,
        'ip' => request()->ip(),
    ]);
});
```

--------------------------------

### Multi-guard impersonation example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/README.md

Demonstrates that impersonation on one guard does not affect logins on other guards. The storefront login does not clear the impersonation on the 'web' guard.

```php
// Admin impersonating user on 'web' guard
Impersonation::enter($admin, $user, 'web');
```

```php
// Unrelated storefront login on 'storefront' guard
// does NOT clear the impersonation on 'web'
auth()->guard('storefront')->login($customer);
```

--------------------------------

### Custom Middleware for Logging Impersonation Activity

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Middleware that logs requests from impersonated users, including the impersonator ID, impersonated user ID, and request path.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

class LogImpersonationActivity
{
    public function handle($request, $next)
    {
        if (Impersonation::isImpersonating()) {
            \Log::info('Request from impersonated user', [
                'impersonator_id' => Impersonation::getImpersonatorId(),
                'impersonated_user' => auth()->user()->id,
                'path' => $request->path(),
            ]);
        }

        return $next($request);
    }
}
```

--------------------------------

### Queue listener for EnterImpersonation with ShouldQueue

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Example of a queued event listener class that implements ShouldQueue. Because the event uses SerializesModels, the listener runs asynchronously.

```php
// In your event listener class
class LogImpersonation implements ShouldQueue
{
    public function handle(EnterImpersonation $event)
    {
        // Runs asynchronously
    }
}
```

--------------------------------

### Style prop examples

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Banner-Component.md

Shows how to set the banner's color scheme using the style prop. Use 'light' for light styling and 'auto' for dark mode support.

```blade
<!-- Use light styling -->
<x-impersonate::banner style='light'/>
```

```blade
<!-- Use auto dark mode -->
<x-impersonate::banner style='auto'/>
```

--------------------------------

### Closure example for guard and redirectTo

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/types.md

Configures impersonation with closures that are evaluated at action execution time via Filament's evaluate() method.

```php
Impersonate::make()
    ->guard(fn () => auth()->getDefaultDriver())
    ->redirectTo(fn () => route('dashboard'))
```

--------------------------------

### getImpersonator(): Authenticatable|null

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Retrieves the Authenticatable instance of the user who is currently impersonating another user. Returns null if not impersonating.

```APIDOC
## getImpersonator(): Authenticatable|null

### Description
Retrieves the Authenticatable instance of the user who is currently impersonating another user.

### Method
getImpersonator

### Parameters
None

### Return Value
- **Authenticatable|null** - The impersonator's Authenticatable instance, or null if not impersonating.

### Example
```php
use STS\FilamentImpersonate\Facades\Impersonation;

$impersonator = Impersonation::getImpersonator();
echo "Impersonating as: " . $impersonator->name;
```
```

--------------------------------

### leave() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/ImpersonateManager.md

Checks if impersonation is active and calls leave() to end it. After success, auth()->user() returns the original impersonator.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

if (Impersonation::isImpersonating()) {
    if (Impersonation::leave()) {
        // Successfully left impersonation
        // auth()->user() now returns the original impersonator
    }
}
```

--------------------------------

### Configure logging channels in config/logging.php

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Sets up the default log channel as a stack of 'single' and 'slack' channels. All impersonation failures are written to the configured log channel.

```php
// config/logging.php
'channels' => [
    'default' => env('LOG_CHANNEL', 'stack'),
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single', 'slack'],
    ],
    'single' => [
        'driver' => 'single',
        'path' => storage_path('logs/laravel.log'),
        'level' => 'debug',
    ],
]
```

--------------------------------

### isImpersonating(): bool

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Checks whether the current session is impersonating another user. Returns true if impersonation is active, false otherwise.

```APIDOC
## isImpersonating(): bool

### Description
Checks whether the current session is impersonating another user.

### Method
isImpersonating

### Parameters
None

### Return Value
- **bool** - True if impersonation is active, false otherwise.

### Example
```php
use STS\FilamentImpersonate\Facades\Impersonation;

if (Impersonation::isImpersonating()) {
    echo "Currently impersonating a user";
}
```
```

--------------------------------

### User Model Implementing Authenticatable

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/types.md

Example of a typical User model implementing the Authenticatable interface. Laravel's default User model already implements this.

```php
use Illuminate\Contracts\Auth\Authenticatable;

class User extends Model implements Authenticatable
{
    // ...
}
```

--------------------------------

### clear() usage example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/ImpersonateManager.md

Calls clear() to remove all impersonation session data. Does not fire events or restore the impersonator's session.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

Impersonation::clear();
// All impersonation session data is now removed
```

--------------------------------

### configurePackage() method

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/FilamentImpersonateServiceProvider.md

Configures the package during discovery: registers the web route, config file, translations, and views.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name(static::$name)
        ->hasRoute('web')
        ->hasConfigFile()
        ->hasTranslations()
        ->hasViews();
}
```

--------------------------------

### Trigger custom behavior on impersonation start

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Listens to EnterImpersonation to cache an impersonation flag for 8 hours and activate a feature flag to disable password changes during impersonation.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;

Event::listen(EnterImpersonation::class, function (EnterImpersonation $event) {
    // Disable sensitive features during impersonation
    cache()->put(
        "impersonating_user:{$event->impersonated->id}",
        true,
        now()->addHours(8)
    );

    // Disable password changes during impersonation
    feature('disable_password_change_when_impersonated')->activate();
});
```

--------------------------------

### Listen to EnterImpersonation event for custom logging

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Registers a listener for the STS\FilamentImpersonate\Events\EnterImpersonation event, which fires when impersonation succeeds. The event provides impersonator and impersonated user objects; this example logs their IDs.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;

Event::listen(EnterImpersonation::class, function (EnterImpersonation $event) {
    Log::info('User impersonated', [
        'impersonator' => $event->impersonator->id,
        'impersonated' => $event->impersonated->id,
    ]);
});
```

--------------------------------

### Check if Impersonating with Impersonation::isImpersonating()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Use this snippet to check whether the current session is impersonating a user. It calls the facade's isImpersonating() method and echoes a message if true.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

if (Impersonation::isImpersonating()) {
    echo "Currently impersonating a user";
}
```

--------------------------------

### bootingPackage() - Register banner render hook and load views

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/FilamentImpersonateServiceProvider.md

Called after all providers are registered. Registers a render hook for the impersonation banner (default hook: 'panels::body.start') and loads views from the 'impersonate' namespace. The banner visibility is determined by the component itself.

```php
public function bootingPackage(): void
{
    FilamentView::registerRenderHook(
        config('filament-impersonate.banner.render_hook', 'panels::body.start'),
        static fn (): string => Blade::render('<x-filament-impersonate::banner/>')
    );

    $this->loadViewsFrom(__DIR__.'/../resources/views', 'impersonate');
}
```

--------------------------------

### Configure leave_middleware in config file

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/configuration.md

Config file entry for leave_middleware, reads from FILAMENT_IMPERSONATE_LEAVE_MIDDLEWARE with default 'web'. The middleware stack must include session middleware because the leave route uses GET and session-based checks.

```php
// config/filament-impersonate.php
'leave_middleware' => env('FILAMENT_IMPERSONATE_LEAVE_MIDDLEWARE', 'web'),
```

--------------------------------

### Resolve ImpersonateManager directly from container

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Shows two ways to resolve the ImpersonateManager directly from the Laravel service container: using the class name or the 'impersonate' alias. Requires importing the ImpersonateManager class.

```php
use STS\FilamentImpersonate\ImpersonateManager;

$manager = app(ImpersonateManager::class);
// or
$manager = app('impersonate');
```

--------------------------------

### ImpersonateManager Methods

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/SUMMARY.txt

Core impersonation session manager with 8 public methods for starting, stopping, and managing impersonation sessions. These methods are called programmatically to control impersonation.

```APIDOC
## ImpersonateManager Methods

### Description
Core impersonation session manager with 8 public methods for starting, stopping, and managing impersonation sessions. These methods are called programmatically to control impersonation.

### Methods
- **start()** - Starts an impersonation session.
- **stop()** - Stops the current impersonation session.
- **isImpersonating()** - Checks if an impersonation session is active.
- **getImpersonator()** - Returns the impersonator user.
- **getImpersonated()** - Returns the impersonated user.
- **getSessionData()** - Returns the session data structure.
- **setSessionData()** - Sets the session data.
- **clearSession()** - Clears the impersonation session.

### Usage Example
```php
Impersonate::start($impersonator, $impersonated);
```
```

--------------------------------

### Authorization Policy Integration with Impersonation::isImpersonating()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

In a UserPolicy, allows impersonated users to view the users list by returning true when impersonating, otherwise checks the is_admin flag.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

class UserPolicy
{
    public function viewAny(User $user): bool
    {
        // Allow impersonated users to view users list
        if (Impersonation::isImpersonating()) {
            return true;
        }

        return $user->is_admin;
    }
}
```

--------------------------------

### Register ImpersonateManager as scoped service and alias

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Registers the ImpersonateManager as a scoped service and aliases it to 'impersonate' in the service container. Typically placed in a service provider's register method.

```php
$this->app->scoped(ImpersonateManager::class);
$this->app->alias(ImpersonateManager::class, 'impersonate');
```

--------------------------------

### Authorization in Model Methods with Impersonation::isImpersonating()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Prevents impersonating premium users or service accounts by returning false when impersonating, otherwise checks the is_service_account and is_premium flags.

```php
use STS\FilamentImpersonate\Facades\Impersonation;

class User extends Model
{
    public function canBeImpersonated(): bool
    {
        // Prevent impersonating premium users or service accounts
        if (Impersonation::isImpersonating()) {
            return false;
        }

        return !$this->is_service_account && !$this->is_premium;
    }
}
```

--------------------------------

### Log Impersonation Events

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/README.md

Listens to EnterImpersonation and LeaveImpersonation events to log impersonation start and end. Uses the security log channel and includes impersonator and impersonated emails.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;
use STS\FilamentImpersonate\Events\LeaveImpersonation;

Event::listen(EnterImpersonation::class, function ($event) {
    Log::channel('security')->info('Impersonation started', [
        'impersonator' => $event->impersonator->email,
        'impersonated' => $event->impersonated->email,
    ]);
});

Event::listen(LeaveImpersonation::class, function ($event) {
    Log::channel('security')->info('Impersonation ended', [
        'impersonator' => $event->impersonator->email,
        'impersonated' => $event->impersonated?->email,
    ]);
});
```

--------------------------------

### impersonateRecord() implicit table action example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

In table actions, the current table row's record is used automatically. This example shows the fluent call without explicit record specification.

```php
Impersonate::make()
// Automatically uses the current table row's User record
```

--------------------------------

### Audit logging listener for impersonation events

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Defines an ImpersonationAuditListener class with handleEnter and handleLeave methods that create AuditLog entries for impersonation start and end, capturing impersonator/impersonated IDs, IP address, and user agent.

```php
use STS\FilamentImpersonate\Events\EnterImpersonation;
use STS\FilamentImpersonate\Events\LeaveImpersonation;

class ImpersonationAuditListener
{
    public function handleEnter(EnterImpersonation $event)
    {
        AuditLog::create([
            'type' => 'impersonation.start',
            'impersonator_id' => $event->impersonator->id,
            'impersonated_id' => $event->impersonated->id,
            'ip_address' => request()->ip(),
            'user_agent' => request()->userAgent(),
        ]);
    }

    public function handleLeave(LeaveImpersonation $event)
    {
        AuditLog::create([
            'type' => 'impersonation.end',
            'impersonator_id' => $event->impersonator->id,
            'impersonated_id' => $event->impersonated?->id,
            'ip_address' => request()->ip(),
        ]);
    }
}
```

--------------------------------

### Safe Leave Link with CSRF Protection

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/endpoints.md

A GET request to the leave route is safe without a CSRF token because the route is protected by Laravel's CSRF middleware but only accessible via direct GET requests within the same origin.

```html
<a href="{{ route('filament-impersonate.leave') }}">Leave</a>
```

--------------------------------

### registeringPackage() method

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/FilamentImpersonateServiceProvider.md

Registers the ImpersonateManager as a scoped service with alias 'impersonate', attaches event listeners for impersonation and auth events, and registers the icon.

```php
public function registeringPackage(): void
{
    $this->app->scoped(ImpersonateManager::class);
    $this->app->alias(ImpersonateManager::class, 'impersonate');

    Event::listen(EnterImpersonation::class, fn () => $this->clearAuthHashes());
    Event::listen(LeaveImpersonation::class, fn () => $this->clearAuthHashes());
    Event::listen(Login::class, fn (Login $event) => $this->clearImpersonationForGuard($event->guard));
    Event::listen(Logout::class, fn (Logout $event) => $this->clearImpersonationForGuard($event->guard));

    $this->registerIcon();
}
```

--------------------------------

### getImpersonatorGuardName(): string|null

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Retrieves the name of the guard used by the impersonator. Returns null if not impersonating.

```APIDOC
## getImpersonatorGuardName(): string|null

### Description
Retrieves the name of the guard used by the impersonator.

### Method
getImpersonatorGuardName

### Parameters
None

### Return Value
- **string|null** - The guard name, or null if not impersonating.
```

--------------------------------

### Configure Impersonate action with guard, redirect, back, and SPA options

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Shows advanced configuration for the Impersonate action: setting the guard, redirect URL, back URL, and SPA behavior. The redirectTo and spa methods accept closures; backTo uses a route helper.

```php
Impersonate::make()
    ->guard('web')
    ->redirectTo(fn () => route('dashboard'))
    ->backTo(route('filament.admin.resources.users.index'))
    ->spa(fn () => request()->expectsJson() === false)
```

--------------------------------

### getImpersonatorGuardUsingName(): string|null

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Retrieves the guard name using the impersonator's guard. Returns null if not impersonating.

```APIDOC
## getImpersonatorGuardUsingName(): string|null

### Description
Retrieves the guard name using the impersonator's guard.

### Method
getImpersonatorGuardUsingName

### Parameters
None

### Return Value
- **string|null** - The guard name, or null if not impersonating.
```

--------------------------------

### Session-based guard configuration (correct vs. token guard)

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/README.md

Shows the required 'session' driver for impersonation and contrasts it with an unsupported token-based guard. The token guard will not work because impersonation relies on session storage.

```php
// ✓ Correct
'guards' => [
    'web' => ['driver' => 'session', 'provider' => 'users'],
]
```

```php
// ✗ Won't work
'guards' => [
    'api' => ['driver' => 'token', 'provider' => 'users'],
]
```

--------------------------------

### getImpersonatorId(): int|string|null

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonation-Facade.md

Retrieves the ID of the user who is currently impersonating another user. Returns null if not impersonating.

```APIDOC
## getImpersonatorId(): int|string|null

### Description
Retrieves the ID of the user who is currently impersonating another user.

### Method
getImpersonatorId

### Parameters
None

### Return Value
- **int|string|null** - The impersonator's ID, or null if not impersonating.

### Example
```php
use STS\FilamentImpersonate\Facades\Impersonation;

$impersonatorId = Impersonation::getImpersonatorId();
```
```

--------------------------------

### backTo() method signature

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Defines the URL to return to when leaving impersonation. Returns a fluent static instance. Falls back to referrer or Filament panel URL if not specified.

```php
public function backTo(Closure|string $backTo): static
```

--------------------------------

### Position prop example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Banner-Component.md

Set position to 'bottom' to display the banner at the bottom of the page instead of the default top.

```blade
<!-- Banner at bottom -->
<x-impersonate::banner position='bottom'/>
```

--------------------------------

### Authenticatable Usage in Package - enter() Method

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/types.md

Shows how the package's enter method accepts Authenticatable instances for the from and to users, with an optional guard name.

```php
public function enter(
    Authenticatable $from,
    Authenticatable $to,
    ?string $guardName = null
): bool
```

--------------------------------

### impersonateRecord() relationship access example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Uses a closure to access a related user, such as a customer relationship on the current record.

```php
// Accessing a relationship
Impersonate::make()
    ->impersonateRecord(fn($record) => $record->customer)
```

--------------------------------

### Fixed prop example

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Banner-Component.md

Set fixed to false to make the banner scroll with the page instead of staying fixed to the viewport.

```blade
<!-- Banner scrolls with page -->
<x-impersonate::banner :fixed='false'/>
```

--------------------------------

### Configure guard and redirectTo for Impersonate action

Source: https://github.com/stechstudio/filament-impersonate/blob/master/README.md

Define a custom guard and redirect route for the Impersonate action.

```php
Impersonate::make()
    ->guard('another-guard')
    ->redirectTo(route('some.other.route'));
```

--------------------------------

### withSpa()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Convenience method to enable SPA navigation. Equivalent to calling spa(true).

```APIDOC
## withSpa()

### Description
Convenience method to enable SPA navigation.

### Method
`public function withSpa(): static`

### Parameters
None

### Return Type
`static` (fluent)

### Behavior
- Equivalent to calling `spa(true)`
- Useful as a readable alternative to `spa(true)`

### Example
```php
Impersonate::make()
    ->withSpa()
```
```

--------------------------------

### Get impersonator ID with Impersonation::getImpersonatorId()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/ImpersonateManager.md

Retrieves the authentication identifier of the impersonator, or null if no impersonation is active. Returns int|string|null.

```php
public function getImpersonatorId(): int|string|null
```

```php
use STS\FilamentImpersonate\Facades\Impersonation;

$impersonatorId = Impersonation::getImpersonatorId();
// e.g., 42
```

--------------------------------

### Listen to EnterImpersonation with Event::listen()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Events.md

Shows the basic pattern for listening to the EnterImpersonation event using Laravel's Event::listen() method. The callback receives the event instance.

```php
Event::listen(EnterImpersonation::class, function ($event) {
    // handle event
});
```

--------------------------------

### Opt out of SPA navigation for Impersonate action

Source: https://github.com/stechstudio/filament-impersonate/blob/master/README.md

Use withoutSpa() to force a full page load when the redirect target is not a Livewire-aware page.

```php
Impersonate::make()
    ->redirectTo(route('some.other.route'))
    ->withoutSpa();
```

--------------------------------

### withSpa() - Enable SPA navigation

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Convenience method to enable SPA navigation. Equivalent to calling spa(true). Useful as a readable alternative to spa(true).

```php
public function withSpa(): static
```

```php
Impersonate::make()
    ->withSpa()
```

--------------------------------

### ImpersonateManager

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/00-START-HERE.txt

Programmatic manager for impersonation. Provides methods to start and stop impersonation, check authorization, and manage session state.

```APIDOC
## ImpersonateManager

### Description
Manages impersonation sessions programmatically. Provides methods to start and stop impersonation, check authorization, and manage session state.

### Methods

#### impersonate($user, $guard = null)
- **Description**: Starts impersonation of the given user.
- **Parameters**: 
  - `$user` (Authenticatable) - Required - The user to impersonate.
  - `$guard` (string|null) - Optional - The guard to use.
- **Returns**: bool

#### leave($guard = null)
- **Description**: Stops the current impersonation session.
- **Parameters**: 
  - `$guard` (string|null) - Optional - The guard to use.
- **Returns**: bool

#### isImpersonating()
- **Description**: Checks if an impersonation session is active.
- **Returns**: bool

#### getImpersonator()
- **Description**: Returns the original user who started the impersonation.
- **Returns**: Authenticatable|null

#### getImpersonated()
- **Description**: Returns the currently impersonated user.
- **Returns**: Authenticatable|null

#### canImpersonate($user)
- **Description**: Checks if the current user can impersonate the given user.
- **Parameters**: 
  - `$user` (Authenticatable) - Required - The user to impersonate.
- **Returns**: bool

#### canBeImpersonated($user)
- **Description**: Checks if the given user can be impersonated.
- **Parameters**: 
  - `$user` (Authenticatable) - Required - The user to check.
- **Returns**: bool

#### getSessionKey($guard = null)
- **Description**: Returns the session key used for storing impersonation data.
- **Parameters**: 
  - `$guard` (string|null) - Optional - The guard to use.
- **Returns**: string
```

--------------------------------

### Use Impersonate action with redirect_to

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/configuration.md

Shows how to use the Impersonate action. By default it uses the redirect_to config; you can override with redirectTo('/app/dashboard').

```php
use STS\FilamentImpersonate\Actions\Impersonate;

// Uses the redirect_to config by default
Impersonate::make();

// Override the config
Impersonate::make()->redirectTo('/app/dashboard');
```

--------------------------------

### Banner in non-Filament layout

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Banner-Component.md

Example of a full HTML layout for a customer portal that includes the banner. The banner is conditionally shown if the user is authenticated.

```blade
<!DOCTYPE html>
<html>
<head>
    <title>Customer Portal</title>
</head>
<body>
    @if(auth()->check())
        @include('layouts.navigation')
    @endif

    {{ $slot }}

    <!-- Show impersonation banner if active -->
    <x-impersonate::banner style='light'/>
</body>
</html>
```

--------------------------------

### Authorization: canBeImpersonated method

Source: https://github.com/stechstudio/filament-impersonate/blob/master/README.md

Add a canBeImpersonated method to control which users can be impersonated. The example prevents impersonating users with emails ending in '@mycorp.com'.

```php
class User {

    public function canBeImpersonated()
    {
        // Let's prevent impersonating other users at our own company
        return !str_ends_with($this->email, '@mycorp.com');
    }
    
}
```

--------------------------------

### Session-based auth guard configuration

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/errors.md

Configure auth guards with the 'session' driver to avoid impersonation errors. The 'api' guard with 'token' driver will not work with impersonation.

```php
// config/auth.php
'guards' => [
    'web' => [
        'driver' => 'session',  // ✓ Correct
        'provider' => 'users',
    ],
    'api' => [
        'driver' => 'token',    // ✗ Won't work with impersonate
        'provider' => 'users',
    ],
]
```

--------------------------------

### getBackTo()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/Impersonate-Action.md

Resolves and returns the back URL. Returns the value set via backTo() if configured, otherwise returns null.

```APIDOC
## getBackTo()

### Description
Resolves and returns the back URL. Returns the value set via `backTo()` if configured, otherwise returns null.

### Method
`getBackTo()`

### Signature
```php
public function getBackTo(): ?string
```

### Parameters
None

### Return Type
`string|null`

### Behavior
- Returns the value set via `backTo()` if configured
- Returns null if not configured (fallback will be used during impersonation)

### Example
```php
$action = Impersonate::make()->backTo('/users');
echo $action->getBackTo();  // '/users'
```
```

--------------------------------

### EnterImpersonation Event

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/SUMMARY.txt

Event triggered when an impersonation session starts. Contains properties for the impersonator and impersonated user, and can be listened to for audit logging or notifications.

```APIDOC
## EnterImpersonation Event

### Description
Event triggered when an impersonation session starts. Contains properties for the impersonator and impersonated user, and can be listened to for audit logging or notifications.

### Properties
- **impersonator** - The user who is impersonating.
- **impersonated** - The user being impersonated.

### Usage Example
```php
Event::listen(EnterImpersonation::class, function ($event) {
    // Log or notify
});
```
```

--------------------------------

### Get impersonator guard name with Impersonation::getImpersonatorGuardName()

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/ImpersonateManager.md

Retrieves the name of the auth guard used by the impersonator, or null if no impersonation is active. Returns string|null.

```php
public function getImpersonatorGuardName(): ?string
```

```php
use STS\FilamentImpersonate\Facades\Impersonation;

$guard = Impersonation::getImpersonatorGuardName();
// e.g., 'web' or 'admin'
```

--------------------------------

### Set redirect_to via environment variable

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/configuration.md

Environment variable for the redirect URL after impersonation begins. Default is '/'. Overrides the config file value.

```env
FILAMENT_IMPERSONATE_REDIRECT=/dashboard
```

--------------------------------

### Package name property: $name

Source: https://github.com/stechstudio/filament-impersonate/blob/master/_autodocs/api-reference/FilamentImpersonateServiceProvider.md

Defines the package name identifier used for publishing assets and routes.

```php
public static string $name = 'filament-impersonate'
```
Tokens:
Raw