Download the PHP package damianulan/laravel-sentinel without Composer

Laravel Sentinel

Laravel Sentinel is a context-aware roles and permissions package for Laravel.

Its core idea is simple:

• roles can be assigned globally or within a specific context
• permissions can be assigned directly to a user
• permissions can also be inherited through roles
• permission checks can optionally receive an Eloquent model instance as context

This makes it useful for applications where a user may have one role in one model context and a different role elsewhere, for example per-project, per-campaign, or per-team access control.

Requirements

• PHP ^8.3
• illuminate/support ^9.0|^10.0|^11.0|^12.0

Installation

Install the package:

Publish the package assets:

Available publish tags:

Run the published migrations:

Generate the two application warden classes used to define your platform's roles and permissions:

Then synchronize those definitions into the database:

Run sentinel:run every time you add, remove, or change role and permission definitions.

How Sentinel Works

Sentinel has four main layers:

1. Warden classes in App\Warden define your canonical roles and permissions as constants and configuration arrays.
2. sentinel:run reads those classes and seeds the roles, permissions, and roles_permissions tables.
3. Your authenticatable model uses Sentinel\Traits\HasRolesAndPermissions.
4. Runtime checks use direct permissions, inherited role permissions, and optional model context.

Database Structure

Published migrations create these tables:

• roles
• permissions
• roles_permissions
• has_roles
• has_permissions

Important pivots:

• has_permissions stores direct permission assignments per morphable model
• has_roles stores role assignments per morphable model and per morphable context

That means a user can have the same role multiple times, each attached to a different context.

Setup

1. Add the trait to your user model

2. Define roles in App\Warden

Generated roles classes extend Sentinel\Config\Warden\RoleWarden.

Example:

Key methods:

• values(): all declared constants plus optional extra items
• assignable(): roles allowed for platform assignment flows
• admins(): roles treated as admin roles by isAdmin()
• labels(): optional slug-to-label mapping

3. Define permissions in App\Warden

Generated permissions classes extend Sentinel\Config\Warden\PermissionWarden.

Example:

Meaning of the assignment arrays:

• ['*']: attach permission to every role
• ['admins']: attach permission to every role returned by RolesLib::admins()
• [RolesLib::ADMIN, RolesLib::MEMBER]: attach permission only to those explicit roles

Important distinction:

• assignable() creates permissions marked as assignable in the database
• nonassignable() creates permissions that still exist and can still be checked, but are not meant for regular UI assignment flows

4. Seed the definitions

Once your warden classes exist:

What sentinel:run does:

• loads the role and permission wardens from App\Warden
• creates missing roles
• creates missing permissions
• attaches permissions to roles
• deletes outdated roles and permissions that no longer exist in the warden classes
• flushes Sentinel's internal cache

Runtime API

The main runtime API lives on the model using HasRolesAndPermissions.

Role relationships and assignment

Roles are assigned either:

• globally through the default context
• specifically to an Eloquent model instance used as the context

Example context model:

You can also assign by role ID or role model:

Revoke role assignments:

Inspect roles:

Direct permissions

Direct permissions are stored separately from role-based permissions.

Inspect direct permission assignments:

hasPermission() only checks direct permission assignments. It does not resolve inherited permissions or context.

Permission checks

Use hasPermissionTo() for the normal application-facing check.

It supports:

• direct permissions
• permissions inherited through roles
• optional model context
• wildcard-style prefix matching using permission-*
• automatic root bypass

Examples:

Behavior notes:

• If the user has the configured root role, hasPermissionTo() always returns true
• If a context is provided, Sentinel checks roles attached to that specific context and also roles attached to the default system context
• If no context is provided, Sentinel checks direct permissions and global role-derived permissions

Admin and root helpers

• isAdmin() checks any role returned by your RoleWarden::admins() definition
• isRoot() checks the slug configured at sentinel.root

Query scopes

The trait also adds scopes:

withPermission() matches both direct permissions and permissions inherited through roles.

Contexts

Sentinel's distinguishing feature is context-aware role assignment.

The default context class is configured in config/sentinel.php:

The built-in System context implements Sentinel\Contracts\DefaultContext and returns key 0.

This means a role assigned without an explicit model context becomes a system-wide role:

To check permissions in a specific context:

You can replace the default context class in config as long as it implements Sentinel\Contracts\DefaultContext.

Gate Integration

Sentinel registers a Gate::before() callback in its service provider.

That means standard Laravel authorization checks can automatically resolve through hasPermissionTo() when the authenticated user exposes that method.

Examples:

The first Eloquent model found in the gate arguments is treated as the Sentinel context.

This makes Sentinel compatible with many normal Laravel authorization flows without writing a separate policy for every permission slug.

Blade Directives

Sentinel registers three Blade conditionals:

Models

Sentinel\Models\Role

Useful methods:

Relationships:

• permissions()

Sentinel\Models\Permission

Useful methods:

Relationships:

• roles()

Configuration

Published config file: config/sentinel.php

Main options:

What these options control:

• default_context: global role context used when no model context is provided
• models.role / models.permission: override the Eloquent models used by Sentinel
• root: the role slug that bypasses all permission checks
• cache.*: cache used to store discovered Warden namespaces

Cache Behavior

Sentinel caches the detected warden classes:

• rolesLib
• permissionsLib

These values are flushed automatically when sentinel:run completes.

If you move or rename your App\Warden classes and want to clear cache manually, rerun:

Middleware

The package includes middleware classes:

• Sentinel\Http\Middleware\RoleMiddleware
• Sentinel\Http\Middleware\PermissionMiddleware

Behavior:

• RoleMiddleware checks Auth::user()->hasRole($role)
• PermissionMiddleware checks Auth::user()->cannot($permission, $context)

Example registration in Laravel 11+:

Example usage:

If you need context-aware permission middleware, pass the appropriate argument pattern for your application or prefer standard Laravel gate checks inside controllers/services where the actual model instance is available.

Testing Helper

The package includes a small testing concern:

Typical Example

A user can be a global admin and also a project-scoped manager:

Another project will not automatically inherit the project-scoped role:

Warden Discovery Rules

Sentinel looks for role and permission wardens under App\Warden by scanning Composer's autoload classmap and finding concrete subclasses of:

• Sentinel\Config\Warden\RoleWarden
• Sentinel\Config\Warden\PermissionWarden

If Sentinel cannot find one of these classes, it throws:

• Role Warden class is not declared in the project!
• Permission Warden class is not declared in the project!

If class discovery seems stale after adding or renaming warden classes, refresh Composer autoload metadata:

Caveats

• Context applies to roles, not to direct permissions
• hasPermission() checks only direct permissions; use hasPermissionTo() for normal authorization decisions
• sentinel:run removes database roles and permissions that are no longer present in your warden definitions
• Middleware can only be context-aware when the relevant model instance is actually available to the middleware

License

MIT. See LICENSE.

Contact

Questions and contributions: [email protected]