README

This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.

Installation

You can install the package via composer:

composer require filippo-toso/resource-permissions

You can publish and run the migrations with:

php artisan vendor:publish --tag="resource-permissions-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="resource-permissions-config"

This is the contents of the published config file:

use Carbon\Carbon;
use Illuminate\Support\Str;

return [
    /**
     * The name of the tables used by the package
     */
    'tables' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'permission_role' => 'permission_role',
        'role_user' => 'role_user',
        'permission_user' => 'permission_user',
    ],

    'models' => [
        // @phpstan-ignore-next-line
        'user' => \App\Models\User::class, // Default user class
        'role' => \FilippoToso\ResourcePermissions\Models\Role::class,
        'permission' => \FilippoToso\ResourcePermissions\Models\Permission::class,
    ],

    // Use file finder in production, database finder in development
    'finder' => (env('APP_ENV') == 'production')
        ? \FilippoToso\ResourcePermissions\Finders\Strategies\FileFinder::class
        : \FilippoToso\ResourcePermissions\Finders\Strategies\DatabaseFinder::class,

    // The FileFinder will cache the results into files for a certain amount of time
    'cache' => [
        'folder' => Str::finish(storage_path('app/resource-permissions'), DIRECTORY_SEPARATOR),
        'ttl' => Carbon::SECONDS_PER_MINUTE * Carbon::MINUTES_PER_HOUR * Carbon::HOURS_PER_DAY,
    ],
];

Usage

Add the HasRolesAndPermissions trait to your User model:

use FilippoToso\ResourcePermissions\Models\Concerns\HasRolesAndPermissions;

// ...

class User
{
    use HasRolesAndPermissions;

    // ...
}

Now you can create a user, a permission, and a role. Then assign the permission to the role and assign the role to the user.

$user = User::create([
    'name' => 'John Snow', 
    'email' => 'john.snow@nightswatch.local', 
    'password' => Hash::make('Ygritte'),
]);

$role = Role::create(['name' => 'lord-commander']);

$permission = Permission::create(['name' => 'lead']);

$role->assignPermission($permission);
$user->assignRole($role);

if ($user->hasPermission($permission)) {
    dump('I shall take no wife, hold no lands, father no children...');
}

You can also assign permissions directly to the user:

$user = User::create([
    'name' => 'John Snow', 
    'email' => 'john.snow@nightswatch.local', 
    'password' => Hash::make('Ygritte'),
]);

$permission = Permission::create(['name' => 'lead']);

$user->assignPermission($permission);

if ($user->hasPermission($permission)) {
    dump('I shall wear no crowns and win no glory...');
}

Both hasRole() and hasPermission() methods accept as first parameter:

a role/permission Model instance
the numeric key of the role/permission Model instance
a string with the role/permission name
a BackednEnum with the role/permission name
an array with any of the above

When you assign a role or a permission to a user, you can pass a second $resource parameter. This is the uniqueness of this package. You can assign a role or a permission to a user relative to a specific Eloquent model. For instance a user can be assigned the manager role of an Organization and the owner role of a project.

This second parameter can be:

a Model instance
a ResourceData object (an internal representation of a resource)
an array with a single element where the key is the Model class and the value is the numeric key of the model
an array with any of the above

Testing

composer test

Changelog

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

Credits

Filippo Toso

License

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

filippo-toso / resource-permissions

Maintainers

Details