name: laravel-queues description: Implement background jobs with queues, workers, batches, chains, middleware, and failure handling. Use when processing async tasks or handling long-running operations. versions: laravel: "12.46" horizon: "5.43" php: "8.5" user-invocable: false references: references/jobs.md, references/dispatching.md, references/workers.md, references/batching.md, references/chaining.md, references/middleware.md, references/failed-jobs.md, references/horizon.md, references/testing.md, references/troubleshooting.md, references/templates/QueueableJob.php.md, references/templates/BatchJob.php.md, references/templates/ChainedJobs.php.md, references/templates/JobMiddleware.php.md, references/templates/JobTest.php.md related-skills: laravel-architecture, laravel-eloquent

Laravel Queues

Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

1. fuse-ai-pilot:explore-codebase - Analyze existing job patterns
2. fuse-ai-pilot:research-expert - Verify Queue docs via Context7
3. mcp__context7__query-docs - Check job and worker patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Decision Guide: Queue Driver

Which driver?
├── Development → sync (instant execution)
├── Small app → database (simple, no Redis)
├── Production → redis (fast, Horizon support)
├── AWS → sqs (managed, scalable)
└── High volume → redis + Horizon (monitoring)

Decision Guide: Job Design

Job type?
├── Simple async → Standard Job
├── Group processing → Batch (progress, cancel)
├── Sequential steps → Chain (A → B → C)
├── Rate limited → Middleware + RateLimiter
├── Unique execution → UniqueJob / WithoutOverlapping
└── Long running → Timeout + Retry settings

Critical Rules

1. Use ShouldQueue for async processing
2. Set tries and backoff for resilience
3. Implement failed() method for error handling
4. Use database transactions carefully with jobs
5. Monitor with Horizon in production

Reference Guide

Concepts

Templates

Quick Reference

Basic Job

final class ProcessOrder implements ShouldQueue
{
    use Queueable;

    public int $tries = 3;
    public int $backoff = 60;
    public int $timeout = 120;

    public function __construct(
        public readonly Order $order,
    ) {}

    public function handle(OrderService $service): void
    {
        $service->process($this->order);
    }

    public function failed(\Throwable $e): void
    {
        Log::error('Order failed', ['id' => $this->order->id]);
    }
}

Dispatch

// Immediate
ProcessOrder::dispatch($order);

// Delayed
ProcessOrder::dispatch($order)->delay(now()->addMinutes(5));

// On specific queue
ProcessOrder::dispatch($order)->onQueue('orders');

Best Practices

DO

• Use final for job classes
• Implement failed() method
• Set appropriate timeout values
• Use Unique for one-at-a-time jobs
• Monitor with Horizon in production

DON'T

• Dispatch inside database transactions (use afterCommit)
• Store large objects in job properties
• Forget to handle failures
• Use sync driver in production