README

Laravel Task Orchestrator

Laravel Task Orchestrator is a lightweight dashboard for orchestrating Artisan command workflows with dependencies, pipelines, scheduling, queue health checks, stale run recovery and real-time monitoring.

It is built for Laravel teams that already use Artisan commands for imports, sync jobs, maintenance workflows or operational tasks, but need a clearer way to run them, monitor them and connect them into reliable workflows.

Instead of hiding important operational work inside cron entries or one-off commands, the package gives developers and operators a central place to see what can run, what is running, what failed and which downstream tasks should run next.

When To Use It

Use this package when your Laravel application has Artisan commands that:

• need to run manually from a dashboard
• need to run on a schedule
• depend on other commands finishing successfully
• should be grouped into import, sync, reporting or maintenance pipelines
• need queue, scheduler and worker visibility
• should recover from hanging queued or running states
• need a simple operational UI without building a custom admin tool

Features

• Task discovery from a small discovery.php configuration file
• Manual task starts from a dashboard
• Scheduled task starts using Laravel's scheduler
• Dependency-aware pipelines
• Automatic downstream execution after successful parent tasks
• Queue connection and queue name per task
• Real-time run status, logs and progress display
• Failed run overview and retry support
• Queue, scheduler and queue worker health checks
• Stale queued/running run recovery
• Per-task timeout configuration
• Failure and recovery email notifications
• Dashboard authorization through a gate or user field
• Responsive dashboard with light and dark mode

Requirements

• PHP 8.2+
• Laravel 12 or 13
• A configured Laravel queue connection
• Laravel's scheduler running in production

Installation

Install the package with Composer:

composer require fanat98/laravel-task-orchestrator

Publish the configuration and frontend assets:

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

Run the package migrations:

php artisan migrate

The dashboard is available at:

/task-orchestrator

The path can be changed with route_prefix in config/task-orchestrator.php.

Quick Start

Create the discovery file configured by config/task-orchestrator.php:

mkdir -p app/TaskOrchestrator
touch app/TaskOrchestrator/discovery.php

Add one command to app/TaskOrchestrator/discovery.php:

<?php

return [
    'commands' => [
        'reports:send-daily' => [
            'name' => 'send-daily-reports',
            'label' => 'Send daily reports',
            'group' => 'Reports',
            'queue' => 'default',
            'schedule' => [
                'expression' => '0 8 * * *',
                'human' => 'Daily at 08:00',
            ],
            'timeout_minutes' => 10,
        ],
    ],
];

Make sure Laravel's scheduler and at least one queue worker are running:

php artisan schedule:work
php artisan queue:work

For production, run the scheduler from cron and manage queue workers with Supervisor, systemd, Laravel Horizon or your platform's worker process manager.

Configuration

The package configuration lives in:

config/task-orchestrator.php

The most commonly changed options are:

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

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

    'authorization' => [
        'enabled' => true,
        'mode' => 'gate',
        'gate' => 'viewTaskOrchestrator',
        'user_field' => 'is_admin',
    ],

    'database_connection' => env('TASK_ORCHESTRATOR_DB_CONNECTION'),

    '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_max_age_seconds' => 180,
    ],

    'notifications' => [
        'enabled' => false,
        'recipients' => [],
    ],
];

For dashboard access, define the configured gate:

use Illuminate\Support\Facades\Gate;

Gate::define('viewTaskOrchestrator', function ($user) {
    return (bool) $user->is_admin;
});

For smaller applications you can also use mode => user_field and set user_field => is_admin.

Defining Tasks

Tasks are declared in the discovery file under the commands key. Each array key is an Artisan command signature and each value describes how Task Orchestrator should present and run it.

<?php

return [
    'commands' => [
        'import:users' => [
            'name' => 'import-users',
            'label' => 'Import users',
            'description' => 'Imports users from the external source.',
            'group' => 'Imports',
            'group_order' => 10,
            'order' => 10,
            'connection' => 'database',
            'queue' => 'imports',
            'schedule' => [
                'expression' => '*/15 * * * *',
                'human' => 'Every 15 minutes',
            ],
            'timeout_minutes' => 20,
        ],
    ],
];

Supported task metadata includes:

• name: unique task identifier used by dependencies
• label: human-readable dashboard label
• description: optional dashboard description
• group, group_order, order: dashboard organization
• depends_on: task names that must succeed before this task runs
• connection: queue connection for the task run
• queue: queue name for the task run
• schedule.expression: cron expression for scheduled runs
• schedule.human: readable schedule text for the dashboard
• timeout_minutes: per-task stale run timeout
• notifications: optional per-task notification settings

Real-World Pipeline Example

This example keeps the commands generic while showing multiple dependencies:

<?php

return [
    'commands' => [
        'import:users' => [
            'name' => 'import-users',
            'label' => 'Import users',
            'group' => 'Imports',
            'order' => 10,
            'queue' => 'imports',
            'schedule' => [
                'expression' => '0 * * * *',
                'human' => 'Hourly',
            ],
            'timeout_minutes' => 20,
        ],

        'watch:users' => [
            'name' => 'watch-users',
            'label' => 'Watch imported users',
            'group' => 'Imports',
            'order' => 20,
            'depends_on' => ['import-users'],
            'queue' => 'imports',
            'timeout_minutes' => 10,
        ],

        'import:control-requirements' => [
            'name' => 'import-control-requirements',
            'label' => 'Import control requirements',
            'group' => 'Reference Data',
            'order' => 10,
            'queue' => 'imports',
            'timeout_minutes' => 30,
        ],

        'import:resources' => [
            'name' => 'import-resources',
            'label' => 'Import resources',
            'group' => 'Reference Data',
            'order' => 20,
            'depends_on' => ['import-control-requirements'],
            'queue' => 'imports',
            'timeout_minutes' => 30,
        ],

        'import:services' => [
            'name' => 'import-services',
            'label' => 'Import services',
            'group' => 'Reference Data',
            'order' => 30,
            'depends_on' => ['import-resources'],
            'queue' => 'imports',
            'timeout_minutes' => 30,
        ],
    ],
];

The resulting flows are:

import-users -> watch-users

import-control-requirements -> import-resources -> import-services

Scheduler And Queue Workers

Task Orchestrator registers discovered task schedules with Laravel's scheduler. In local development you can run:

php artisan schedule:work

In production, run Laravel's scheduler every minute:

* * * * * cd /path/to/application && php artisan schedule:run >> /dev/null 2>&1

You also need at least one queue worker:

php artisan queue:work

If tasks use a custom queue such as imports, make sure a worker listens to it:

php artisan queue:work --queue=imports,default

The package also registers scheduler heartbeat, queue heartbeat and stale run recovery tasks through Laravel's scheduler.

Dashboard

After installation, open:

/task-orchestrator

The dashboard shows task groups, task status, recent runs, failed runs, pipeline execution, health status and links to run details. The route is protected by the configured middleware and the package authorization middleware.

Dependencies And Pipelines

Dependencies are defined with depends_on using task names:

'import:resources' => [
    'name' => 'import-resources',
    'depends_on' => ['import-control-requirements'],
],

When a task succeeds, Task Orchestrator starts downstream tasks whose dependencies are satisfied. Runs created from the same chain share a pipeline context, making it easier to inspect the full workflow.

Execution rules:

• downstream tasks run only after successful dependencies
• failed tasks stop downstream execution
• dependency cycles are rejected
• manual starts run the selected task
• scheduled starts create a new pipeline from the scheduled task
• retries create a new run and can continue downstream execution

Stale Run Recovery

If a queued or running task hangs, the recovery command marks it as failed after its timeout:

php artisan task-orchestrator:recover-stale-runs

Timeout resolution:

• task-level timeout_minutes
• persisted run timeout
• global stale_run_default_minutes
• explicit --minutes= override

The package schedules stale run recovery automatically. You can still run the command manually during incident response.

Health Monitoring

The dashboard reports:

• queue state: healthy, busy or stuck
• scheduler state: running or down
• queue worker state: running or down

Queue health is based on pending jobs and the configured stuck threshold. Scheduler health is based on a scheduler heartbeat written every minute. Queue worker health is based on a worker heartbeat refreshed by scheduled heartbeat jobs and task execution jobs.

When a scheduled task cannot be started (for example because queue worker heartbeat is stale), Task Orchestrator records a failed scheduled run with a clear failure reason in run history. The task is not retried immediately and will run again at the next regular cron due time.

Screenshots

Dashboard screenshot

Task detail screenshot

Task detail screenshot placeholder. Add an image to docs/ and reference it here when available.

Health monitoring screenshot

Health monitoring screenshot placeholder. Add an image to docs/ and reference it here when available.

Troubleshooting

The dashboard returns 403

Check authorization.mode, authorization.gate, authorization.user_field and the authenticated user. For gate mode, make sure the gate exists in your application.

No tasks appear in the dashboard

Check that discovery_path points to an existing PHP file, the file returns an array and tasks are placed under the commands key.

Scheduled tasks do not run

Make sure Laravel's scheduler is running. Locally, use php artisan schedule:work. In production, configure cron to call php artisan schedule:run every minute.

Tasks stay queued

Make sure a queue worker is running for the queue used by the task. If a task uses queue => imports, the worker must listen to imports.

The scheduler or queue worker is marked down

Check that the scheduler is running every minute and that queue workers can process heartbeat jobs. Also verify that the application cache is available because heartbeat state is stored in cache.

A run is stuck in queued or running

Run php artisan task-orchestrator:recover-stale-runs and review timeout_minutes for long-running tasks.

Dependencies do not start

Confirm that depends_on uses task names, not Artisan command names, and that upstream runs completed successfully.

Documentation

More detailed documentation:

• Installation
• Configuration
• Task Discovery
• Pipelines
• Operations
• Authorization

Package Status And Support

This package is early but usable. It is intended for Laravel applications that want a lightweight operational dashboard around Artisan command workflows without adopting a larger workflow engine.

Supported runtime versions:

• PHP 8.2+
• Laravel 12 and 13

Issues, bug reports, practical feedback and contributions are welcome through GitHub.

Testing

Run the package tests with PHPUnit:

vendor/bin/phpunit --configuration phpunit.xml --no-coverage

When developing this package as a local path repository inside a host application, you can also use the host application's PHPUnit binary:

../../vendor/bin/phpunit --configuration /absolute/path/to/packages/laravel-task-orchestrator/phpunit.xml --no-coverage

License

The package is open-sourced software licensed under the MIT license. The license declaration is available in composer.json.