laravel-queues

Laravel 13 のキューを取り上げます。Job、Listener、Notification、Mailable、Broadcast Event で、PHP Attributes を主な設定方法として使用します （#[Connection]、#[Queue]、#[Tries]、#[Timeout]、#[Backoff]、 #[MaxExceptions]、#[FailOnTimeout]、#[UniqueFor]、#[Delay]、#[DebounceFor]）。従来のプロパティによる設定にも対応しています。ジョブのライフサイクル、ディスパッチ、ワーカー、 バッチ処理、チェーン、カスタムミドルウェア、失敗したジョブの処理、Horizon による監視、テスト、トラブルシューティングのほか、AppServiceProvider::boot() の Queue::route() による一元的なキュールーティングを含みます。

Laravel Queues（L13 — Attributes優先）

エージェントのワークフロー（必須）

実装を行う前に、必ず3つのエージェントを並列で起動してください。それぞれ1回ずつ、name を指定して Agent を呼び出します。

1. fuse-ai-pilot:explore-codebase - ジョブクラス、接続、キュールートを監査
2. fuse-ai-pilot:research-expert - Context7 で L13 Queue と Queue::route() を検証
3. mcp__context7__query-docs - キュー属性のパターンを確認

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

Laravel 13 では、Queueable（Jobs、Listeners、Notifications、Mailables、Broadcast Events）の主な設定方法として PHP Attributes が導入されています。一元的なルーティングは、AppServiceProvider::boot() の Queue::route() で設定します。

属性（L13 の主な方法）	従来のプロパティ
#[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)] · #[DeleteWhenMissingModels] · #[Delay(60)]	public $uniqueFor / $deleteWhenMissingModels / $delay
#[DebounceFor(30, maxWait: 120)]（13.6+、debounceId() と併用）	—
属性なし — ->afterCommit() / ShouldQueueAfterCommit	public $afterCommit

Jobs、Listeners、Notifications、Mailables、Broadcast Events に適用されます。

---

重要なルール

1. キューのメタデータは Attributes で宣言します - #[Queue]、#[Tries]、#[Backoff]
2. AppServiceProvider::boot() の Queue::route() でルーティングを一元化します
3. 本番環境のすべてのジョブに failed(Throwable $e) を実装します
4. DB トランザクション内でディスパッチする場合は ->afterCommit()（または after_commit 接続設定）を使用します
5. 本番環境では Horizon を使って Redis キューを監視します

---

アーキテクチャ

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

→ templates/QueueableJob.php.md を参照してください

---

リファレンスガイド

概念

• L12 から L13 への移行： legacy-properties.md
• ジョブのライフサイクル： jobs.md · dispatching.md · workers.md
• 構成： batching.md · chaining.md · middleware.md
• 信頼性： failed-jobs.md · horizon.md · testing.md · troubleshooting.md

テンプレート

テンプレート	使用場面
QueueableJob.php.md	属性ベースのジョブ
BatchJob.php.md	バッチ処理可能なジョブ
ChainedJobs.php.md	ジョブチェーン
JobMiddleware.php.md	カスタムミドルウェア
JobTest.php.md	ジョブのテスト

---

クイックリファレンス

属性ベースのジョブ（L13 の主な方法）

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]); }
}

キュールーティング（一元管理）

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

public function boot(): void
{
    // First argument = job class, or an interface / trait / parent class
    Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'media');
    Queue::route(ShouldBroadcast::class, queue: 'events');
    Queue::route([ProcessVideo::class => ['redis', 'videos']]);

    // Forward a queue to another queue / connection (13.26+)
    Queue::forward('reports', 'reports.fifo', 'sqs');
}

その他の 13.x での追加機能

• Bus::bulk($jobs)（13.13 以降）— 独立した複数のジョブを接続／キューごとにグループ化して一括投入します。バッチ追跡は行いません
• PreparesForDispatch インターフェース（13.9 以降）— prepareForDispatch() が false を返すと、ディスパッチをスキップします
• Illuminate\Queue\Middleware\Release ジョブミドルウェア（13.18 以降）— Release::when($condition, releaseAfter: 60)

→ 従来の public int $tries = 5 スタイルについては、legacy-properties.md を参照してください

---

ベストプラクティス

推奨事項

• ジョブ、リスナー、通知、メール可能クラス、ブロードキャストイベントには属性を使用します
• AppServiceProvider::boot() 内の Queue::route() を通じてルーティングを一元管理します
• トランザクション内でディスパッチする場合は ->afterCommit() を使用します
• ジョブクラスを final にし、failed() を実装して、Horizon で Redis を監視します

禁止事項

• #[Tries] と public int $tries を併用しないでください（信頼できる情報源は 1 つにしてください）
• ->afterCommit()（または after_commit => true）を使わずに、トランザクション内でディスパッチしないでください
• 大きなオブジェクトやクロージャをジョブコンストラクターのプロパティに保存しないでください
• 本番環境では sync ドライバーを使用しないでください