trait HasPermissions

Traits

Build Permission relations from one immutable partition and team snapshot.

Methods

permissionBelongsToMany(string $related, string $table, string $foreignPivotKey, string $relatedPivotKey, string $relationName, PermissionRelationContext|null $context = null)

Build a partition-aware belongs-to-many relation.

permissionMorphToMany(string $related, string $table, string $foreignPivotKey, string $relatedPivotKey, string $relationName, bool $inverse = false, bool $teamScoped = false, PermissionRelationContext|null $context = null)

Build a partition-aware morph-to-many relation.

permissionRelationQuery(Model $related, PermissionPartition|null $partition)

Build the related query using the relation's captured partition.

void
ensurePermissionRelationParentMatches(PermissionRegistrar $registrar, PermissionPartition|null $partition)

Ensure a partition-bearing relation parent belongs to the captured partition.

applyPermissionPartitionToRelation(BelongsToMany $relation, PermissionPartition|null $partition)

Apply the captured partition to pivot reads and writes.

permissionRegistrar()

Get the permission registrar.

eventDispatcher()

Get the event dispatcher.

static void
bootHasPermissions()

Boot permission cleanup and queued assignment handling.

int|bool|null
delete()

Delete the model and its permission assignments atomically.

static bool
shouldDeletePermissionAssignments(Model $model)

Determine whether deleting the model removes permission assignments.

static array|null
deleteSubjectAssignments(string $morphType, mixed $modelKey, string $table)

Delete one kind of assignment for a hard-deleted subject.

static void
deletePermissionRecordAssignments(mixed $modelKey, string $modelAssignmentsTable, string $pivotKey, PermissionPartition|null $partition)

Delete assignment pivots owned by a Role or Permission record.

static PermissionPartition|null
permissionRecordDeletionPartition(Model $model, PermissionRegistrar $registrar)

Resolve and validate a permission record's deletion partition.

string
getPermissionClass()

Get the permission model class.

string
getWildcardClass()

Get the wildcard permission class.

permissions()

A model may have multiple direct permissions.

permissionAssignmentRelation(PermissionRelationContext|null $context = null)

Build the direct permission assignment relation for a captured context.

permissionRelationContext(BelongsToMany $relation)

Get the immutable context captured by a permission assignment relation.

void
forgetStalePermissionRelation(PermissionRegistrar $registrar, string $relation)

Forget an assignment relation loaded for an earlier context.

getCachedDirectPermissions()

Get cached direct permission assignments for this model.

directPermissionsForModelResult()

Get direct permissions for a model-returning public API.

allowedDirectPermissions()

Return allowed direct permissions.

scopePermission(Builder $query, array|Collection|int|Permission|string|UnitEnum $permissions, bool $without = false)

Scope the model query to certain permissions only.

whereEffectivePermission(Builder $query, array $permissionIds)

Add an effective permission predicate for the given permission ids.

wherePermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a permission-effect predicate for direct and role-granted permissions.

whereDirectPermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a direct permission-effect predicate.

whereRolePermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a role permission-effect predicate.

scopeWithoutPermission(Builder $query, array|Collection|int|Permission|string|UnitEnum $permissions)

Scope the model query to only those without certain permissions, whether indirectly by role or by direct permission.

array
convertToPermissionModels(array|Collection|int|Permission|string|UnitEnum $permissions)

Convert the given permissions to permission models.

filterPermission(mixed $permission, string|null $guardName = null)

Find a permission.

bool
hasPermissionTo(mixed $permission, string|null $guardName = null)

Determine if the model may perform the given permission.

bool
hasWildcardPermission(mixed $permission, string|null $guardName = null)

Validates a wildcard permission against all permissions of a user.

bool
checkPermissionTo(mixed $permission, string|null $guardName = null)

An alias to hasPermissionTo(), but avoids throwing an exception.

bool
hasAnyPermission(mixed ...$permissions)

Determine if the model has any of the given permissions.

bool
hasAllPermissions(mixed ...$permissions)

Determine if the model has all of the given permissions.

bool
hasPermissionViaRole(Permission $permission)

Determine if the model has, via roles, the given permission.

bool
hasDirectPermission(mixed $permission)

Determine if the model has the given permission.

getPermissionsViaRoles()

Return all the permissions the model has via roles.

getAllPermissions()

Return all the permissions the model has, both directly and via roles.

getDeniedPermissions()

Return all the permissions the model is denied, both directly and via roles.

givePermissionTo(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Grant the given permission(s) to the model.

denyPermissionTo(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Deny the given permission(s) for the model.

string
assignmentIdIdentity(int|string $id)

Build a collision-safe assignment ID identity.

array
indexAssignmentIds(array $ids)

Index assignment IDs by their collision-safe identities.

int|string
normalizeRelatedPivotId(BelongsToMany $relation, mixed $id)

Normalize an ID read directly from an assignment pivot.

readCurrentAssignmentPivots(BelongsToMany $relation, array $columns, array|null $ids = null)

Read current assignment pivots through their captured relation constraints.

void
queuePermissionAssignments(array $permissions, bool $isDenied, PermissionRelationContext $context, string $pivotClass)

Queue permission assignments until the model is saved.

void
removeQueuedPermissionAssignments(array $permissions, PermissionRelationContext $context)

Remove permission assignments queued for a captured context.

void
flushQueuedPermissionAssignments()

Flush permission assignments queued before the model was saved.

void
attachQueuedPermissionAssignments(array $assignments)

Insert queued permission assignments, with one insert per context and effect.

void
dispatchPermissionAttachedEvent(array $permissions)

Dispatch the permission attached event when enabled and listened for.

bool
permissionAttachedEventIsListenedFor()

Determine whether the permission attached event has listeners.

void
forgetWildcardPermissionIndex()

Forget the wildcard permission index.

syncPermissions(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Remove all current permissions and set the given ones.

array
syncPermissionEffects(array|Collection $allowed = [], array|Collection $denied = [])

Remove all current permissions and set allowed and denied permissions.

revokePermissionTo(array|Collection|int|Permission|string|UnitEnum $permission)

Revoke the given permission(s).

void
dispatchPermissionDetachedEvent(mixed $permission)

Dispatch the permission detached event when enabled and listened for.

bool
permissionDetachedEventIsListenedFor()

Determine whether the permission detached event has listeners.

bool
hasDeniedPermission(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if the model has an explicit denied direct permission.

bool
hasDeniedPermissionViaRoles(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if the model has an explicit denied permission via roles.

getPermissionsViaRolesWithPivots()

Return permissions granted through the model's roles with role-permission pivot data.

loadPermissionsViaRolesWithPivots()

Load permissions granted through the model's roles with role-permission pivot data.

Model|null
permissionForMatch(int|Permission|string|UnitEnum $permission, string $guardName)

Resolve a permission for matching without throwing.

array
deniedPermissionKeys(Collection ...$permissionCollections)

Build lookup keys for denied permissions.

string
permissionComparisonKey(Model $permission)

Build a permission comparison key.

permissionWithRolePivot(Model $permission, Model $role, PermissionRegistrar $registrar)

Clone a permission with the matching role-permission pivot.

bool
pivotIsDenied(Model $model)

Determine if a hydrated pivot marks the permission as denied.

bool
permissionEffectIsDenied(mixed $value)

Normalize a permission assignment effect.

relationCollection(Model $model, string $relation)

Get a hydrated relation collection.

bool
storedPermissionMatches(Model $storedPermission, int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if a stored permission matches an input permission.

string
guardNameForPermissionMatch(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Resolve the guard to use when matching stored permissions.

getPermissionNames()

Get the permission names.

mixed
getStoredPermission(mixed $permissions, PermissionPartition|null $partition = null)

Get the stored permission models for the given permissions.

void
ensureModelSharesGuard(Permission|Role $roleOrPermission)

Ensure the given role or permission uses one of the model's guards.

getGuardNames()

Get the guard names for the model.

string
getDefaultGuardName()

Get the default guard name for the model.

void
forgetCachedPermissions()

Forget the cached permissions.

bool
hasAllDirectPermissions(mixed ...$permissions)

Check if the model has All of the requested Direct permissions.

bool
hasAnyDirectPermission(mixed ...$permissions)

Check if the model has Any of the requested Direct permissions.

Details

protected BelongsToMany permissionBelongsToMany(string $related, string $table, string $foreignPivotKey, string $relatedPivotKey, string $relationName, PermissionRelationContext|null $context = null)

Build a partition-aware belongs-to-many relation.

Parameters

string $related
string $table
string $foreignPivotKey
string $relatedPivotKey
string $relationName
PermissionRelationContext|null $context

Return Value

BelongsToMany

protected MorphToMany permissionMorphToMany(string $related, string $table, string $foreignPivotKey, string $relatedPivotKey, string $relationName, bool $inverse = false, bool $teamScoped = false, PermissionRelationContext|null $context = null)

Build a partition-aware morph-to-many relation.

Parameters

string $related
string $table
string $foreignPivotKey
string $relatedPivotKey
string $relationName
bool $inverse
bool $teamScoped
PermissionRelationContext|null $context

Return Value

MorphToMany

protected Builder permissionRelationQuery(Model $related, PermissionPartition|null $partition)

Build the related query using the relation's captured partition.

Parameters

Model $related
PermissionPartition|null $partition

Return Value

Builder

protected void ensurePermissionRelationParentMatches(PermissionRegistrar $registrar, PermissionPartition|null $partition)

Ensure a partition-bearing relation parent belongs to the captured partition.

Parameters

PermissionRegistrar $registrar
PermissionPartition|null $partition

Return Value

void

protected BelongsToMany applyPermissionPartitionToRelation(BelongsToMany $relation, PermissionPartition|null $partition)

Apply the captured partition to pivot reads and writes.

Parameters

BelongsToMany $relation
PermissionPartition|null $partition

Return Value

BelongsToMany

at line 54
protected PermissionRegistrar permissionRegistrar()

Get the permission registrar.

Return Value

PermissionRegistrar

at line 62
protected Dispatcher eventDispatcher()

Get the event dispatcher.

Return Value

Dispatcher

at line 70
static void bootHasPermissions()

Boot permission cleanup and queued assignment handling.

Return Value

void

at line 169
int|bool|null delete()

Delete the model and its permission assignments atomically.

Return Value

int|bool|null

at line 183
static protected bool shouldDeletePermissionAssignments(Model $model)

Determine whether deleting the model removes permission assignments.

Parameters

Model $model

Return Value

bool

at line 193
static protected array|null deleteSubjectAssignments(string $morphType, mixed $modelKey, string $table)

Delete one kind of assignment for a hard-deleted subject.

Parameters

string $morphType
mixed $modelKey
string $table

Return Value

array|null

at line 249
static protected void deletePermissionRecordAssignments(mixed $modelKey, string $modelAssignmentsTable, string $pivotKey, PermissionPartition|null $partition)

Delete assignment pivots owned by a Role or Permission record.

Parameters

mixed $modelKey
string $modelAssignmentsTable
string $pivotKey
PermissionPartition|null $partition

Return Value

void

at line 276
static protected PermissionPartition|null permissionRecordDeletionPartition(Model $model, PermissionRegistrar $registrar)

Resolve and validate a permission record's deletion partition.

Parameters

Model $model
PermissionRegistrar $registrar

Return Value

PermissionPartition|null

at line 306
string getPermissionClass()

Get the permission model class.

Return Value

string

at line 318
string getWildcardClass()

Get the wildcard permission class.

Return Value

string

at line 340
BelongsToMany permissions()

A model may have multiple direct permissions.

Return Value

BelongsToMany

at line 348
protected BelongsToMany permissionAssignmentRelation(PermissionRelationContext|null $context = null)

Build the direct permission assignment relation for a captured context.

Parameters

PermissionRelationContext|null $context

Return Value

BelongsToMany

at line 368
protected PermissionRelationContext permissionRelationContext(BelongsToMany $relation)

Get the immutable context captured by a permission assignment relation.

Parameters

BelongsToMany $relation

Return Value

PermissionRelationContext

at line 377
protected void forgetStalePermissionRelation(PermissionRegistrar $registrar, string $relation)

Forget an assignment relation loaded for an earlier context.

Parameters

PermissionRegistrar $registrar
string $relation

Return Value

void

at line 388
protected Collection getCachedDirectPermissions()

Get cached direct permission assignments for this model.

Return Value

Collection

at line 482
protected Collection directPermissionsForModelResult()

Get direct permissions for a model-returning public API.

Return Value

Collection

at line 500
protected Collection allowedDirectPermissions()

Return allowed direct permissions.

Return Value

Collection

at line 514
Builder scopePermission(Builder $query, array|Collection|int|Permission|string|UnitEnum $permissions, bool $without = false)

Scope the model query to certain permissions only.

Parameters

Builder $query
array|Collection|int|Permission|string|UnitEnum $permissions
bool $without

Return Value

Builder

at line 539
protected Builder whereEffectivePermission(Builder $query, array $permissionIds)

Add an effective permission predicate for the given permission ids.

Parameters

Builder $query
array $permissionIds

Return Value

Builder

at line 564
protected Builder wherePermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a permission-effect predicate for direct and role-granted permissions.

Parameters

Builder $query
int|string $permissionId
bool $denied

Return Value

Builder

at line 584
protected Builder whereDirectPermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a direct permission-effect predicate.

Parameters

Builder $query
int|string $permissionId
bool $denied

Return Value

Builder

at line 599
protected Builder whereRolePermissionEffect(Builder $query, int|string $permissionId, bool $denied)

Add a role permission-effect predicate.

Parameters

Builder $query
int|string $permissionId
bool $denied

Return Value

Builder

at line 616
Builder scopeWithoutPermission(Builder $query, array|Collection|int|Permission|string|UnitEnum $permissions)

Scope the model query to only those without certain permissions, whether indirectly by role or by direct permission.

Parameters

Builder $query
array|Collection|int|Permission|string|UnitEnum $permissions

Return Value

Builder

at line 626
protected array convertToPermissionModels(array|Collection|int|Permission|string|UnitEnum $permissions)

Convert the given permissions to permission models.

Parameters

array|Collection|int|Permission|string|UnitEnum $permissions

Return Value

array

Exceptions

PermissionDoesNotExist

at line 659
Permission filterPermission(mixed $permission, string|null $guardName = null)

Find a permission.

Parameters

mixed $permission
string|null $guardName

Return Value

Permission

Exceptions

PermissionDoesNotExist

at line 696
bool hasPermissionTo(mixed $permission, string|null $guardName = null)

Determine if the model may perform the given permission.

Parameters

mixed $permission
string|null $guardName

Return Value

bool

Exceptions

PermissionDoesNotExist

at line 720
protected bool hasWildcardPermission(mixed $permission, string|null $guardName = null)

Validates a wildcard permission against all permissions of a user.

Parameters

mixed $permission
string|null $guardName

Return Value

bool

at line 757
bool checkPermissionTo(mixed $permission, string|null $guardName = null)

An alias to hasPermissionTo(), but avoids throwing an exception.

Parameters

mixed $permission
string|null $guardName

Return Value

bool

at line 771
bool hasAnyPermission(mixed ...$permissions)

Determine if the model has any of the given permissions.

Parameters

mixed ...$permissions

Return Value

bool

at line 789
bool hasAllPermissions(mixed ...$permissions)

Determine if the model has all of the given permissions.

Parameters

mixed ...$permissions

Return Value

bool

at line 805
protected bool hasPermissionViaRole(Permission $permission)

Determine if the model has, via roles, the given permission.

Parameters

Permission $permission

Return Value

bool

at line 825
bool hasDirectPermission(mixed $permission)

Determine if the model has the given permission.

Parameters

mixed $permission

Return Value

bool

Exceptions

PermissionDoesNotExist

at line 838
Collection getPermissionsViaRoles()

Return all the permissions the model has via roles.

Return Value

Collection

at line 853
Collection getAllPermissions()

Return all the permissions the model has, both directly and via roles.

Return Value

Collection

at line 872
Collection getDeniedPermissions()

Return all the permissions the model is denied, both directly and via roles.

Return Value

Collection

at line 931
HasPermissions givePermissionTo(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Grant the given permission(s) to the model.

Parameters

array|Collection|int|Permission|string|UnitEnum|null ...$permissions

Return Value

HasPermissions

at line 939
HasPermissions denyPermissionTo(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Deny the given permission(s) for the model.

Parameters

array|Collection|int|Permission|string|UnitEnum|null ...$permissions

Return Value

HasPermissions

at line 1044
protected string assignmentIdIdentity(int|string $id)

Build a collision-safe assignment ID identity.

Parameters

int|string $id

Return Value

string

at line 1055
protected array indexAssignmentIds(array $ids)

Index assignment IDs by their collision-safe identities.

Parameters

array $ids

Return Value

array

at line 1069
protected int|string normalizeRelatedPivotId(BelongsToMany $relation, mixed $id)

Normalize an ID read directly from an assignment pivot.

Parameters

BelongsToMany $relation
mixed $id

Return Value

int|string

at line 1082
protected Collection readCurrentAssignmentPivots(BelongsToMany $relation, array $columns, array|null $ids = null)

Read current assignment pivots through their captured relation constraints.

Parameters

BelongsToMany $relation
array $columns
array|null $ids

Return Value

Collection

at line 1250
protected void queuePermissionAssignments(array $permissions, bool $isDenied, PermissionRelationContext $context, string $pivotClass)

Queue permission assignments until the model is saved.

Queuing a permission again replaces its queued effect.

Parameters

array $permissions
bool $isDenied
PermissionRelationContext $context
string $pivotClass

Return Value

void

at line 1299
protected void removeQueuedPermissionAssignments(array $permissions, PermissionRelationContext $context)

Remove permission assignments queued for a captured context.

Parameters

array $permissions
PermissionRelationContext $context

Return Value

void

at line 1321
protected void flushQueuedPermissionAssignments()

Flush permission assignments queued before the model was saved.

Return Value

void

at line 1348
protected void attachQueuedPermissionAssignments(array $assignments)

Insert queued permission assignments, with one insert per context and effect.

Parameters

array $assignments

Return Value

void

at line 1396
protected void dispatchPermissionAttachedEvent(array $permissions)

Dispatch the permission attached event when enabled and listened for.

Parameters

array $permissions

Return Value

void

at line 1408
protected bool permissionAttachedEventIsListenedFor()

Determine whether the permission attached event has listeners.

Return Value

bool

at line 1417
void forgetWildcardPermissionIndex()

Forget the wildcard permission index.

Return Value

void

at line 1427
HasPermissions syncPermissions(array|Collection|int|Permission|string|UnitEnum|null ...$permissions)

Remove all current permissions and set the given ones.

Parameters

array|Collection|int|Permission|string|UnitEnum|null ...$permissions

Return Value

HasPermissions

at line 1444
array syncPermissionEffects(array|Collection $allowed = [], array|Collection $denied = [])

Remove all current permissions and set allowed and denied permissions.

For unsaved models, assignments are queued until the model is saved and the returned change set is empty because no database rows are changed yet.

Parameters

array|Collection $allowed
array|Collection $denied

Return Value

array

at line 1505
HasPermissions revokePermissionTo(array|Collection|int|Permission|string|UnitEnum $permission)

Revoke the given permission(s).

Parameters

array|Collection|int|Permission|string|UnitEnum $permission

Return Value

HasPermissions

at line 1543
protected void dispatchPermissionDetachedEvent(mixed $permission)

Dispatch the permission detached event when enabled and listened for.

Parameters

mixed $permission

Return Value

void

at line 1555
protected bool permissionDetachedEventIsListenedFor()

Determine whether the permission detached event has listeners.

Return Value

bool

at line 1564
bool hasDeniedPermission(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if the model has an explicit denied direct permission.

Parameters

int|Permission|string|UnitEnum $permission
string|null $guardName

Return Value

bool

at line 1578
bool hasDeniedPermissionViaRoles(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if the model has an explicit denied permission via roles.

Parameters

int|Permission|string|UnitEnum $permission
string|null $guardName

Return Value

bool

at line 1615
protected Collection getPermissionsViaRolesWithPivots()

Return permissions granted through the model's roles with role-permission pivot data.

Return Value

Collection

at line 1634
protected Collection loadPermissionsViaRolesWithPivots()

Load permissions granted through the model's roles with role-permission pivot data.

Return Value

Collection

at line 1665
protected Model|null permissionForMatch(int|Permission|string|UnitEnum $permission, string $guardName)

Resolve a permission for matching without throwing.

Parameters

int|Permission|string|UnitEnum $permission
string $guardName

Return Value

Model|null

at line 1692
protected array deniedPermissionKeys(Collection ...$permissionCollections)

Build lookup keys for denied permissions.

Parameters

Collection ...$permissionCollections

Return Value

array

at line 1710
protected string permissionComparisonKey(Model $permission)

Build a permission comparison key.

Parameters

Model $permission

Return Value

string

at line 1718
protected Model permissionWithRolePivot(Model $permission, Model $role, PermissionRegistrar $registrar)

Clone a permission with the matching role-permission pivot.

Parameters

Model $permission
Model $role
PermissionRegistrar $registrar

Return Value

Model

at line 1741
protected bool pivotIsDenied(Model $model)

Determine if a hydrated pivot marks the permission as denied.

Parameters

Model $model

Return Value

bool

at line 1750
protected bool permissionEffectIsDenied(mixed $value)

Normalize a permission assignment effect.

Parameters

mixed $value

Return Value

bool

at line 1759
protected Collection relationCollection(Model $model, string $relation)

Get a hydrated relation collection.

Parameters

Model $model
string $relation

Return Value

Collection

at line 1778
protected bool storedPermissionMatches(Model $storedPermission, int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Determine if a stored permission matches an input permission.

Parameters

Model $storedPermission
int|Permission|string|UnitEnum $permission
string|null $guardName

Return Value

bool

at line 1803
protected string guardNameForPermissionMatch(int|Permission|string|UnitEnum $permission, string|null $guardName = null)

Resolve the guard to use when matching stored permissions.

Parameters

int|Permission|string|UnitEnum $permission
string|null $guardName

Return Value

string

at line 1830
Collection getPermissionNames()

Get the permission names.

Return Value

Collection

at line 1841
protected mixed getStoredPermission(mixed $permissions, PermissionPartition|null $partition = null)

Get the stored permission models for the given permissions.

Parameters

mixed $permissions
PermissionPartition|null $partition

Return Value

mixed

at line 1931
protected void ensureModelSharesGuard(Permission|Role $roleOrPermission)

Ensure the given role or permission uses one of the model's guards.

Parameters

Permission|Role $roleOrPermission

Return Value

void

Exceptions

GuardDoesNotMatch

at line 1941
protected Collection getGuardNames()

Get the guard names for the model.

Return Value

Collection

at line 1949
protected string getDefaultGuardName()

Get the default guard name for the model.

Return Value

string

at line 1957
void forgetCachedPermissions()

Forget the cached permissions.

Return Value

void

at line 1967
bool hasAllDirectPermissions(mixed ...$permissions)

Check if the model has All of the requested Direct permissions.

Parameters

mixed ...$permissions

Return Value

bool

at line 1985
bool hasAnyDirectPermission(mixed ...$permissions)

Check if the model has Any of the requested Direct permissions.

Parameters

mixed ...$permissions

Return Value

bool