Laravel Queues (L13 — Attributes-first)
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Audit job classes, connections, queue routes
- fuse-ai-pilot:research-expert - Verify L13 Queue + Queue::route() via Context7
- 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
- Declare queue metadata with Attributes -
#[Queue], #[Tries], #[Backoff]
- Centralise routing with
Queue::route() in AppServiceProvider::boot()
- Implement
failed(Throwable $e) for every production job
- Use
#[AfterCommit] when dispatching inside DB transactions
- 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
1---2name: laravel-queues3description: Use when implementing Laravel 13 background jobs — queue attributes, workers, batching, chaining, middleware, or Queue::route() routing.4versions:5 laravel: "13.0"6 horizon: "5.43"7 php: "8.3"8user-invocable: false9references: references/legacy-properties.md, 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.md10related-skills: laravel-attributes, laravel-architecture, laravel-eloquent11metadata:12 source: https://skillmd.com/skills/fusengine/laravel-queues13---1415<objective>16Covers Laravel 13 queues with PHP Attributes as the primary configuration17mechanism on Jobs, Listeners, Notifications, Mailables, and Broadcast Events18(#[Connection], #[Queue], #[Tries], #[Timeout], #[Backoff],19#[MaxExceptions], #[FailOnTimeout], #[UniqueFor], #[AfterCommit]) alongside20legacy property equivalents. Includes job lifecycle, dispatching, workers,21batching, chaining, custom middleware, failed-job handling, Horizon22monitoring, testing, troubleshooting, and centralised queue routing via23Queue::route() in AppServiceProvider::boot().24</objective>2526# Laravel Queues (L13 — Attributes-first)2728## Agent Workflow (MANDATORY)2930Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:31321. **fuse-ai-pilot:explore-codebase** - Audit job classes, connections, queue routes332. **fuse-ai-pilot:research-expert** - Verify L13 Queue + Queue::route() via Context7343. **mcp__context7__query-docs** - Check queue attribute patterns3536After implementation, run **fuse-ai-pilot:sniper** for validation.3738---3940## Overview4142Laravel 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()`.4344| Attribute (L13 MAIN) | Legacy property |45|----------------------|-----------------|46| `#[Connection('redis')]` · `#[Queue('podcasts')]` | `public $connection` · `public $queue` |47| `#[Tries(5)]` · `#[Timeout(120)]` · `#[MaxExceptions(3)]` | `public int $tries / $timeout / $maxExceptions` |48| `#[Backoff([10, 30, 60])]` · `#[FailOnTimeout]` | `public $backoff` · `public bool $failOnTimeout` |49| `#[UniqueFor(3600)]` · `#[AfterCommit]` · `#[DeleteWhenMissingModels]` | `public $uniqueFor / $afterCommit / $deleteWhenMissingModels` |5051> Applies to **Jobs, Listeners, Notifications, Mailables, and Broadcast Events**.5253---5455## Critical Rules56571. **Declare queue metadata with Attributes** - `#[Queue]`, `#[Tries]`, `#[Backoff]`582. **Centralise routing with `Queue::route()`** in `AppServiceProvider::boot()`593. **Implement `failed(Throwable $e)`** for every production job604. **Use `#[AfterCommit]`** when dispatching inside DB transactions615. **Monitor Redis queues with Horizon** in production6263---6465## Architecture6667```68app/69├── Jobs/70│ └── ProcessPodcast.php # #[Connection, Queue, Tries, Backoff]71├── Providers/72│ └── AppServiceProvider.php # Queue::route('podcasts', 'redis')73└── Listeners/74 └── SendShipmentNotification.php # #[Queue('mail')]75```7677→ See [templates/QueueableJob.php.md](references/templates/QueueableJob.php.md)7879---8081## Reference Guide8283### Concepts8485- **Migration L12→L13:** [legacy-properties.md](references/legacy-properties.md)86- **Jobs lifecycle:** [jobs.md](references/jobs.md) · [dispatching.md](references/dispatching.md) · [workers.md](references/workers.md)87- **Composition:** [batching.md](references/batching.md) · [chaining.md](references/chaining.md) · [middleware.md](references/middleware.md)88- **Reliability:** [failed-jobs.md](references/failed-jobs.md) · [horizon.md](references/horizon.md) · [testing.md](references/testing.md) · [troubleshooting.md](references/troubleshooting.md)8990### Templates9192| Template | When to Use |93|----------|-------------|94| [QueueableJob.php.md](references/templates/QueueableJob.php.md) | Attribute-based job |95| [BatchJob.php.md](references/templates/BatchJob.php.md) | Batchable job |96| [ChainedJobs.php.md](references/templates/ChainedJobs.php.md) | Job chain |97| [JobMiddleware.php.md](references/templates/JobMiddleware.php.md) | Custom middleware |98| [JobTest.php.md](references/templates/JobTest.php.md) | Job test |99100---101102## Quick Reference103104### Attribute-based Job (L13 MAIN)105106```php107use Illuminate\Queue\Attributes\{Connection, Queue, Tries, Timeout, Backoff, MaxExceptions, FailOnTimeout, UniqueFor};108use Illuminate\Contracts\Queue\ShouldQueue;109use Illuminate\Foundation\Queue\Queueable;110111#[Connection('redis')]112#[Queue('podcasts')]113#[Tries(5)]114#[Timeout(120)]115#[Backoff([10, 30, 60])]116#[MaxExceptions(3)]117#[FailOnTimeout]118#[UniqueFor(3600)]119final class ProcessPodcast implements ShouldQueue120{121 use Queueable;122123 public function __construct(public readonly Podcast $podcast) {}124125 public function handle(PodcastService $service): void { $service->process($this->podcast); }126127 public function failed(\Throwable $e): void { Log::error('Podcast failed', ['id' => $this->podcast->id, 'e' => $e]); }128}129```130131### Queue Routing (centralised)132133```php134// app/Providers/AppServiceProvider.php135use Illuminate\Support\Facades\Queue;136137public function boot(): void138{139 Queue::route('podcasts', connection: 'redis', queue: 'media');140 Queue::route('mail', connection: 'redis', queue: 'transactional');141}142```143144→ Legacy `public int $tries = 5` style — see [legacy-properties.md](references/legacy-properties.md)145146---147148## Best Practices149150### DO151- Use **Attributes** on Jobs, Listeners, Notifications, Mailables, Broadcast Events152- Centralise routing via `Queue::route()` in `AppServiceProvider::boot()`153- Use `#[AfterCommit]` when dispatching inside a transaction154- `final` job classes, implement `failed()`, monitor Redis with Horizon155156### DON'T157- Mix `#[Tries]` and `public int $tries` (single source of truth)158- Dispatch in a transaction without `#[AfterCommit]`159- Store large objects/closures in job constructor properties160- Use `sync` driver in production