Download the PHP package miracuthbert/laravel-roles without Composer

Laravel Roles

An Eloquent roles and permissions package for Laravel 5.8 and up.

Installation

To can install the package via composer:

Setup

The package takes advantage of Laravel Auto-Discovery, so it doesn't require you to manually add the ServiceProvider.

If you don't use auto-discovery, add the ServiceProvider to the providers array in config/app.php

Migrations

You first need to publish the packages migrations:

For those who had published migrations earlier use command(s) below to publish updated changes:

Then run the migrate command:

Seeding

By default the package includes a seeder for roles and permissions, RolesAndPermissionsTableSeeder.

You can add it to your DatabaseSeeder or use the command below to run it in isolation.

See the usage section on how to assign a role to a user via the console.

Configuration

To customize the package usage, copy the package config to your local config by using the publish command:

The package includes configuration for:

Role Sharing

allow_shared_roles key enables the package to query for roles that can be shared by models.

Example, an admin role for Team model can be shared and easily managed by the app admin, compared to a manager role that may vary between teams.

User Model

The default user model is App\Models\User::class the default namespace of User model.

You can change the default user model by changing model key under users in the config file.

See the usage section on how to enable roles and permissions on the User model.

Middleware

Under middleware you can configure the abort_code, which by default is 403.

Permitable Types

You can setup the types of role and permissions allowed to be created within your app.

This can be useful in a multi-tenant app for filtering out Admin and Tenant based permissions and roles.

For example if your application has teams and each member performs unique tasks you can define a permission or role type team under permitables in the config file which can be used to filter out only team permissions or roles.

Permitable types for non admin roles need to be linked to added as a key in the models array in the config file.

Models

You can also map permitables types (mentioned above) to related models.

Each model can only be related to a single permitable type.

Usage

To start assigning roles and permissions to users, you must first add the LaravelRolesUserTrait trait to the User model.

The User model should match the one indicated in the package's config file. See configuration.

Assigning a Role

Basic

To assign a role to a user you can call the assignRole method on a User model instance.

The assignRole method accepts a role (Role model instance), expiresAt a date which is optional and giver an instance Eloquent Model among models registered in configuration which is optional.

The expiresAt value must be a future date.

giver value can omitted when role assigned belongs to a registered model

Via Console

To assign role via console use command below, passing in a registered User's email and a valid Role slug.

For example a user with email [email protected] and a Role named Admin Root with slug admin-root will be:

You can seed the roles and permissions table with the seeder that comes with the package. See Seeding.

Revoking a Role

Revoking a role is the same as assign, where the revokeRoleAt method is called on a User model instance.

The method accepts a role (Role model instance) and expiresAt a date which is optional.

If the expiresAt date is not given the role will be revoked immediately.

Revoking all Roles

To revoke all roles from a user, call the revokeRoles method on a User model instance.

The method accepts an optional array of roles (or a collection of Role model instances).

If no value is passed to method, the user's valid roles will be revoked.

Note: Revoking a role just set's the expired timestamp, not deleting the history of user's roles.

Detaching all Roles

To detach all roles from a user, call the detachRoles method on a User model instance.

The method accepts an optional array of roles (or a collection of Role model instances).

Detaching roles from a user with completely delete the history of user's roles.

Authorization

There are various ways you can authorize a user using the package:

Roles

To check a user has a valid role use the slug of a valid Role model.

The role must be usable (active).

Via User Model

Checking for multiple roles:

Or

Via Blade Helpers

Middleware

You can user the role middleware to check if user has access.

It accepts a role slug and permission slug or name.

In Routes

In Controller

See permissions section to learn how to authorize a user via permissions.

Permissions

To check a user has access via permission use a slug or name of a valid Permission model.

eg. a permission named browse admin can be passed as browse-admin or browse admin.

The permission must be usable (active).

An additional parameter giver is accepted, if you have to check for permissions based on the model that assigned it.

For example, to check a user has a permission through a role of type team:

• You can be pass an instance of Team model
• Or pass a type with a corresponding id: team:1.

Whether the id is a slug or a basic id, it will be resolved by the package.

When passing a type make sure it has a corresponding model registered under the package's config in the models key.

Via Gates

Via User model

Via Blade Helpers

Middleware

Using middleware there are two ways:

In Routes

In Controller

Security Vulnerabilities

If you discover a security vulnerability, please send an e-mail to Cuthbert Mirambo via [email protected]. All security vulnerabilities will be promptly addressed.

Credits

• Cuthbert Mirambo

License

The project is open-sourced software licensed under the MIT license.