laravel-queues

Laravel Queues (L13 — Attributes-first)

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Audit job classes, connections, queue routes
2. fuse-ai-pilot:research-expert - Verify L13 Queue + Queue::route() via Context7
3. mcp__context7__query-docs - Check queue attribute patterns

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

---

Overview

Laravel 13 introduces PHP Attributes on Queueables (Jobs, Listeners, Notifications, Mailables, Broadcast Events) as the primary configuration mechanism. Centralised routing is configured via Queue::route() in AppServiceProvider::boot().

Attribute (L13 MAIN)	Legacy property
#[Connection('redis')] · #[Queue('podcasts')]	public $connection · public $queue
#[Tries(5)] · #[Timeout(120)] · #[MaxExceptions(3)]	public int $tries / $timeout / $maxExceptions
#[Backoff([10, 30, 60])] · #[FailOnTimeout]	public $backoff · public bool $failOnTimeout
#[UniqueFor(3600)] · #[AfterCommit] · #[DeleteWhenMissingModels]	public $uniqueFor / $afterCommit / $deleteWhenMissingModels

Applies to Jobs, Listeners, Notifications, Mailables, and Broadcast Events.

---

Critical Rules

1. Declare queue metadata with Attributes - #[Queue], #[Tries], #[Backoff]
2. Centralise routing with Queue::route() in AppServiceProvider::boot()
3. Implement failed(Throwable $e) for every production job
4. Use #[AfterCommit] when dispatching inside DB transactions
5. Monitor Redis queues with Horizon in production

---

Architecture

app/
├── Jobs/
│   └── ProcessPodcast.php       # #[Connection, Queue, Tries, Backoff]
├── Providers/
│   └── AppServiceProvider.php   # Queue::route('podcasts', 'redis')
└── Listeners/
    └── SendShipmentNotification.php  # #[Queue('mail')]

→ See templates/QueueableJob.php.md

---

Reference Guide

Concepts

• Migration L12→L13: legacy-properties.md
• Jobs lifecycle: jobs.md · dispatching.md · workers.md
• Composition: batching.md · chaining.md · middleware.md
• Reliability: failed-jobs.md · horizon.md · testing.md · troubleshooting.md

Templates

Template	When to Use
QueueableJob.php.md	Attribute-based job
BatchJob.php.md	Batchable job
ChainedJobs.php.md	Job chain
JobMiddleware.php.md	Custom middleware
JobTest.php.md	Job test

---

Quick Reference

Attribute-based Job (L13 MAIN)

use Illuminate\Queue\Attributes\{Connection, Queue, Tries, Timeout, Backoff, MaxExceptions, FailOnTimeout, UniqueFor};
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

#[Connection('redis')]
#[Queue('podcasts')]
#[Tries(5)]
#[Timeout(120)]
#[Backoff([10, 30, 60])]
#[MaxExceptions(3)]
#[FailOnTimeout]
#[UniqueFor(3600)]
final class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    public function __construct(public readonly Podcast $podcast) {}

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

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

Queue Routing (centralised)

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::route('podcasts', connection: 'redis', queue: 'media');
    Queue::route('mail',     connection: 'redis', queue: 'transactional');
}

→ Legacy public int $tries = 5 style — see legacy-properties.md

---

Best Practices

DO

• Use Attributes on Jobs, Listeners, Notifications, Mailables, Broadcast Events
• Centralise routing via Queue::route() in AppServiceProvider::boot()
• Use #[AfterCommit] when dispatching inside a transaction
• final job classes, implement failed(), monitor Redis with Horizon

DON'T

• Mix #[Tries] and public int $tries (single source of truth)
• Dispatch in a transaction without #[AfterCommit]
• Store large objects/closures in job constructor properties
• Use sync driver in production