Download the PHP package balfour/laravel-custodian without Composer

laravel-custodian

A super lightweight library for handling role based permissions in Laravel.

This library is in early release and is pending unit tests.

Table of Contents

• Why
• Installation
• Configuration
• Configuring User Model
• Usage
  • Creating Roles
  • Registering Permissions
  • Listing Available Permissions
  • Assigning Permissions to Roles
  • Revoking Permissions from Roles
  • Assigning Roles to Users
  • Syncing User Roles
  • Revoking Roles from Users
  • Listing User Roles
  • Retrieving a User's Permissions
  • Authorizing Users

Why?

There are some great existing role based authorization libraries out there, so why another one?

For our internal systems, we wanted something which is:

1. simple to use
2. does not contain all the bells and whistles
3. works with the framework's existing authorization library
4. focuses on performance first
5. elegantly modeled without a plethora of pivot tables - json type works fine!

We've managed to keep things simple and efficient by:

1. creating just 2 tables, a roles table and a role_user table mapping users to roles
2. storing assigned permissions in a json column on the roles table
3. performing just a single database query to retrieve all users, assigned roles & permissions
4. keeping an in-object mapping cache of user -> permissions
5. decorating this mapping cache with an external cache of your choice (memcached, redis, etc)

Installation

Configuration

The package works out the box without any configuration, however if you'd like to publish the config file, you can do so using:

php artisan vendor:publish --provider="Balfour\LaravelCustodian\ServiceProvider"

Custom User Model

The library will try to detect the path of your user model from the auth config's default guard.

If you'd like to use a custom model such as \App\User::class, you can specify a class path in the user_model config value.

An alternative way to set the user model on the fly is via the Balfour\LaravelCustodian\UserModelResolver::setModel(\App\User::class) function.

Super Admins

The admins config value takes an array of email addresses which should be given super admin access on the custodian. This means that these users will automatically pass all gate (permission) checks.

We do not recommend using this outside of testing. You should rather make use of Laravel's Gate::before or Gate::after hooks to accomplish this.

Configuring User Model

Add the HasRoles trait to your user model.

This will establish a relationship between users and roles; and also give you the following utility methods:

Usage

Creating Roles

Registering Permissions

You must register permissions before they can be assigned to roles.

The package does not store available permissions in the database, but instead, registers them against a PermissionRegistrar. This means that permissions must be registered upon bootstrap, such as in your app's AppServiceProvider, or a module/package's ServiceProvider.

Listing Available Permissions

Assigning Permissions to Roles

Revoking Permissions from Roles

Assigning Roles to Users

Syncing User Roles

Revoking Roles from Users

Listing User Roles

Retrieving a User's Permissions

Authorizing Users

The library does not add any special functionality for checking if a user can perform a specific permission (or ability).

Please see the Laravel Authorization documentation for more info on this subject.