README

Laravel Permissions

This is a package to integrate with Laravel 5.5 - 5.8

Installation

Require this package with composer:

composer require denismitr/laravel-permissions

After updating composer, add the PermissionsServiceProvider to the providers array in config/app.php like so:

Denismitr\Permissions\PermissionsServiceProvider::class,

Then if you need to use one of the provided middleware, you can add a auth.group middleware to your Http Kernel.php like so:

'auth.group.all' => \Denismitr\Permissions\Middleware\AuthGroupAllMiddleware::class,
'auth.group.any' => \Denismitr\Permissions\Middleware\AuthGroupAnyMiddleware::class,

This one insures that user belongs to all required auth groups

Publish config and migrations

php artisan vendor:publish

and pick Provider: Denismitr\Permissions\PermissionsServiceProvider from the list

Migration

Then run php artisan migrate and the following 5 tables will be created:

auth_groups
permissions
auth_group_users
auth_group_permissions

Creating the CRUD and populating these tables is up to you.

Usage

First include InteractsWithAuthGroups trait into the User model like so:

use InteractsWithAuthGroups;

To add users to an AuthGroup and give them group permissions:

// Given we have
AuthGroup::create(['name' => 'superusers']);

// To find an auth group by name
AuthGroup::named('superusers')->addUser($userA)->addUser($userB);

$userA->isOneOf('superusers'); //true
$userB->isOneOf('superusers'); // true

// Gives permission to the choosen group
AuthGroup::named('superusers')->givePermissionTo($editArticlesPermission);
AuthGroup::named('superusers')->givePermissionTo($editBlogPermission);

// These methods check if user has a permission through any auth group,
// to which user belongs
$userA->hasPermissionTo('edit-articles'); // true
$userA->isAllowedTo('edit-blog'); // true

$userB->hasPermissionTo('edit-blog'); // true
$userB->isAllowedTo('edit-articles'); // true

Check if auth group already exists

AuthGroup::existsWithName('accountants'); // returns true or false

Private groups and/or teams

User can create private groups or basically teams. Note that there is a canOwnAuthGroups method on InteractsWithAuthGroups trait that returns true by default. If you want to define some custom rules on whether this or that user is allowed to create auth groups, which you probably do, you need to override that method in your user model.

$privateGroup = $this->owner->createNewAuthGroup('My private group', 'My private group description');

$privateGroup
    ->addUser($this->userA)
    ->addUser($this->userB); // Custome role can be specified ->addUser($this->userB, 'accountant');
    
$authGroup->hasUser($this->userA); // true
$authGroup->isOwnedBy($this->owner); // true
$this->owner->ownsAuthGroup($authGroup); // true

$authGroup->forUser($this->userA)->allowTo('edit-articles');

Roles

roles are just strings and they are supposed to be used just as additional helpers.

$user->onAuthGroup($privateGroup)->getRole(); // Owner (this one can be setup in config of the package)

$user->joinAuthGroup($bloggers, 'Invited user');
$user->joinAuthGroup($editors, 'Supervisor');

$user->onAuthGroup($editors)->getRole(); // 'Invited user'
$user->onAuthGroup($privateGroup)->getRole(); // 'Supervisor'

$user->onAuthGroup($bloggers)->hasRole('Invited user'); // true
$user->onAuthGroup($editors)->hasRole('Supervisor'); // true
$user->onAuthGroup($privateGroup)->hasRole('Pinguin'); // false

To withdraw permissions

$authGroup->revokePermissionTo('delete post', 'edit post');

Grant permission through auth group:

$admin->joinAuthGroup('admins'); // group must already exist

$admin->onAuthGroup('admins')->grantPermissionTo('administrate-blog'); // permission must already exist
// same as
$admin->onAuthGroup('admins')->allowTo('administrate-blog'); // permission must already exist
// or
$admin->onAuthGroup('admins')->givePermissionTo('administrate-blog');

// later

$blogAdminPermission->isGrantedFor($this->admin);

To check for permissions:

$user->hasPermissionTo('edit post', 'delete post');
$user->can('delete post');

Attention!!! for compatibility reasons the can method can support only single ability argument

Current AuthGroup

User can have a current auth group, via a current_auth_group_id column that is being added to the users table by the package migrations. This feature can be used to emulate switching between teams for example.

// Given
$user = User::create(['email' => 'new@user.com']);
$authGroupA = AuthGroup::create(['name' => 'Auth group A']);
$authGroupB = AuthGroup::create(['name' => 'Auth group B']);

// Do that
$user->joinAuthGroup($authGroupA);
$user->joinAuthGroup($authGroupB);

// Expect user is on two authGroups
$user->isOneOf($authGroupA); // true
$user->isOneOf($authGroupB); // true

// Do switch to authGroupB
$user->switchToAuthGroup($authGroupB);

// currentAuthGroup() method returns a current AuthGroup model or null in case user is
// not a member of any group
// currentAuthGroupName() works in the same way and can be used to display current team or group name
$user->currentAuthGroup(); // $authGroupB
$user->currentAuthGroupName(); // Auth group B

Note that in case user belongs to one or more auth groups the currentAuthGroup() method will automatically choose and set one of the users auth group as current, persist it on User model via current_auth_group_id column and return it. The same applies to currentAuthGroupName().

Plus a bonus a blade authgroup and team directives:

@authgroup('staff')
// do stuff
@endauthgroup

And it's alias

@team('some team')
// do stuff
@endteam

Some other directives

@isoneof('admins')
...
@endisoneof

@isoneofany('writers|bloggers')
...
@endisoneofany

@isoneofall('authors,writers,bloggers')
...
@endisoneofall

Author

Denis Mitrofanov

denismitr / laravel-permissions

Maintainers

Details