Laravel Task Orchestrator Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require fanat98/laravel-task-orchestrator
   php artisan vendor:publish --provider="Fanat98\TaskOrchestrator\TaskOrchestratorServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Basic Task Definition: Define a task in a service class (e.g., app/Services/ExampleTask.php):

   namespace App\Services;
   
   use Fanat98\TaskOrchestrator\Contracts\Task;
   
   class ExampleTask implements Task
   {
       public function execute(): void
       {
           // Your task logic here
           \Log::info('Task executed');
       }
   }
   

3. Register Task in Orchestrator: In a service provider (e.g., AppServiceProvider):

   public function boot()
   {
       \Fanat98\TaskOrchestrator\Facades\TaskOrchestrator::registerTask(
           'example_task',
           \App\Services\ExampleTask::class
       );
   }
   

4. Run Task via CLI:

   php artisan task:run example_task
   

5. Dashboard Access: Visit /task-orchestrator to monitor tasks in real-time.

First Use Case: Scheduled Task

1. Define a Scheduled Task:

   use Illuminate\Support\Facades\Schedule;
   
   Schedule::call(function () {
       \Fanat98\TaskOrchestrator\Facades\TaskOrchestrator::run('example_task');
   })->everyMinute();
   

2. Verify in Dashboard: Check the dashboard for execution logs, status, and duration.

Implementation Patterns

Task Dependencies

Define dependencies between tasks to enforce execution order:

TaskOrchestrator::registerTask('task_a', TaskA::class)
    ->dependsOn(['task_b', 'task_c']);

Real-Time Monitoring

• Webhook Integration: Extend the dashboard with custom webhooks for notifications:

  TaskOrchestrator::onTaskCompleted(function ($task) {
      // Send Slack/email notification
  });
  

• Event Listeners: Listen to task events for custom logic:

  TaskOrchestrator::listen('task.started', function ($task) {
      \Log::debug("Task {$task->name} started");
  });
  

Scheduling Workflows

• Cron Jobs: Use Laravel’s scheduler to trigger orchestrated tasks:

  Schedule::command('task:run workflow_name')->daily();
  

• Dynamic Scheduling: Schedule tasks programmatically:

  TaskOrchestrator::schedule('task_a', now()->addMinutes(5));
  

Task Retries and Fallbacks

Configure retry logic for tasks:

TaskOrchestrator::registerTask('faulty_task', FaultyTask::class)
    ->retries(3)
    ->fallback(function ($task) {
        \Log::error("Task {$task->name} failed after retries");
    });

Gotchas and Tips

Pitfalls

1. Task Registration Timing:

   • Ensure tasks are registered before they are called. Use service provider boot methods or booted events.
   • Fix: Register tasks in AppServiceProvider@boot or a dedicated provider.

2. Dependency Loops:

   • Circular dependencies (e.g., task_a depends on task_b, which depends on task_a) will cause silent failures.
   • Fix: Validate dependencies manually or use a dependency graph library.

3. Dashboard Permissions:

   • The dashboard routes are not protected by default. Secure them with middleware:

     Route::middleware(['auth'])->group(function () {
         TaskOrchestrator::routes();
     });
     

4. Long-Running Tasks:

   • Tasks running longer than PHP’s max_execution_time may appear stuck.
   • Fix: Use queues (TaskOrchestrator::queueTask()) or increase max_execution_time in php.ini.

Debugging Tips

1. Log Task Execution: Enable debug mode and check Laravel logs for task lifecycle events:

   TaskOrchestrator::enableDebugLogging();
   

2. Inspect Task State: Use Tinker to check task status:

   php artisan tinker
   >>> \Fanat98\TaskOrchestrator\Models\Task::first()->status
   

3. Clear Stuck Tasks: Manually update task status in the database if needed:

   UPDATE tasks SET status = 'pending' WHERE name = 'stuck_task';
   

Extension Points

1. Custom Task Models: Extend the Task model to add fields (e.g., priority, metadata):

   php artisan make:model TaskExtension -m
   

   Then update the migration and model.

2. Add Task Metrics: Track custom metrics (e.g., CPU usage) by extending the Task class:

   class CustomTask extends \Fanat98\TaskOrchestrator\Models\Task
   {
       protected $casts = [
           'cpu_usage' => 'integer',
       ];
   }
   

3. Integrate with Queues: Offload tasks to queues for async execution:

   TaskOrchestrator::queueTask('long_running_task', now()->addHour());
   

4. Localization: Override dashboard translations in resources/lang/{locale}/task-orchestrator.php:

   return [
       'status' => [
           'pending' => 'In queue',
       ],
   ];