class PermissionRegistrar

Constants

DEFAULT_ROLE_PIVOT_KEY

DEFAULT_PERMISSION_PIVOT_KEY

DEFAULT_TEAM_FOREIGN_KEY

DEFAULT_CACHE_EXPIRATION_SECONDS

DEFAULT_CACHE_COLUMN_NAMES_EXCEPT

ROLE_CATALOG_CACHE_KEY

MODEL_ROLES_CACHE_KEY_PREFIX

MODEL_PERMISSIONS_CACHE_KEY_PREFIX

MODEL_CACHE_TOKEN_KEY

PERMISSION_CATALOG_CONTEXT_KEY

WILDCARD_PERMISSION_INDEX_CONTEXT_KEY

MODEL_VIA_ROLE_PERMISSIONS_CONTEXT_KEY

protected MODEL_ROLE_ASSIGNMENTS_CONTEXT_KEY

protected MODEL_DIRECT_PERMISSIONS_CONTEXT_KEY

protected MODEL_CLASS_CATALOG_CONTEXT_KEY

protected DIRTY_CACHE_TOKENS_CONTEXT_KEY

protected DIRTY_CACHE_VALUES_CONTEXT_KEY

Properties

static protected string|null $partitionColumn
static protected null|Closure(): null|int|string $partitionResolver
static protected bool $initialized
protected string $permissionClass
protected string $roleClass
protected string|null $teamClass
string $pivotRole
string $pivotPermission
int $cacheExpirationTime
bool $teams
protected PermissionsTeamResolver $teamResolver
string $teamsKey
string $cacheKey
protected string $modelRolesCacheKeyPrefix
protected string $modelPermissionsCacheKeyPrefix
protected string $modelCacheTokenKey
protected CacheManager $cacheManager
protected string|null $cacheStoreName
protected Pivot>>> $assignmentPivotClasses
protected PermissionRelationContext}>> $loadedRelationProvenance

Methods

__construct(Repository $config, Container $app, ModelCacheCoordinator $modelCacheCoordinator)

Create a new permission registrar.

static void
resolvePartitionUsing(string $column, Closure $resolver)

Configure the permission row partition resolver.

static bool
partitioningEnabled()

Determine whether permission row partitioning is configured.

static string|null
partitionColumn()

Get the configured permission partition column.

resolvePartition()

Resolve the current permission partition.

partitionFromRecord(Model $model)

Resolve a permission partition from a persisted record.

void
ensureModelMatchesPartition(Model $model, PermissionPartition $partition)

Ensure a model belongs to the captured permission partition.

void
ensureModelUsesPermissionConnection(Model $model)

Ensure a Role or Permission model uses the permission storage connection.

void
initializeCache()

Initialize cache and config-backed registrar state.

void
validateModelClasses()

Validate the configured model classes.

void
validateCacheColumnExclusions()

Validate that cache serialization retains required model columns.

void
validateRoleClass(string $roleClass)

Validate a configured role model class.

void
validatePermissionClass(string $permissionClass)

Validate a configured permission model class.

configuredCacheRepository()

Get the configured cache repository.

cacheRepository()

Get the memoized cache repository for the current coroutine.

void
setPermissionsTeamId(int|string|Model|null $id)

Set the current permissions team id.

int|string|null
getPermissionsTeamId()

Get the current permissions team id.

void
ensureTeamIsSelectedForMutation(PermissionRelationContext|null $context = null)

Ensure a team-scoped mutation has a selected team.

bool
registerPermissions(Gate $gate)

Register the permission check method on the gate.

bool
forgetCachedPermissions()

Flush the permission cache.

bool
forgetCachedPermissionsFor(PermissionPartition|null $partition)

Flush the permission cache for an explicit partition.

void
invalidatePermissionCatalogAfterMutation(PermissionPartition|null $partition)

Invalidate the permission catalog after a model mutation settles.

void
rotateModelAssignmentCacheTokenAfterMutation(PermissionPartition|null $partition)

Rotate the model assignment cache namespace after a model mutation settles.

void
invalidateModelRoleCacheAfterMutation(Model $model, PermissionPartition|null $partition, int|string|null $team)

Invalidate a model's role cache after a mutation settles.

void
invalidateModelRoleCacheForIdentityAfterMutation(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Invalidate an exact model identity's role cache after a mutation settles.

void
invalidateModelPermissionCacheAfterMutation(Model $model, PermissionPartition|null $partition, int|string|null $team)

Invalidate a model's permission cache after a mutation settles.

void
invalidateModelPermissionCacheForIdentityAfterMutation(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Invalidate an exact model identity's permission cache after a mutation settles.

rememberModelViaRolePermissions(Model $model, Closure $callback)

Remember a model's permissions granted through roles.

rememberModelDirectPermissions(Model $model, Closure $callback)

Remember a model's hydrated direct permissions.

array
rememberModelRoleAssignments(Model $model, Closure $callback)

Remember a model's role assignment ids.

array
rememberModelPermissionAssignments(Model $model, Closure $callback)

Remember a model's permission assignment ids.

string
modelCacheKey(string $prefix, Model $model)

Build the cache key for model assignment caches.

string
modelCacheKeyForIdentity(string $prefix, string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Build an assignment cache key for an explicit identity and context.

string
modelRuntimeCacheKey(Model $model)

Build the runtime cache key segment for coroutine-local model state.

string
modelRuntimeCacheKeyForIdentity(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Build a coroutine-local cache key for an explicit identity and context.

string
modelAssignmentCacheToken(PermissionPartition|null $partition = null)

Get the current model assignment cache token.

string
newModelAssignmentCacheToken()

Create a new model assignment cache namespace token.

void
forgetWildcardPermissionIndex(Model|null $record = null)

Forget the cached wildcard permission index.

array
getWildcardPermissionIndex(Model $record)

Get the wildcard permission index for a model.

array
getDeniedWildcardPermissionIndex(Model $record)

Get the wildcard index of a model's denied permissions.

string
wildcardPermissionIndexKey(Model $record)

Build the coroutine-local wildcard permission index key.

void
forgetRuntimeCacheItem(string $contextKey, string $itemKey)

Forget one item from a coroutine-local permission cache.

void
forgetRuntimeCacheItemsForPartition(string $contextKey, PermissionPartition|null $partition)

Forget coroutine-local permission cache items for a partition.

void
clearPermissionsCollection()

Clear already-loaded permissions collection.

void
clearAllPermissionRuntimeState()

Clear all permission runtime state in the current coroutine.

void
clearPermissionRuntimeStateFor(PermissionPartition|null $partition)

Clear permission runtime state for an explicit partition.

void
markLoadedRelation(Model $model, string $relation, Collection $collection, PermissionRelationContext $context)

Mark the context that produced a loaded permission relation.

bool
loadedRelationIsCurrent(Model $model, string $relation)

Determine whether a loaded permission relation matches current context.

void
forgetLoadedRelationProvenance(Model $model, string|null $relation = null)

Forget loaded permission relation provenance for a model.

getPermissions(array $params = [], bool $onlyOne = false, string|null $permissionClass = null)

Get the permissions based on the passed params.

getRoles(array $params = [], bool $onlyOne = false, string|null $roleClass = null)

Get the roles based on the passed params.

Collection|null
indexedModels(array $params, bool $onlyOne, string $modelType)

Get indexed models for supported exact lookup shapes.

filterModels(Collection $models, array $params, bool $onlyOne)

Filter a model collection by attributes.

static bool
attributeMatches(mixed $actual, mixed $expected)

Determine if an attribute matches a requested value.

string
getPermissionClass()

Get the permission model class.

getPermissionConnection()

Get the connection that owns permission storage.

void
runPermissionStorageMutationAfterSubjectCommit(Connection $subjectConnection, Closure $mutation)

Run a permission-storage mutation in step with its subject transaction.

string
getCacheKey()

Get the current global permission cache key.

string
partitionedCacheKey(string $key, PermissionPartition|null $partition = null)

Add the permission partition to a cache key.

resolvedPartitionArgument(PermissionPartition|null $partition)

Resolve an optional explicit partition argument.

string
partitionRuntimePrefix(PermissionPartition|null $partition)

Build the runtime key prefix for a partition.

setPermissionClass(string $permissionClass)

Set the permission model class.

string
getRoleClass()

Get the role model class.

setRoleClass(string $roleClass)

Set the role model class.

string|null
getTeamClass()

Get the team model class.

string
getAssignmentPivotClass(Model $model, string $relation)

Get the pivot class selected by a model's public assignment relation.

setTeamClass(string|null $teamClass)

Set the team model class.

getCacheRepository()

Get the unmemoized repository for observing committed shared cache state.

getCacheStore()

Get the cache store.

getPermissionsWithRoles(string|null $permissionClass = null)

Get permissions with their roles.

getRolesForCache()

Get roles for cache.

bool
hasDeniedRolePermissions()

Determine if any role in the catalog is denied a permission.

static bool
isUid(mixed $value)

Determine if a value is a UUID or ULID.

static void
flushState()

Flush all static state.

Details

at line 136
__construct(Repository $config, Container $app, ModelCacheCoordinator $modelCacheCoordinator)

Create a new permission registrar.

Parameters

Repository $config
Container $app
ModelCacheCoordinator $modelCacheCoordinator

at line 156
static void resolvePartitionUsing(string $column, Closure $resolver)

Configure the permission row partition resolver.

Register before resolving the Permission registrar or Gate.

The column and callback persist in static properties for the worker lifetime and affect every subsequent permission operation.

Parameters

string $column
Closure $resolver

Return Value

void

at line 177
static bool partitioningEnabled()

Determine whether permission row partitioning is configured.

Return Value

bool

at line 185
static string|null partitionColumn()

Get the configured permission partition column.

Return Value

string|null

at line 193
PermissionPartition|null resolvePartition()

Resolve the current permission partition.

Return Value

PermissionPartition|null

at line 211
PermissionPartition partitionFromRecord(Model $model)

Resolve a permission partition from a persisted record.

Parameters

Model $model

Return Value

PermissionPartition

at line 241
void ensureModelMatchesPartition(Model $model, PermissionPartition $partition)

Ensure a model belongs to the captured permission partition.

Parameters

Model $model
PermissionPartition $partition

Return Value

void

at line 256
void ensureModelUsesPermissionConnection(Model $model)

Ensure a Role or Permission model uses the permission storage connection.

Parameters

Model $model

Return Value

void

at line 271
void initializeCache()

Initialize cache and config-backed registrar state.

The values are stored on the singleton registrar and affect every later permission lookup in this worker.

Return Value

void

at line 338
protected void validateModelClasses()

Validate the configured model classes.

Return Value

void

at line 347
protected void validateCacheColumnExclusions()

Validate that cache serialization retains required model columns.

Return Value

void

at line 393
protected void validateRoleClass(string $roleClass)

Validate a configured role model class.

Parameters

string $roleClass

Return Value

void

at line 413
protected void validatePermissionClass(string $permissionClass)

Validate a configured permission model class.

Parameters

string $permissionClass

Return Value

void

at line 431
protected Repository configuredCacheRepository()

Get the configured cache repository.

Return Value

Repository

at line 439
protected Repository cacheRepository()

Get the memoized cache repository for the current coroutine.

Return Value

Repository

at line 667
void setPermissionsTeamId(int|string|Model|null $id)

Set the current permissions team id.

Parameters

int|string|Model|null $id

Return Value

void

at line 675
int|string|null getPermissionsTeamId()

Get the current permissions team id.

Return Value

int|string|null

at line 683
void ensureTeamIsSelectedForMutation(PermissionRelationContext|null $context = null)

Ensure a team-scoped mutation has a selected team.

Parameters

PermissionRelationContext|null $context

Return Value

void

at line 699
bool registerPermissions(Gate $gate)

Register the permission check method on the gate.

Parameters

Gate $gate

Return Value

bool

at line 724
bool forgetCachedPermissions()

Flush the permission cache.

Return the backend result when settled immediately, or true once the reset is registered against an open transaction.

Return Value

bool

at line 732
bool forgetCachedPermissionsFor(PermissionPartition|null $partition)

Flush the permission cache for an explicit partition.

Parameters

PermissionPartition|null $partition

Return Value

bool

at line 746
void invalidatePermissionCatalogAfterMutation(PermissionPartition|null $partition)

Invalidate the permission catalog after a model mutation settles.

Parameters

PermissionPartition|null $partition

Return Value

void

at line 758
void rotateModelAssignmentCacheTokenAfterMutation(PermissionPartition|null $partition)

Rotate the model assignment cache namespace after a model mutation settles.

Parameters

PermissionPartition|null $partition

Return Value

void

at line 788
void invalidateModelRoleCacheAfterMutation(Model $model, PermissionPartition|null $partition, int|string|null $team)

Invalidate a model's role cache after a mutation settles.

Parameters

Model $model
PermissionPartition|null $partition
int|string|null $team

Return Value

void

at line 804
void invalidateModelRoleCacheForIdentityAfterMutation(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Invalidate an exact model identity's role cache after a mutation settles.

Parameters

string $morphType
int|string $modelKey
PermissionPartition|null $partition
int|string|null $team

Return Value

void

at line 836
void invalidateModelPermissionCacheAfterMutation(Model $model, PermissionPartition|null $partition, int|string|null $team)

Invalidate a model's permission cache after a mutation settles.

Parameters

Model $model
PermissionPartition|null $partition
int|string|null $team

Return Value

void

at line 852
void invalidateModelPermissionCacheForIdentityAfterMutation(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Invalidate an exact model identity's permission cache after a mutation settles.

Parameters

string $morphType
int|string $modelKey
PermissionPartition|null $partition
int|string|null $team

Return Value

void

at line 885
Collection rememberModelViaRolePermissions(Model $model, Closure $callback)

Remember a model's permissions granted through roles.

Parameters

Model $model
Closure $callback

Return Value

Collection

at line 905
Collection rememberModelDirectPermissions(Model $model, Closure $callback)

Remember a model's hydrated direct permissions.

Parameters

Model $model
Closure $callback

Return Value

Collection

at line 926
array rememberModelRoleAssignments(Model $model, Closure $callback)

Remember a model's role assignment ids.

Parameters

Model $model
Closure $callback

Return Value

array

at line 952
array rememberModelPermissionAssignments(Model $model, Closure $callback)

Remember a model's permission assignment ids.

Parameters

Model $model
Closure $callback

Return Value

array

at line 966
protected string modelCacheKey(string $prefix, Model $model)

Build the cache key for model assignment caches.

Parameters

string $prefix
Model $model

Return Value

string

at line 980
protected string modelCacheKeyForIdentity(string $prefix, string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Build an assignment cache key for an explicit identity and context.

Parameters

string $prefix
string $morphType
int|string $modelKey
PermissionPartition|null $partition
int|string|null $team

Return Value

string

at line 999
protected string modelRuntimeCacheKey(Model $model)

Build the runtime cache key segment for coroutine-local model state.

Parameters

Model $model

Return Value

string

at line 1012
protected string modelRuntimeCacheKeyForIdentity(string $morphType, int|string $modelKey, PermissionPartition|null $partition, int|string|null $team)

Build a coroutine-local cache key for an explicit identity and context.

Parameters

string $morphType
int|string $modelKey
PermissionPartition|null $partition
int|string|null $team

Return Value

string

at line 1030
string modelAssignmentCacheToken(PermissionPartition|null $partition = null)

Get the current model assignment cache token.

Parameters

PermissionPartition|null $partition

Return Value

string

at line 1059
protected string newModelAssignmentCacheToken()

Create a new model assignment cache namespace token.

Return Value

string

at line 1067
void forgetWildcardPermissionIndex(Model|null $record = null)

Forget the cached wildcard permission index.

Parameters

Model|null $record

Return Value

void

at line 1095
array getWildcardPermissionIndex(Model $record)

Get the wildcard permission index for a model.

Parameters

Model $record

Return Value

array

at line 1105
array getDeniedWildcardPermissionIndex(Model $record)

Get the wildcard index of a model's denied permissions.

Parameters

Model $record

Return Value

array

at line 1141
protected string wildcardPermissionIndexKey(Model $record)

Build the coroutine-local wildcard permission index key.

Parameters

Model $record

Return Value

string

at line 1149
protected void forgetRuntimeCacheItem(string $contextKey, string $itemKey)

Forget one item from a coroutine-local permission cache.

Parameters

string $contextKey
string $itemKey

Return Value

void

at line 1159
protected void forgetRuntimeCacheItemsForPartition(string $contextKey, PermissionPartition|null $partition)

Forget coroutine-local permission cache items for a partition.

Parameters

string $contextKey
PermissionPartition|null $partition

Return Value

void

at line 1178
void clearPermissionsCollection()

Clear already-loaded permissions collection.

Return Value

void

at line 1186
protected void clearAllPermissionRuntimeState()

Clear all permission runtime state in the current coroutine.

Return Value

void

at line 1199
protected void clearPermissionRuntimeStateFor(PermissionPartition|null $partition)

Clear permission runtime state for an explicit partition.

Parameters

PermissionPartition|null $partition

Return Value

void

at line 1236
void markLoadedRelation(Model $model, string $relation, Collection $collection, PermissionRelationContext $context)

Mark the context that produced a loaded permission relation.

Parameters

Model $model
string $relation
Collection $collection
PermissionRelationContext $context

Return Value

void

at line 1257
bool loadedRelationIsCurrent(Model $model, string $relation)

Determine whether a loaded permission relation matches current context.

Parameters

Model $model
string $relation

Return Value

bool

at line 1298
void forgetLoadedRelationProvenance(Model $model, string|null $relation = null)

Forget loaded permission relation provenance for a model.

Parameters

Model $model
string|null $relation

Return Value

void

at line 1385
Collection getPermissions(array $params = [], bool $onlyOne = false, string|null $permissionClass = null)

Get the permissions based on the passed params.

Parameters

array $params
bool $onlyOne
string|null $permissionClass

Return Value

Collection

at line 1425
Collection getRoles(array $params = [], bool $onlyOne = false, string|null $roleClass = null)

Get the roles based on the passed params.

Parameters

array $params
bool $onlyOne
string|null $roleClass

Return Value

Collection

at line 1534
protected Collection|null indexedModels(array $params, bool $onlyOne, string $modelType)

Get indexed models for supported exact lookup shapes.

The indexes reflect cached models as they were loaded. Callers save changed models before further lookups, which refreshes the catalog, so lookups stay O(1) without rescanning returned models.

Parameters

array $params
bool $onlyOne
string $modelType

Return Value

Collection|null

at line 1648
protected Collection filterModels(Collection $models, array $params, bool $onlyOne)

Filter a model collection by attributes.

Parameters

Collection $models
array $params
bool $onlyOne

Return Value

Collection

at line 1669
static protected bool attributeMatches(mixed $actual, mixed $expected)

Determine if an attribute matches a requested value.

Parameters

mixed $actual
mixed $expected

Return Value

bool

at line 1693
string getPermissionClass()

Get the permission model class.

Return Value

string

at line 1701
Connection getPermissionConnection()

Get the connection that owns permission storage.

Return Value

Connection

at line 1719
void runPermissionStorageMutationAfterSubjectCommit(Connection $subjectConnection, Closure $mutation)

Run a permission-storage mutation in step with its subject transaction.

Parameters

Connection $subjectConnection
Closure $mutation

Return Value

void

at line 1735
string getCacheKey()

Get the current global permission cache key.

Return Value

string

at line 1743
protected string partitionedCacheKey(string $key, PermissionPartition|null $partition = null)

Add the permission partition to a cache key.

Parameters

string $key
PermissionPartition|null $partition

Return Value

string

at line 1757
protected PermissionPartition|null resolvedPartitionArgument(PermissionPartition|null $partition)

Resolve an optional explicit partition argument.

Parameters

PermissionPartition|null $partition

Return Value

PermissionPartition|null

at line 1767
protected string partitionRuntimePrefix(PermissionPartition|null $partition)

Build the runtime key prefix for a partition.

Parameters

PermissionPartition|null $partition

Return Value

string

at line 1780
PermissionRegistrar setPermissionClass(string $permissionClass)

Set the permission model class.

The model class is stored on the singleton registrar and affects every later permission lookup in this worker.

Parameters

string $permissionClass

Return Value

PermissionRegistrar

at line 1797
string getRoleClass()

Get the role model class.

Return Value

string

at line 1810
PermissionRegistrar setRoleClass(string $roleClass)

Set the role model class.

The model class is stored on the singleton registrar and affects every later role lookup in this worker.

Parameters

string $roleClass

Return Value

PermissionRegistrar

at line 1827
string|null getTeamClass()

Get the team model class.

Return Value

string|null

at line 1837
string getAssignmentPivotClass(Model $model, string $relation)

Get the pivot class selected by a model's public assignment relation.

Parameters

Model $model
string $relation

Return Value

string

at line 1859
PermissionRegistrar setTeamClass(string|null $teamClass)

Set the team model class.

The model class is stored on the singleton registrar and affects every later team permission lookup in this worker.

Parameters

string|null $teamClass

Return Value

PermissionRegistrar

at line 1872
Repository getCacheRepository()

Get the unmemoized repository for observing committed shared cache state.

Return Value

Repository

at line 1880
Store getCacheStore()

Get the cache store.

Return Value

Store

at line 1888
protected Collection getPermissionsWithRoles(string|null $permissionClass = null)

Get permissions with their roles.

Parameters

string|null $permissionClass

Return Value

Collection

at line 1898
protected Collection getRolesForCache()

Get roles for cache.

Return Value

Collection

at line 1954
bool hasDeniedRolePermissions()

Determine if any role in the catalog is denied a permission.

Return Value

bool

at line 2171
static bool isUid(mixed $value)

Determine if a value is a UUID or ULID.

Parameters

mixed $value

Return Value

bool

at line 2191
static void flushState()

Flush all static state.

Return Value

void