README

This package is a part of the Rosalana eco-system. It provides a way to manage user roles and permissions across the Rosalana applications, allowing for a unified and consistent approach to user management.

Note: This package is a extension of the Rosalana Core package.

Installation
Configuration
Features
May Show in the Future
License

Installation

To install the rosalana/roles package, you must first have the rosalana/core package installed. If you haven't installed it yet, please refer to the rosalana/core documentation.

After installing the rosalana/core package, use the rosalana:add command from the Rosalana CLI and select rosalana/roles from the list:

php artisan rosalana:add

After installing the package, you should publish its assets using the following command:

php artisan rosalana:publish

You can specify which files to publish. Publishing the configuration files is required to set up the package properly. Other files are optional and can be published as needed. However, it is recommended to publish all files to take full advantage of the package features.

Configuration

After publishing the package, you will find a rosalana.php configuration file in the config directory of your Laravel application. You can customize these options according to your needs.

This file will grow over time as you add more Rosalana packages to your application. Each package contributes its own configuration section. The rosalana.php file serves as the central configuration hub for all Rosalana packages.

rosalana/roles package provides configuration options for:

enum: The class that defines the Global Roles used in the application. Publish the RoleEnum class to customize it.
auto-migrate: Automatically migrate database if deprecated permissions are detected. This feature is not yet implemented.
banned: An array of roles that are considered banned or suspended. If a user has any of these roles, they are considered suspended and cannot access the application. Leave this empty to disable this automatic suspension.

Features

Roleable Models

The rosalana/roles package allows you to assign and manage roles for users within the context of specific Eloquent models — such as projects, teams, or workspaces.

Unlike traditional RBAC systems where roles are global, this package is designed for context-aware role management. Each user can hold a different role depending on the model they are interacting with.

Defining Roleable Models

To start using roles, you simply add the Roleable trait to any model you want to make roleable:

use Rosalana\Roles\Traits\Roleable;

class Workspace extends Model
{
    use Roleable;
}

The model will automatically gain methods to manage roles, permissions and users associated with it.

$workspace->users(); // associated users
$workspace->roles(); // associated roles
$workspace->roleOf($user); // get the role of a user in this workspace

You can also manage roles and users directly:

$workspace->join($user, 'admin');
$workspace->leave($user);
$workspace->newRole('editor', ['edit', 'view']);
$workspace->hasRole('editor');

Configuring Roleable Models

Each roleable model defines its own role context, making the roles clear, isolated, and easy to manage.

You can define the roleable models behavior with static methods in the model itself:

use Rosalana\Roles\Traits\Roleable;

class Workspace extends Model
{
    use Roleable;

    public static function getUsersPivotTable(): string
    {
        return 'workspace_users'; // default is '{class_name}_users'
    }

    public static function permissions(): array
    {
        return ['view', 'edit', 'delete']; // default is []
    }

    /**
     * Define with roles should be created by new model instance.
     */
    public static function defaultRoles(): array
    {
        return [
            'default' => ['*'], // this is default
        ]
    }

    public static function defaultRole(): string
    {
        return 'default'; // default role name for new users
    }
}

HasRoles Models

Models that should receive roles (typically User) must implement the HasRoles trait.

This trait gives your model the ability to join or leave roleable models, query assigned roles, and check for permissions in context.

Defining HasRoles Models

To make a model able to hold roles, simply add the HasRoles trait:

use Rosalana\Roles\Traits\HasRoles;

class User extends Model
{
    use HasRoles;
}

This enables expressive methods like:

$user->join($workspace, 'admin'); // Assign user to a workspace
$user->leave($workspace); // Remove user from the workspace
$user->roleIn($workspace); // Get the Role model instance
$user->hasRole('admin', $workspace); // Check role in context

You can also perform permission checks:

$user->hasPermission('edit', $workspace); // Check if user can edit in this workspace
$user->hasAnyPermission(['view', 'edit'], $workspace); // Check if user has any of the permissions

The trait uses the internal RolesManager to handle role assignment and validation. All role actions are strictly contextual — they always require a target model.

Role Model

The Role model represents a single role within a specific roleable model.

It contains:

name – the role's unique name (e.g. "admin")
permissions – an array of allowed permissions
roleable_type and roleable_id – the model this role belongs to

You usually don't create roles manually via Role::create(). Instead, use the newRole() method from the roleable model:

$workspace->newRole('editor', ['view', 'edit']);

You can also retrieve and manipulate roles directly:

$role = $workspace->roles()->where('name', 'editor')->first();
$role->addPermission('publish');
$role->removePermission('delete');
$role->setPermissions(['view', 'edit']); // replaces all

The Role model performs validation: It ensures all permissions assigned to the role exist in the roleable model's defined permissions. If not, it throws an exception — preventing invalid permission states.

Permission Helpers

The Role model includes several permission helpers:

$role->hasPermission('edit');                  // true / false
$role->hasPermissions(['view', 'edit']); // true / false
$role->hasAnyPermission(['view', 'delete']);   // true / false
$role->hasAllPermissions(['view', 'edit']); // true / false

These methods resolve wildcards (*) and aliases automatically using the configuration on the roleable model.

Roles Manager

At the heart of the package is a powerful RolesManager class. It provides the full API for assigning, retrieving, and validating roles between users and models.

The manager requires two things:

The roleable model (e.g. Project)
The user you want to check or assign

You can fluently define the context and run any role-related action:

use Rosalana\Roles\Facades\Roles;

$manager = Roles::on($project)->for($user); 
// or Roles::context($project, $user);

$manager->assign('admin'); // assign 'admin' role to user in project
$manager->detach(); // leave the project
$manager->get(); // get the role instance
$manager->is('editor'); // true / false
$manager->can('edit'); // true / false

The assign() method automatically replaces the current role if the user is already assigned. You don’t need to check if the user is a member — it just works.

Suspended Users

The package supports automatic suspension of users based on their assigned Global Role. If a user has a role listed in the banned configuration, they are considered suspended and cannot access the application.

The middleware Rosalana\Roles\Http\Middleware\AccountSuspendedException checks if the user has a banned role and throws an HttpException if they do. This middleware is registered on the web middleware group. Do not forget to logout the user if they are suspended. Otherwise, they will be caught in a redirect loop. You can do this in your bootstrap/app.php.

Laravel Gate Integration

The package automatically integrates with Laravel's Gate system, allowing you to use the can method to check permissions in your controllers and views.

All model-specific permissions are automatically registered with the Gate by scanning the roleable models and their defined permissions. In production environment, this happens only once and then cached for performence. Don't forget to run php artisan cache:clear in your deployment scripts to ensure the cache is cleared after any changes to roles or permissions.

May Show in the Future

Auto-migration: Automatically migrate database if deprecated permissions are detected.

Stay tuned — we're actively shaping the foundation of the Rosalana ecosystem.

License

Rosalana Roles is open-source under the MIT license, allowing you to freely use, modify, and distribute it with minimal restrictions.

You may not be able to use our systems but you can use our code to build your own.

For details on how to contribute or how the Rosalana ecosystem is maintained, please refer to each repository’s individual guidelines.

Questions or feedback?

Feel free to open an issue or contribute with a pull request. Happy coding with Rosalana!

rosalana / roles

Maintainers

Details