← Back to Plugin Architecture

5.6.1 Activities Plugin Architecture & Configuration

Last Updated: December 3, 2025
Status: Complete
Plugin: Activities

Table of Contents

Plugin Architecture Overview

The Activities Plugin is a foundational KMP component that manages member authorization workflows for activity-based participation. It provides comprehensive authorization lifecycle management, multi-level approval workflows, and temporal access control.

Key Design Principles

Plugin Dependencies

The Activities Plugin depends on:

Core Components

Authorization Entity

Represents a member’s authorization to participate in a specific activity.

For comprehensive technical reference including all properties, relationships, database schema, status constants, temporal management, and usage examples, see Authorization Entity Reference.

Status Constants:

const APPROVED_STATUS = "Approved";      // Authorization is active and valid
const PENDING_STATUS = "Pending";        // Authorization awaiting approval
const DENIED_STATUS = "Denied";          // Authorization request was rejected
const REVOKED_STATUS = "Revoked";        // Previously approved authorization was revoked
const EXPIRED_STATUS = "Expired";        // Authorization has passed its expiration date
const RETRACTED_STATUS = "Retracted";    // Member retracted pending request

Core Responsibilities:

Activity Entity

Defines authorization types that members can request. For comprehensive technical reference including all properties, relationships, virtual properties, and usage examples, see Activity Entity Reference.

Key Configuration:

Key Method:

// Discover members with approval authority for this activity
public function getApproversQuery(int $branch_id): SelectQuery

ActivityGroup Entity

Provides categorical organization for related activities.

Structure:

AuthorizationApproval Entity

Tracks individual approval decisions in multi-level approval workflows.

For comprehensive technical reference including all properties, relationships, database schema, workflow architecture, security implementation, and usage examples, see AuthorizationApproval Entity Reference.

Tracks:

Key Methods:

Service Layer: AuthorizationManagerInterface

Core business logic abstraction for authorization workflows.

Key Responsibilities:

// Request new authorization or renewal
public function request(
    int $activityId,
    int $requesterId,
    bool $isRenewal = false,
    array $data = []
): ServiceResult

// Process approval decision
public function approve(
    int $authorizationId,
    int $approverId,
    array $data = []
): ServiceResult

// Deny authorization request
public function deny(
    int $authorizationId,
    int $approverId,
    string $denyReason = ''
): ServiceResult

// Revoke active authorization
public function revoke(
    int $authorizationId,
    int $revokerId,
    string $revokedReason = ''
): ServiceResult

Default Implementation: DefaultAuthorizationManager

Plugin Initialization

Migration Order

The Activities Plugin uses configurable migration order (default: 0) to control initialization sequence relative to other plugins.

Configuration in config/plugins.php:

'Activities' => [
    'migrationOrder' => 1,  // Optional: set to 1 for base system behavior
]

Bootstrap Process

The bootstrap() method initializes the plugin with:

  1. Navigation Registration: Registers dynamic navigation provider
  2. View Cell Registration: Registers context-sensitive UI components
  3. Configuration Versioning: Manages configuration migrations and updates
  4. Default Settings: Initializes application settings

Configuration Version Management:

$currentConfigVersion = "25.01.11.c";  // Updated on each configuration change

$configVersion = StaticHelpers::getAppSetting(
    "Activities.configVersion",
    "0.0.0",
    null,
    true
);

if ($configVersion != $currentConfigVersion) {
    // Perform configuration migrations
    StaticHelpers::setAppSetting("Activities.configVersion", $currentConfigVersion);
    // Initialize default settings
}

Service Registration

The plugin registers core services with CakePHP’s dependency injection container.

AuthorizationManagerInterface Registration

public function services(ContainerInterface $container): void
{
    $container->add(
        AuthorizationManagerInterface::class,
        DefaultAuthorizationManager::class,
    )->addArgument(ActiveWindowManagerInterface::class);
}

Service Characteristics:

Usage in Controllers

class AuthorizationsController extends AppController
{
    private AuthorizationManagerInterface $authorizationManager;

    public function __construct(AuthorizationManagerInterface $authorizationManager)
    {
        $this->authorizationManager = $authorizationManager;
    }

    public function request()
    {
        $result = $this->authorizationManager->request(
            $activityId,
            $this->Authentication->getIdentity()->id
        );
        
        if ($result->isSuccess()) {
            $this->Flash->success('Authorization requested');
        } else {
            $this->Flash->error($result->getMessage());
        }
    }
}

Navigation & UI Integration

Dynamic Navigation Provider

The ActivitiesNavigationProvider generates context-aware navigation items based on user permissions and plugin state.

Navigation Categories:

Feature: Real-time badge support displaying pending approval counts

Permission-Based Visibility: Navigation items only appear when user has required permissions

View Cell Integration

The ActivitiesViewCellProvider registers context-sensitive UI components.

Integration Points:

Registration Pattern:

public static function getViewCells($urlParams, $user): array
{
    $cells = [];
    
    // Conditional rendering based on page context
    if ($urlParams['controller'] === 'Members' && $urlParams['action'] === 'view') {
        $cells[] = [
            'type' => ViewCellRegistry::PLUGIN_TYPE_TAB,
            'label' => 'Authorizations',
            'cell' => 'Activities.MemberAuthorizations',
            'order' => 15,
        ];
    }
    
    return $cells;
}

Configuration Management

Application Settings

The plugin manages the following application settings:

Activities.configVersion

Activities.NextStatusCheck

Plugin.Activities.Active

Versioned Configuration Updates

Configuration migrations handle:

Routing & Middleware

Plugin Routes

Routes are configured under the /activities path prefix.

Route Examples:

Fallback Routing: Standard CakePHP controller/action patterns for REST-like operations

Route Configuration:

public function routes(RouteBuilder $routes): void
{
    $routes->plugin(
        'Activities',
        ['path' => '/activities'],
        function (RouteBuilder $builder) {
            // Standard CakePHP fallback routing
            $builder->fallbacks();
        }
    );
}

Middleware

Currently no custom middleware is required. Extension point available for future middleware needs:

Potential Applications:

Console Commands

Reserved for future CLI commands supporting:

Planned Usage:

bin/cake activities cleanup_expired
bin/cake activities status_report
bin/cake activities migrate_data

References