Creating a Custom Laravel 4 Auth Driver

How to create you own custom Auth driver in Laravel 4

Extending Laravel's Auth system isn't currently covered in the Laravel 4 docs, so I thought I'd create a quick guide to it as I recently had to do it for my Auth package, Verify.

Anatomy of the Auth system

First, a little primer on how Laravel actually handles its Auth system.

The Auth class isn't actually a class in the traditional sense: it's a facade. I won't go into too much detail about facades here, but they basically hide complex functionality in a convenient wrapper, which in this case is the Auth 'class'. If you do some digging, you'll find that when you call Auth::attempt(), you're actually calling the attempt method on the Guard class.

Drivers and providers are used to swap out functionality dynamically. Your driver is a wrapper for the code, and the provider provides the differing functionality of the internal methods. (This is a very simplified way to look at it!)

In Laravel 4's Session class, a similar technique is used, but with drivers and stores, so this guide should translate fairly easily. (Both Auth and Session systems extend the Support Manager class!)

Extension time!

To extend the Auth system, you use the extend method. This will register your driver, allowing it to be used.

The code can be placed in a few places, but the most logical ones are either global.php if you're working on an app, or in the boot method of your service provider if you're editing a package. For this tutorial, I'll assume you're placing your code in global.php.

The Code

use Illuminate\Auth\Guard;

Auth::extend('driver_name', function()
{
    return new Guard(
        new Provider(),
        App::make('session.store')
    );
});

Now, the code may be confusing, so let's go through it.

The line is simply including the necessary class to use. (If you place this code in a package, you may need to require more.)

use Illuminate\Auth\Guard;

Next, we call the extend method on the Auth 'class', which is really calling it on the AuthManager class. The first parameter is the name of your driver, the second is the closure that contains your driver's code.

Auth::extend('driver_name', function()
{
    // Driver code
});

Whatever you return in the closure is what handles the calls on the Auth class that aren't defined in the AuthManager class (remember, it's a facade!). Laravel 4's Guard class holds all the methods you need, such as attempt, login etc, so it makes sense to return that.

return new Guard(
    // Guard parameters
);

The Guard class requires two parameters, a provider and an implementation of the Store class. (Passing an instance of the app's session is fine, and is what's done in both the default providers.)

return new Guard(
    new Provider(),
    App::make('session.store')
);

Guard vs Provider

If you want to add new methods to Auth, you'll need to extend the Guard class and return your custom one. However, if you only want to edit how some of the methods behave, chances are you won't need to edit any of the methods in the Guard class: internally, it delegates a lot of the work to its first parameter, the provider.

Extending the Guard Class

I'd recommend using the existing Guard class as a base. You can save your custom Guard class anywhere, and call it anything, just make sure you can autoload it correctly!

Then, after adding your new methods to the class, change your extend code to the following:

Auth::extend('driver_name', function()
{
    return new CustomGuard(
        // Custom guard parameters
    );
});

Creating a Custom User Provider

I'd recommend using a default provider class, such as the EloquentUserProvider class, as a base. You can save your provider anywhere, with any name, just make sure you can autoload it correctly!

Then, after adding your custom code, change your extend code to the following:

Auth::extend('driver_name', function()
{
    return new Guard(
        new CustomUserProvider(
            // Custom provider parameters
        ),
        App::make('session.store')
    );
);

Activating the Driver

To activate your new custom driver, simple change the driver value in the auth config to whatever you called your driver!

Your custom driver should now be used whenever you use the Auth facade.

And that's it. If you have any suggestions or questions about this post, please let me know and I'll help as best I can!

Want to let me know what you think of Creating a Custom Laravel 4 Auth Driver? Why not leave a comment, follow me on Twitter , or !

Comments

comments powered by Disqus