Talon Laravel Package

Getting Started

First Steps

1. Installation Add Talon to your Laravel project via Composer:

   composer require phalcon/talon
   

   Publish the config file (if available) and run migrations (if applicable).

2. Core Concepts

   • Talon is a task automation and workflow orchestration package designed for Laravel, inspired by Phalcon’s workflow capabilities.
   • It provides a declarative syntax for defining complex, multi-step processes (e.g., data pipelines, batch jobs, or sequential operations).
   • Key classes:
     • Talon\Workflow – Defines a workflow with steps.
     • Talon\Step – Individual tasks in a workflow (e.g., database operations, API calls, file processing).
     • Talon\Runner – Executes workflows with retries, timeouts, and logging.

3. First Use Case: Simple Workflow Define a workflow in a service class or directly in a controller:

   use Phalcon\Talon\Workflow;
   use Phalcon\Talon\Step;
   
   $workflow = new Workflow('user_export');
   $workflow->step(new Step('fetch_users', function () {
       return User::all();
   }))
           ->step(new Step('export_to_csv', function ($users) {
               // Export logic here
           }));
   
   $result = $workflow->run();
   

Implementation Patterns

1. Defining Workflows

• Modular Workflows: Break down complex tasks into reusable workflows.

  // app/Workflows/ProcessOrder.php
  class ProcessOrder extends Workflow
  {
      public function __construct()
      {
          $this->step(new Step('validate_order', [OrderValidator::class, 'validate']))
                ->step(new Step('update_inventory', [InventoryService::class, 'deductStock']))
                ->step(new Step('send_notification', [NotificationService::class, 'dispatch']));
      }
  }
  

• Dynamic Steps: Use closures or callables for flexibility.

  $workflow->step(new Step('custom_step', fn($data) => $this->customLogic($data)));
  

2. Error Handling and Retries

• Configure retries and fallbacks per step or globally:

  $workflow->step(new Step('api_call', [ApiService::class, 'fetchData'])
      ->retry(3)
      ->fallback(fn() => $this->handleFallback())
  );
  

• Global retry settings in config (if supported):

  'workflows' => [
      'default_retry_attempts' => 2,
      'timeout_seconds' => 30,
  ],
  

3. Integration with Laravel Ecosystem

• Queue Jobs: Run workflows asynchronously:

  ProcessOrder::dispatch()->onQueue('workflows');
  

• Event Listeners: Trigger workflows on events:

  event(new OrderPlaced($order));
  // Inside listener:
  ProcessOrder::dispatch($order);
  

• Artisan Commands: Schedule workflows via CLI:

  Artisan::call('workflow:run', ['name' => 'user_export']);
  

4. Logging and Monitoring

• Enable logging for debugging:

  $workflow->setLogger(app(\Monolog\Logger::class));
  

• Track workflow execution in a database (if extended):

  $workflow->trackInDatabase(); // Hypothetical method
  

Gotchas and Tips

Pitfalls

1. State Management

   • Talon may not persist workflow state by default. If steps depend on previous outputs, ensure data is passed correctly:

     // Bad: Assumes $users exists globally
     $workflow->step(new Step('export', [Exporter::class, 'export']));
     
     // Good: Explicitly pass data
     $workflow->step(new Step('export', [Exporter::class, 'export'], ['users' => $users]));
     

   • Fix: Use closures or bind data explicitly.

2. Circular Dependencies

   • Avoid workflows that reference each other recursively (e.g., WorkflowA calls WorkflowB, which calls WorkflowA).
   • Fix: Refactor into linear or parallel steps.

3. Performance Bottlenecks

   • Long-running steps can block the entire workflow. Use queues or parallel execution (if supported):

     $workflow->step(new Step('slow_task')->parallel());
     

4. Configuration Overrides

   • Global config (e.g., config/talon.php) may override step-specific settings.
   • Tip: Always check step-level configurations first.

Debugging Tips

• Log Step Outputs:

  $workflow->step(new Step('debug_step')->logOutput());
  

• Inspect Workflow State:

  dd($workflow->getSteps()); // View all steps before execution
  

• Test Steps Isolated:

  $step = new Step('test_step', [TestService::class, 'run']);
  $result = $step->execute(['input' => 'data']); // Test without full workflow
  

Extension Points

1. Custom Step Types Extend Talon\Step to add domain-specific logic:

   class DatabaseStep extends Step
   {
       public function execute($data)
       {
           return DB::table('users')->where('active', 1)->get();
       }
   }
   

2. Middleware for Steps Add pre/post-processing:

   $workflow->step(new Step('log_step')
       ->middleware([LogMiddleware::class, 'before'])
       ->middleware([LogMiddleware::class, 'after'])
   );
   

3. Event Hooks Listen for workflow events (if supported):

   event(new WorkflowStarting($workflow));
   

Pro Tips

• Use Workflows for CRUD Operations: Combine validation, processing, and notifications in one workflow.
• Leverage for Migrations: Automate post-migration tasks (e.g., seed data, cache warming).
• Parallelize Independent Steps: If steps don’t depend on each other, run them concurrently:

  $workflow->step(new Step('task1')->parallel())
            ->step(new Step('task2')->parallel());