Laravel Queues (L13 — Attributes-first)
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- explore-codebase - Audit job classes, connections, queue routes
- research-expert - Verify L13 Queue + Queue::route() via Context7
- mcp__context7__query-docs - Check queue attribute patterns
After implementation, run 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-queues-23description: Use when implementing Laravel 13 background jobs — queue attributes, workers, batching, chaining, middleware, or Queue::route() routing.4---56<objective>7Covers Laravel 13 queues with PHP Attributes as the primary configuration8mechanism on Jobs, Listeners, Notifications, Mailables, and Broadcast Events9(#[Connection], #[Queue], #[Tries], #[Timeout], #[Backoff],10#[MaxExceptions], #[FailOnTimeout], #[UniqueFor], #[AfterCommit]) alongside11legacy property equivalents. Includes job lifecycle, dispatching, workers,12batching, chaining, custom middleware, failed-job handling, Horizon13monitoring, testing, troubleshooting, and centralised queue routing via14Queue::route() in AppServiceProvider::boot().15</objective>1617# Laravel Queues (L13 — Attributes-first)1819## Agent Workflow (MANDATORY)2021Before ANY implementation, use `TeamCreate` to spawn 3 agents:22231. **explore-codebase** - Audit job classes, connections, queue routes242. **research-expert** - Verify L13 Queue + Queue::route() via Context7253. **mcp__context7__query-docs** - Check queue attribute patterns2627After implementation, run **sniper** for validation.2829---3031## Overview3233Laravel 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()`.3435| Attribute (L13 MAIN) | Legacy property |36|----------------------|-----------------|37| `#[Connection('redis')]` · `#[Queue('podcasts')]` | `public $connection` · `public $queue` |38| `#[Tries(5)]` · `#[Timeout(120)]` · `#[MaxExceptions(3)]` | `public int $tries / $timeout / $maxExceptions` |39| `#[Backoff([10, 30, 60])]` · `#[FailOnTimeout]` | `public $backoff` · `public bool $failOnTimeout` |40| `#[UniqueFor(3600)]` · `#[AfterCommit]` · `#[DeleteWhenMissingModels]` | `public $uniqueFor / $afterCommit / $deleteWhenMissingModels` |4142> Applies to **Jobs, Listeners, Notifications, Mailables, and Broadcast Events**.4344---4546## Critical Rules47481. **Declare queue metadata with Attributes** - `#[Queue]`, `#[Tries]`, `#[Backoff]`492. **Centralise routing with `Queue::route()`** in `AppServiceProvider::boot()`503. **Implement `failed(Throwable $e)`** for every production job514. **Use `#[AfterCommit]`** when dispatching inside DB transactions525. **Monitor Redis queues with Horizon** in production5354---5556## Architecture5758```59app/60├── Jobs/61│ └── ProcessPodcast.php # #[Connection, Queue, Tries, Backoff]62├── Providers/63│ └── AppServiceProvider.php # Queue::route('podcasts', 'redis')64└── Listeners/65 └── SendShipmentNotification.php # #[Queue('mail')]66```6768→ See [templates/QueueableJob.php.md](references/templates/QueueableJob.php.md)6970---7172## Reference Guide7374### Concepts7576- **Migration L12→L13:** [legacy-properties.md](references/legacy-properties.md)77- **Jobs lifecycle:** [jobs.md](references/jobs.md) · [dispatching.md](references/dispatching.md) · [workers.md](references/workers.md)78- **Composition:** [batching.md](references/batching.md) · [chaining.md](references/chaining.md) · [middleware.md](references/middleware.md)79- **Reliability:** [failed-jobs.md](references/failed-jobs.md) · [horizon.md](references/horizon.md) · [testing.md](references/testing.md) · [troubleshooting.md](references/troubleshooting.md)8081### Templates8283| Template | When to Use |84|----------|-------------|85| [QueueableJob.php.md](references/templates/QueueableJob.php.md) | Attribute-based job |86| [BatchJob.php.md](references/templates/BatchJob.php.md) | Batchable job |87| [ChainedJobs.php.md](references/templates/ChainedJobs.php.md) | Job chain |88| [JobMiddleware.php.md](references/templates/JobMiddleware.php.md) | Custom middleware |89| [JobTest.php.md](references/templates/JobTest.php.md) | Job test |9091---9293## Quick Reference9495### Attribute-based Job (L13 MAIN)9697```php98use Illuminate\Queue\Attributes\{Connection, Queue, Tries, Timeout, Backoff, MaxExceptions, FailOnTimeout, UniqueFor};99use Illuminate\Contracts\Queue\ShouldQueue;100use Illuminate\Foundation\Queue\Queueable;101102#[Connection('redis')]103#[Queue('podcasts')]104#[Tries(5)]105#[Timeout(120)]106#[Backoff([10, 30, 60])]107#[MaxExceptions(3)]108#[FailOnTimeout]109#[UniqueFor(3600)]110final class ProcessPodcast implements ShouldQueue111{112 use Queueable;113114 public function __construct(public readonly Podcast $podcast) {}115116 public function handle(PodcastService $service): void { $service->process($this->podcast); }117118 public function failed(\Throwable $e): void { Log::error('Podcast failed', ['id' => $this->podcast->id, 'e' => $e]); }119}120```121122### Queue Routing (centralised)123124```php125// app/Providers/AppServiceProvider.php126use Illuminate\Support\Facades\Queue;127128public function boot(): void129{130 Queue::route('podcasts', connection: 'redis', queue: 'media');131 Queue::route('mail', connection: 'redis', queue: 'transactional');132}133```134135→ Legacy `public int $tries = 5` style — see [legacy-properties.md](references/legacy-properties.md)136137---138139## Best Practices140141### DO142- Use **Attributes** on Jobs, Listeners, Notifications, Mailables, Broadcast Events143- Centralise routing via `Queue::route()` in `AppServiceProvider::boot()`144- Use `#[AfterCommit]` when dispatching inside a transaction145- `final` job classes, implement `failed()`, monitor Redis with Horizon146147### DON'T148- Mix `#[Tries]` and `public int $tries` (single source of truth)149- Dispatch in a transaction without `#[AfterCommit]`150- Store large objects/closures in job constructor properties151- Use `sync` driver in production