rspade_system/app/RSpade/man/tasks.txt

RSX TASK SYSTEM
================

The RSX Task system provides a structured way to define and execute background
tasks, similar to how Controllers handle HTTP requests but for CLI/background
execution.

## OVERVIEW

Tasks are static methods in Service classes that can be executed from:
- Command line (via `rsx:task:run`)
- Internal PHP code (via `Task::internal()`)
- Future: Queue systems, cron scheduling, progress tracking

## CREATING SERVICES

Services are classes that extend `Rsx_Service_Abstract` and live in:
    /rsx/services/

Example service structure:

    <?php
    use App\RSpade\Core\Service\Rsx_Service_Abstract;

    class My_Service extends Rsx_Service_Abstract
    {
        #[Task('Description of what this task does')]
        public static function my_task(array $params = [])
        {
            // Task implementation
            return [
                'message' => 'Task completed',
                'data' => 'result data'
            ];
        }
    }

## TASK METHODS

Tasks must:
- Be public static methods
- Have the #[Task('description')] attribute
- Accept array $params = [] parameter
- Return data (will be JSON-encoded for CLI output)

Task signature:
    public static function task_name(array $params = [])

## PARAMETER HANDLING

Services inherit parameter helpers from Rsx_Service_Abstract:

    protected static function __param($params, $key, $default = null)
    protected static function __has_param($params, $key)

Example usage:
    $name = static::__param($params, 'name', 'Guest');
    if (static::__has_param($params, 'force')) {
        // ...
    }

## PRE-TASK HOOK

Override pre_task() to run validation/auth before any task executes:

    public static function pre_task(array $params = [])
    {
        if (!RsxAuth::check()) {
            throw new \Exception("Authentication required");
        }
        return null; // Continue to task
    }

If pre_task() returns non-null, task execution halts and returns that value.

## LISTING TASKS

View all available tasks:
    php artisan rsx:task:list

Output shows services and their tasks with descriptions:
    Service_Test
      hello_world              - Test task with no arguments
      greet                    - Test task with optional name parameter
      calculate                - Test task with multiple parameters

## RUNNING TASKS

Execute a task from command line:
    php artisan rsx:task:run Service task_name

With parameters:
    php artisan rsx:task:run Service task_name --param=value
    php artisan rsx:task:run Service greet --name=John

Boolean flags:
    php artisan rsx:task:run Service task_name --force

JSON values (auto-parsed):
    php artisan rsx:task:run Service task_name --data='{"key":"value"}'

Debug mode (wrapped response):
    php artisan rsx:task:run Service task_name --debug

## OUTPUT MODES

Default mode - Raw JSON response (just the return value):
    {
        "message": "Task completed",
        "count": 42
    }

Debug mode - Wrapped response with success indicator:
    {
        "success": true,
        "result": {
            "message": "Task completed",
            "count": 42
        }
    }

## INTERNAL TASK CALLS

Call tasks from PHP code using Task::internal():

    use App\RSpade\Core\Task\Task;

    $result = Task::internal('Service_Name', 'task_name', [
        'param1' => 'value1',
        'param2' => 'value2'
    ]);

This is useful for:
- Composing complex tasks from simpler ones
- Calling tasks from controllers
- Background job processing

Example composition:
    #[Task('Run all seeders')]
    public static function seed_all(array $params = [])
    {
        $clients = Task::internal('Seeder_Service', 'seed_clients', $params);
        $contacts = Task::internal('Seeder_Service', 'seed_contacts', $params);

        return [
            'clients' => $clients,
            'contacts' => $contacts
        ];
    }

## ERROR HANDLING

All errors return JSON (never throws to stderr):
    {
        "success": false,
        "error": "Error message",
        "error_type": "Exception",
        "trace": "..."
    }

Exit codes:
- 0: Success
- 1: Error

## ATTRIBUTE CONFLICTS

A method cannot have multiple execution type attributes. These conflict:
- #[Route] (HTTP routes)
- #[Ajax_Endpoint] (Ajax endpoints)
- #[Task] (CLI tasks)

The manifest build will fail if these are mixed on the same method.

## USE CASES

Tasks are ideal for:
- Database seeders
- Data migrations
- Report generation
- Batch processing
- Maintenance operations
- Background jobs
- Scheduled operations

Example services:
    Seeder_Service     - Database seeding
    Report_Service     - Generate reports
    Cleanup_Service    - Maintenance tasks
    Import_Service     - Data imports
    Export_Service     - Data exports

## FUTURE FEATURES (NOT YET IMPLEMENTED)

The Task system is designed to support future enhancements:
- Queue integration (dispatch tasks to Redis/database queue)
- Cron scheduling (#[Schedule] attribute)
- Progress tracking (long-running tasks report progress)
- Task history (log of all task executions)
- Task dependencies (ensure X runs before Y)
- Parallel execution (run multiple tasks concurrently)

## EXAMPLES

See example services:
    /rsx/services/service_test.php   - Basic task examples
    /rsx/services/seeder_service.php - Database seeding examples

Test tasks:
    php artisan rsx:task:list
    php artisan rsx:task:run Service_Test hello_world
    php artisan rsx:task:run Service_Test greet --name=Brian
    php artisan rsx:task:run Service_Test calculate --a=10 --b=5 --op=multiply