README

Impersonate package for the Laravel Framework

What is that?

Laravel has no default impersonation wrapper for low-level methods. This package highly inspired by Symfony impersonation which looks much more flexible rather than several inspected Laravel implementations. Package fully implement GET-parameter-driven behavior. Also, this package does not restrict you in using custom user providers (for instance, if you use Propel), guards and can be used with Twig as view templater. Some ideas inspired by existing impersonation packages for Laravel (:+1: thanks to those authors!).

Installation

composer require scif/laravel-pretend

Add service provider to config/app.php after Laravel service providers but before your own:

    'providers' => [
       …
        Scif\LaravelPretend\LaravelPretendServiceProvider::class,
        /*
         * Application Service Providers...
         */
         …
     ]

Add middleware handling impersonation:

to your Kernel class:

protected $middlewareGroups = [
    'web' => [
        …
        Scif\LaravelPretend\Middleware\Impersonate::class,
    ],

This way is most common and covers all cases I can assume.

or by any suitable methods for some especial cases.

The latest step of installation is a configuring authorization gate. Package bundled with gate called impersonate. This gate checks if your user model implements Scif\LaravelPretend\Interfaces\Impersonable and check method canImpersonate(): bool.

So your model can looks like:

class User extends Authenticatable implements Impersonable
{
…

    public function canImpersonate(): bool
    {
        return $this->isAdmin();
    }
}

☝️ You can use out of box implementation of this gate or override it in your own AuthServiceProvider. You can override name of gate used to check permissions in configuration as well.

Configuration

Configuration file can be easily copied to your project by vendor:publish command:

php ./artisan  vendor:publish --provider=Scif\\LaravelPretend\\LaravelPretendServiceProvider --tag=config

Configuration consist of just two options:

return [
    'impersonate' => [
        'user_identifier' => 'email',
        'auth_check' => 'impersonate',
    ]
];

user_identifier — this string will be used as name of field using to retrieve user object from user provider (method retrieveByCredentials()). The default value email makes your impersonation urls beauty: ?_switch_user=admin@site.com is much clear rather than ?_switch_user=43. But it's up to you
auth_check — this string is a name of Gate used to check ability of user to impersonate. In fact the default Gate could be easily overriden in AuthServiceProvider of your application.

Usage

As mentioned above, this package repeats Symfony style of using GET-parameters to manage impersonation.

Blade using is pretty straightforward:

// generates link with impersonation
{{ route('home', ['_switch_user' => 'admin@site.com']) }}

// exit impersonation
    @if ($app['impersonator']->isImpersonated())
        <a href="{{ route('home', ['_switch_user' => '_exit']) }}">Exit impersonation</a>
    @else
        <a href="{{ route('logout') }}">Logout</a>
    @endif

And here is a simple example using in twig:

// generates link with impersonation
{{ route('home', {'_switch_user': 'admin@site.com'}) }}

// more advance usage
                {% if auth_user() %}
                    {% if app.impersonator.impersonated %}
                        <a class="btn btn-default" href="{{ route('home', {'_switch_user': '_exit'}) }}">Exit impersonation</a>
                    {% else %}
                        <form action="{{ route('logout') }}" method="post">
                            {{ csrf_field() }}
                            <button class="btn btn-default">Logout</button>
                        </form>
                    {% endif %}
                {% endif %}

Events

On entering and exitting impersontaion this package raises events: Scif\LaravelPretend\Event\Impersontated, Scif\LaravelPretend\Event\Unimpersontated. Name of events is their fully qualified class names, so simplest event listener will looks like:

use Scif\LaravelPretend\Event\Impersontated;
…
    Event::listen(Impersonated::class, function (Impersonated $event) {
        //
    });

Forbid impersonation

You can use bundled ForbidImpersonation middleware to forbid using of impersonation for some route groups, routes or controllers.

PHP7? Ugh! Wtf??

Yes, PHP7 is awesome! So, if you want to use it with PHP5 — create an issue and I will think about a separate branch or other suitable solution.

Contribution

Any type of contributions is highly appreciated. Don't be a shy — help this project become even better!

scif / laravel-pretend

Maintainers

Details