Last indexed: 7 February 2026 (4603b0)

Core Permission System

The core authorization system comprises three primary components that work together to provide role-based access control (RBAC) with caching:

HasPermission trait (importance: 20.08): Provides permission checking, assignment, and management methods to owner models
HasRole trait (importance: 5.86): Extends HasPermission to add role assignment and checking capabilities
PermissionManager class (importance: 5.86): Central service managing caching, model resolution, and cross-cutting concerns

These components integrate through dependency injection and shared caching strategies, with PermissionManager serving as the coordination point for cache operations and configuration.

Sources: src/Traits/HasPermission.php17-25 src/Traits/HasRole.php17-24 src/PermissionManager.php15-39

Component Responsibilities

Each core component has distinct responsibilities within the authorization system:

Component	Location	Primary Responsibilities
`HasPermission`	src/Traits/HasPermission.php	Permission checking (`hasPermission`, `hasDirectPermission`, `hasPermissionViaRoles`) Permission assignment (`givePermissionTo`, `giveForbiddenTo`, `revokePermissionTo`) Permission caching (`getCachedPermissions`) Forbidden permission logic
`HasRole`	src/Traits/HasRole.php	Role checking (`hasRole`, `hasAnyRoles`, `hasAllRoles`) Role assignment (`assignRole`, `removeRole`, `syncRoles`) Role caching (`getCachedRoles`) Uses `HasPermission` trait
`PermissionManager`	src/PermissionManager.php	Global roles cache (`getAllRolesWithPermissions`) Owner-specific caching (`cacheOwnerRoles`, `cacheOwnerPermissions`) Cache invalidation (`clearOwnerCache`, `clearAllRolesPermissionsCache`) Model class resolution (`getRoleClass`, `getPermissionClass`) Cache key generation

Sources: src/Traits/HasPermission.php26-534 src/Traits/HasRole.php25-306 src/PermissionManager.php15-224

Architecture Overview

The system implements a trait-based architecture where owner models (User, Team, etc.) gain authorization capabilities by using the provided traits. The PermissionManager class coordinates caching operations and provides model resolution services.

Core Component Architecture

Sources: src/Traits/HasPermission.php26-534 src/Traits/HasRole.php25-306 src/PermissionManager.php15-224

Trait Composition

The HasRole trait extends HasPermission functionality, creating a unified authorization interface:

Sources: src/Traits/HasRole.php27 src/Traits/HasPermission.php26

Permission Evaluation Algorithm

The hasPermission() method implements a hierarchical evaluation algorithm where forbidden permissions take precedence over allowed permissions. This ensures explicit denials override any grants.

Permission Check Flow (hasPermission)

Precedence Order:

Direct forbidden permissions (highest priority)
Role forbidden permissions
Direct allowed permissions
Role allowed permissions (lowest priority)

Sources: src/Traits/HasPermission.php166-178 src/Traits/HasPermission.php457-467 src/Traits/HasPermission.php472-504 src/Traits/HasPermission.php184-194 src/Traits/HasPermission.php199-231

Caching Architecture

The system implements a two-tier caching strategy managed by PermissionManager:

Cache Types and Operations

Cache Level	Cache Key	Stored Data	Managed By	Updated By
Global	`permission.cache.keys.roles`	All roles with their permissions	`getAllRolesWithPermissions()`	`clearAllRolesPermissionsCache()`
Owner-specific (Roles)	`permission.cache.keys.owner_roles:{ownerType}:{ownerId}`	Owner's assigned roles	`cacheOwnerRoles()`	`clearOwnerCache()`
Owner-specific (Permissions)	`permission.cache.keys.owner_permissions:{ownerType}:{ownerId}`	Owner's direct permissions	`cacheOwnerPermissions()`	`clearOwnerCache()`

Sources: src/PermissionManager.php124-135 src/PermissionManager.php140-156 src/PermissionManager.php161-180 src/PermissionManager.php207-223

Cache Access Pattern

Sources: src/Traits/HasPermission.php60-89 src/PermissionManager.php174-180 src/PermissionManager.php196-202

Integration with PermissionManager

Both traits access PermissionManager through dependency injection to coordinate caching operations:

PermissionManager Access Pattern

Trait Method	PermissionManager Call	Purpose
`getCachedPermissions()`	`getOwnerCachedPermissions()`	Retrieve cached permissions
`getCachedPermissions()`	`cacheOwnerPermissions()`	Store permissions on cache miss
`givePermissionTo()`	`clearOwnerCache()`	Invalidate after permission change
`revokePermissionTo()`	`clearOwnerCache()`	Invalidate after permission removal
`syncPermissions()`	`clearOwnerCache()`	Invalidate after sync operation
`getCachedRoles()`	`getOwnerCachedRoles()`	Retrieve cached roles
`getCachedRoles()`	`cacheOwnerRoles()`	Store roles on cache miss
`assignRole()`	`clearOwnerCache()`	Invalidate after role assignment
`removeRole()`	`clearOwnerCache()`	Invalidate after role removal
`syncRoles()`	`clearOwnerCache()`	Invalidate after sync operation