README.md

Brandenburg

Laravel Authorization Package

A opinionated Authorization package to closely integrate with standard Laravel Gates. It differs from other authorization packages by using hard-coded permissions defined within gate policies, rather than duplicating them within the Database.

TLDR; This package provides Users with Roles which are granted access to permissions (Laravel Gates).

Package maintenance

Unfortunately I am no longer actively working in the Laravel ecosystem and as such am unable to maintian this package. If anyone would like to take over the maintenance of the package please get in touch (open an issue or contact me on Twitter).

Version compatibility

Laravel	Brandenburg
<=5.7.x	1.1.x
>=5.8.x	1.2.x
^6.0	1.3.x
^7.0	1.4.x
^8.0	1.5.x

Installation

composer require silvanite/brandenburg

This package uses auto-loading in Laravel 5.5 of both the service provider and the BrandenburgPolicy Facade

For Laravel 5.1 - 5.4 load the Service Provider and Facade.

// config/app.php
'providers' => [
    ...
    Silvanite\Brandenburg\Providers\BrandenburgServiceProvider::class,
];

'aliases' => [
    ...
    'BrandenburgPolicy' => Silvanite\Brandenburg\Facades\PolicyFacade::class,
],

Three additional tables are required to enable User Roles. These will be installed automatically when you run the migrations. See the migration in this repository's source code for details about the tables created.

php artisan migrate

If you are not going to use Brandenburg's default migrations, you should change the ignoreMigrations option in the configuration file. You may export the default migrations using:

php artisan vendor:publish --tag=brandenburg-config

Usage

This package provides two traits. The main trait is intended for your user model which enabled model relationships.

use Silvanite\Brandenburg\Traits\HasRoles;

class User
{
    use HasRoles;
    ...
}

The second Trait ValidatesPermissions can optionally be used in your AuthServiceProvider when writing Gates. It can be used to stop users from getting locked out or to make some permissions optional by allowing access to a permission if no user in the system has been given access to it.

// AuthServiceProvider.php

if ($this->nobodyHasAccess('create-articles')) {
    return true;
};

// Check if the user has access
...

Creating Roles

Use the Silvanite\Brandenburg\Role model to create and manage user roles.

$editor = Silvanite\Brandenburg\Role::create([
    'name' => 'Editor',
    'slug' => 'editor',
]);

Creating Permissions

All Gates defined within your application will automatically be available as Permissions, there is no need/way to create these specifically in the database. Please see the Laravel Gates documentation for additional information.

Managing Roles and Permissions

All permissions are assigned by providing the key defined by your Gate. They can be granted and revoked.

// Grant access
$editor->grant('create-articles');

// Revoke access
$editor->revoke('create-articles');

A couple of additional helper methods provide a convenient way to manage permissions.

// Grant access to a set of permissions and remove all other permissions
$editor->setPermissions([
    'create-articles',
    'read-articles',
    'update-articles',
    'delete-articles',
]);

// Revoke all permissions
$editor->revokeAll();

You can see which permissions a given role has by accessing the permissions attribute.

$editorPermissions = $editor->permissions;

// returns ['create-articles', 'read-articles', 'update-articles', 'delete-articles']

Assigning/Removing Roles

Roles can be assigned/removed directly from the User model (provided the HasRoles trait is used). You can either pass in the Role model or the slug of the role.

// Using slug
$user->assignRole('editor');
$user->removeRole('editor');

// Using model
use Silvanite\Brandenburg\Role;

$user->assignRole(Role::first());
$user->removeRole(Role::first());

There is also a helper method to sync roles (or you can simply use the eloquent relationship itself).

$user->setRolesById([1, 3, 4]);

// Same as
$user->roles()->sync([1, 3, 4]);

Validating Access Rights

Within your Gate definition you can validate if a given user has access to a specific permission, which will be based on the user Role(s).

$canCreateArticle = $user->hasRoleWithPermission('create-articles');

Outside of your Gate definitions you should use the standard Laravel Gate methods and helpers to check if a user has access rights. See the Laravel Documentation for more details.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Run the tests: ./vendor/bin/phpunit
5. Push to the branch: git push origin my-new-feature
6. Submit a pull request

Support

If you require any support please contact me on Twitter or open an issue on this repository.

License

GPL