alp-develop/laravel-impersonate

Secure user impersonation for Laravel applications

v1.0.0 2026-04-12 05:05 UTC

Requires

• php: ^8.1
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.0
• orchestra/testbench: ^8.0|^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• alp-develop

• laravel
• impersonation
• impersonate
• user-switching

README

Secure user impersonation for Laravel applications. Built with a session-based architecture, versioned context, automatic validation middleware, and a full event system.

Requirements

• PHP 8.1+
• Laravel 10.x, 11.x , 12.x or 13.x

Installation

composer require alp-develop/laravel-impersonate

Publish the configuration file:

php artisan vendor:publish --tag=impersonate-config

Quick Start

1. Implement the contract on your User model

use AlpDevelop\LaravelImpersonate\Contracts\Impersonatable;
use AlpDevelop\LaravelImpersonate\Traits\HasImpersonation;

class User extends Authenticatable implements Impersonatable
{
    use HasImpersonation;
}

2. Define a Gate policy

The package registers an impersonate gate that returns false by default. Override it in your AuthServiceProvider:

use Illuminate\Support\Facades\Gate;

Gate::define('impersonate', function ($user, $target) {
    return $user->is_admin;
});

3. Start and stop impersonation

use AlpDevelop\LaravelImpersonate\Facades\Impersonate;

Impersonate::start($targetUser);
Impersonate::start($targetUser, ttl: 30);
Impersonate::stop();

Documentation

Section	Description
Configuration	All config options with types, defaults and examples
Authorization	Three-layer authorization model, validation order, role-based examples
Middleware	HandleImpersonation and ForbidDuringImpersonation setup and behavior
Events	All 5 events with payloads, listener examples, and flow diagram
API Reference	Full reference: Facade, Contract, Trait, Value Object, Enum, Macros, Blade directives
Security	Session regeneration, versioned context, automatic validation, IP tracking, recommendations

Testing

composer test

Changelog

See CHANGELOG.md for recent changes.

License

MIT License. See LICENSE for details.