doc88/flux-role-permission

Library for implementing access control by permissions in Laravel applications.

1.0.2 2020-07-10 14:07 UTC

This package is auto-updated.

Last update: 2024-03-10 22:33:07 UTC


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');
    });