OfficesTable
extends BaseTable
in package
Offices Table - Hierarchical office structure and permission-based access
Manages office positions with hierarchical deputy/reporting relationships, warrant requirements, role assignments, and branch-scoped access control.
Tags
Table of Contents
Constants
- CACHE_GROUPS_TO_CLEAR = []
- CACHES_TO_CLEAR = []
- ID_CACHES_TO_CLEAR = []
Properties
- $CurrentOfficers : OfficersTable|HasMany
- $Departments : DepartmentsTable|BelongsTo
- $Deputies : OfficesTable|HasMany
- $DeputyTo : OfficesTable|BelongsTo
- $DirectReports : OfficesTable|HasMany
- $GrantsRole : RolesTable|BelongsTo
- $Officers : OfficersTable|HasMany
- $PreviousOfficers : OfficersTable|HasMany
- $ReportsTo : OfficesTable|BelongsTo
- $UpcomingOfficers : OfficersTable|HasMany
Methods
- addBranchScopeQuery() : SelectQuery
- Add branch-based data scoping to a query.
- afterDelete() : void
- After delete hook to capture impersonation audit trail entries.
- afterSave() : void
- After-save handler for automatic cache invalidation.
- buildRules() : RulesChecker
- Configure database-level integrity rules.
- findCompatibleBranchForOffice() : int|null
- Determine the appropriate branch ID for an office's reports_to_branch_id.
- findOrCreate() : Office
- get() : Office
- initialize() : void
- Initialize table configuration and associations.
- newEmptyEntity() : Office
- newEntity() : Office
- officesMemberCanWork() : array<string|int, int>
- Get offices accessible to a user based on permissions and hierarchical position.
- patchEntity() : Office
- save() : Office|false
- saveOrFail() : Office
- validationDefault() : Validator
- Configure validation rules for office entities.
- logImpersonationAction() : void
- Record impersonated writes to audit log table.
- calculateAccessibleOffices() : array<string|int, int>
- Calculate accessible offices based on user positions and permissions.
- getAllOfficeIds() : array<string|int, int>
- Get all office IDs for super users and global permission holders.
- getDeputyOffices() : array<string|int, int>
- Get deputy office IDs for a given office.
- getDirectReportOffices() : array<string|int, int>
- Get direct report office IDs for a given office.
- getOfficesForPosition() : array<string|int, int>
- Get accessible offices for a specific user position.
- getPositionPermissions() : array<string|int, mixed>
- Get permissions for a user's position.
- getReportingTreeOffices() : array<string|int, int>
- Return the office IDs that are reachable from a given office through deputy or reporting relationships in breadth-first order.
- getUserOfficerPositions() : array<string|int, mixed>
- Get user's current officer positions.
- hasGlobalOfficerPermissions() : bool
- Check if user has global officer management permissions.
Constants
CACHE_GROUPS_TO_CLEAR
protected
array<string|int, string>
CACHE_GROUPS_TO_CLEAR
= []
Cache groups to clear entirely on save
CACHES_TO_CLEAR
protected
array<string|int, array{string, string}>
CACHES_TO_CLEAR
= []
Static cache entries to clear on save
ID_CACHES_TO_CLEAR
protected
array<string|int, array{string, string}>
ID_CACHES_TO_CLEAR
= []
Entity-ID cache prefixes to clear on save
Properties
$CurrentOfficers
public
OfficersTable|HasMany
$CurrentOfficers
$Departments
public
DepartmentsTable|BelongsTo
$Departments
$Deputies
public
OfficesTable|HasMany
$Deputies
$DeputyTo
public
OfficesTable|BelongsTo
$DeputyTo
$DirectReports
public
OfficesTable|HasMany
$DirectReports
$GrantsRole
public
RolesTable|BelongsTo
$GrantsRole
$Officers
public
OfficersTable|HasMany
$Officers
$PreviousOfficers
public
OfficersTable|HasMany
$PreviousOfficers
$ReportsTo
public
OfficesTable|BelongsTo
$ReportsTo
$UpcomingOfficers
public
OfficersTable|HasMany
$UpcomingOfficers
Methods
addBranchScopeQuery()
Add branch-based data scoping to a query.
public
addBranchScopeQuery(SelectQuery $query, array<string|int, int> $branchIDs) : SelectQuery
Child tables should override for custom branch relationships.
Parameters
- $query : SelectQuery
-
The query to modify
- $branchIDs : array<string|int, int>
-
Authorized branch IDs
Return values
SelectQuery —Query with branch filtering
afterDelete()
After delete hook to capture impersonation audit trail entries.
public
afterDelete(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void
Parameters
- $event : EventInterface
-
Delete event
- $entity : EntityInterface
-
Entity being deleted
- $options : ArrayObject
-
Delete options
afterSave()
After-save handler for automatic cache invalidation.
public
afterSave(EventInterface $event, EntityInterface $entity, ArrayObject $options) : void
Parameters
- $event : EventInterface
-
The afterSave event
- $entity : EntityInterface
-
The saved entity
- $options : ArrayObject
-
Save options
buildRules()
Configure database-level integrity rules.
public
buildRules(RulesChecker $rules) : RulesChecker
Parameters
- $rules : RulesChecker
-
The rules object
Return values
RulesCheckerfindCompatibleBranchForOffice()
Determine the appropriate branch ID for an office's reports_to_branch_id.
public
findCompatibleBranchForOffice(int $startBranchId, int|null $reportsToOfficeId) : int|null
Finds a branch starting from $startBranchId (and moving up the parent chain if necessary) that is compatible with the branch types allowed for the specified reports-to office.
Parameters
- $startBranchId : int
-
The branch where the officer is being hired.
- $reportsToOfficeId : int|null
-
The ID of the office this officer reports to, or null.
Return values
int|null —The branch ID compatible with the reports-to office, or null if no reports-to office was provided.
findOrCreate()
public
findOrCreate(mixed $search[, callable|null $callback = = 'null' ][, array<string|int, mixed> $options = = '[]' ]) : Office
Parameters
- $search : mixed
- $callback : callable|null = = 'null'
- $options : array<string|int, mixed> = = '[]'
Return values
Officeget()
public
get(mixed $primaryKey[, array<string|int, mixed>|string $finder = = '\'all\'' ][, CacheInterface|string|null $cache = = 'null' ][, Closure|string|null $cacheKey = = 'null' ], mixed ...$args) : Office
Parameters
- $primaryKey : mixed
- $finder : array<string|int, mixed>|string = = '\'all\''
- $cache : CacheInterface|string|null = = 'null'
- $cacheKey : Closure|string|null = = 'null'
- $args : mixed
Return values
Officeinitialize()
Initialize table configuration and associations.
public
initialize(array<string, mixed> $config) : void
Parameters
- $config : array<string, mixed>
-
The configuration for the Table
newEmptyEntity()
public
newEmptyEntity() : Office
Return values
OfficenewEntity()
public
newEntity(array<string|int, mixed> $data[, array<string|int, mixed> $options = = '[]' ]) : Office
Parameters
- $data : array<string|int, mixed>
- $options : array<string|int, mixed> = = '[]'
Return values
OfficeofficesMemberCanWork()
Get offices accessible to a user based on permissions and hierarchical position.
public
officesMemberCanWork(Member $user, int|null $branchId) : array<string|int, int>
Super users and those with workWithAllOfficers permission get all offices.
Other users get offices based on their current officer positions and
hierarchical permissions (deputies, direct reports, reporting tree).
Parameters
- $user : Member
-
The user to check access for
- $branchId : int|null
-
Branch context for permission checking
Return values
array<string|int, int> —Office IDs the user can work with
patchEntity()
public
patchEntity(EntityInterface $entity, array<string|int, mixed> $data[, array<string|int, mixed> $options = = '[]' ]) : Office
Parameters
- $entity : EntityInterface
- $data : array<string|int, mixed>
- $options : array<string|int, mixed> = = '[]'
Return values
Officesave()
public
save(EntityInterface $entity[, array<string|int, mixed> $options = = '[]' ]) : Office|false
Parameters
- $entity : EntityInterface
- $options : array<string|int, mixed> = = '[]'
Return values
Office|falsesaveOrFail()
public
saveOrFail(EntityInterface $entity[, array<string|int, mixed> $options = = '[]' ]) : Office
Parameters
- $entity : EntityInterface
- $options : array<string|int, mixed> = = '[]'
Return values
OfficevalidationDefault()
Configure validation rules for office entities.
public
validationDefault(Validator $validator) : Validator
Parameters
- $validator : Validator
-
Validator instance
Return values
ValidatorlogImpersonationAction()
Record impersonated writes to audit log table.
protected
logImpersonationAction(string $defaultOperation, EntityInterface $entity) : void
Parameters
- $defaultOperation : string
-
Operation fallback (save/delete)
- $entity : EntityInterface
-
Affected entity
calculateAccessibleOffices()
Calculate accessible offices based on user positions and permissions.
private
calculateAccessibleOffices(Member $user, array<string|int, mixed> $userOfficerPositions, int $branchId) : array<string|int, int>
Parameters
- $user : Member
-
The user entity
- $userOfficerPositions : array<string|int, mixed>
-
User's current officer positions
- $branchId : int
-
Branch context for permission checking
Return values
array<string|int, int> —Unique office IDs the user can access
getAllOfficeIds()
Get all office IDs for super users and global permission holders.
private
getAllOfficeIds() : array<string|int, int>
Return values
array<string|int, int> —All office IDs
getDeputyOffices()
Get deputy office IDs for a given office.
private
getDeputyOffices(int $officeId) : array<string|int, int>
Parameters
- $officeId : int
-
The office ID.
Return values
array<string|int, int>getDirectReportOffices()
Get direct report office IDs for a given office.
private
getDirectReportOffices(int $officeId) : array<string|int, int>
Parameters
- $officeId : int
-
The office ID.
Return values
array<string|int, int>getOfficesForPosition()
Get accessible offices for a specific user position.
private
getOfficesForPosition(Member $user, Officer $position, int $branchId, array<string|int, mixed> &$permissionCache) : array<string|int, int>
Parameters
- $user : Member
-
The user entity.
- $position : Officer
-
The user's officer position.
- $branchId : int
-
The branch ID.
- $permissionCache : array<string|int, mixed>
-
Permission cache for optimization.
Return values
array<string|int, int>getPositionPermissions()
Get permissions for a user's position.
private
getPositionPermissions(Member $user, Officer $position, int $branchId) : array<string|int, mixed>
Parameters
- $user : Member
-
The user entity.
- $position : Officer
-
The user's officer position.
- $branchId : int
-
The branch ID.
Return values
array<string|int, mixed>getReportingTreeOffices()
Return the office IDs that are reachable from a given office through deputy or reporting relationships in breadth-first order.
private
getReportingTreeOffices(int $rootOfficeId) : array<string|int, int>
Parameters
- $rootOfficeId : int
-
The starting office ID whose reporting tree will be traversed; the returned list excludes this root.
Return values
array<string|int, int> —An array of office IDs encountered in breadth-first order, excluding the root office.
getUserOfficerPositions()
Get user's current officer positions.
private
getUserOfficerPositions(Member $user) : array<string|int, mixed>
Parameters
- $user : Member
-
The user to get positions for
Return values
array<string|int, mixed> —Current officer position entities
hasGlobalOfficerPermissions()
Check if user has global officer management permissions.
private
hasGlobalOfficerPermissions(Member $user) : bool
Parameters
- $user : Member
-
The user to check
Return values
bool —True if user has workWithAllOfficers permission