Permission Model

This page documents the Permission model, which represents individual permissions in the authorization system. A permission is a discrete authorization unit (e.g., "edit-post", "delete-user") that can be assigned directly to owners or grouped into roles.

For information about the Role model and its relationship with permissions, see Role Model. For the database schema that stores permissions, see Database Migrations.

Purpose and Scope

The Permission model is an Eloquent model that:

• Represents individual permission records stored in the database
• Defines a many-to-many relationship with roles through a pivot table
• Integrates with the HasRole trait to enable permissions to have roles assigned
• Supports guard-based segmentation for multi-authentication contexts
• Enables the is_forbidden flag through pivot table attributes

Sources: src/Models/Permission.php1-48

Model Class Structure

The Permission model extends Hypervel\Database\Eloquent\Model and implements the PermissionContract interface.

Sources: src/Models/Permission.php22-24 src/Contracts/Permission.php1-18

Model Attributes

The Permission model defines the following properties:

Attribute	Type	Description	Mass Assignable
id	int	Primary key identifier	No
name	string	Unique permission name (e.g., "edit-post")	Yes
guard_name	string	Authentication guard this permission belongs to	Yes
created_at	Carbon	Timestamp when permission was created	No
updated_at	Carbon	Timestamp when permission was last modified	No

Mass Assignment Configuration

The model specifies mass assignable attributes via the $fillable property:

src/Models/Permission.php29-32

Only name and guard_name can be mass-assigned. The id and timestamp fields are protected from mass assignment vulnerabilities.

Sources: src/Models/Permission.php15-32

Roles Relationship

The Permission model defines a many-to-many relationship with roles through the roles() method:

Relationship Configuration

The roles() method returns a BelongsToMany relationship configured as follows:

Configuration	Value	Source
Related Model	config('permission.models.role')	Configurable, defaults to Role::class
Pivot Table	config('permission.table_names.role_has_permissions')	Configurable, defaults to 'role_has_permissions'
Foreign Key	config('permission.column_names.permission_pivot_key')	Configurable, defaults to 'permission_id'
Related Key	config('permission.column_names.role_pivot_key')	Configurable, defaults to 'role_id'
Pivot Columns	is_forbidden, created_at, updated_at	Accessed via ->withPivot() and ->withTimestamps()

src/Models/Permission.php37-47

Pivot Table Attributes

The relationship includes access to pivot table attributes:

• is_forbidden: A boolean flag indicating whether this permission is explicitly denied when assigned through this role. When true, the permission acts as a negative permission (explicit denial).
• created_at / updated_at: Timestamps for when the permission-role relationship was created or modified.

Sources: src/Models/Permission.php37-47

HasRole Trait Integration

The Permission model uses the HasRole trait, which provides role management capabilities. This creates a unique situation where permissions can themselves have roles assigned.

Trait Methods Available

Through the HasRole trait, a Permission instance gains these methods:

Method	Purpose	Return Type
roles()	Define morphToMany relationship to roles	MorphToMany
hasRole()	Check if permission has a specific role	bool
hasAnyRoles()	Check if permission has any of specified roles	bool
hasAllRoles()	Check if permission has all specified roles	bool
assignRole()	Assign roles to the permission	static
removeRole()	Remove roles from the permission	static
syncRoles()	Synchronize permission's roles	array
getCachedRoles()	Get roles with caching	Collection

Dual Relationship System

The Permission model has two distinct role relationships:

1. roles() from the model itself src/Models/Permission.php37-47: Returns roles that have this permission assigned to them (via role_has_permissions table). This is a BelongsToMany relationship.

2. roles() from HasRole trait src/Traits/HasRole.php87-96: Returns roles assigned to this permission as an owner (via owner_has_roles table). This is a MorphToMany relationship.

The model's own roles() method takes precedence, so the trait's roles() method is effectively overridden. The trait's role management methods (assignRole(), hasRole(), etc.) still function and operate on the owner_has_roles polymorphic table.

Sources: src/Models/Permission.php24 src/Traits/HasRole.php1-306

Guard Name System

The guard_name attribute enables multi-guard support, allowing permissions to be segmented by authentication context.

Guard-Based Segmentation

Permissions with different guard_name values are isolated from each other:

Use Case	Example guard_name	Purpose
Web Authentication	"web"	Permissions for web-authenticated users
API Authentication	"api"	Permissions for API-authenticated requests
Admin Panel	"admin"	Separate permission namespace for administrators
Custom Guards	"tenant_guard"	Application-specific authentication contexts

Guard Matching

The authorization system uses guard_name to:

1. Match permissions to the current authentication guard
2. Filter permission queries to only relevant permissions
3. Prevent cross-guard permission leakage

The guard_name is typically set when creating a permission and should match one of the authentication guards defined in the application's authentication configuration.

Sources: src/Models/Permission.php16-17 src/Models/Permission.php29-32

Database Representation

The Permission model maps to the permissions table in the database. The table name is determined by configuration but defaults to "permissions".

Table Structure

Unique Constraint

The combination of name and guard_name must be unique. This ensures:

• No duplicate permission names within the same guard
• Different guards can have permissions with the same name
• Prevents accidental permission duplication

Configuration References

The Permission model respects these configuration values:

Configuration Key	Default Value	Usage in Model
permission.models.role	Role::class	Related model in roles() relationship
permission.table_names.role_has_permissions	"role_has_permissions"	Pivot table name
permission.column_names.permission_pivot_key	"permission_id"	Foreign key column
permission.column_names.role_pivot_key	"role_id"	Related key column

These configurations allow customization without modifying the model class. See Configuration Reference for complete configuration options.

Sources: src/Models/Permission.php37-47

Contract Implementation

The Permission model implements the PermissionContract interface, which defines the minimum contract:

src/Contracts/Permission.php1-18

The interface requires only the roles() method, establishing the minimum API that any permission implementation must provide. This allows for potential alternative implementations while maintaining compatibility with the authorization system.

Sources: src/Contracts/Permission.php9-18