laravel-queues

Laravel Queues

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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

Component	Purpose
Jobs	Background tasks with retries, timeouts
Workers	Process jobs from queues
Batches	Group jobs with progress tracking
Chains	Sequential job execution
Middleware	Rate limiting, deduplication
Horizon	Redis queue monitoring dashboard

---

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

Topic	Reference	When to Consult
Jobs	jobs.md	Creating job classes
Dispatching	dispatching.md	Sending jobs to queues
Workers	workers.md	Running queue workers
Batching	batching.md	Grouping jobs
Chaining	chaining.md	Sequential jobs
Middleware	middleware.md	Rate limiting, dedup
Failed Jobs	failed-jobs.md	Error handling
Horizon	horizon.md	Monitoring dashboard
Testing	testing.md	Job testing
Troubleshooting	troubleshooting.md	Common issues

Templates

Template	When to Use
QueueableJob.php.md	Standard job with retries
BatchJob.php.md	Batchable job
ChainedJobs.php.md	Job chain implementation
JobMiddleware.php.md	Custom middleware
JobTest.php.md	Testing jobs

---

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