KMP PHP API Reference

DefaultAuthorizationManager
in package
implements AuthorizationManagerInterface uses MailerAwareTrait

Default Authorization Manager Service

Purpose: Production implementation of AuthorizationManagerInterface providing comprehensive authorization lifecycle management, multi-level approval workflows, and temporal validation for Activities plugin member authorization system.

Core Responsibilities:

  • Authorization Request Processing - Complete authorization request lifecycle management
  • Multi-Level Approval Workflows - Sequential approval chains with forwarding logic
  • Authorization Status Management - Approval, denial, and revocation operations
  • Email Notification System - Automated approver and requester notifications
  • ActiveWindow Integration - Temporal validation and automatic role assignment
  • Transaction Management - Database consistency and rollback protection

Architecture: This service implements the AuthorizationManagerInterface contract and provides the core business logic for authorization workflows within the Activities plugin. It integrates with multiple KMP systems including the ActiveWindowManager for temporal validation, the email system for notifications, and the RBAC system for automatic role assignment.

Authorization Workflow:

Request → Pending → (Multi-Level Approvals) → Approved/Denied → Active/Expired/Revoked

Business Logic Features:

  • Renewal vs. New Authorization validation
  • Duplicate request prevention
  • Multi-approver sequential workflows
  • Secure token-based email approval
  • Automatic role assignment on approval
  • Temporal expiration management
  • Comprehensive audit trail

Security Implementation:

  • Database transaction management for consistency
  • Secure token generation for email-based approvals
  • Validation of approver permissions
  • Prevention of duplicate or conflicting requests
  • Audit trail for all authorization actions

Integration Points:

  • AuthorizationManagerInterface - Service contract compliance
  • ActiveWindowManagerInterface - Temporal validation and role management
  • MailerAwareTrait - Email notification system integration
  • TableRegistry - Database table access and management
  • ServiceResult - Standardized operation result patterns
  • StaticHelpers - Token generation and utility functions

Performance Considerations:

  • Database transaction management minimizes lock time
  • Efficient query patterns for approval count validation
  • Batch processing for multi-approval workflows
  • Email notification batching for performance

Usage Examples:

// Authorization request processing
$result = $authManager->request(
    requesterId: 123,
    activityId: 456,
    approverId: 789,
    isRenewal: false
);

// Multi-level approval processing
$result = $authManager->approve(
    authorizationApprovalId: 100,
    approverId: 789,
    nextApproverId: 101  // For sequential approvals
);

// Authorization denial with audit trail
$result = $authManager->deny(
    authorizationApprovalId: 100,
    approverId: 789,
    denyReason: "Insufficient qualifications"
);

// Authorization revocation
$result = $authManager->revoke(
    authorizationId: 200,
    revokerId: 789,
    revokedReason: "Policy violation"
);

Error Handling: All methods return ServiceResult objects with detailed error messages and transaction rollback on failure. Common error scenarios include validation failures, duplicate requests, approver permission issues, and email notification failures.

Troubleshooting:

  • Verify ActiveWindowManager service availability for temporal operations
  • Check email configuration for notification delivery
  • Validate approver permissions for authorization activities
  • Monitor transaction logs for database consistency issues
Tags
see
AuthorizationManagerInterface

Service contract definition

see
ActiveWindowManagerInterface

Temporal validation service

see
ServiceResult

Standardized result pattern

see
Authorization

Entity authorization entity

see
AuthorizationApproval

Approval tracking entity

used-by
DefaultAuthorizationManagerTest

Table of Contents

Interfaces

AuthorizationManagerInterface
Contract for managing member activity authorizations.

Methods

__construct()  : mixed
Constructor.
approve()  : ServiceResult
Process Authorization Approval
deny()  : ServiceResult
Process Authorization Denial
request()  : ServiceResult
Process Authorization Request
retract()  : ServiceResult
Retract Pending Authorization Request
revoke()  : ServiceResult
Process Authorization Revocation
sendAuthorizationStatusToRequester()  : bool
Send Authorization Status Notification to Requester
getApprovalsRequiredCount()  : int
Get Required Approvals Count
getNeedsMoreRenewals()  : bool
Check if More Approvals Needed
processApprovedAuthorization()  : bool
Process Final Authorization Approval
processForwardToNextApprover()  : bool
Process Forward to Next Approver
saveAuthorizationApproval()  : bool
Save Authorization Approval Record
sendApprovalRequestNotification()  : bool
Send Approval Request Notification to Approver
sendRetractedNotificationToApprover()  : bool
Send Retraction Notification to Approver

Methods

approve()

Process Authorization Approval

public approve(int $authorizationApprovalId, int $approverId[, int|null $nextApproverId = null ]) : ServiceResult

Handles authorization approval with support for multi-level approval workflows. Manages sequential approver chains and final authorization activation.

Approval Workflow Logic:

  • Records approver decision with timestamp and approval status
  • Checks if additional approvals are required based on activity configuration
  • For multi-approval: Forwards to next approver in sequence
  • For final approval: Activates authorization and assigns roles
  • Integrates with ActiveWindowManager for temporal validation
  • Sends notifications to all relevant parties

Multi-Level Support: Activities can require multiple approvers for new authorizations or renewals. Method handles sequential approval chains by checking required approval counts and forwarding to next approver when additional approvals needed.

Role Assignment: Upon final approval, integrates with ActiveWindowManager to:

  • Start temporal validation window
  • Assign configured role to member
  • Set expiration based on activity term length
  • Create audit trail for role assignment

Transaction Management: Comprehensive transaction management ensures consistency across approval recording, authorization updates, role assignments, and notifications.

Parameters
$authorizationApprovalId : int

Authorization approval record ID

$approverId : int

Member ID of approver making decision

$nextApproverId : int|null = null

Member ID of next approver (for multi-level)

Return values
ServiceResult —

Success/failure result with workflow status

deny()

Process Authorization Denial

public deny(int $authorizationApprovalId, int $approverId, string $denyReason) : ServiceResult

Handles authorization denial with comprehensive audit trail and notification system. Updates authorization status and records denial reasoning for accountability.

Denial Workflow:

  • Records approver decision with timestamp and denial reason
  • Updates authorization status to denied
  • Sets authorization temporal window to past (immediately expired)
  • Creates audit trail with approver ID and reasoning
  • Sends notification to requester with denial details

Audit Trail Features:

  • Records approver ID for accountability
  • Captures denial reason for future reference
  • Timestamps decision for workflow tracking
  • Maintains complete approval chain history

Status Management: Denied authorizations are set to expired status with past temporal window to ensure they don't interfere with future authorization requests while maintaining complete audit trail.

Notification System: Automatically notifies requester of denial decision with:

  • Denial reason from approver
  • Approver identity for transparency
  • Activity details for context
  • Guidance for future requests
Parameters
$authorizationApprovalId : int

Authorization approval record ID

$approverId : int

Member ID of approver making denial decision

$denyReason : string

Reason for denial (required for audit trail)

Return values
ServiceResult —

Success/failure result with denial confirmation

request()

Process Authorization Request

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

Creates a new authorization request with approval workflow initialization. Handles both new authorizations and renewals with comprehensive validation.

Business Logic:

  • Validates renewal eligibility (existing approved authorization required)
  • Prevents duplicate pending requests for same activity
  • Creates authorization entity with pending status
  • Initializes approval workflow with first approver
  • Generates secure token for email-based approval
  • Sends notification to designated approver

Validation Rules:

  • Renewal: Must have existing approved authorization that hasn't expired
  • Duplicate Prevention: No pending requests for same member/activity combination
  • Approver Validation: Approver must have permission to authorize activity

Transaction Management: Method creates database transaction for consistency across authorization creation, approval initialization, and notification sending. Rolls back on any failure to maintain data integrity.

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

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

getApprovalsRequiredCount()

Get Required Approvals Count

private getApprovalsRequiredCount(bool $isRenewal, mixed $activity) : int

Determines the number of approvals required based on authorization type and activity configuration settings.

Configuration Logic:

  • New Authorizations: Uses activity.num_required_authorizors
  • Renewal Authorizations: Uses activity.num_required_renewers
  • Supports different approval requirements for new vs. renewal
Parameters
$isRenewal : bool

Whether authorization is a renewal

$activity : mixed

Activity entity with approval requirements

Return values
int —

Number of approvals required

getNeedsMoreRenewals()

Check if More Approvals Needed

private getNeedsMoreRenewals(int $requiredApprovalCount, int $authorizationId, mixed $approvalTable) : bool

Determines whether authorization requires additional approvals before final activation based on current approval count and requirements.

Approval Logic:

  • Compares current approved count to required count
  • Returns true if additional approvals needed
  • Supports multi-level approval workflows
  • Handles single-approval activities efficiently
Parameters
$requiredApprovalCount : int

Total approvals required

$authorizationId : int

Authorization ID to check

$approvalTable : mixed

Authorization approvals table

Return values
bool —

True if more approvals needed, false if ready for activation

processApprovedAuthorization()

Process Final Authorization Approval

private processApprovedAuthorization(mixed $authorization, int $approverId, mixed $authTable) : bool

Handles final approval processing including status updates, role assignment, and temporal validation activation through ActiveWindowManager integration.

Final Approval Operations:

  • Updates authorization status to approved
  • Increments approval count for audit trail
  • Activates temporal validation window
  • Assigns configured role to member
  • Sends confirmation notification to requester

ActiveWindow Integration: Calls ActiveWindowManager.start() to begin temporal validation with:

  • Authorization effective date
  • Activity-defined term length
  • Role assignment automation
  • Expiration date calculation
Parameters
$authorization : mixed

Authorization entity to approve

$approverId : int

Member ID of final approver

$authTable : mixed

Authorizations table instance

Return values
bool —

Success/failure of approval processing

processForwardToNextApprover()

Process Forward to Next Approver

private processForwardToNextApprover(int $approverId, int $nextApproverId, mixed $authorization, mixed $approvalTable, mixed $authTable) : bool

Handles forwarding authorization to next approver in multi-level approval workflows with validation, token generation, and notification management.

Multi-Level Workflow Logic:

  • Validates next approver exists and has permission
  • Updates authorization status to pending (for next level)
  • Increments approval count for tracking
  • Creates new approval record for next approver
  • Generates secure token for email-based approval
  • Sends notifications to both parties

Security Validation:

  • Verifies next approver ID is valid
  • Confirms approver has authorization permission
  • Generates unique secure token for approval

Notification Flow:

  • Notifies next approver of pending request
  • Informs requester of workflow progress
  • Provides transparent approval chain visibility
Parameters
$approverId : int

Current approver ID

$nextApproverId : int

Next approver ID in chain

$authorization : mixed

Authorization entity

$approvalTable : mixed

Authorization approvals table

$authTable : mixed

Authorizations table

Return values
bool —

Success/failure of forwarding process

saveAuthorizationApproval()

Save Authorization Approval Record

private saveAuthorizationApproval(int $approverId, mixed $approval, mixed $approvalTable, mixed $transConnection) : bool

Persists approval decision with timestamp, approver identity, and approval status for audit trail and workflow tracking.

Approval Recording:

  • Sets response timestamp for workflow tracking
  • Records approver ID for accountability
  • Sets approval status (approved = true)
  • Maintains complete audit trail

Transaction Safety: Includes transaction rollback on save failure to maintain database consistency during approval processing.

Parameters
$approverId : int

Member ID making approval decision

$approval : mixed

Authorization approval entity

$approvalTable : mixed

Authorization approvals table

$transConnection : mixed

Database transaction connection

Return values
bool —

Success/failure of approval recording

sendApprovalRequestNotification()

Send Approval Request Notification to Approver

private sendApprovalRequestNotification(int $activityId, int $requesterId, int $approverId, string $authorizationToken) : bool

Sends authorization approval request notifications to designated approvers with secure token-based approval links and complete request context.

Security Features:

  • Secure token generation for email-based approval
  • Token-based authentication for approval actions
  • Prevention of unauthorized approval access

Notification Content:

  • Requester identity and details
  • Activity information and requirements
  • Secure approval/denial links
  • Request context and urgency
  • Workflow position (if multi-level)

Token Management: Generates cryptographically secure tokens for each approval request to enable email-based approval while maintaining security and preventing unauthorized access to approval functionality.

Parameters
$activityId : int

Activity ID for context

$requesterId : int

Member ID of requester

$approverId : int

Member ID of designated approver

$authorizationToken : string

Secure token for email-based approval

Return values
bool —

Success/failure of notification sending

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


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results