Worker Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require coka/worker-bundle in your Laravel project. No additional configuration is required for basic usage—this bundle is designed to integrate seamlessly with Laravel’s existing queue system.

2. First Use Case Define a worker job by extending Oka\WorkerBundle\Worker\WorkerInterface:

   namespace App\Jobs;
   
   use Oka\WorkerBundle\Worker\WorkerInterface;
   
   class ProcessOrder implements WorkerInterface
   {
       public function execute(): void
       {
           // Your job logic here
           \Log::info('Processing order...');
       }
   }
   

   Dispatch the job via Laravel’s queue:

   ProcessOrder::dispatch();
   

3. Where to Look First

   • Worker Interface: src/Worker/WorkerInterface.php (defines the contract for workers).
   • Worker Trait: src/Worker/WorkerTrait.php (provides default implementations for common worker behaviors).
   • Bundle Configuration: config/oka_worker.php (if generated; check for customization points).

Implementation Patterns

Core Workflow

1. Job Dispatching Use Laravel’s built-in queue system (ProcessOrder::dispatch()) to enqueue workers. The bundle abstracts worker execution without replacing Laravel’s queue system.

2. Worker Execution Workers are processed by Laravel’s queue workers (php artisan queue:work). The bundle adds no additional CLI commands—leverage existing Laravel queue tools:

   php artisan queue:work --queue=high_priority
   

3. Dependency Injection Inject dependencies into workers via Laravel’s container:

   use Illuminate\Contracts\Queue\ShouldQueue;
   
   class ProcessOrder implements WorkerInterface, ShouldQueue
   {
       public function __construct(private OrderRepository $orders)
       {
       }
   
       public function execute(): void
       {
           $this->orders->process();
       }
   }
   

Integration Tips

• Queue Connections: Configure workers to use specific queue connections (e.g., database, redis) via Laravel’s queue.php.
• Retry Logic: Implement ShouldQueue and Illuminate\Bus\Queueable for retries/failures:

  public function failed(\Throwable $exception)
  {
      \Log::error("Worker failed: " . $exception->getMessage());
  }
  

• Event Listeners: Trigger events post-execution:

  public function execute(): void
  {
      event(new OrderProcessed($this->order));
  }
  

Gotchas and Tips

Pitfalls

1. No Built-in CLI Unlike Symfony-based bundles, this package does not introduce new CLI commands. Use Laravel’s queue:work instead.

2. No Worker Pooling The bundle does not manage worker processes (e.g., Supervisor). Configure Laravel’s queue worker separately:

   php artisan queue:work --daemon --sleep=3 --tries=3
   

3. Limited Documentation The package lacks examples for advanced use cases (e.g., worker timeouts, custom middleware). Refer to Laravel’s queue documentation for gaps.

Debugging

• Worker Failures: Check Laravel’s queue failure table (failed_jobs) or logs (storage/logs/laravel.log).
• Execution Context: Use WorkerTrait::log() for debugging:

  trait WorkerTrait {
      protected function log(string $message): void
      {
          \Log::debug("[Worker] {$message}");
      }
  }
  

Extension Points

1. Custom Worker Middleware Attach middleware to workers via Laravel’s queue middleware:

   // app/Providers/AppServiceProvider.php
   public function boot()
   {
       Queue::before(function (JobProcessing $event) {
           if ($event->job instanceof WorkerInterface) {
               // Pre-execution logic
           }
       });
   }
   

2. Worker Metadata Extend the WorkerInterface to add metadata (e.g., priority, timeout):

   interface WorkerInterface {
       public function getPriority(): int;
       public function getTimeout(): int;
   }
   

   Then filter workers in middleware or queue listeners.

3. Symfony Integration If using Symfony components, manually register the bundle in config/bundles.php (as shown in README), but note this is redundant in Laravel. The bundle is Laravel-agnostic under the hood.