README

This is a private composer repository for White Sunrise, LLC software and web development.

This package is sti under open development and should not be used in production

This package allows a quick and tested way to setup a multi-auth user validation and authentication system, with custom middleware, guards, migrations, and seeders for testing. This package has only been tested in Laravel 5.3 and 5.4. See below for installation instructions and other information.

About White Sunrise LLC

White Sunrise has been creating great websites and cloud-based software since 2008. We are known for innovative and leading-edge development to create custom solutions for our clients

Find out more about us here.

Installation

This package can be easily installed as a private composer package. See below for details and docs.

Laravel 5.4

Create a folder named packages in your Laravel project directory, and clone the repository into that folder:

cd <project-root-directory>
mkdir packages && cd packages
git clone git@github.com:whitesunrise/guardian.git

Add the cloned repository to your project's composer.json file in the autoload section like so:

"autoload": {
    "classmap": [
        "database"
    ],
    "psr-4": {
        "App\\": "app/",
        "WhiteSunrise\\Guardian\\": "packages/whitesunri/whitesunri/src/"
    }
},

Clear composer and artisan autoload from your project root:

composer dumpautoload && php artisan clear-compiled

Open your config/app.php and add the following to the providers array:

WhiteSunrise\Guardian\GuardianServiceProvider::class,

In the same config/app.php and add the following to the aliases array:

'Guardian' =>  WhiteSunrise\Guardian\Facades\GuardianFacade::class,

Publish the package configuration file to config/guardian.php:

php artisan vendor:publish --provider="WhiteSunrise\Guardian\GuardianServiceProvider" --tag=config

Open your config/auth.php and make the following 3 changes for the Admin User class:

In the providers array:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => App\Models\User::class,
    ],
    'admins' => [
        'driver' => 'eloquent',
        'model' => App\Models\AdminUser::class,
    ],
],

In the guards array:

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
    'web_admin' => [
        'driver' => 'session',
        'provider' => 'admins',
    ],

    'api' => [
        'driver' => 'token',
        'provider' => 'users',
    ],
],

In the passwords array:

'passwords' => [
    'users' => [
        'provider' => 'users',
        'table' => 'password_resets',
        'expire' => 60,
    ],
    'admins' => [
        'provider' => 'admins',
        'table' => 'admin_password_resets',
        'expire' => 60,
    ],
],

If you want to use Middleware (requires Laravel 5.1 or later. you also need to add the following to the routeMiddleware array in app/Http/Kernel.php:

'role' => \WhiteSunrise\Guardian\Middleware\GuardianRole::class,
'permission' => \WhiteSunrise\Guardian\Middleware\GuardianPermission::class,
'ability' => \WhiteSunrise\Guardian\Middleware\GuardianAbility::class,

Configuration

Set the proper values in the config/auth.php.

To further customize table names and model namespaces, edit the config/guardian.php configuration file.

Users

Guardian uses the app/Models directory for storing models. If you used [Laravel's Authentication Quickstart](https://laravel.com/docs/5.4/authentication#authentication-quickstart. to generate your User model and controllers, make sure you update the values in your config file.

Generate the Guardian migrations:

php artisan whitesunrise:guardian:make:migration all

This will generate the <timestamp>_guardian_create_roles_tables.php and <timestamp>_guardian_create_permissions_tables.php migrations. Now you can run the migration(s.:

php artisan migrate

After the migration, five new tables will be present:

roles - stores role records
permissions - stores permission records
role_users - stores [many-to-many](http://laravel.com/docs/4.2/eloquent#many-to-many. relations between roles and users
role_admin_users - stores [many-to-many](http://laravel.com/docs/4.2/eloquent#many-to-many. relations between roles and admin users
permission_roles - stores [many-to-many](http://laravel.com/docs/4.2/eloquent#many-to-many. relations between roles and permissions

Models

Role

Generate the new Role model inside app/models/Role.php by running:

artisan whitesunrise:guardian:make:model role

The Role model is used for both the User and AdminUser models. Both have pivot tables to keep user data separate. Role model has four main attributes:

name - Unique human readable name for the Role. For example: "User Administrator", "Project Owner", "Widget Co. Employee".
slug - Unique name for the Role, used for looking up role information in the application layer. For example: "admin", "owner", "employee".
description - A more detailed explanation of what the Role does. This field is optional.
parent_id - Optional field to inherit permissions from another role.

Both parent_id and description are optional; their fields are nullable in the database.

Alternatively, you may use an existing Role model instead by extending the GuardianRole class, shown below.

namespace App\Models;

use WhiteSunrise\Guardian\Models\GuardianRole;

class Role extends GuardianRole
{
}

Permission

Generate the new Permission model inside app/models/Permission.php by running:

artisan whitesunrise:guardian:make:model permission

The Permission model has three main attributes:

name - Unique human readable name for the permission. For example "Create Posts", "Edit Users", "Post Payments", "Subscribe to mailing list".
slug - Unique name for the permission, used for looking up permission information in the application layer. For example: "create-post", "edit-user", "post-payment", "mailing-list-subscribe".
description - A more detailed explanation of the Permission.

In general, it may be helpful to think of the last two attributes in the form of a sentence: "The permission name allows a user to description."

Alternatively, you may use an existing Permission model instead by extending the GuardianPermission class, shown below.

<?php

namespace App\Models;

use WhiteSunrise\Guardian\Models\GuardianPermission;

class Permission extends GuardianPermission
{
}

User

Next, use the GuardianUserTrait trait in your existing User model. For example:

<?php

namespace App\Models;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Support\Facades\Auth;
use WhiteSunrise\Guardian\Traits\GuardianUserTrait;

class User extends Authenticatable
{
    use Notifiable;
    use GuardianUserTrait;

    // continued...
}

This will enable the relation with Role and add the following methods to the User model:

roles()
hasRole($roleSlug, $requireAll = false) - accepts either a string or an array of roles to check
can($permissionSlug, $requireAll = false) - accepts either a string or an array of permissions to check
ability($roles, $permissions, $options) - more advanced role and permission checking
attachRoles($role)
detachRoles($role)
withoutRoles($roles) static method that returns the users WITHOUT the specified roles
withRoles($roles) static method that returns the users WITH the specified roles

Admin User

Next, use the GuardianAdminUserTrait trait in your existing AdminUser model. For example:

<?php

namespace App\Models;

use Illuminate\Notifications\Notifiable;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Support\Facades\Auth;
use WhiteSunrise\Guardian\Traits\GuardianAdminUserTrait;

class AdminUser extends Authenticatable
{
    use Notifiable;
    use GuardianAdminUserTrait;

    // continued...
}

This will enable the relation with Role and add the following methods to the User model:

roles()
hasRole($roleSlug, $requireAll = false) - accepts either a string or an array of roles to check
can($permissionSlug, $requireAll = false) - accepts either a string or an array of permissions to check
ability($roles, $permissions, $options) - more advanced role and permission checking
attachRoles($role)
detachRoles($role)
withoutRoles($roles) static method that returns the users WITHOUT the specified roles
withRoles($roles) static method that returns the users WITH the specified roles

Don't forget to dump composer autoload:

composer dump-autoload

Seeders

Generate the seeder files: artisan whitesunrise:guardian:make:seeder

Add the seeders to your DatabaseSeeder class:

$this->call(GuardianRolesTableSeeder::class);

Generate the seeder files: artisan whitesunrise:guardian:make:seeder
Add the following to your DatabaseSeeder class: $this->call(GuardianRolesTableSeeder::class); or run artisan db:seed --class=GuardianRolesTableSeeder
Add the following to your DatabaseSeeder class: $this->call(GuardianPermissionsTableSeeder::class); or run artisan db:seed --class=GuardianPermissionsTableSeeder

Usage

Concepts

You can generate any of the following models using the artisan commands: User, AdminUser, Role, and Permission

Generate all the models: artisan whitesunrise:guardian:make:model all
Generate a specific model: artisan whitesunrise:guardian:make:model <user|admin_user|role|permission>

Generate the seeder files: artisan whitesunrise:guardian:make:seeder
Add the following to your DatabaseSeeder class: $this->call(GuardianRolesTableSeeder::class); or run artisan db:seed --class=GuardianRolesTableSeeder
Add the following to your DatabaseSeeder class: $this->call(GuardianPermissionsTableSeeder::class); or run artisan db:seed --class=GuardianPermissionsTableSeeder

(Optionally) Add the Facade to your aliases in config/app.php:

'Guardian' => WhiteSunrise\Guardian\Facades\GuardianFacade::class,

(Optionally) Generate the models: artisan whitesunrise:guardian:make:model

Use the GuardianUserTrait in your User model:

<?php

use WhiteSunrise\Guardian\Traits\GuardianUserTrait;

class User extends Eloquent
{
    use GuardianUserTrait; // add this trait to your user model

    ...
}

whitesunrise / guardian

Maintainers

Details