rspade_system/app/RSpade/Core/Task/Task.php

<?php
/**
 * CODING CONVENTION:
 * This file follows the coding convention where variable_names and function_names
 * use snake_case (underscore_wherever_possible).
 */

namespace App\RSpade\Core\Task;

use Exception;
use App\RSpade\Core\Manifest\Manifest;
use App\RSpade\Core\Service\Rsx_Service_Abstract;

/**
 * Task - Unified task execution system
 *
 * Handles background task execution:
 * - Internal PHP task calls (internal method)
 * - Future: Queue integration, scheduling, progress tracking
 */
class Task
{
    /**
     * Execute a task internally from PHP code
     *
     * Used for server-side code to invoke tasks without CLI overhead.
     * This is useful for calling tasks from other tasks, background jobs, etc.
     *
     * @param string $rsx_service Service name (e.g., 'Seeder_Service')
     * @param string $rsx_task Task/method name (e.g., 'seed_clients')
     * @param array $params Parameters to pass to the task
     * @return mixed The response from the task method
     * @throws Exception
     */
    public static function internal($rsx_service, $rsx_task, $params = [])
    {
        // Get manifest to find service
        $manifest = Manifest::get_all();
        $service_class = null;
        $file_info = null;

        // Search for service class in manifest
        foreach ($manifest as $file_path => $info) {
            // Skip non-PHP files or files without classes
            if (!isset($info['class']) || !isset($info['fqcn'])) {
                continue;
            }

            // Check if class name matches exactly (without namespace)
            $class_basename = basename(str_replace('\\', '/', $info['fqcn']));

            if ($class_basename === $rsx_service) {
                $service_class = $info['fqcn'];
                $file_info = $info;
                break;
            }
        }

        if (!$service_class) {
            throw new Exception("Service class not found: {$rsx_service}");
        }

        // Check if class exists
        if (!class_exists($service_class)) {
            throw new Exception("Service class does not exist: {$service_class}");
        }

        // Check if it's a subclass of Rsx_Service_Abstract
        if (!Manifest::php_is_subclass_of($service_class, Rsx_Service_Abstract::class)) {
            throw new Exception("Service {$service_class} must extend Rsx_Service_Abstract");
        }

        // Check if method exists and has Task attribute
        if (!isset($file_info['public_static_methods'][$rsx_task])) {
            throw new Exception("Task {$rsx_task} not found in service {$service_class}");
        }

        $method_info = $file_info['public_static_methods'][$rsx_task];
        $has_task = false;

        // Check for Task attribute in method metadata
        if (isset($method_info['attributes'])) {
            foreach ($method_info['attributes'] as $attr_name => $attr_instances) {
                if ($attr_name === 'Task' || str_ends_with($attr_name, '\\Task')) {
                    $has_task = true;
                    break;
                }
            }
        }

        if (!$has_task) {
            throw new Exception("Method {$rsx_task} in service {$service_class} must have #[Task] attribute");
        }

        // Call pre_task() if exists
        if (method_exists($service_class, 'pre_task')) {
            $pre_result = $service_class::pre_task($params);
            if ($pre_result !== null) {
                // pre_task returned something, use that as response
                return $pre_result;
            }
        }

        // Call the actual task method
        $response = $service_class::$rsx_task($params);

        // Filter response through JSON encode/decode to remove PHP objects
        // (similar to Ajax behavior)
        $filtered_response = json_decode(json_encode($response), true);

        return $filtered_response;
    }

    /**
     * Format task response for CLI output
     * Wraps the response in a consistent format
     *
     * @param mixed $response Task return value
     * @return array Formatted response
     */
    public static function format_task_response($response): array
    {
        return [
            'success' => true,
            'result' => $response,
        ];
    }
}