Getting Started

Install and rely on package discovery (Laravel 5.5+); there is nothing to register manually:

composer require lab404/laravel-impersonate
php artisan vendor:publish --provider="Lab404\Impersonate\ImpersonateServiceProvider" --tag=config

Publish the config early — it gives you session_key (default impersonated_by), take_redirect_to, leave_redirect_to, and the default guard. Then add the trait to your authenticatable model and lock it down immediately, because both policy methods return true by default:

// app/Models/User.php
use Lab404\Impersonate\Models\Impersonate;

class User extends Authenticatable
{
    use Impersonate;

    public function canImpersonate(): bool
    {
        return $this->hasRole('support') || $this->hasRole('admin');
    }

    public function canBeImpersonated(): bool
    {
        return ! $this->hasAnyRole(['admin', 'billing_owner']) && ! $this->mfa_enrolled;
    }
}

The first real use case is a support console button. Two POST routes — take and leave — plus a persistent banner, is the whole happy path:

Route::middleware('auth')->group(function () {
    Route::post('/impersonate/{user}', [ImpersonationController::class, 'take'])->name('impersonate.take');
    Route::post('/impersonate/leave', [ImpersonationController::class, 'leave'])->name('impersonate.leave');
});

public function take(Request $request, User $user)
{
    abort_unless($request->user()->canImpersonate(), 403);
    abort_unless($user->canBeImpersonated(), 403);
    abort_if($request->user()->is($user), 403);

    $request->user()->impersonate($user);

    return redirect()->route('dashboard');
}

public function leave(Request $request)
{
    $request->user()->leaveImpersonate();

    return redirect()->route('admin.users.index');
}

After that, the two things you'll reach for daily are is_impersonating() / Impersonate::isImpersonating() and Impersonate::getImpersonator().

Implementation Patterns

Guard the route, not just the model. canImpersonate() is a model method — pair it with a gate or middleware on the route so a misconfigured model can't expose the endpoint:

Route::post('/impersonate/{user}', ...)->middleware('can:impersonate-users');

Always ship a banner. The package deliberately provides no UI. A layout-level block is the cheapest safety net you'll build:

@impersonating
    <div class="impersonation-banner">
        Impersonating <strong>{{ auth()->user()->name }}</strong>.
        <form method="POST" action="{{ route('impersonate.leave') }}">
            @csrf
            <button>Leave</button>
        </form>
    </div>
@endImpersonating

Directives available: @impersonating / @endImpersonating, @canImpersonate, @canBeImpersonated (each accepts an optional guard name), plus the helpers is_impersonating(), can_impersonate(), can_be_impersonated($user).

Log via events, not controllers. Lab404\Impersonate\Events\TakeImpersonation and LeaveImpersonation both carry $impersonator and $impersonated as Authenticatable instances. Put the audit write in a listener so it fires no matter which entry point triggers impersonation:

Event::listen(TakeImpersonation::class, function (TakeImpersonation $e) {
    ImpersonationLog::create([
        'impersonator_id' => $e->impersonator->getAuthIdentifier(),
        'impersonated_id' => $e->impersonated->getAuthIdentifier(),
        'ip'              => request()->ip(),
        'created_at'      => now(),
    ]);
});

Block sensitive routes with the shipped middleware. impersonate.protect (aliased by the service provider to Lab404\Impersonate\Middleware\ProtectAgainstImpersonation) aborts when impersonating. Apply it to password change, email change, MFA enrolment, billing, and account deletion — never globally:

Route::middleware('impersonate.protect')->group(function () {
    Route::get('/settings/security', ...);
    Route::post('/billing/payment-method', ...);
});

Multi-guard is the differentiator — use it deliberately. Pass the guard explicitly and keep both models trait-equipped:

auth('admin')->user()->impersonate($customer, 'web');

Impersonate::getImpersonator();          // resolved back through the original guard
@impersonating('web') ... @endImpersonating

Note the guard-name handling in getImpersonator() and in "can't leave" was fixed only in 1.7.2 — pin at least that.

Feature-test the switch. Asserting on the session key and the authenticated user catches almost every wiring mistake:

$this->actingAs($support)->post(route('impersonate.take', $customer))->assertRedirect();

$this->assertAuthenticatedAs($customer);
$this->assertTrue(session()->has(config('impersonate.session_key')));

Gotchas and Tips

Default-open policy. canImpersonate() and canBeImpersonated() return true out of the box. Overriding them is step one, not a later hardening task.
Attribution is your job. Every action taken while impersonating is written as the impersonated user's action. The package emits events; it does not stamp your audit trail. Add a middleware that pushes impersonator_id into your log context on every request while is_impersonating() is true.
Session-only. Impersonation swaps the user inside the existing session guard. Token/stateless APIs, Sanctum personal-access-token flows, and Auth::onceUsingId()-style auth won't participate. If your app is API-first, this is the wrong tool.
Route verb and CSRF. Take/leave must be POST with CSRF. A GET impersonation endpoint will eventually be triggered by a browser prefetch, a link scanner, or a support agent's back button.
No built-in expiry. Once taken, impersonation persists until leaveImpersonate() or session expiry — an abandoned tab stays impersonated for hours. Consider a timestamp in the session checked by middleware, or a short session lifetime for support sessions.
password.confirm leakage. Laravel's recent-password-confirmation flag lives in the session, so an impersonated session can inherit the admin's confirmation window. Keep impersonate.protect on anything behind password.confirm.
Queued work captures the wrong identity. Jobs and notifications dispatched mid-impersonation serialize the impersonated user. Dispatch audit/mail with explicit user IDs rather than reading auth()->user() later.
Config redirects are easy to bypass. If you write your own controller and call redirect() yourself, take_redirect_to / leave_redirect_to never apply. 1.7.6 added dynamic redirection on leave — check which path you're actually on before debugging a redirect that "doesn't respect config."
MissingUserProvider / InvalidUserProvider (1.7.0+) mean the guard in config/auth.php has no provider or a non-Eloquent one. It fails loudly instead of silently — good, but it will surface at impersonation time, not boot time, so smoke-test each guard in staging.
Non-integer keys are fine now. Identity resolution uses getAuthIdentifier(), so UUID/ULID models work — but only past 1.5.1/1.7.0. Older versions assumed id, including in can_be_impersonated().
Shared session domains. If several apps sit on the same cookie domain, change session_key to something app-specific or you'll get cross-app impersonation reads.
Extension seam. Custom policy belongs in the model's canImpersonate / canBeImpersonated overrides and in event listeners around the trait — the package is intentionally a primitive, not a governance layer. Don't fork it to add approval workflows; wrap it.

Laravel Impersonate Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips