tinker_tickets/models/WorkflowModel.php

<?php
/**
 * WorkflowModel - Handles status transition workflows and validation
 *
 * Uses caching for frequently accessed transition rules since they rarely change.
 */
require_once dirname(__DIR__) . '/helpers/CacheHelper.php';

class WorkflowModel {
    private mysqli $conn;
    private static string $CACHE_PREFIX = 'workflow';
    private static int $CACHE_TTL = 600; // 10 minutes

    public function __construct(mysqli $conn) {
        $this->conn = $conn;
    }

    /**
     * Get all active transitions (with caching)
     *
     * @return array All active transitions indexed by from_status
     */
    private function getAllTransitions(): array {
        return CacheHelper::remember(self::$CACHE_PREFIX, 'all_transitions', function() {
            $sql = "SELECT from_status, to_status, requires_comment, requires_admin
                    FROM status_transitions
                    WHERE is_active = TRUE";
            $result = $this->conn->query($sql);

            $transitions = [];
            while ($row = $result->fetch_assoc()) {
                $from = $row['from_status'];
                if (!isset($transitions[$from])) {
                    $transitions[$from] = [];
                }
                $transitions[$from][$row['to_status']] = [
                    'to_status' => $row['to_status'],
                    'requires_comment' => (bool)$row['requires_comment'],
                    'requires_admin' => (bool)$row['requires_admin']
                ];
            }

            return $transitions;
        }, self::$CACHE_TTL);
    }

    /**
     * Get allowed status transitions for a given status
     *
     * @param string $currentStatus Current ticket status
     * @return array Array of allowed transitions with requirements
     */
    public function getAllowedTransitions(string $currentStatus): array {
        $allTransitions = $this->getAllTransitions();

        if (!isset($allTransitions[$currentStatus])) {
            return [];
        }

        return array_values($allTransitions[$currentStatus]);
    }

    /**
     * Check if a status transition is allowed
     *
     * @param string $fromStatus Current status
     * @param string $toStatus Desired status
     * @param bool $isAdmin Whether user is admin
     * @return bool True if transition is allowed
     */
    public function isTransitionAllowed(string $fromStatus, string $toStatus, bool $isAdmin = false): bool {
        // Allow same status (no change)
        if ($fromStatus === $toStatus) {
            return true;
        }

        $allTransitions = $this->getAllTransitions();

        if (!isset($allTransitions[$fromStatus][$toStatus])) {
            return false; // Transition not defined
        }

        $transition = $allTransitions[$fromStatus][$toStatus];

        if ($transition['requires_admin'] && !$isAdmin) {
            return false; // Admin required
        }

        return true;
    }

    /**
     * Get all possible statuses from transitions table
     *
     * @return array Array of unique status values
     */
    public function getAllStatuses(): array {
        return CacheHelper::remember(self::$CACHE_PREFIX, 'all_statuses', function() {
            $sql = "SELECT DISTINCT from_status as status FROM status_transitions
                    UNION
                    SELECT DISTINCT to_status as status FROM status_transitions
                    ORDER BY status";
            $result = $this->conn->query($sql);

            $statuses = [];
            while ($row = $result->fetch_assoc()) {
                $statuses[] = $row['status'];
            }

            return $statuses;
        }, self::$CACHE_TTL);
    }

    /**
     * Get transition requirements
     *
     * @param string $fromStatus Current status
     * @param string $toStatus Desired status
     * @return array|null Transition requirements or null if not found
     */
    public function getTransitionRequirements(string $fromStatus, string $toStatus): ?array {
        $allTransitions = $this->getAllTransitions();

        if (!isset($allTransitions[$fromStatus][$toStatus])) {
            return null;
        }

        $transition = $allTransitions[$fromStatus][$toStatus];
        return [
            'requires_comment' => $transition['requires_comment'],
            'requires_admin' => $transition['requires_admin']
        ];
    }

    /**
     * Clear workflow cache (call when transitions are modified)
     */
    public static function clearCache(): void {
        CacheHelper::delete(self::$CACHE_PREFIX);
    }
}