laravel-background-processing

name	laravel-background-processing
description	Build scalable asynchronous workflows using Queues, Jobs, and Events in Laravel. Use when implementing queued jobs, event-driven workflows, or async processing in Laravel.
metadata	{"triggers":{"files":["app/Jobs/**/*.php","app/Events/**/*.php","app/Listeners/**/*.php"],"keywords":["ShouldQueue","dispatch","batch","chain","listener"]}}

Laravel Background Processing

Priority: P1 (HIGH)

Structure

app/
├── Jobs/               # Asynchronous tasks
├── Events/             # Communication flags
└── Listeners/          # Task reactions

Implementation Guidelines

Queued Jobs

• Job Creation: Use php artisan make:job ProcessOrder. Classes must implement ShouldQueue.
• Execution: Implement logic inside handle() method. Pass only model IDs to constructor, not full Eloquent model.
• Dispatching: Trigger via ProcessOrder::dispatch($orderId).

Advanced Workflow Patterns

• Job Chaining: Use Bus::chain([new ProcessPayment($order), new SendReceipt($order)])->dispatch() for sequential dependencies. Handle failures with ->catch(fn => ...).
• Job Batching: Use Bus::batch([new ImportRow(1), ...])->then(...)->catch(...)->dispatch(). Use $this->batch()->cancel() to abort and track via $batch->progress().

Events & Listeners

• Scaffolding: Run php artisan make:event OrderPlaced and php artisan make:listener SendConfirmation --event=OrderPlaced.
• Async Execution: Add ShouldQueue to listeners to process them asynchronously.
• Activation: Trigger with Event::dispatch(new OrderPlaced($order)).

Reliability & Monitoring

• Error Handling: Implement public function failed(Throwable $exception) in your job class. Use public int $tries = 3 and public int $backoff = 60 for retries.
• Setup: Run queue:failed-table migration to track dead jobs.
• Monitoring: Use Laravel Horizon (run php artisan horizon) for real-time observability; never use queue:work in production.

Anti-Patterns

• No heavy logic in request path: Defer tasks >100ms to Queues.
• No full model in job payload: Pass IDs; Eloquent fetches on run.
• No deep event listener chains: Keep listener depth shallow.
• No unmonitored queues: Configure retries and Horizon alerts.

References

• Job Chaining & Event Patterns

Horizon checklist

• Horizon deployments must publish and edit config/horizon.php, then run php artisan horizon; do not use queue:work as the production monitor.

Canonical response anchors

When this skill applies, preserve the following domain terminology or equivalent concrete examples in the answer when relevant:

• composer

• batch()->cancel

• Additional task-grounded exact anchors: ImportRow