README

Laravel Task Orchestrator

A lightweight task orchestration layer for Laravel that adds visibility, dependencies, pipelines, and a modern UI on top of your Artisan commands.

✨ Features

• 🔗 Task dependencies (depends_on)
• 🔄 Automatic pipeline execution (upstream → downstream)
• 🧠 Task discovery via config file
• 📊 Dashboard with real-time status
• 🧩 Pipeline view (visual flow of tasks)
• 🎯 Manual & scheduled triggers
• 🟢 Status tracking (queued, running, succeeded, failed)
• 🩺 Queue + scheduler health monitoring in dashboard
• 👷 Queue worker liveness monitoring (running/down)
• 🧯 Stale run recovery (auto-fail hanging tasks)
• ⏱ Per-task timeout configuration
• 🌙 Dark / Light mode
• 📱 Responsive UI

📸 Screenshots

🚀 Installation

composer require fanat98/laravel-task-orchestrator

Publish config and assets:

php artisan vendor:publish --tag=task-orchestrator-config
php artisan vendor:publish --tag=task-orchestrator-assets

Run migrations:

php artisan migrate

⚙️ Basic Configuration

Config file:

config/task-orchestrator.php

Example:

return [
    'route_prefix' => 'task-orchestrator',

    'middleware' => ['web', 'auth'],

    'authorization' => [
        'mode' => 'user_field',
        'field' => 'is_admin',
    ],

    'discovery_path' => app_path('TaskOrchestrator/discovery.php'),

    'fail_on_invalid_dependencies' => false,

    'stale_run_default_minutes' => 10,

    'health' => [
        'queue_stuck_threshold_seconds' => 300,
        'queue_worker' => [
            'heartbeat_max_age_seconds' => 60,
        ],
        'scheduler_heartbeat_cache_key' => 'task-orchestrator:scheduler-heartbeat',
        'scheduler_heartbeat_max_age_seconds' => 180,
        'scheduler_heartbeat_ttl_seconds' => 86400,
    ],
];

🧩 Task Discovery

Create:

app/TaskOrchestrator/discovery.php

Example:

<?php

return [
    'commands' => [
        'import:control-requirements' => [
            'name' => 'control-requirements',
            'label' => 'Import Control Requirements',
            'group' => 'ETL Imports',
            'group_order' => 10,
            'order' => 10,
            'connection' => 'database',
            'queue' => 'imports',
            'schedule' => [
                'expression' => '* * * * *',
                'human' => 'Every minute',
            ],
            'timeout_minutes' => 30,
        ],

        'import:resources' => [
            'name' => 'import-resources',
            'label' => 'Import Resources',
            'group' => 'ETL Imports',
            'group_order' => 10,
            'order' => 20,
            'depends_on' => ['control-requirements'],
            'timeout_minutes' => 30,
        ],

        'import:services' => [
            'name' => 'import-services',
            'label' => 'Import Services',
            'group' => 'ETL Imports',
            'group_order' => 10,
            'order' => 30,
            'depends_on' => ['import-resources'],
            'timeout_minutes' => 30,
        ],

        'control-verifications:notify-inactive' => [
            'name' => 'notify-inactive-control-verifications',
            'label' => 'Notify inactive control verifications',
            'group' => 'Control Verifications',
            'group_order' => 20,
            'order' => 10,
            'depends_on' => ['import-services'],
            'timeout_minutes' => 5,
        ],
    ],
];

🔄 Pipelines

Tasks with dependencies automatically form pipelines:

control-requirements → resources → services → notify

When a task succeeds:

• downstream tasks are triggered automatically
• all runs are grouped into a pipeline

Manual starts trigger only the selected task.

🧯 Stale Run Recovery

Recover hanging tasks:

php artisan task-orchestrator:recover-stale-runs

Behavior:

• uses per-task timeout_minutes if defined
• otherwise uses global config default

🩺 Dashboard Health Monitoring

The dashboard reports queue, scheduler, and queue worker health:

• queue healthy: no pending jobs
• queue busy: pending jobs exist but oldest pending age is below threshold
• queue stuck: oldest pending age exceeds threshold
• scheduler running: heartbeat is recent
• scheduler down: heartbeat is stale or missing
• queue worker running: worker heartbeat is recent
• queue worker down: worker heartbeat is stale or missing

Queue worker heartbeat is updated by a hybrid mechanism:

• scheduled QueueHeartbeatJob (every minute)
• task execution heartbeat updates inside ExecuteTaskRunJob

🔐 Authorization

Option 1 – User field

'authorization' => [
    'mode' => 'user_field',
    'field' => 'is_admin',
],

Option 2 – Gate

Gate::define('viewTaskOrchestrator', fn ($user) => $user->is_admin);

🎨 UI

• Dashboard overview
• Task groups
• Pipeline visualization
• Latest runs
• Failed runs
• Dark / Light mode toggle

📚 Documentation

More detailed documentation:

• Installation
• Configuration
• Task Discovery
• Pipelines
• Authorization

🛠 Requirements

• PHP 8.2+
• Laravel 10 / 11 / 12

📄 License

MIT