README

Laravel RBAC

Enhance Laravel 11 with opinionated extension for spatie/laravel-permissions. Before your permission list grows and maintenance becomes an issue, this package offers simple way of defining roles and their permissions.

Installation

You can install the package via composer:

composer require binary-cats/laravel-rbac

You can publish the config file with:

php artisan vendor:publish --tag="rbac-config"

This is the contents of the published config file:

return [
    /*
    |--------------------------------------------------------------------------
    | Role base access reset control
    |--------------------------------------------------------------------------
    |
    | When running rbac:reset those commands will be executed in sequence
    |
    */

    'jobs' => [
        \BinaryCats\LaravelRbac\Jobs\FlushPermissionCache::class,
        \BinaryCats\LaravelRbac\Jobs\ResetPermissions::class,
        \BinaryCats\LaravelRbac\Jobs\SyncDefinedRoles::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Role base access ability set
    |--------------------------------------------------------------------------
    |
    | Place your ability files in this folder, and they will be auto discovered
    |
    */
    'path' => app()->path('Abilities'),

    /*
    |--------------------------------------------------------------------------
    | Defined Roles
    |--------------------------------------------------------------------------
    |
    | Defined roles are immutable by users
    |
    */

    'roles' => [

    ],
];

Usage

php artisan rbac:reset

In a simple setup we usually have two basic parts of an RBAC: a permission and a role. Permissions are usually grouped by functional or business logic domain and a Role encapsulates them for a specific guard.

Create Abilities
Define Roles
Connect the dots

Abilities

To avoid collision with spatie/laravel-permission we are going to use BackedEnum Ability enums to hold out enumerated permissions: You can read more on using enums as permissions at the official docs.

To create an Ability:

php artisan make:ability PostAbility

This will generate a PostAbility in App\Abilities:

namespace App\Abilities;

enum PostAbility: string
{
    case ViewPost = 'view post';
    case CreatePost = 'create post';
    case UpdatePost = 'update post';
    case DeletePost = 'delete post';
}

Default stub contains fairly standard CRUD enumeration, generated using the name of the ability. Feel free to publish the stubs and adjsut as needed.

Defined Roles

As the name suggests, a DefinedRole offers a mechanism to simplify the definition of all permissions needed for a given role. To create an EditorRole run:

php artisan make:role EditorRole

This will generate an EditorRole within App\Roles:

use BinaryCats\LaravelRbac\DefinedRole;

class EditorRole extends DefinedRole
{
    /** @var array|string[]  */
    protected array $guards = [
        'web'
    ];

    /**
     * List of enumerated permissions for the `web` guard
     *
     * @return array
     */
    public function web(): array
    {
        return [];
    }
}

This class contains a (now testable!) configuration definition for the role and its web guard. Pretty neat! We can now adjust it like so:

namespace App\Roles;

use App\Abilities\PostAbility;
use BinaryCats\LaravelRbac\DefinedRole;

class EditorRole extends DefinedRole
{
    /** @var array|string[]  */
    protected array $guards = [
        'web'
    ];

    /**
     * List of enumerated permissions for the `web` guard
     *
     * @return array
     */
    public function web(): array
    {
        return [
            PostAbility::CreatePost,
            PostAbility::UpdatePost,
            PostAbility::ViewPost,
        ];
    }
}

Now you are confident a specific role has specific permissions!

Connect the dots

Now that we have the abilities and roles, simply register role with rbac.php config:

    'roles' => [
        \App\Roles\EditorRole::class,
        ...
    ],

When you run rbac:reset next time, your RBAC will be reset automatically.

Integration

I suggest adding the script to post-autoload-dump of your composer.json to make sure the RBAC is reset on every composer dump:

        "post-autoload-dump": [
            "Illuminate\\Foundation\\ComposerScripts::postAutoloadDump",
            "@php artisan rbac:reset"
        ],

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email cyrill.kalita@gmail.com instead of using issue tracker.

Postcardware

You're free to use this package, but if it makes it to your production environment we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Credits

License

The MIT License (MIT). Please see License File for more information.

binary-cats / laravel-rbac

Maintainers

Details