PHPackages                             oltrematica/laravel-role-lite - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. oltrematica/laravel-role-lite

ActiveLibrary[Authentication & Authorization](/categories/authentication)

oltrematica/laravel-role-lite
=============================

a lightweight Laravel package that provides simple role management functionality.

v2.0.1(3mo ago)114.8k↓53.7%[1 PRs](https://github.com/Oltrematica/laravel-role-lite/pulls)MITPHPPHP ^8.3CI passing

Since Mar 8Pushed 1w ago1 watchersCompare

[ Source](https://github.com/Oltrematica/laravel-role-lite)[ Packagist](https://packagist.org/packages/oltrematica/laravel-role-lite)[ RSS](/packages/oltrematica-laravel-role-lite/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (7)Dependencies (39)Versions (15)Used By (0)

[![GitHub Tests Action Status](https://github.com/Oltrematica/laravel-role-lite/actions/workflows/run-tests.yml/badge.svg)](https://github.com/Oltrematica/laravel-role-lite/actions/workflows/run-tests.yml/badge.svg)[![GitHub PhpStan Action Status](https://github.com/Oltrematica/laravel-role-lite/actions/workflows/phpstan.yml/badge.svg)](https://github.com/Oltrematica/laravel-role-lite/actions/workflows/phpstan.yml/badge.svg)[![Latest Version on Packagist](https://camo.githubusercontent.com/3d6ea3bb48af9c607e3bc252d0f33047e2b7a0201687eb607a25d4f40dc02543/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6c7472656d61746963612f6c61726176656c2d726f6c652d6c6974652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oltrematica/laravel-role-lite)[![Total Downloads](https://camo.githubusercontent.com/1bf33813cd1e5bc1649d253a98d610f13789d3e7dd3bc0bd89bbbb731a8b2867/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f6c7472656d61746963612f6c61726176656c2d726f6c652d6c6974652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/oltrematica/laravel-role-lite)

Laravel Role Lite
=================

[](#laravel-role-lite)

A lightweight role and permission management package for Laravel applications.

Laravel Role Lite provides a simple, intuitive API for managing roles and permissions. Assign roles to users, attach permissions to roles, and check access throughout your application with minimal configuration. The permissions system is **opt-in**: if you only need roles, skip the permission migrations and the feature stays out of your way.

Prerequisites
-------------

[](#prerequisites)

- Laravel v10, v11, v12, or v13
- PHP 8.3 or higher

Installation
------------

[](#installation)

```
composer require oltrematica/laravel-role-lite
```

Publish and run the role migrations:

```
php artisan vendor:publish --tag=oltrematica-role-lite-migrations
php artisan migrate
```

**Optional — permissions system.** If you also want database-driven permissions, publish and run the permission migrations:

```
php artisan vendor:publish --tag=oltrematica-role-lite-permission-migrations
php artisan migrate
```

Configuration
-------------

[](#configuration)

The default configuration works for most applications. To customise it, publish the config file:

```
php artisan vendor:publish --tag=oltrematica-role-lite-config
```

The published file lives at `config/oltrematica-role-lite.php`.

### Table Names

[](#table-names)

```
'table_names' => [
    'roles'           => 'roles',       // roles table
    'users'           => 'users',       // your users table
    'role_user'       => 'role_user',   // role ↔ user pivot
    'permissions'     => 'permissions', // permissions table (opt-in)
    'role_permission' => 'role_permission', // role ↔ permission pivot (opt-in)
],
```

### Model Names

[](#model-names)

```
'model_names' => [
    // Leave null to auto-detect from auth.providers.users.model
    'user' => null,
],
```

### Permissions Settings

[](#permissions-settings)

```
'permissions' => [
    'cache_ttl'       => 3600,        // seconds; set to 0 to disable caching
    'cache_prefix'    => 'role_lite', // prefix for all cache keys
    'default_actions' => [            // used by Permission::createForModel()
        'view_any', 'view', 'create', 'update', 'delete',
        'restore', 'force_delete', 'delete_any', 'force_delete_any', 'restore_any',
    ],
],
```

---

Roles
-----

[](#roles)

### Setup

[](#setup)

Add the `HasRoles` trait to your `User` model (or any Eloquent model):

```
use Oltrematica\RoleLite\Trait\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}
```

Using a `BackedEnum` for role names is recommended — it keeps role identifiers in one place and prevents typos:

```
enum Role: string
{
    case ADMIN     = 'admin';
    case EDITOR    = 'editor';
    case MODERATOR = 'moderator';
}
```

### Assigning Roles

[](#assigning-roles)

```
// Assign a single role (string or BackedEnum)
$user->assignRole('admin');
$user->assignRole(Role::ADMIN);

// Sync replaces all current roles with the given set
$user->syncRoles('editor', 'moderator');
$user->syncRoles(Role::EDITOR, Role::MODERATOR);

// Remove a role
$user->removeRole('editor');
$user->removeRole(Role::EDITOR);
```

### Checking Roles

[](#checking-roles)

```
// Exact match
$user->hasRole('admin');
$user->hasRole(Role::ADMIN);

// Has all of the given roles
$user->hasRoles('admin', 'editor');
$user->hasRoles(Role::ADMIN, Role::EDITOR);

// Has at least one of the given roles
$user->hasAnyRoles('admin', 'editor');
$user->hasAnyRoles(Role::ADMIN, Role::EDITOR);

// Convenience checks
$user->hasSomeRoles(); // true if user has at least one role
$user->hasNoRoles();   // true if user has no roles
```

---

Permissions
-----------

[](#permissions)

Permissions are stored in the database and assigned to **roles** — not directly to users. A user gains a permission through any of their roles.

### Setup

[](#setup-1)

Add `HasPermissions` to your `User` model. It requires `HasRoles` to also be present:

```
use Oltrematica\RoleLite\Trait\HasRoles;
use Oltrematica\RoleLite\Trait\HasPermissions;

class User extends Authenticatable
{
    use HasRoles, HasPermissions;
}
```

### Creating Permissions

[](#creating-permissions)

```
use Oltrematica\RoleLite\Models\Permission;

// Create a permission with an arbitrary name
Permission::create(['name' => 'publish_posts']);

// Create (or find) a structured permission for a model class and action
// Name format: snake_case(ClassName).action → e.g. "blog_post.create"
$permission = Permission::findOrCreateForModel(BlogPost::class, 'create');
$permission = Permission::findOrCreateForModel(BlogPost::class, 'create', 'Can create blog posts');

// Create the full default action set for a model in one call
// Produces: blog_post.view_any, blog_post.view, blog_post.create, blog_post.update, etc.
$permissions = Permission::createForModel(BlogPost::class);

// Pass a custom action list
$permissions = Permission::createForModel(BlogPost::class, ['view', 'create', 'update']);
```

### Granting and Revoking Permissions

[](#granting-and-revoking-permissions)

Permissions are granted/revoked at the **role** level:

```
use Oltrematica\RoleLite\Models\Role;
use Oltrematica\RoleLite\Models\Permission;

$role       = Role::where('name', 'editor')->first();
$permission = Permission::where('name', 'blog_post.create')->first();

$role->grantPermission($permission);
$role->revokePermission($permission);

// Replace all permissions for a role at once
$role->syncPermissions([$permissionA->id, $permissionB->id]);
```

You can also grant/revoke via the user, which targets the user's first role by default or a specific role:

```
// Grant through the user's first role
$user->givePermissionTo('publish_posts');
$user->givePermissionTo(PostPermission::PUBLISH);

// Grant through a specific role
$editorRole = Role::where('name', 'editor')->first();
$user->givePermissionTo('publish_posts', $editorRole);

// Revoke
$user->revokePermissionTo('publish_posts');
$user->revokePermissionTo('publish_posts', $editorRole);
```

### Checking Permissions

[](#checking-permissions)

```
// Single permission
$user->hasPermissionTo('blog_post.create');
$user->hasPermissionTo(PostPermission::CREATE);

// Any of the given permissions
$user->hasAnyPermission('blog_post.view', 'blog_post.create');

// All of the given permissions
$user->hasAllPermissions('blog_post.view', 'blog_post.create');

// Model + action shorthand (builds "blog_post.create" internally)
$user->canDo(BlogPost::class, 'create');

// Retrieve all permissions granted to the user (across all their roles)
$permissions = $user->getAllPermissions();
```

### Using Permissions in Laravel Policies

[](#using-permissions-in-laravel-policies)

The `ChecksPermissions` trait simplifies writing database-driven policies. It automatically derives the model name from the policy class name (`CustomerPolicy` → `customer`, `ServiceVisitPolicy` → `service_visit`):

```
use Oltrematica\RoleLite\Trait\ChecksPermissions;

class CustomerPolicy
{
    use ChecksPermissions;

    public function viewAny(User $user): bool
    {
        return $this->checkPermission($user, 'view_any');
        // checks: customer.view_any
    }

    public function create(User $user): bool
    {
        return $this->checkPermission($user, 'create');
        // checks: customer.create
    }
}
```

If the model class cannot be inferred from the policy name, pass it explicitly:

```
public function viewAny(User $user): bool
{
    return $this->checkPermission($user, 'view_any', Customer::class);
}
```

You can also resolve the permission name without performing a check:

```
$name = $this->getPermissionName('create');
// → "customer.create"

$name = $this->getPermissionName('create', Order::class);
// → "order.create"
```

### PermissionService and Cache Management

[](#permissionservice-and-cache-management)

`PermissionService` is a singleton that loads all role-permission mappings into a two-tier cache (in-memory + distributed). This means permission checks within the same request never hit the database more than once.

The cache is cleared automatically whenever you call `grantPermission`, `revokePermission`, or `syncPermissions` on a role.

If you need to clear it manually — for example after bulk database operations:

```
use Oltrematica\RoleLite\Services\PermissionService;

app(PermissionService::class)->clearCache();
```

Configure caching behaviour in `config/oltrematica-role-lite.php`:

```
'permissions' => [
    'cache_ttl'    => 3600,        // TTL in seconds; 0 disables the distributed cache
    'cache_prefix' => 'role_lite', // prefix for cache keys
],
```

---

Events
------

[](#events)

The package fires events for role and permission changes that you can listen to in your application.

### Role Events

[](#role-events)

EventFired when`Oltrematica\RoleLite\Events\UserRoleCreated`A role is assigned to a user`Oltrematica\RoleLite\Events\UserRoleDeleted`A role is removed from a user`Oltrematica\RoleLite\Events\UserRoleUpdated`A role assignment is updated### Permission Events

[](#permission-events)

EventFired when`Oltrematica\RoleLite\Events\PermissionGranted`A permission is granted to a role`Oltrematica\RoleLite\Events\PermissionRevoked`A permission is revoked from a roleBoth permission events receive a `PermissionRole` pivot model with `role_id` and `permission_id` properties.

---

Code Quality
------------

[](#code-quality)

### Rector

[](#rector)

```
composer refactor
```

### PhpStan

[](#phpstan)

```
composer analyse
```

### Pint

[](#pint)

```
composer format
```

### Automated Tests

[](#automated-tests)

```
composer test
```

---

Contributing
------------

[](#contributing)

Feel free to contribute by submitting issues or pull requests. We welcome any improvements or bug fixes.

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance91

Actively maintained with recent releases

Popularity29

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity61

Established project with proven stability

 Bus Factor1

Top contributor holds 84.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~56 days

Recently: every ~97 days

Total

8

Last Release

92d ago

Major Versions

v1.0.4 → v2.0.02026-04-04

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/143425497?v=4)[Oltrematica Srl](/maintainers/oltrematica)[@Oltrematica](https://github.com/Oltrematica)

---

Top Contributors

[![mirchaemanuel](https://avatars.githubusercontent.com/u/1971953?v=4)](https://github.com/mirchaemanuel "mirchaemanuel (43 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (4 commits)")

---

Tags

laravelpermissionsRole Managementoltrematica

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/oltrematica-laravel-role-lite/health.svg)

```
[![Health](https://phpackages.com/badges/oltrematica-laravel-role-lite/health.svg)](https://phpackages.com/packages/oltrematica-laravel-role-lite)
```

###  Alternatives

[spatie/laravel-permission

Permission handling for Laravel 12 and up

12.9k102.4M1.4k](/packages/spatie-laravel-permission)[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k3.9M130](/packages/bezhansalleh-filament-shield)[spatie/laravel-passkeys

Use passkeys in your Laravel app

471890.7k39](/packages/spatie-laravel-passkeys)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[chiiya/filament-access-control

Admin user, role and permission management for Laravel Filament

21852.5k](/packages/chiiya-filament-access-control)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)