Laravel Impersonate

The package dispatches two events that you can listen to:

• TakeImpersonation: Fired when an impersonation session begins.
• LeaveImpersonation: Fired when an impersonation session ends.

Both events provide access to the following properties:

• $event->impersonator: The User model instance of the original user.
• $event->impersonated: The User model instance of the user being impersonated.

To install the package, require it via Composer and register the service provider in your Laravel application.

1. Install via Composer:

composer require lab404/laravel-impersonate

2. Register the service provider in config/app.php:

'providers' => [
    // ...
    Lab404\Impersonate\ImpersonateServiceProvider::class,
],

3. Add the Lab404\Impersonate\Models\Impersonate trait to your User model to enable impersonation capabilities.

The package provides a route macro to set up built-in routes for impersonating and leaving impersonation. You must call this macro within your web middleware group.

Registering the routes

In your routes/web.php or RouteServiceProvider:

Route::impersonate();

Generating URLs

• Impersonate a user: route('impersonate', $id)
  • For multi-guard setups: route('impersonate', ['id' => $id, 'guardName' => 'admin'])
• Leave impersonation: route('impersonate.leave')

Publish the configuration file using:

php artisan vendor:publish --tag=impersonate

Configuration Keys:

• session_key: The session key used to store the original user ID (default: 'impersonated_by').
• take_redirect_to: Where to redirect after taking an impersonation (used by the built-in controller). Can be a URI, the keyword back, or a route name.
• leave_redirect_to: Where to redirect after leaving an impersonation (used by the built-in controller). Can be a URI, the keyword back, or a route name.

The package includes a default configuration file. You can publish this file to your application's config directory using the following Artisan command:

php artisan vendor:publish --tag=impersonate

The configuration file will be named laravel-impersonate.php.

You can interact with the ImpersonateManager directly via the app('impersonate') helper or dependency injection to perform advanced operations.

Available Methods:

• $manager->findUserById($id): Find a user by ID.
• $manager->isImpersonating(): Returns true if the current session is an impersonation.
• $manager->take($from, $to): Manually switch from one user to another.
• $manager->leave(): Leave the current impersonation.
• $manager->getImpersonatorId(): Retrieve the ID of the user who is performing the impersonation.

$manager = app('impersonate');

$manager->isImpersonating();
$manager->take($from, $to);
$manager->leave();
$manager->getImpersonatorId();

The package provides three Blade directives to conditionally show UI elements based on impersonation status:

• @canImpersonate($guard = null): Renders content if the current user is allowed to impersonate others.
• @canBeImpersonated($user, $guard = null): Renders content if the specific $user is allowed to be impersonated.
• @impersonating($guard = null): Renders content if the current user is currently impersonating someone else.

@canImpersonate($guard = null)
    <a href="{{ route('impersonate', $user->id) }}">Impersonate this user</a>
@endCanImpersonate

@canBeImpersonated($user, $guard = null)
    <a href="{{ route('impersonate', $user->id) }}">Impersonate this user</a>
@endCanBeImpersonated

@impersonating($guard = null)
    <a href="{{ route('impersonate.leave') }}">Leave impersonation</a>
@endImpersonating

Once the Impersonate trait is added to your User model, you can use the following methods on the currently authenticated user instance:

• impersonate($other_user): Authenticate as another user.
• leaveImpersonation(): Return to the original authenticated user.

Auth::user()->impersonate($other_user);
// You're now logged as the $other_user

Auth::user()->leaveImpersonation();
// You're now logged as your original user.

Use the impersonate.protect middleware to prevent impersonated users from accessing sensitive routes (e.g., payment settings or credit card details). If an impersonator attempts to access a protected route, they will be blocked.

Router::get('/my-credit-card', function() {
    echo "Can't be accessed by an impersonator";
})->middleware('impersonate.protect');

By default, any user can impersonate any other user. You can restrict this by adding specific methods to your User model:

• canImpersonate(): Controls whether the current user is allowed to start an impersonation session.
• canBeImpersonated(): Controls whether a user is allowed to be the target of an impersonation session.

/**
 * @return bool
 */
public function canImpersonate()
{
    return $this->is_admin == 1;
}

/**
 * @return bool
 */
public function canBeImpersonated()
{
    return $this->can_be_impersonated == 1;
}