WarrantManagerInterface
in
Warrant Manager Interface
Defines the contract for managing KMP warrant lifecycle: requests, approvals, and lifecycle management for authorized roles/positions within branches.
Tags
Table of Contents
Constants
- REQUEST_REUSED_REASON : string = 'Equivalent pending warrant request already in...
Methods
- activateApprovedRoster() : ServiceResult
- Activate warrants in an already-approved roster.
- cancel() : ServiceResult
- Cancel/revoke a specific warrant by ID.
- cancelByEntity() : ServiceResult
- Cancel all warrants associated with a specific entity.
- decline() : ServiceResult
- Decline an entire warrant roster and cancel all contained warrants.
- declineSingleWarrant() : ServiceResult
- Decline a single warrant within a roster.
- getWarrantPeriod() : WarrantPeriod|null
- Find or create a warrant period covering the specified date range.
- request() : ServiceResult
- Submit a batch of warrant requests for approval.
- syncWorkflowApprovalToRoster() : ServiceResult
- Sync a workflow approval response to the roster's denormalized counter.
- withdrawPendingRequests() : ServiceResult
- Withdraw all in-flight warrants for one exact warrant identity.
Constants
REQUEST_REUSED_REASON
public
string
REQUEST_REUSED_REASON
= 'Equivalent pending warrant request already in flight'
Informational result reason when an exact in-flight request is reused.
Methods
activateApprovedRoster()
Activate warrants in an already-approved roster.
public
activateApprovedRoster(int $rosterId, int $approverId) : ServiceResult
Expects roster status=APPROVED and correct approval_count. Activates pending warrants and expires overlapping ones. Idempotent: returns success if no pending warrants remain.
Parameters
- $rosterId : int
-
ID of the approved WarrantRoster
- $approverId : int
-
ID of the member who approved
Return values
ServiceResult —Success if warrants activated or already active
cancel()
Cancel/revoke a specific warrant by ID.
public
cancel(int $warrant_id, string $reason, int $rejecter_id, DateTime $expiresOn) : ServiceResult
Parameters
- $warrant_id : int
-
ID of the warrant to cancel
- $reason : string
-
Explanation for cancellation
- $rejecter_id : int
-
ID of member cancelling
- $expiresOn : DateTime
-
When warrant should terminate
Return values
ServiceResult —Always returns success
cancelByEntity()
Cancel all warrants associated with a specific entity.
public
cancelByEntity(string $entityType, int $entityId, string $reason, int $rejecter_id, DateTime $expiresOn) : ServiceResult
Parameters
- $entityType : string
-
Entity type (e.g., 'Branches', 'Activities')
- $entityId : int
-
ID of the entity instance
- $reason : string
-
Explanation for cancellation
- $rejecter_id : int
-
ID of member cancelling
- $expiresOn : DateTime
-
When warrants should terminate
Return values
ServiceResult —Always returns success
decline()
Decline an entire warrant roster and cancel all contained warrants.
public
decline(int $warrant_roster_id, int $rejecter_id, string $reason) : ServiceResult
Parameters
- $warrant_roster_id : int
-
ID of the WarrantRoster to decline
- $rejecter_id : int
-
ID of the member declining
- $reason : string
-
Explanation for the decline
Return values
ServiceResult —Success if declined, failure with errors
declineSingleWarrant()
Decline a single warrant within a roster.
public
declineSingleWarrant(int $warrant_id, string $reason, int $rejecter_id) : ServiceResult
Parameters
- $warrant_id : int
-
ID of the warrant to decline
- $reason : string
-
Explanation for decline
- $rejecter_id : int
-
ID of member declining
Return values
ServiceResult —Success if declined, failure with errors
getWarrantPeriod()
Find or create a warrant period covering the specified date range.
public
getWarrantPeriod(DateTime $startOn, DateTime|null $endOn) : WarrantPeriod|null
Parameters
- $startOn : DateTime
-
Desired warrant start date
- $endOn : DateTime|null
-
Desired warrant end date
Return values
WarrantPeriod|null —Matching period, or null if none found
request()
Submit a batch of warrant requests for approval.
public
request(string $request_name, string $desc, array<string|int, WarrantRequest> $warrantRequests[, int|null $requestedBy = null ]) : ServiceResult
Parameters
- $request_name : string
-
Name for the warrant roster
- $desc : string
-
Description of the warrant requests
- $warrantRequests : array<string|int, WarrantRequest>
-
Array of warrant request objects
- $requestedBy : int|null = null
-
Member ID of the user who initiated the request
Return values
ServiceResult —Success with roster ID, or failure with errors. Exact retries return the existing roster ID and REQUEST_REUSED_REASON.
syncWorkflowApprovalToRoster()
Sync a workflow approval response to the roster's denormalized counter.
public
syncWorkflowApprovalToRoster(int $rosterId, int $approverId[, string|null $notes = null ][, DateTimeInterface|null $approvedOn = null ]) : ServiceResult
Increments approval_count on the warrant_rosters table. Dedup is handled by the workflow engine's approval manager. Does NOT change roster status or activate warrants.
Parameters
- $rosterId : int
-
ID of the WarrantRoster
- $approverId : int
-
ID of the approving member
- $notes : string|null = null
-
Optional approval notes (unused, kept for interface compat)
- $approvedOn : DateTimeInterface|null = null
-
When approval occurred (unused, kept for interface compat)
Return values
ServiceResult —Success after counter increment
withdrawPendingRequests()
Withdraw all in-flight warrants for one exact warrant identity.
public
withdrawPendingRequests(string $entityType, int $entityId, int $memberId, int|null $memberRoleId, int $requestedBy, string $reason) : ServiceResult
Current warrants are never changed. Matching pending warrants are marked replaced; shared rosters keep running, while emptied rosters and their approval workflows are closed.
Parameters
- $entityType : string
-
Warranted entity type
- $entityId : int
-
Warranted entity ID
- $memberId : int
-
Warrant recipient
- $memberRoleId : int|null
-
Linked member-role assignment
- $requestedBy : int
-
Member recording the withdrawal
- $reason : string
-
Audit reason
Return values
ServiceResult —Success with the withdrawn warrant count