queue:listen — キューを監視しジョブを処理するコマンド

公式情報

ドキュメント	リンク	主な内容
Laravel 公式: Queues	https://laravel.com/docs/12.x/queues	キュー全体の設定・queue:listen の使い方・オプション
Laravel API: Listener	https://api.laravel.com/docs/12.x/Illuminate/Queue/Listener.html	listen() メソッドのシグネチャ
Laravel Horizon	https://laravel.com/docs/12.x/horizon	ダッシュボードと高度なキュー管理

---

php artisan queue:listen の使い方

コマンド構文

php artisan queue:listen [connection] [queue] [options]

引数	説明
connection	キュードライバ（例: redis, database）
queue	オプション。省略時は default
options	フラグの集合

主要フラグ

フラグ	値	効果
--tries=NUM	整数	失敗したジョブを再試行する最大回数（デフォルトは retry_after）
--delay=SECONDS	整数	再試行までの遅延時間
--memory=SIZE	整数	メモリ上限（MB）に到達するとワーカーを再起動
--sleep=SECONDS	整数	キューが空の場合に待機する秒数
--max-jobs=NUM	整数	指定件数のジョブを処理したら終了
--queue=NAME	文字列	デフォルトキューを上書き
--quiet	なし	出力を抑制
--once	なし	1件だけジョブを実行して終了
--daemon	なし	デーモンモードで実行（毎回ブートストラップしない）
--timeout=SECONDS	整数	ジョブ実行タイムアウト（秒）

ヒント：ローカル開発時は --tries=3 でジョブを 3 回までリトライさせると便利です。

最小構成の実例

php artisan queue:listen redis --queue=emails --tries=5

• redis 接続で emails キューを監視
• ジョブが失敗した場合、Laravel の Queue::failing() イベントがトリガーされます

Listener オプション（Laravel 12.x）

use Illuminate\Queue\ListenerOptions;

$options = ListenerOptions::make()
    ->tries(5)
    ->backoff([10, 20, 30]);   // 秒単位のリトライ遅延

Queue::listen('redis', 'emails', $options);

---

よくある落とし穴

問題	原因	対処
接続が見つからない	config/queue.php または .env に設定が無い	必要な接続を追加
プロセスが古い	Docker 等で古いワーカーが残っている	queue:restart でリロード
メモリリーク	長時間実行のジョブでメモリが増大	--memory=128 などを設定
キュー名が合わない	ジョブの $queue プロパティや dispatchToQueue() で指定ミス	ジョブクラスとキュー名を一致させる

---

さらに学ぶためのリソース

タイトル	リンク
Laravel Queue Docs (v12)	https://laravel.com/docs/12.x/queues
Horizon Dashboard	https://laravel.com/docs/12.x/horizon
Artisan Cheat Sheet	https://artisan.page/9.x/queuelisten
ローカル開発ガイド	https://laraveldaily.com/lesson/queues-laravel/queue-listen-local

上記リンクを参照して、最新の設定やベストプラクティスを確認してください。