KMP PHP API Reference

DefaultAuthorizationManager
in package
implements AuthorizationManagerInterface uses QueuedMailerAwareTrait

Default Authorization Manager Service

Production implementation of AuthorizationManagerInterface providing authorization lifecycle management for the Activities plugin.

Handles authorization request creation, activation, revocation, and retraction. Approval and denial workflows are handled by the unified workflow engine.

Tags
see
AuthorizationManagerInterface

Service contract definition

ActiveWindowManagerInterface

Temporal validation service

ServiceResult

Standardized result pattern

Authorization

Authorization entity

Table of Contents

Interfaces

AuthorizationManagerInterface
Contract for managing member activity authorizations.

Properties

$mailer  : Mailer
$activeWindowManager  : ActiveWindowManagerInterface
$triggerDispatcher  : TriggerDispatcher

Methods

__construct()  : mixed
Constructor.
activate()  : ServiceResult
Activate a fully-approved authorization.
request()  : ServiceResult
Create a new authorization request in pending status.
retract()  : ServiceResult
Retract Pending Authorization Request
revoke()  : ServiceResult
Process Authorization Revocation
queueMail()  : Mailer
Returns a mailer instance.
queueMailJob()  : void
Queues a mail job to be processed later.
sendAuthorizationStatusToRequester()  : bool
Send Authorization Status Notification to Requester
sendMailNow()  : Mailer
Returns a mailer instance.
buildMemberCardUrl()  : string
Build a member card URL.
cancelWorkflowApprovalsForEntity()  : ServiceResult
Cancel all open workflow engine state for an authorization entity.
sendRetractedNotificationToApprover()  : bool
Send Retraction Notification to Approver
workflowInstanceMatchesAuthorization()  : bool
Determine whether a workflow instance belongs to the given authorization.

Properties

Methods

activate()

Activate a fully-approved authorization.

public activate(int $authorizationId, int $approverId) : ServiceResult

Sets status to APPROVED, starts ActiveWindow, assigns role. Does not send notifications (workflow handles those separately).

Parameters
$authorizationId : int

Authorization ID to activate

$approverId : int

Member ID of the final approver

Return values
ServiceResult —

Success with activated and memberRoleId data

request()

Create a new authorization request in pending status.

public request(int $requesterId, int $activityId, int $approverId, bool $isRenewal) : ServiceResult

Validates renewal eligibility, prevents duplicates, and creates the authorization entity. Notification and approval workflow are handled by the workflow engine after this method returns.

Parameters
$requesterId : int

Member ID requesting authorization

$activityId : int

Activity ID for authorization request

$approverId : int

Member ID of designated approver

$isRenewal : bool

Whether this is a renewal of existing authorization

Return values
ServiceResult —

Success/failure result with error details

retract()

Retract Pending Authorization Request

public retract(int $authorizationId, int $requesterId) : ServiceResult

Allows a member to retract their own pending authorization request. This provides member autonomy to cancel requests sent to wrong approvers or no longer needed.

Business Logic:

  • Validates authorization is in pending status
  • Ensures requester owns the authorization
  • Updates status to retracted
  • Maintains audit trail
  • Optionally notifies approver of retraction

Validation Rules:

  • Authorization must exist
  • Authorization must be in PENDING status
  • Requester must match authorization member_id
  • Authorization cannot have been approved/denied

Transaction Management: Uses database transactions to ensure consistency:

  • Status update to RETRACTED
  • Optional notification sending
  • Rollback on any failure

Success Result Data: Returns ServiceResult with:

  • success: true
  • data: ['authorization' => retracted authorization entity]

Error Scenarios:

  • Authorization not found: "Authorization not found"
  • Not pending: "Only pending authorizations can be retracted"
  • Wrong owner: "You can only retract your own authorization requests"
  • Status update failure: "Failed to update authorization status"
Parameters
$authorizationId : int

Authorization record ID to retract

$requesterId : int

Member ID of person retracting (must be authorization owner)

Return values
ServiceResult —

Success/failure result with retraction confirmation

revoke()

Process Authorization Revocation

public revoke(int $authorizationId, int $revokerId, string $revokedReason) : ServiceResult

Handles revocation of active authorizations with ActiveWindow integration and comprehensive audit trail maintenance.

Revocation Workflow:

  • Validates authorization exists and is revocable
  • Integrates with ActiveWindowManager to stop temporal validation
  • Updates authorization status to revoked
  • Records revoker ID and revocation reason
  • Automatically removes associated role assignments
  • Sends notification to affected member

ActiveWindow Integration: Uses ActiveWindowManager.stop() to:

  • End temporal validation window immediately
  • Remove role assignments granted by authorization
  • Update authorization status to revoked
  • Create complete audit trail of revocation

Role Management: Revocation automatically removes any roles that were granted by the authorization, ensuring immediate cessation of elevated permissions and maintaining security compliance.

Audit Requirements:

  • Records revoker identity for accountability
  • Captures revocation reason for compliance
  • Timestamps revocation for temporal tracking
  • Maintains complete authorization lifecycle history

Notification Process: Automatically notifies affected member of revocation with:

  • Revocation reason and revoker identity
  • Effective date of revocation
  • Impact on permissions and roles
  • Appeal or reauthorization process information
Parameters
$authorizationId : int

Authorization record ID to revoke

$revokerId : int

Member ID of person performing revocation

$revokedReason : string

Reason for revocation (required for audit)

Return values
ServiceResult —

Success/failure result with revocation confirmation

queueMail()

Returns a mailer instance.

protected queueMail(string $name, mixed $action, mixed $to, mixed $vars) : Mailer
Parameters
$name : string

Mailer's name.

$action : mixed
$to : mixed
$vars : mixed
Tags
throws
MissingMailerException

if undefined mailer class.

Return values
Mailer

queueMailJob()

Queues a mail job to be processed later.

protected queueMailJob(array<string|int, mixed> $data) : void
Parameters
$data : array<string|int, mixed>

Data to be passed to the mailer.

sendAuthorizationStatusToRequester()

Send Authorization Status Notification to Requester

protected sendAuthorizationStatusToRequester(int $activityId, int $requesterId, int $approverId, string $status[, int|null $nextApproverId = null ]) : bool

Sends status update notifications to authorization requesters with comprehensive workflow context and next steps information.

Notification Context:

  • Activity name and details
  • Current authorization status
  • Approver identity for transparency
  • Next approver in chain (if applicable)
  • Requester personalization

Status Types Handled:

  • Approved: Final approval with role assignment details
  • Denied: Denial reason and appeal process
  • Pending: Forward to next approver information
  • Revoked: Revocation details and impact
Parameters
$activityId : int

Activity ID for context

$requesterId : int

Member ID of requester

$approverId : int

Member ID of current approver

$status : string

Current authorization status

$nextApproverId : int|null = null

Next approver ID (for multi-level workflows)

Return values
bool —

Success/failure of notification sending

sendMailNow()

Returns a mailer instance.

protected sendMailNow(array<string|int, mixed> $data) : Mailer
Parameters
$data : array<string|int, mixed>
Tags
throws
MissingMailerException

if undefined mailer class.

Return values
Mailer

buildMemberCardUrl()

Build a member card URL.

private buildMemberCardUrl(int $memberId) : string
Parameters
$memberId : int

Member ID

Return values
string —

URL to the member card

cancelWorkflowApprovalsForEntity()

Cancel all open workflow engine state for an authorization entity.

private cancelWorkflowApprovalsForEntity(int $authorizationId, string $cancellationReason) : ServiceResult

Finds workflow instances linked to the given authorization ID (both current and legacy entity_type values, including older instances that only stored authorizationId in context) and cancels any pending approvals as well as the waiting/running workflow instance itself.

Parameters
$authorizationId : int

Authorization record ID

$cancellationReason : string

Human-readable cancellation reason

Return values
ServiceResult

sendRetractedNotificationToApprover()

Send Retraction Notification to Approver

private sendRetractedNotificationToApprover(int $activityId, int $requesterId, int $approverId) : bool

Notifies the approver that an authorization request they were reviewing has been retracted by the requester.

Notification Context:

  • Activity name
  • Requester name
  • Retraction timestamp
Parameters
$activityId : int

Activity ID for context

$requesterId : int

Member ID of requester who retracted

$approverId : int

Member ID of approver to notify

Return values
bool —

Success/failure of notification sending

workflowInstanceMatchesAuthorization()

Determine whether a workflow instance belongs to the given authorization.

private workflowInstanceMatchesAuthorization(WorkflowInstance $instance, int $authorizationId) : bool
Parameters
$instance : WorkflowInstance

Workflow instance candidate

$authorizationId : int

Authorization record ID

Return values
bool
On this page

Search results