Laravel Queueable Action Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require spatie/laravel-queueable-action
   

   Publish the config (optional):

   php artisan vendor:publish --provider="Spatie\QueueableAction\QueueableActionServiceProvider"
   

2. First Use Case Create an action class extending Spatie\QueueableAction\Action:

   use Spatie\QueueableAction\Action;
   
   class ProcessOrderAction extends Action
   {
       public function run()
       {
           // Your business logic here
           Order::find($this->orderId)->process();
       }
   }
   

   Queue the action:

   $action = new ProcessOrderAction(orderId: $orderId);
   $action->onQueue('orders')->execute();
   

3. Where to Look First

   • README for core concepts.
   • config/queueable-action.php for default queue settings.
   • app/Console/Kernel.php to verify queue workers are configured.

Implementation Patterns

Core Workflows

1. Basic Queueing

   $action = new MyAction(...);
   $action->onQueue()->execute(); // Uses default queue
   

2. Custom Queue Names

   $action->onQueue('high-priority')->execute();
   

3. Delayed Execution

   $action->delay(now()->addMinutes(10))->execute();
   

4. Chaining Actions

   $action1 = new Action1(...);
   $action2 = new Action2(...);
   
   $action1->onQueue()->execute();
   $action2->onQueue('secondary')->execute();
   

Integration Tips

• Dependency Injection: Pass required dependencies via constructor.

  class MyAction extends Action {
      public function __construct(private OrderRepository $orders) {}
  }
  

• Event Dispatching: Dispatch events after execution:

  public function run() {
      $this->orders->process($this->orderId);
      event(new OrderProcessed($this->orderId));
  }
  

• Job Chaining: Use Laravel’s afterCommit() for database-heavy actions:

  $action->onQueue()->afterCommit()->execute();
  

• Middleware: Apply middleware to actions:

  $action->onQueue()->withMiddleware(CheckUserPermission::class)->execute();
  

Gotchas and Tips

Pitfalls

1. Queue Worker Must Be Running

   • Ensure php artisan queue:work is running (or supervised via Supervisor/Foreman).
   • Debug: Check jobs table for stuck jobs or laravel.log for worker errors.

2. Serialization Issues

   • Avoid passing non-serializable objects (e.g., closures, resources) to actions.
   • Fix: Use IDs or DTOs instead.

3. Default Queue Overrides

   • If QUEUE_CONNECTION in .env is sync, actions won’t queue.
   • Fix: Explicitly set a queue name or verify .env:

     QUEUE_CONNECTION=database
     

4. Transaction Conflicts

   • Actions run outside the original request’s transaction.
   • Fix: Use afterCommit() for critical DB operations.

5. Missing run() Method

   • Forgetting to define run() will throw BadMethodCallException.
   • Fix: Always implement run() in your action class.

Debugging

• Check Job Payloads:

  php artisan queue:table
  

  Inspect the payload column for malformed data.

• Log Queue Events: Add to AppServiceProvider:

  public function boot()
  {
      Queue::before(function ($job, $data) {
          Log::debug('Queueing job', ['job' => get_class($job), 'data' => $data]);
      });
  }
  

Tips

1. Queue Namespacing Use namespaced queues for better organization:

   $action->onQueue('notifications.email')->execute();
   

2. Dynamic Queues Set queue names dynamically:

   $queue = $this->user->isPremium() ? 'premium-jobs' : 'standard-jobs';
   $action->onQueue($queue)->execute();
   

3. Action Metadata Store metadata in the action’s constructor:

   class MyAction extends Action {
       public function __construct(
           public string $userId,
           public string $metadata = 'default'
       ) {}
   }
   

4. Testing Use Queue::fake() in tests:

   public function test_action_is_queued()
   {
       Queue::fake();
       $action->onQueue()->execute();
       Queue::assertPushed(MyAction::class);
   }
   

5. Performance

   • Batch small actions into a single job to reduce overhead.
   • Use onQueue()->withoutOverlapping() for idempotent actions:

     $action->onQueue()->withoutOverlapping(10)->execute();
     

6. Custom Job Class Extend Spatie\QueueableAction\Jobs\QueueableActionJob for advanced use cases:

   class CustomJob extends QueueableActionJob {
       public function retryUntil()
       {
           return now()->addMinutes(5); // Custom retry logic
       }
   }
   

   Then bind it in QueueableActionServiceProvider.