 |
VOOZH | about |
|
VOOZH | about |
This page documents the Role model class, which represents a role entity in the permission system. The Role model is a standard Eloquent model that serves as a container for permissions and can be assigned to owner entities (users, teams, etc.).
For information about the database schema that stores roles, see Database Migrations. For details about the Permission model and its relationship with roles, see Permission Model. For comprehensive documentation of permission-checking methods available on the Role model, see HasPermission Trait.
Sources: src/Models/Role.php1-49
The Role model is located at src/Models/Role.php and follows this inheritance hierarchy:
The Role model:
Hypervel\Database\Eloquent\Model - provides standard Eloquent ORM functionalityHypervel\Permission\Contracts\Role - enforces the permissions() method contractHypervel\Permission\Traits\HasPermission - gains permission assignment and checking capabilitiesSources: src/Models/Role.php22-24 src/Contracts/Role.php1-18
The Role model defines the following attributes:
| Attribute | Type | Description | Fillable |
|---|---|---|---|
id | int | Primary key identifier | No |
name | string | Role name (e.g., "admin", "editor") | Yes |
guard_name | string | Authentication guard identifier | Yes |
created_at | Carbon | Timestamp when role was created | No |
updated_at | Carbon | Timestamp when role was last modified | No |
permissions | Collection<Permission> | Related permissions (read-only) | No |
Only name and guard_name are mass assignable through the $fillable property:
Sources: src/Models/Role.php15-32
The Role model defines a many-to-many relationship with the Permission model through the permissions() method.
The relationship is defined at src/Models/Role.php37-47 with the following characteristics:
| Configuration Aspect | Value | Config Key |
|---|---|---|
| Related Model | Permission::class | permission.models.permission |
| Pivot Table | role_has_permissions | permission.table_names.role_has_permissions |
| Foreign Key | role_id | permission.column_names.role_pivot_key |
| Related Key | permission_id | permission.column_names.permission_pivot_key |
| Timestamps | Enabled | N/A |
| Pivot Columns | is_forbidden | N/A |
The relationship includes two important pivot table features:
->withTimestamps()is_forbidden boolean column enables negative permissions (explicit denials) via ->withPivot(['is_forbidden'])When is_forbidden is true, the permission is explicitly denied to the role, overriding any other permission grants.
Sources: src/Models/Role.php37-47 src/Contracts/Role.php14-17
The guard_name attribute links roles to specific authentication guards, enabling multi-tenancy and context-specific authorization.
guard_name values operate independentlyExample: A user might have the "editor" role for the "web" guard and "viewer" role for the "api" guard simultaneously.
Sources: src/Models/Role.php29-32
The Role model uses the HasPermission trait, which provides permission management capabilities. This creates a unique scenario where roles themselves can have permissions.
All methods from the trait are available on Role instances. Key methods include:
| Method | Purpose | Example |
|---|---|---|
hasPermission($permission) | Check if role has a permission | $role->hasPermission('edit-posts') |
givePermissionTo(...$permissions) | Assign permissions to role | $role->givePermissionTo('edit', 'delete') |
revokePermissionTo(...$permissions) | Remove permissions from role | $role->revokePermissionTo('delete') |
syncPermissions($allow, $forbidden) | Replace all permissions | $role->syncPermissions(['edit'], ['delete']) |
giveForbiddenTo(...$permissions) | Explicitly deny permissions | $role->giveForbiddenTo('admin-access') |
getAllPermissions() | Get all permissions | $role->getAllPermissions() |
Sources: src/Models/Role.php24 src/Traits/HasPermission.php26-534
When the HasPermission trait is applied to a Role model, certain behaviors differ from when it's applied to owner models (like Users):
The trait detects when it's being used on a Role via checks like:
Permission via Roles: Roles don't have "permissions via roles" since they are roles
falseCaching Strategy: Roles use the global roles cache instead of owner-specific cache
getAllRolesWithPermissions()Cache Invalidation: Modifying role permissions clears the global cache
clearAllRolesPermissionsCache()Forbidden Permission Checks: Roles bypass role-based forbidden checks
false for Role instancesSources: src/Traits/HasPermission.php64-68 src/Traits/HasPermission.php131-133 src/Traits/HasPermission.php201-203 src/Traits/HasPermission.php279-283 src/Traits/HasPermission.php475-477
The Role model's relationship method uses configuration values for flexibility and customization:
The permissions() method retrieves configuration values at runtime:
| Configuration Key | Default Value | Purpose |
|---|---|---|
permission.models.permission | Permission::class | Class name for Permission model |
permission.table_names.role_has_permissions | role_has_permissions | Pivot table name |
permission.column_names.role_pivot_key | role_id | Foreign key to roles table |
permission.column_names.permission_pivot_key | permission_id | Foreign key to permissions table |
This configuration-driven approach allows customization without modifying the model code. For complete configuration documentation, see Configuration Reference.
Sources: src/Models/Role.php39-44
Sources: src/Models/Role.php1-49 src/Traits/HasPermission.php276-363
Refresh this wiki