Laravel Impersonate Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lab404/laravel-impersonate
   

   The package auto-discovers and registers itself (Laravel 5.5+).

2. Publish Configuration (optional):

   php artisan vendor:publish --provider="Lab404\Impersonate\ImpersonateServiceProvider"
   

   This creates config/impersonate.php for customization (e.g., guards, middleware).

3. Add Routes (in routes/web.php):

   Route::middleware(['auth', 'can:impersonate'])->group(function () {
       Route::get('/impersonate/{user}', [\Lab404\Impersonate\Http\Controllers\ImpersonateController::class, 'impersonate']);
       Route::get('/leave-impersonation', [\Lab404\Impersonate\Http\Controllers\ImpersonateController::class, 'leave']);
   });
   

4. First Use Case:

   • Log in as an admin.
   • Visit /impersonate/3 (replace 3 with a user ID).
   • You’re now authenticated as that user. Visit /leave-impersonation to return to your admin session.

Where to Look First

• Documentation: Start with the "Quick Start" section.
• Blade Helpers: Use @impersonatable and @canImpersonate directives in views to show/hide impersonation UI conditionally.
• Middleware: Extend \Lab404\Impersonate\Middleware\Impersonate to add custom logic (e.g., log impersonation events).

First Practical Workflow

1. Debug a User-Specific Bug:

   • Reproduce an issue reported by a user (e.g., a checkout failure).
   • Impersonate the user via /impersonate/{user_id}.
   • Recreate the steps to identify the root cause (e.g., missing permission, UI glitch).
   • Leave impersonation and fix the issue in your codebase.

2. Test Role-Based Features:

   • Impersonate a "customer" role to verify a new feature works as expected.
   • Switch to an "admin" role to test moderation workflows.

Implementation Patterns

Core Workflows

1. Impersonation Flow

// In a controller or command
use Lab404\Impersonate\Facades\Impersonate;

// Impersonate a user by ID
Impersonate::impersonate($userId);

// Impersonate a user model directly
Impersonate::impersonate($userModel);

// Leave impersonation
Impersonate::leave();

2. Middleware Integration

Restrict impersonation to specific roles (e.g., admins):

// app/Http/Middleware/CheckImpersonationPermission.php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Lab404\Impersonate\Facades\Impersonate;

class CheckImpersonationPermission
{
    public function handle(Request $request, Closure $next)
    {
        if (Impersonate::isImpersonating()) {
            abort_if(!auth()->user()->isAdmin(), 403);
        }
        return $next($request);
    }
}

Register in app/Http/Kernel.php:

protected $routeMiddleware = [
    // ...
    'can.impersonate' => \App\Http\Middleware\CheckImpersonationPermission::class,
];

3. Blade Directives

Show impersonation UI only to authorized users:

@auth
    @canImpersonate
        <a href="/impersonate/{{ $user->id }}">Impersonate</a>
    @endcanImpersonate

    @impersonating
        <a href="/leave-impersonation">Leave Impersonation</a>
    @endimpersonating
@endauth

4. Multi-Guard Support

Configure for API and web guards in config/impersonate.php:

'guards' => [
    'web' => [
        'enabled' => true,
    ],
    'api' => [
        'enabled' => true,
    ],
],

Impersonate via a specific guard:

Impersonate::impersonate($userId, 'api');

Advanced Patterns

1. Custom User Provider

Extend impersonation to work with non-Eloquent users:

// app/Providers/ImpersonateServiceProvider.php
use Lab404\Impersonate\ImpersonateManager;

public function boot()
{
    $this->app->extend(ImpersonateManager::class, function ($app, $manager) {
        $manager->extend('custom_guard', function ($app) {
            return new class($app['auth']) {
                public function findUserById($userId)
                {
                    return CustomUser::find($userId); // Your custom logic
                }
            };
        });
        return $manager;
    });
}

2. Event Listeners

Log impersonation sessions:

// app/Providers/EventServiceProvider.php
protected $listen = [
    \Lab404\Impersonate\Events\ImpersonateStarted::class => [
        \App\Listeners\LogImpersonation::class,
    ],
    \Lab404\Impersonate\Events\ImpersonateEnded::class => [
        \App\Listeners\LogImpersonation::class,
    ],
];

3. Dynamic Redirects

Redirect users after leaving impersonation:

// config/impersonate.php
'redirect_after_leave' => 'dashboard',

Or dynamically:

Impersonate::leave('/custom-redirect?user=' . $userId);

4. Impersonation in Tests

Test impersonation logic in PHPUnit:

public function testImpersonation()
{
    $user = User::factory()->create();
    Impersonate::impersonate($user);

    $this->assertTrue(Impersonate::isImpersonating());
    $this->assertEquals($user->id, auth()->id());

    Impersonate::leave();
    $this->assertFalse(Impersonate::isImpersonating());
}

Gotchas and Tips

Pitfalls

1. Session Leaks:

   • Issue: Impersonation may not clear cached data (e.g., auth()->user() in service containers).
   • Fix: Use Impersonate::leave() in a finally block or middleware to ensure cleanup:

     try {
         Impersonate::impersonate($user);
         // Your logic
     } finally {
         Impersonate::leave();
     }
     

2. Multi-Guard Conflicts:

   • Issue: Impersonating across guards (e.g., web and api) can cause auth state mismatches.
   • Fix: Explicitly specify the guard when impersonating:

     Impersonate::impersonate($userId, 'api');
     

3. Blade Caching:

   • Issue: @impersonating directives may not update if Blade views are cached.
   • Fix: Clear cached views or use @once directives:

     @once
         @impersonating
             <!-- Dynamic content -->
         @endimpersonating
     @endonce
     

4. User Model Requirements:

   • Issue: The package expects getAuthIdentifier() on user models. Custom models may fail.
   • Fix: Ensure your model implements Illuminate\Contracts\Auth\Authenticatable:

     use Illuminate\Contracts\Auth\Authenticatable;
     
     class User implements Authenticatable {
         public function getAuthIdentifierName() { ... }
         public function getAuthIdentifier() { ... }
         // ...
     }
     

5. Middleware Order:

   • Issue: Middleware like auth may interfere with impersonation checks.
   • Fix: Place impersonation middleware after auth in app/Http/Kernel.php:

     protected $middleware = [
         // ...
         \App\Http\Middleware\CheckImpersonationPermission::class,
     ];
     

Debugging Tips

1. Check Impersonation State:

   dd(Impersonate::isImpersonating(), auth()->user());
   

2. Inspect Guard Configuration:

   dd(config('impersonate.guards'));
   

3. Enable Debug Logging: Add to config/impersonate.php:

   'debug' => env('IMPERSONATE_DEBUG', false),
   

   Logs impersonation events to storage/logs/laravel.log.

4. Verify User Provider: If findUserById fails, check your guard’s user provider:

   dd(auth()->guard('web')->provider());
   

Configuration Quirks

1. Default Guard: The package