doc88/flux-role-permission

Library for implementing access control by permissions in Laravel applications.

1.0.2 2020-07-10 14:07 UTC

Requires

• php: >= 7.2.0

MIT

• Douglas Men

README

Library for managing user permissions in Laravel applications.

Requirements

• Laravel >= 6.0

Installation

• Run the command below at the project root to add the package to the Laravel application:

    composer require doc88/flux-role-permission

• In the providers list in the config/app.php file add:

    'providers' => [
        ...
        Doc88\FluxRolePermission\FluxRolePermissionServiceProvider::class,
    ]

• Run the command below at the root of your project to publish the new provider:

    php artisan vendor:publish

• Run migrations

    php artisan migrate

• In your User Model add the following lines:

    use Doc88\FluxRolePermission\Traits\HasRolePermissions;

    class User {
        use HasRolePermissions;
    }

Usage

Doc88\FluxRolePermission\Permission Class

Class used to List, Register, Verify and Revoke permissions.

• List All Permissions

    // All Registered Permissions
    Permission::all();

    // Return (array):
    [
        [
            "id" => 3
            "name" => "List Companies"
            "slug" => "list-companies"
        ],
        [
            "id" => 4
            "name" => "Delete Companies"
            "slug" => "delete-companies"
        ]
    ]

• List a Permission

    // Get the Permission
    Permission::get('list-users');

    // Return (array):    
    [
        "id" => 3
        "name" => "List Users"
        "slug" => "list-users"
    ]

• Create a Permission

    // Creating a new Permission
    Permission::create('create-companies');

    // Return (boolean): 
    true or false    

• Delete a Permission

    // Deleting a Permission
    Permission::delete('list-companies');

    // Return (boolean): 
    true or false

• List User’s Permissions

    // List all the User's Permissions
    Permission::list($user);

    // Return (array):
    [
        [
            "id" => 3
            "name" => "List Companies"
            "slug" => "list-companies"
        ],
        [
            "id" => 4
            "name" => "Delete Companies"
            "slug" => "delete-companies"
        ],
        [
            "id" => 5
            "name" => "Create Company"
            "slug" => "create-companies"
        ]
    ]
    

• Checks a User’s Permission

    // Checking if the user has permission
    Permission::has(auth()->user(), 'list-companies');
    
    // Return (boolean): 
    true or false

• Records permission to an User

    // Grants permission for the User
    Permission::register(auth()->user(), 'list-companies');
    
    // Return (boolean): 
    true or false

• Revokes a permission

    // Revokes permission
    Permission::revoke(auth()->user(), 'list-companies');

    // Return (boolean): 
    true or false
    

Using the User Model

It is possible to List, Register, Verify and Revoke permissions using the User class.

• List User Permissions

    $user = User::find(1);
    
    // User's Permissions
    $user->listPermissions();

    // Return (array):
    [
        [
            "id" => 3
            "name" => "List Companies"
            "slug" => "list-companies"
        ],
        [
            "id" => 4
            "name" => "Delete Companies"
            "slug" => "delete-companies"
        ],
        [
            "id" => 5
            "name" => "Create Company"
            "slug" => "create-companies"
        ]
    ]

• Checks User Permission

    $user = User::find(1);
    
    // Checking if the user has permission
    $user->hasPermission('list-companies');
    
    // Return (boolean):
    true or false

• Records permission to an User

    $user = User::find(1);
    
    // Grants permission to the User
    $user->registerPermission('list-companies');
    
    // Return (boolean):
    true or false

• Revokes permission

    $user = User::find(1);
    
    // Revokes permission
    $user->revokePermission('list-companies');

    // Return (boolean):
    true or false    

Doc88\FluxRolePermission\Role Class

Class used to List, Register, Verify and Revoke roles.

• List All Roles

    // All Registered Roles
    Role::all();

    // Return (array):
    [
        [
            "id" => 3
            "name" => "Companies"
            "slug" => "companies"
        ],
        [
            "id" => 4
            "name" => "Users"
            "slug" => "users"
        ]
    ]

• List a Role

    // Get the role
    Role::get('users');

    // Return (array):
    [
        "id" => 5
        "name" => "Users"
        "slug" => "users"
        "permissions" => {
            [
                0 => array:3 [
                    "id" => 3
                    "name" => "List Users"
                    "slug" => "list-users"
                ],
                1 => array:3 [
                    "id" => 4
                    "name" => "Delete Users"
                    "slug" => "delete-users"
                ],
                2 => array:3 [
                    "id" => 5
                    "name" => "Create Users"
                    "slug" => "create-users"
                ]
            ]
        }
    ]

• Create a Role

    // Creating a new Role
    Role::create('Users');

    // Creating a new Role with permissions
    Role::create('users', ['list-users', 'create-users', 'delete-users']);

    // Return (array): 
    [
        "id": 7,
        "name": "Users",
        "slug": "users"
    ]  

• Update a Role

    // Updating a Role
    Role::update('users', ['slug' => 'new-slug', 'permissions' => ['list-users', 'create-users']]);

    // Return (array): 
    [
        "id" => 4
        "name" => "New Slug"
        "slug" => "new-slug"
        "permissions" => {
            [
                "id" => 7
                "name" => "List Users"
                "slug" => "list-users"
            ],
            [
                "id" => 8
                "name" => "Create Users"
                "slug" => "create-users"
            ]
        }
    ]

• Add Permission to a Role

    // Deleting a Role
    Role::addPermission('sales', 'list-sales');

    // Return (boolean): 
    true or false

• Remove Permission from a Role

    // Deleting a Role
    Role::removePermission('sales', 'list-sales');

    // Return (boolean): 
    true or false

• Delete a Role

    // Deleting a Role
    Role::delete('sales');

    // Return (boolean): 
    true or false

• List User’s Roles

    // List all the User's Roles
    Role::list($user);

    // Return (array):
    [
        [
            "id" => 3
            "name" => "Companies"
            "slug" => "companies"
        ],
        [
            "id" => 4
            "name" => "Sales"
            "slug" => "sales"
        ]
    ]
    

• Checks a User’s Role

    // Checking if the user has role
    Role::has(auth()->user(), 'companies');
    
    // Return (boolean): 
    true or false

• Records Role to an User

    // Grants role for the User
    Role::register(auth()->user(), 'companies');
    
    // Return (boolean): 
    true or false

• Revokes a Role

    // Revokes role
    Role::revoke(auth()->user(), 'companies');

    // Return (boolean): 
    true or false    

Using the User Model

It is possible to List, Register, Verify and Revoke roles using the User class.

• List User Roles

    $user = User::find(1);
    
    // User's Roles
    $user->listRoles();

    // Return (array):
    [
        [
            "id" => 3
            "name" => "Companies"
            "slug" => "companies"
        ],
        [
            "id" => 4
            "name" => "Sales"
            "slug" => "sales"
        ]
    ]

• Checks User Role

    $user = User::find(1);
    
    // Checking if the user has role
    $user->hasRole('companies');
    
    // Return (boolean):
    true or false

• Records role to an User

    $user = User::find(1);
    
    // Grants role to the User
    $user->registerRole('companies');
    
    // Return (boolean):
    true or false

• Revokes role

    $user = User::find(1);
    
    // Revokes role
    $user->revokeRole('companies');

    // Return (boolean):
    true or false    

Middleware

• In the $routeMiddleware array in the app\Http\Kernel.php file add:

    protected $routeMiddleware = [
        ...
        'permissions' => Doc88\FluxRolePermission\Http\Middleware\FluxRolePermission::class,
        ...
    ]

• Middleware Usage:

    // routes/web.php

    Route::get('list-companies', 'CompanyController@index')->middleware('permissions:list-companies');
    // or
    Route::group(['middleware' => 'permissions:list-companies'], function () {
        Route::get('list-companies', 'CompanyController@index');
    });