teksite / authorize
Authorization package for managing roles and permissions in Laravel applications
Requires
- php: ^8.3
- laravel/framework: ^12.0|^13.0
Requires (Dev)
- orchestra/testbench: ^11.0
- phpunit/phpunit: ^11.5|^12.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
A flexible and model-independent authorization package for Laravel.
Teksite Authorize provides a simple way to manage:
- Permissions
- Roles
- Role hierarchy
- Direct model permissions
- Model roles
- Role-based permissions
- Laravel Gates
- Authorization caching
- Super administrator access
- Polymorphic authorization relationships
The package is designed to work with any Eloquent model, not only User.
Features
- Model-independent authorization
- Polymorphic roles
- Polymorphic permissions
- Direct permissions for any Eloquent model
- Role-based permissions
- Multiple roles per model
- Multiple permissions per model
- Permission and role lookup by ID or title
- Laravel Gate integration
- Super administrator support
- Role hierarchy
- Authorization cache with automatic invalidation
- Artisan installation command
- Factory support
- Validation rule helpers
Requirements
- PHP
^8.3 - Laravel
^13.0
The package uses modern features such as typed class constants and PHP attributes on Eloquent models and Artisan commands, so these minimum versions are required.
Installation
Install the package through Composer:
composer require teksite/authorize
Then run the installation command:
php artisan authorize:install
This command:
- copies the authorization migrations into
database/migrations - publishes the configuration file to
config/authorize.php
Existing files are never overwritten.
After that, run:
php artisan migrate
Configuration
The package configuration is available at:
config/authorize.php
Package defaults are always merged, so a published config file only needs to contain the keys you want to override. Keys added in newer package versions keep working without re-publishing.
Example:
<?php return [ /* |-------------------------------------------------------------------------- | Boot Gates |-------------------------------------------------------------------------- */ 'boot_gates' => true, 'boot_gates_in_console' => false, /* |-------------------------------------------------------------------------- | Cache |-------------------------------------------------------------------------- */ 'cache_enabled' => true, 'cache_ttl' => 86400, // 24 hours 'flush_on_save' => true, /* |-------------------------------------------------------------------------- | Cleanup |-------------------------------------------------------------------------- */ 'detach_on_delete' => true, /* |-------------------------------------------------------------------------- | Super Admin |-------------------------------------------------------------------------- */ 'super_admin_role' => 'administrator', /* |-------------------------------------------------------------------------- | Observers |-------------------------------------------------------------------------- */ 'observers' => [ 'permission' => \Teksite\Authorize\Observers\PermissionObserver::class, 'role' => \Teksite\Authorize\Observers\RoleObserver::class, ], ];
Configuration options
boot_gates
Determines whether permissions should be registered as Laravel Gates.
'boot_gates' => true,
Set to false if you do not want the package to register Gates automatically.
boot_gates_in_console
Determines whether authorization Gates should be booted while Laravel is running in console mode.
Default:
'boot_gates_in_console' => false,
This avoids unnecessary database access when running Artisan commands.
Important: queue workers, scheduled tasks and Artisan commands all run in console mode. With the default value, Gate checks (
Gate::allows(),can()) inside queued jobs and commands will deny permission abilities because the Gates are not registered. Set this option totrueif your jobs or commands rely on permission Gates. Direct calls such as$user->hasPermission()are not affected.
cache_enabled
Enables or disables authorization caching.
'cache_enabled' => true,
When disabled, authorization data is loaded directly from the database.
cache_ttl
Defines the authorization cache lifetime in seconds.
'cache_ttl' => 86400,
The default value is 24 hours (86400 seconds).
flush_on_save
Determines whether a model's authorization cache is cleared every time the model is saved.
'flush_on_save' => true,
This is the default for backward compatibility. A model's authorization cache key does not depend on its attributes, so for models that are saved very often (for example, updating last_login_at on every login) you can set it to false to avoid needless cache operations.
Changes made through the package API (assignRole(), syncPermissions(), role/permission changes) always invalidate the cache regardless of this option.
detach_on_delete
Determines whether roles and direct permissions of a model are detached when the model is deleted.
'detach_on_delete' => true,
Polymorphic pivot tables cannot use foreign keys, so without this cleanup the rows of a deleted model would remain. If a primary key is ever reused, the new model would silently inherit the old model's roles and permissions.
For models that use SoftDeletes, assignments are kept on soft delete and detached only on force delete.
super_admin_role
Defines the role that should bypass permission checks.
'super_admin_role' => 'administrator',
If the authenticated or authorized model has this role, permission checks return true.
Set it to null if you do not want to use a super administrator role.
observers
Maps the permission and role models to the observers that keep the authorization cache in sync. Set an entry to null to disable it, or point it to your own class (preferably one that extends the package observer).
Database Structure
The package creates five tables.
auth_permissions
Stores permissions.
| Column | Description |
|---|---|
id |
Permission ID |
title |
Unique permission name |
description |
Optional description |
created_at |
Creation timestamp |
updated_at |
Update timestamp |
Example:
posts.read
posts.create
posts.update
posts.delete
Avoid purely numeric titles (for example
"5"). Numeric strings are interpreted as IDs when checking permissions.
auth_roles
Stores roles.
| Column | Description |
|---|---|
id |
Role ID |
title |
Unique role name |
description |
Optional description |
hierarchy |
Role hierarchy level (lower number = higher authority) |
created_at |
Creation timestamp |
updated_at |
Update timestamp |
Example roles:
administrator
manager
editor
author
The database default for
hierarchyis15, which is a high-authority value. Always sethierarchyexplicitly when creating roles.
auth_permission_role
Connects permissions to roles.
A role can have many permissions, and a permission can belong to many roles.
auth_permission_models
Connects permissions directly to any Eloquent model using a polymorphic relationship.
auth_role_models
Connects roles to any Eloquent model using a polymorphic relationship.
Basic Usage
Add HasAuthorization to a Model
Any Eloquent model can use the authorization system.
For example:
<?php namespace App\Models; use Illuminate\Database\Eloquent\Model; use Teksite\Authorize\Traits\HasAuthorization; class User extends Model { use HasAuthorization; }
The package is not limited to User.
For example:
class Admin extends Model { use HasAuthorization; }
Or:
class Customer extends Model { use HasAuthorization; }
Or:
class Employee extends Model { use HasAuthorization; }
As long as the model is an Eloquent model, it can use the Trait.
Permissions
Creating a Permission
use Teksite\Authorize\Models\Permission; $permission = Permission::create([ 'title' => 'posts.read', 'description' => 'Read posts', ]);
Finding a Permission
By ID:
$permission = Permission::find(1);
By title:
$permission = Permission::where('title', 'posts.read')->first();
Roles
Creating a Role
use Teksite\Authorize\Models\Role; $role = Role::create([ 'title' => 'editor', 'description' => 'Post editor', 'hierarchy' => 50, ]);
Assigning Permissions to a Role
$role->permissions()->sync([ $permission->id, ]);
Multiple permissions can be assigned:
$role->permissions()->sync([ $readPermission->id, $createPermission->id, $updatePermission->id, ]);
Changes made through the permissions() relationship (attach, sync, detach with IDs) automatically invalidate the authorization cache. See Cache Invalidation.
Assigning Roles to a Model
$user->assignRole('editor');
The role can also be specified by ID:
$user->assignRole(1);
Or by Role model:
$user->assignRole($role);
Multiple roles:
$user->assignRole([ 'editor', 'author', ]);
By default, assignRole() replaces the existing roles.
To keep existing roles:
$user->assignRole('editor', false);
Warning: unknown titles and IDs are silently ignored. With the default replace behavior,
assignRole('edtior')(typo) results in an empty list and removes all existing roles of the model. The same applies tosyncPermissions().
Assigning Direct Permissions
Permissions can be assigned directly to a model without using a role.
$user->syncPermissions('posts.delete');
By ID:
$user->syncPermissions(5);
Using a Permission model:
$user->syncPermissions($permission);
Multiple permissions:
$user->syncPermissions([ 'posts.read', 'posts.create', 'posts.update', ]);
By default, existing direct permissions are replaced.
To keep existing permissions:
$user->syncPermissions([ 'posts.read', 'posts.create', ], false);
Matching Rules
hasRole() and hasPermission() accept an ID, a title, a model instance, or an array of those.
- Numeric strings (
"5") are treated as IDs. - Titles are matched exactly and case-sensitively (
'Editor'does not match'editor'), regardless of the database collation. - By default, any requested item is enough.
- With
$any = false, every requested item must be owned. An item that does not exist (for example a typo) counts as not owned, so the check fails.
Checking Roles
Check whether a model has a role:
$user->hasRole('editor');
By ID:
$user->hasRole(1);
Using a Role model:
$user->hasRole($role);
Multiple roles:
$user->hasRole([ 'editor', 'author', ]);
By default, hasRole() checks whether any requested role exists.
To require all roles:
$user->hasRole([ 'editor', 'author', ], false);
Checking Permissions
Check a permission:
$user->hasPermission('posts.read');
By ID:
$user->hasPermission(1);
Using a Permission model:
$user->hasPermission($permission);
Multiple permissions:
$user->hasPermission([ 'posts.read', 'posts.update', ]);
By default, hasPermission() checks whether any requested permission exists.
To require all permissions:
$user->hasPermission([ 'posts.read', 'posts.update', ], false);
Permission Sources
A model can receive permissions from two sources:
- Direct permissions
- Permissions inherited from roles
For example:
User
├── Direct Permissions
│ ├── posts.delete
│ └── users.read
│
└── Roles
└── editor
├── posts.read
├── posts.create
└── posts.update
hasPermission() considers both sources.
Getting Permissions
Get All Permissions
By default, only permission IDs are returned:
$user->getAllPermissions();
Example:
[
1,
2,
3,
]
To get permission titles:
$user->getAllPermissions(false);
Example:
[
1 => 'posts.read',
2 => 'posts.update',
3 => 'posts.delete',
]
Get Direct Permissions
This only returns permissions directly assigned to the model.
$user->getDirectPermissions();
Example:
[
1 => 'posts.delete',
2 => 'users.read',
]
Role permissions are not included.
Get Permissions Through Roles
$user->getPermissionsByRoles();
Example:
[
'editor' => [
1 => 'posts.read',
2 => 'posts.create',
3 => 'posts.update',
],
]
Getting Roles
Get role IDs:
$user->getDirectRoles(true);
Example:
[
1,
2,
]
Get roles with their titles:
$user->getDirectRoles();
Example:
[
1 => 'editor',
2 => 'author',
]
Super Administrator
The package supports a configurable super administrator role.
Configuration:
'super_admin_role' => 'administrator',
If a model has this role:
$user->hasRole('administrator');
then:
$user->hasPermission('anything');
will return:
true
You can also check it directly:
$user->isSuperAdmin();
The bypass also applies to Laravel Gates, but only for abilities that are registered permissions.
Laravel Gates
The package automatically registers every permission as a Laravel Gate.
For example, if the database contains:
posts.read
posts.create
posts.update
posts.delete
you can use:
Gate::allows('posts.read');
Or:
Gate::authorize('posts.update');
In Blade:
@can('posts.delete') <button>Delete</button> @endcan
The Gate internally uses the model's:
hasPermission()
method.
Notes:
- The list of permission names is cached (see
cache_ttl) and is refreshed automatically when a permission is created, renamed or deleted. - Gates are registered when the application boots. In long-running workers (for example Laravel Octane), restart the workers after adding new permissions.
- Gates are not booted in console mode by default. See
boot_gates_in_console.
Route Authorization
Because permissions are registered as Laravel Gates, Laravel's normal authorization features can be used.
Example:
Route::get('/posts', function () { // })->middleware('can:posts.read');
Role Hierarchy
Roles have a hierarchy value. A lower number means higher authority.
For example:
administrator = 10
manager = 30
editor = 50
author = 70
viewer = 90
A model can access (manage) another model or role only when its own hierarchy number is strictly lower than the target's. Equal values are not enough.
The model's strongest (minimum) hierarchy value can be retrieved with:
$user->hierarchy();
The weakest (maximum) value:
$user->hierarchy(false, true);
Both values:
$user->hierarchy(true, true);
returns:
[
'min' => ...,
'max' => ...,
]
null is returned when the model has no roles.
When a model has several roles, the minimum value (the strongest role) is used for comparisons.
Comparing Model Hierarchy
A model can be compared against another authorization model:
$user->canAccessModelByHierarchy($anotherUser);
Possible results:
true
false
or:
null
false is also returned when the current model has no roles. null means the target model does not have a hierarchy value.
The target model must use:
HasAuthorization
Comparing Against a Role
A model can also be compared against a Role:
$user->canAccessRoleByHierarchy('manager');
By ID:
$user->canAccessRoleByHierarchy(2);
Using a Role model:
$user->canAccessRoleByHierarchy($role);
null is returned when the role does not exist.
Authorization Cache
Authorization data is cached by default.
The package caches:
- Model permissions
- Model roles
- Model hierarchy
- Permission Gate list
Cache can be configured using:
'cache_enabled' => true, 'cache_ttl' => 86400,
Clearing Authorization Cache
Clear all authorization caches for a model:
$user->clearAuthorizationCache();
Warming Authorization Cache
You can pre-load authorization information:
$user->warmAuthorizationCache();
This loads:
- Permissions
- Roles
- Hierarchy
into the authorization cache.
Cache Architecture
The package creates model-specific cache keys using the model's morph class and primary key.
Example:
authorize:permissions:App\Models\User:1
authorize:roles:App\Models\User:1
authorize:hierarchy:App\Models\User:1
This prevents collisions between different model types that have the same primary key.
For example:
User #1
Admin #1
will have different authorization cache keys.
Each cached value also carries a global epoch token (stored under authorize:epoch). Changes that affect many models at once (a role or permission is changed, or a role/permission relation changes) simply replace the epoch, which invalidates every cached value in a single cheap operation. Outdated entries are ignored and then expire by TTL. A value that was being computed while an invalidation happened can never be served afterwards.
Because of this, authorization data is always at most as stale as the last invalidation, and never longer than cache_ttl.
Polymorphic Authorization
One of the main features of the package is that authorization is not tied to a specific model.
For example:
$user->assignRole('editor'); $admin->assignRole('administrator'); $customer->syncPermissions('orders.read'); $employee->syncPermissions([ 'reports.read', 'reports.create', ]);
All of these models can use the same authorization system.
This is achieved through Laravel polymorphic relationships.
Model Relationships
Models using HasAuthorization receive:
$user->roles();
and:
$user->permissions();
Both relationships are polymorphic.
Role Relationships
A Role has many permissions:
$role->permissions;
A Role can be assigned to many models through the polymorphic relation.
The pivot of the role/permission relation is the Teksite\Authorize\Models\PermissionRole model.
Permission Relationships
A Permission belongs to many roles:
$permission->roles;
A Permission can also be directly assigned to many models.
Validation Rules
Both Permission and Role provide suggested validation rules.
Permission
Create:
Permission::rules('create');
Update:
Permission::rules('update', $permission->id);
Role
Create:
Role::rules('create');
Update:
Role::rules('update', $role->id);
The Role rules include validation for permissions and hierarchy.
Factories
The package provides factories for Permission and Role.
Permission factory:
Permission::factory()->create();
Multiple permissions:
Permission::factory()->count(10)->create();
Role factory:
Role::factory()->create();
Multiple roles:
Role::factory()->count(5)->create();
Example
A complete example:
use App\Models\User; use Teksite\Authorize\Models\Permission; use Teksite\Authorize\Models\Role; $read = Permission::create([ 'title' => 'posts.read', ]); $create = Permission::create([ 'title' => 'posts.create', ]); $update = Permission::create([ 'title' => 'posts.update', ]); $editor = Role::create([ 'title' => 'editor', 'description' => 'Can manage posts', 'hierarchy' => 50, ]); $editor->permissions()->sync([ $read->id, $create->id, $update->id, ]); $user = User::find(1); $user->assignRole($editor); $user->hasRole('editor'); $user->hasPermission('posts.read'); $user->getAllPermissions();
Direct Permission Example
Roles are not mandatory.
A model can receive permissions directly:
$user->syncPermissions([ 'posts.read', 'posts.update', ]);
Then:
$user->hasPermission('posts.read');
returns:
true
Authorization Flow
The authorization flow can be summarized as:
Model
|
+-- Direct Permissions
|
+-- Roles
|
+-- Permissions
When checking:
$model->hasPermission('posts.update');
the package checks:
1. Do the requested identifiers (ID, title, model) resolve to a valid list?
2. Does the model own the permission(s), directly or through a role?
(any / all, depending on the $any argument)
3. If not, is the model a super administrator?
4. Return the authorization result.
Cache Invalidation
The package clears the relevant caches automatically in these situations:
| Change | What happens |
|---|---|
assignRole() / syncPermissions() |
That model's cache is cleared |
A model using HasAuthorization is saved |
That model's cache is cleared (see flush_on_save) |
A model using HasAuthorization is deleted |
Its cache is cleared and its roles/permissions are detached (see detach_on_delete) |
A Role's title or hierarchy changes, or a Role is deleted |
All authorization caches are invalidated |
A Permission's title changes, or a Permission is deleted |
All authorization caches and the Gate list are invalidated |
| A Permission is created | The Gate list is refreshed |
attach(), sync() or detach($ids) on $role->permissions() or $permission->roles() |
All authorization caches are invalidated |
Changing only the description of a role or permission does not clear any cache.
The following changes bypass Eloquent events, so they are not detected automatically:
$role->permissions()->detach()called without arguments- Changes made with the query builder or raw SQL
- Rows removed by database-level cascades
- Calling
attach()/detach()directly on$model->roles()or$model->permissions()
After such changes, clear the cache manually:
use Teksite\Authorize\Support\AuthorizationCache; // a role or permission changed AuthorizationCache::forgetRole($role); AuthorizationCache::forgetPermission($permission); // a single model changed $user->clearAuthorizationCache();
Artisan Command
Install authorization migrations and the configuration file:
php artisan authorize:install
The command creates:
create_permissions_table.php
create_roles_table.php
inside:
database/migrations
and publishes:
config/authorize.php
Existing files are not overwritten.
Disabling Gate Booting
If you do not want automatic Laravel Gate registration:
'boot_gates' => false,
The model authorization methods such as:
hasPermission()
hasRole()
remain available.
Disabling Cache
To disable authorization caching:
'cache_enabled' => false,
Authorization data will then be resolved directly from the database without using the package cache.
Recommended Permission Naming
It is recommended to use a consistent permission naming convention.
For example:
users.read
users.create
users.update
users.delete
posts.read
posts.create
posts.update
posts.delete
orders.read
orders.create
orders.update
orders.delete
This makes permissions easier to organize and use with Laravel Gates.
Recommended Role Structure
A typical application could use:
administrator
manager
editor
author
viewer
with hierarchy values such as (lower number = higher authority):
administrator = 10
manager = 30
editor = 50
author = 70
viewer = 90
The exact hierarchy values are application-dependent.
Summary
Model Methods
assignRole() syncPermissions() hasRole() hasPermission() getAllPermissions() getDirectPermissions() getPermissionsByRoles() getDirectRoles() isSuperAdmin() hierarchy() canAccessModelByHierarchy() canAccessRoleByHierarchy() clearAuthorizationCache() warmAuthorizationCache()
Model Relationships
roles()
permissions()
Permission Methods
Permission::rules() Permission::factory() $permission->roles()
Role Methods
Role::rules() Role::factory() $role->permissions()
License
This package is open-source software licensed under the MIT license.
Contributing
Contributions, bug reports, feature requests, and pull requests are welcome.
Before submitting a pull request, make sure that:
- The code follows Laravel conventions.
- Existing functionality is not broken.
- New functionality is covered by tests where appropriate.
- Authorization cache behavior is considered for authorization-related changes.
Security
If you discover a security vulnerability, please report it privately to the package maintainer instead of opening a public issue.
Credits
Developed by Teksite.
Package:
teksite/authorize
A model-independent authorization system for Laravel.