Verify (Laravel 5)

A simple role/permission authentication package for Laravel 5.

These docs are for the Laravel 5 package.

Verify can be installed via Composer or downloaded from GitHub.

Any issues should also be raised via the GitHub issue system; pull requests welcome!

Add Verify to your composer.json file:

"require": {
  "toddish/verify": "~4.*"
}

Now, run a composer update on the command line from the root of your project:

composer update

Add the Verify Service Provider to your config in app/config/app.php:

'providers' => [
  'Toddish\Verify\Providers\VerifyServiceProvider
],

Change your Auth driver to 'verify' in app/config/auth.php:

'driver' => 'verify',

You may also change the 'model' value to 'Toddish\Verify\Models\User' if you want to be able to load Verify's User model when using Auth::user().

Alternatively, you can simply create your own User model, and extend Verify's:

use Toddish\Verify\Models\User as VerifyUser;

class User extends VerifyUser
{
  // Code
}

Run this on the command line from the root of your project:

php artisan vendor:publish

Or, if you want to publish parts of Verify individually:

php artisan vendor:publish --provider="Toddish\Verify\Providers\VerifyServiceProvider" --tag="config"

The available tags are config, migrations and seeds.

Now migrate the database tables for Verify. Run this on the command line from the root of your project:

php artisan migrate
php artisan db:seed

You should now have all the tables imported, complete with a sample user, called admin, with a password of password.

The package is intentionally lightweight. You add Users, Roles and Permissions like any other Model.

$user = new Toddish\Verify\Models\User;
$role = new Toddish\Verify\Models\Role;
$permission = new Toddish\Verify\Models\Permission;

etc.

All models are in the namespace 'Toddish\Verify\Models\'.

The relationships are as follows:

Relationships are handled via the ORM, too:

$role->permissions()->sync([$permission->id, $permission2->id]);

More information on relationships can be found in the Laravel Eloquent docs.

Basic Examples

// Create a new Permission
$permission = new Toddish\Verify\Models\Permission;
$permission->name = 'delete_user';
$permission->save();

// Create a new Role
$role = new Toddish\Verify\Models\Role;
$role->name = 'Moderator';
$role->level = 7;
$role->save();

// Assign the Permission to the Role
$role->permissions()->sync([$permission->id]);

// Create a new User
$user = new Toddish\Verify\Models\User;
$user->username = 'Todd';
$user->email = 'todd@toddish.co.uk';
$user->password = 'password'; // This is automatically salted and encrypted
$user->save();

// Assign the Role to the User
$user->roles()->sync([$role->id]);

// Using the public methods available on the User object
var_dump($user->is('Moderator')); // true
var_dump($user->is('Admin')); // false

var_dump($user->can('delete_user')); // true
var_dump($user->can('add_user')); // false

var_dump($user->level(7)); // true
var_dump($user->level(5, '<=')); // false

User Flags

Users have 3 flags: Verified, Disabled, Deleted.

These flags are set on the User object:

$user = User::find(1);
$user->deleted_at != NULL; // User has been deleted
$user->verified = 1; // User has been verified
$user->disabled = 1; // User has been disabled

The flags decide, along with a correct identifier/password, if a user can log in when using the verify method.

Logging a User in

Verify has a new method to log a user in, called verify.There are two main differences between this and the normal attempt Auth method. (These differences also affect the validate and stateless methods)

Firstly, the method returns a string, instead of a simple boolean. This tells you, if the user was unsucessful, why they were unsucessful.

use Toddish\Verify\Helpers\Verify;

switch (Auth::verify($credentials))
{
  case Verify::SUCCESS:
    // Successful log in
    break;
  case Verify::INVALID_CREDENTIALS:
  case Verify::UNVERIFIED:
  case Verify::DISABLED:
    // Error!
    break;
}

Secondly, instead of passing in a column explictly, you can pass in the key 'identifier', which will validate the user against the values specified in the 'identified_by' config option. (username and email by default).

Auth::verify([
  'identifier' => 'todd@toddish.co.uk',
  'another_column' => 1,
  'password' => 'password'
]);

Would be the same as (with the default options)...

Auth::attempt([
  'username' => 'todd@toddish.co.uk',
  'another_column' => 1,
  'password' => 'password'
]);

Auth::attempt([
  'email' => 'todd@toddish.co.uk',
  'another_column' => 1,
  'password' => 'password'
]);

Note that it still appends each extra term you pass in too!

If you don't want or need this, simply never pass in the 'identifier' key and the method will function as normal.

User Model Scopes

New in Laravel 4 are model scopes, and the Verify user model now has them implemented.

They are basically shorthand where clauses in your query:

use Toddish\Verify\Models\User as User;

User::verified(); // Where verified = 1
User::unverified(); // Where verified = 0
User::disabled(); // Where disabled = 1
User::enabled(); // Where disabled = 0

$users = User::verified()->disabled()->get(); // All verified but disabled users

A separate config file is provided to keep configuration separate from other Auth libraries.

Option Type Default Description
identified_by Array ['username', 'email'] An array of the database columns to authenticate against.
super_admin String 'Super Admin' The name of the super admin, who returns true on all permission checks.
prefix String '' The prefix to use for the database tables. e.g 'verify_' for 'verify_users'.
models Array ['user' => 'Toddish\Verify\Models\User',
'role' => 'Toddish\Verify\Models\Role',
'permission' => 'Toddish\Verify\Models\Permission']
The models to load, incase you want to override them
crud_permissions Array ['create_', 'read_', 'update_', 'delete_'] Prefixes for the artisan add crud permission

The User Object

$user = User::find($id);
$user->is($roles):Boolean
Option Type Default Description
$roles String|Array A single role name (String) or multiple role names (Array).

Checks if the user is a certain role, or is one of many roles if passed an array.

$user->is('Super Admin');
$user->is(array('Super Admin', 'Moderator'));
$user->can($permissions):Boolean
Option Type Default Description
$permissions String|Array A single permission name (String) or multiple permission names (Array).

Checks if the user is has a certain permission, or has one of many permissions if passed an array.

$user->can('delete_users');
$user->can(array('delete_users', 'add_users'));
$user->level($level [, $operator]):Boolean
Option Type Default Description
$level Integer A level of a role.
$operator String '>=' The operation to perform, all the standard operators are valid (<, <=, =, >=, >).

Each role can have a numerical level as well; this is useful if you want to check someone has a higher role than someone else.

When using this method, the '=' modifier will check if the user has a role with the level, '>' and '>=' will check against the highest level the user has, and '<' and '<=' will check against the lowest.

// User has 2 roles with levels 3 and 7
$user->level(7); // TRUE
$user->level(5, '='); // FALSE
$user->level(3, '<='); // TRUE

The Auth Library

Verify extends the functionality of the default Laravel Auth library.

Auth::verify($credentials [, $remember = false [, $login = true]]):Boolean

The differences from the default 'attempt' method noted below will also affect the 'validate' and 'stateless' methods.

Attempts to log in a user.

use Toddish\Verify\Helpers\Verify;

switch (Auth::verify($credentials))
{
  case Verify::SUCCESS:
    // Successful log in
    break;
  case Verify::INVALID_CREDENTIALS:
  case Verify::UNVERIFIED:
  case Verify::DISABLED:
    // Error!
    break;
}

If the key 'identifier' is passed, the credentials will be validated against the values stored in the config option 'identified_by'. All other terms passed in will be appended as normal.

See the example in the other examples section for more information on how this works.