OfficerAssignmentWorkflowActions
in package
uses
WorkflowContextAwareTrait
Ephemeral workflow actions for editing an existing officer assignment.
The assignment, its granted role, the required audit note, and any warrant shortening or retroactive termination are deliberately handled in one database transaction. Warrant-extension requests and notifications remain separate workflow nodes so installations can customize those policies.
Table of Contents
Constants
- ENTITY_TYPE : mixed = 'Officers.Officers'
- PENDING_WITHDRAWAL_REASON : mixed = 'Officer term shortened; the issued warrant now...
- TERM_NOTE_REQUIRED_ERROR : mixed = 'A note is required when changing an officer te...
- TERMINAL_ASSIGNMENT_ERROR : mixed = 'Only current or upcoming officer assignments c...
- UPDATE_FAILED_ERROR : mixed = 'The officer assignment could not be updated.'
Properties
Methods
- __construct() : mixed
- prepareAssignmentUpdateNotificationVars() : array<string, mixed>
- Prepare officer-assignment update notification variables.
- requestWarrantExtension() : array<string, mixed>
- Request a covering warrant without cancelling the officer's current one.
- updateOfficerAssignment() : array<string, mixed>
- Update an officer assignment and its security-sensitive dependants.
- resolveValue() : mixed
- Resolve a config value from context if it starts with '$.'.
- asDateTime() : DateTime|null
- Normalize an ORM date value to DateTime.
- buildChangeSummary() : string
- Build plain-text change details for the member notification.
- createTermNote() : void
- Persist the officer term audit note.
- dateKey() : string|null
- deriveOfficerStatus() : string
- Derive the assignment status using normalized term boundaries.
- displayDate() : string
- getOfficerForUpdate() : Officer
- Load and lock an assignment before evaluating mutable source state.
- parseDate() : DateTime|null
- Parse a submitted ISO date without accepting normalized invalid dates.
- requestWarrantExtensionUnderLock() : array<string, mixed>
- Check and create an extension while holding the officer assignment lock.
- resolveActorId() : int
- Resolve the audit actor from trusted engine context, with a direct-call fallback.
- shortenCurrentWarrants() : int
- Shorten active current warrants that outlast a revised officer term.
- syncGrantedMemberRole() : void
- Synchronize the dates on the role granted by an officer assignment.
- terminateCurrentAndPendingWarrants() : int
- Terminate exact current and pending warrant records for a past-end correction.
- warrantExtensionFailureResult() : array<string, mixed>
- Return a user-safe partial-success result for extension failures.
Constants
ENTITY_TYPE
private
mixed
ENTITY_TYPE
= 'Officers.Officers'
PENDING_WITHDRAWAL_REASON
private
mixed
PENDING_WITHDRAWAL_REASON
= 'Officer term shortened; the issued warrant now covers the complete revised term.'
TERM_NOTE_REQUIRED_ERROR
private
mixed
TERM_NOTE_REQUIRED_ERROR
= 'A note is required when changing an officer term.'
TERMINAL_ASSIGNMENT_ERROR
private
mixed
TERMINAL_ASSIGNMENT_ERROR
= 'Only current or upcoming officer assignments can be updated.'
UPDATE_FAILED_ERROR
private
mixed
UPDATE_FAILED_ERROR
= 'The officer assignment could not be updated.'
Properties
$warrantManager
private
WarrantManagerInterface
$warrantManager
Methods
__construct()
public
__construct(WarrantManagerInterface $warrantManager) : mixed
Parameters
- $warrantManager : WarrantManagerInterface
-
Warrant lifecycle service.
prepareAssignmentUpdateNotificationVars()
Prepare officer-assignment update notification variables.
public
prepareAssignmentUpdateNotificationVars(array<string, mixed> $context, array<string, mixed> $config) : array<string, mixed>
Parameters
- $context : array<string, mixed>
-
Workflow context.
- $config : array<string, mixed>
-
Resolved action configuration.
Return values
array<string, mixed>requestWarrantExtension()
Request a covering warrant without cancelling the officer's current one.
public
requestWarrantExtension(array<string, mixed> $context, array<string, mixed> $config) : array<string, mixed>
Parameters
- $context : array<string, mixed>
-
Workflow context.
- $config : array<string, mixed>
-
Resolved action configuration.
Return values
array<string, mixed>updateOfficerAssignment()
Update an officer assignment and its security-sensitive dependants.
public
updateOfficerAssignment(array<string, mixed> $context, array<string, mixed> $config) : array<string, mixed>
Parameters
- $context : array<string, mixed>
-
Workflow context.
- $config : array<string, mixed>
-
Resolved action configuration.
Return values
array<string, mixed>resolveValue()
Resolve a config value from context if it starts with '$.'.
protected
resolveValue(mixed $value, array<string|int, mixed> $context) : mixed
Parameters
- $value : mixed
-
Raw value or context path (e.g. '$.trigger.memberId')
- $context : array<string|int, mixed>
-
Current workflow context
Return values
mixed —Resolved value
asDateTime()
Normalize an ORM date value to DateTime.
private
asDateTime(mixed $value) : DateTime|null
Parameters
- $value : mixed
-
ORM date value.
Return values
DateTime|nullbuildChangeSummary()
Build plain-text change details for the member notification.
private
buildChangeSummary(bool $startChanged, bool $endChanged, bool $emailChanged, bool $deputyChanged, DateTime|null $previousStart, DateTime|null $previousEnd, DateTime $newStart, DateTime|null $newEnd) : string
Parameters
- $startChanged : bool
-
Whether the start date changed.
- $endChanged : bool
-
Whether the end date changed.
- $emailChanged : bool
-
Whether the office email changed.
- $deputyChanged : bool
-
Whether the deputy description changed.
- $previousStart : DateTime|null
-
Previous start date.
- $previousEnd : DateTime|null
-
Previous end date.
- $newStart : DateTime
-
New start date.
- $newEnd : DateTime|null
-
New end date.
Return values
stringcreateTermNote()
Persist the officer term audit note.
private
createTermNote(Officer $officer, int $actorId, string $termNote, DateTime|null $previousStart, DateTime|null $previousEnd, DateTime $newStart, DateTime|null $newEnd, DateTime $recordedAt, bool $pastEnd, int $shortenedWarrantCount, int $terminatedWarrantCount, int $withdrawnPendingWarrantCount) : void
Parameters
- $officer : Officer
-
Officer assignment.
- $actorId : int
-
Note author.
- $termNote : string
-
User-supplied reason.
- $previousStart : DateTime|null
-
Previous start date.
- $previousEnd : DateTime|null
-
Previous end date.
- $newStart : DateTime
-
New start date.
- $newEnd : DateTime|null
-
New end date.
- $recordedAt : DateTime
-
Change recording time.
- $pastEnd : bool
-
Whether the new end is in the past.
- $shortenedWarrantCount : int
-
Number of shortened current warrants.
- $terminatedWarrantCount : int
-
Number of terminated warrants.
- $withdrawnPendingWarrantCount : int
-
Number of obsolete pending warrants withdrawn.
dateKey()
private
dateKey(DateTime|null $date) : string|null
Parameters
- $date : DateTime|null
-
Date to normalize.
Return values
string|nullderiveOfficerStatus()
Derive the assignment status using normalized term boundaries.
private
deriveOfficerStatus(DateTime $startOn, DateTime|null $expiresOn, DateTime $now) : string
Parameters
- $startOn : DateTime
-
Term start.
- $expiresOn : DateTime|null
-
Term end.
- $now : DateTime
-
Recording time.
Return values
stringdisplayDate()
private
displayDate(DateTime|null $date) : string
Parameters
- $date : DateTime|null
-
Date to format.
Return values
stringgetOfficerForUpdate()
Load and lock an assignment before evaluating mutable source state.
private
getOfficerForUpdate(int $officerId) : Officer
SQLite serializes writes and does not support FOR UPDATE. MySQL and PostgreSQL use an explicit row lock to prevent concurrent lost updates.
Parameters
- $officerId : int
-
Officer assignment id.
Return values
OfficerparseDate()
Parse a submitted ISO date without accepting normalized invalid dates.
private
parseDate(mixed $value, string $label, bool $allowEmpty) : DateTime|null
Parameters
- $value : mixed
-
Submitted value.
- $label : string
-
Human-readable field label.
- $allowEmpty : bool
-
Whether an empty value is valid.
Return values
DateTime|nullrequestWarrantExtensionUnderLock()
Check and create an extension while holding the officer assignment lock.
private
requestWarrantExtensionUnderLock(int $officerId, int $actorId, string $existingMessage) : array<string, mixed>
SQLite serializes writes at the database level and does not support FOR UPDATE; MySQL and PostgreSQL use the explicit row lock below.
Parameters
- $officerId : int
-
Officer assignment id.
- $actorId : int
-
Trusted requesting member id.
- $existingMessage : string
-
Warrant result from the update action.
Return values
array<string, mixed>resolveActorId()
Resolve the audit actor from trusted engine context, with a direct-call fallback.
private
resolveActorId(array<string, mixed> $context, array<string, mixed> $config) : int
Parameters
- $context : array<string, mixed>
-
Workflow context.
- $config : array<string, mixed>
-
Resolved action configuration.
Return values
intshortenCurrentWarrants()
Shorten active current warrants that outlast a revised officer term.
private
shortenCurrentWarrants(Officer $officer, int $actorId, DateTime $expiresOn, DateTime $recordedAt) : int
Already-issued warrants may be shortened, but this update path never lengthens one. A longer term is handled by the separate extension-request workflow action.
Parameters
- $officer : Officer
-
Officer assignment.
- $actorId : int
-
Member recording the change.
- $expiresOn : DateTime
-
Revised officer term end.
- $recordedAt : DateTime
-
Change recording time.
Return values
int —Number of shortened current warrant records.
syncGrantedMemberRole()
Synchronize the dates on the role granted by an officer assignment.
private
syncGrantedMemberRole(Officer $officer, DateTime $startOn, DateTime|null $expiresOn, bool $syncStart, bool $syncEnd) : void
Parameters
- $officer : Officer
-
Officer assignment.
- $startOn : DateTime
-
Role start date.
- $expiresOn : DateTime|null
-
Role end date.
- $syncStart : bool
-
Whether the start date changed.
- $syncEnd : bool
-
Whether the end date changed.
terminateCurrentAndPendingWarrants()
Terminate exact current and pending warrant records for a past-end correction.
private
terminateCurrentAndPendingWarrants(Officer $officer, int $actorId, DateTime $recordedAt) : int
Parameters
- $officer : Officer
-
Officer assignment.
- $actorId : int
-
Member recording the change.
- $recordedAt : DateTime
-
Change recording time.
Return values
int —Number of terminated warrant records.
warrantExtensionFailureResult()
Return a user-safe partial-success result for extension failures.
private
warrantExtensionFailureResult() : array<string, mixed>