キューとジョブ - Knowledge of Laravel

キューとは

Webアプリケーションでは、メール送信・画像のリサイズ・外部APIへの問い合わせなど、完了まで数秒かかる処理が発生することがあります。これをHTTPリクエストの中で同期的に行うと、ユーザーはレスポンスが返るまで待ち続けなければなりません。 Laravelのキューを使うと、こうした重い処理をバックグラウンドで非同期に実行できます。リクエストはすぐにレスポンスを返し、実際の処理はワーカープロセスが別途こなしてくれます。

キューはデータベース・Redis・Amazon SQSなど複数のバックエンドに対応しています。開発環境では sync ドライバを使うと、キューを使わずジョブを即時実行できます。

キューの設定

config/queue.php

キューの設定は config/queue.php に集約されています。 QUEUE_CONNECTION 環境変数で使用するドライバを切り替えます。

// config/queue.php
'default' => env('QUEUE_CONNECTION', 'database'),

.env の設定

# ドライバの選択
QUEUE_CONNECTION=database

# Redisを使う場合
# QUEUE_CONNECTION=redis
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

データベースドライバの準備

database ドライバを使う場合、ジョブを保存するテーブルが必要です。 Laravel 11以降の新規プロジェクトには最初からマイグレーションが含まれていますが、含まれていない場合は次のコマンドで作成します。

php artisan make:queue-table
php artisan migrate

Redisドライバの準備

redis ドライバを使う場合は config/database.php にRedis接続設定を追加し、 Composerでドライバをインストールします。

composer require predis/predis

SQS Overflow Storage

Amazon SQS はメッセージペイロードの最大サイズに制限があります。ペイロードが大きくなるジョブを扱う場合は、超過分をキャッシュストアに保存し、SQSにはポインターのみを送る設定を追加します。

'sqs' => [
    // ...
    'overflow' => [
        'enabled' => env('SQS_OVERFLOW_ENABLED', false),
        'store' => env('SQS_OVERFLOW_STORE'),
        'always' => false,
        'delete_after_processing' => true,
        'flush_on_clear' => env('SQS_OVERFLOW_FLUSH_ON_CLEAR', false),
    ],
],

enabled を有効にすると、1MB以上のペイロードを指定したキャッシュストアへ保存します。
always を true にすると、サイズに関係なくすべてのSQSペイロードをキャッシュストアに保存します。
delete_after_processing はジョブ成功後に保存済みペイロードを削除します（デフォルト true）。
flush_on_clear を true にすると queue:clear 実行時にoverflow用ストアを flush します。通常のキャッシュを消さないため、専用ストアと組み合わせて使ってください。

ジョブクラスの作成

make:job コマンド

make:job Artisanコマンドでジョブクラスのひな型を生成します。

php artisan make:job SendWelcomeEmail

app/Jobs/SendWelcomeEmail.php が生成されます。

ジョブクラスの構造

<?php

namespace App\Jobs;

use App\Models\User;
use App\Mail\WelcomeMail;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Support\Facades\Mail;

class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    /**
     * ジョブのインスタンスを作成する
     */
    public function __construct(
        public User $user,
    ) {}

    /**
     * ジョブを実行する
     */
    public function handle(): void
    {
        Mail::to($this->user->email)->send(new WelcomeMail($this->user));
    }
}

ShouldQueue インターフェースを実装することで、このジョブがキューで非同期処理されることをLaravelに伝えます。 Queueable トレイトがジョブのキュー操作に必要なメソッドを提供します。

コンストラクタにEloquentモデルを渡すと、Laravelは自動的にIDだけをシリアライズします。実行時にデータベースから最新データを再取得するため、キューのペイロードが軽くなります。

ジョブのディスパッチ

dispatch()

コントローラやサービスからジョブをキューに送り出すには dispatch() を使います。

use App\Jobs\SendWelcomeEmail;

// ルートやコントローラの中で
public function register(Request $request): RedirectResponse
{
    $user = User::create($request->validated());

    // ジョブをキューに積む
    SendWelcomeEmail::dispatch($user);

    return redirect('/dashboard');
}

遅延ディスパッチ

delay() メソッドでジョブの実行を指定時間後に遅らせられます。

// 5分後に実行
SendWelcomeEmail::dispatch($user)->delay(now()->addMinutes(5));

dispatchAfterResponse()

dispatchAfterResponse() を使うと、HTTPレスポンスをユーザーに返した直後にジョブを実行します。 sync ドライバでも動作するため、専用のワーカーが不要な軽量な用途に向いています。

SendWelcomeEmail::dispatchAfterResponse($user);

特定のキューへのディスパッチ

SendWelcomeEmail::dispatch($user)->onQueue('emails');

Queue Routing

特定のジョブクラスをデフォルトで決まった接続・キューに振り向けるには、ServiceProviderの boot() で Queue::route() を使います。ジョブクラスごとに onQueue() / onConnection() を書く代わりに一元管理できます。

use App\Concerns\RequiresVideo;
use App\Jobs\ProcessPodcast;
use App\Jobs\ProcessVideo;
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts');
    Queue::route(RequiresVideo::class, queue: 'video');
}

インターフェース・トレイト・親クラスも指定できます。それらを実装・使用・継承するすべてのジョブに自動で適用されます。複数ジョブをまとめてルーティングする場合は配列を渡します。

Queue::route([
    ProcessPodcast::class => ['podcasts', 'redis'], // queue と connection
    ProcessVideo::class => 'videos',                // queue のみ（デフォルト接続を使用）
]);

Queue Routing はジョブ側の onQueue() / onConnection() で上書きできます。

同期実行(テスト・開発用)

dispatchSync() を使うと、キューを経由せずに即時実行します。

SendWelcomeEmail::dispatchSync($user);

バルクディスパッチ

多数の独立したジョブを一度にディスパッチする場合、Bus ファサードの bulk() メソッドを使用できます。バッチ処理のような追跡やコールバックが不要なケースに最適です。 Bus::bulk() は、ジョブを設定されたキュー接続とキュー名でグループ化し、各グループをまとめてキューにプッシュするため効率的です。

use App\Jobs\ProcessUser;
use Illuminate\Support\Facades\Bus;

Bus::bulk(
    $users->map(fn ($user) => new ProcessUser($user))
);

Bus::bulk() はジョブをバッチとしてまとめてキューに送信します。バッチ処理（Bus::batch()）とは異なり、進捗追跡や完了コールバックは提供されません。独立した大量のジョブをシンプルに一括送信したい場合に適しています。

ジョブの処理

queue:work コマンド

キューワーカーを起動してジョブを処理します。

php artisan queue:work

特定のドライバやキューを指定することもできます。

# Redisのemailsキューだけを処理
php artisan queue:work redis --queue=emails

# databaseドライバを使う
php artisan queue:work database

queue:work は起動したまま動き続けます。コードを変更したときは queue:restart でワーカーを再起動してください。本番環境ではSupervisorなどのプロセスマネージャーで管理するのが一般的です。

キューワーカーの監視オプション

よく使うオプションを組み合わせてワーカーを細かく制御できます。

php artisan queue:work --tries=3 --timeout=60 --sleep=3

オプション	説明
`--tries=N`	ジョブの最大試行回数。超えると失敗ジョブとして記録される
`--timeout=N`	ジョブ1件の最大実行秒数。超えるとワーカーを強制終了する
`--sleep=N`	キューが空のときに次のポーリングまで待機する秒数(デフォルト: 3)
`--max-jobs=N`	N件処理したらワーカーを終了する
`--max-time=N`	N秒経過したらワーカーを終了する
`--queue=A,B`	優先順位付きでキューを処理する(Aを優先)

ジョブクラスにリトライ設定を書く

コマンドラインオプションより、ジョブクラス自体に設定を書く方が管理しやすい場合があります。

use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;

#[Tries(3)]
#[Timeout(60)]
class SendWelcomeEmail implements ShouldQueue
{
    use Queueable;

    // ...
}

ジョブのリリース（Release ミドルウェア）

特定の条件を満たすときにジョブを実行せずキューに戻したい場合、Release ミドルウェアを使うと簡潔に書けます。

use Illuminate\Queue\Middleware\Release;

/**
 * ジョブが通過するミドルウェアを返す
 */
public function middleware(): array
{
    return [
        // $condition が true のとき60秒後にリリース
        Release::when($this->order->isPending(), releaseAfter: 60),
    ];
}

Release::unless() は条件が false のときにリリースします。

return [
    // 注文が支払い済みでないとき60秒後にリリース
    Release::unless($this->order->isPaid(), releaseAfter: 60),
];

クロージャを使うと、より複雑な条件を記述できます。

return [
    Release::when(function (): bool {
        return ! $this->order->isPaid();
    }, releaseAfter: 60),
];

ジョブをリリースしてもジョブの試行回数はカウントアップされます。#[Tries] や $tries プロパティを適切に設定してください。

失敗したジョブの処理

failed_jobs テーブルの準備

ジョブが最大試行回数を超えると、failed_jobs テーブルに記録されます。テーブルがない場合は次のコマンドで作成します。

php artisan make:queue-failed-table
php artisan migrate

失敗時のクリーンアップ

ジョブに failed() メソッドを定義すると、失敗したときの後処理を記述できます。

use Throwable;

public function failed(?Throwable $exception): void
{
    // 管理者にSlack通知を送るなど
    // Notification::route('slack', config('app.slack_webhook'))
    //     ->notify(new JobFailedNotification($this, $exception));
}

例外によるリトライ停止

例外の種類によってはリトライさせず即座に失敗させたい場合があります。bootstrap/app.php の withExceptions() 内で dontRetry を使って対象の例外クラスを指定します。

use App\Exceptions\InvalidPodcastSourceException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetry([
        InvalidPodcastSourceException::class,
    ]);
})

より細かい制御が必要な場合は dontRetryWhen にクロージャを渡します。クロージャが true を返すとジョブは即座に失敗としてマークされ、リトライされません。

use App\Exceptions\PodcastProcessingException;
use Illuminate\Foundation\Configuration\Exceptions;

->withExceptions(function (Exceptions $exceptions): void {
    $exceptions->dontRetryWhen(function (PodcastProcessingException $e) {
        return $e->reason() === 'Subscription expired';
    });
})

バリデーションエラーや決済失敗（サブスクリプション期限切れなど）のように、何度リトライしても結果が変わらない例外はこの方法で即座に失敗させると効率的です。

失敗したジョブの一覧確認

php artisan queue:failed

失敗したジョブのリトライ

# 特定のジョブIDを指定してリトライ
php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# すべての失敗ジョブをリトライ
php artisan queue:retry all

失敗したジョブの削除

# 特定のジョブを削除
php artisan queue:forget ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece

# すべての失敗ジョブを削除
php artisan queue:flush

よく使うキュードライバ

database ドライバ

追加のミドルウェアなしに使い始められるシンプルなドライバです。 jobs テーブルにジョブを保存し、ワーカーがポーリングして処理します。

長所: セットアップが簡単、既存のRDBMSをそのまま使える
短所: データベースへの負荷が高いため、大量のジョブには不向き

QUEUE_CONNECTION=database

redis ドライバ

本番環境で最もよく使われる高速なドライバです。インメモリで動作するためデータベースよりもスループットが高く、大量のジョブを処理できます。

長所: 高速、スケーラブル
短所: Redisサーバーの用意が必要

QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

Redisキューを本番運用する場合は Laravel Horizon の導入を検討してください。美しいダッシュボードでジョブの状況をリアルタイムに監視できます。

Supervisorによる本番運用

本番環境では、queue:work プロセスが何らかの理由で停止したときに自動で再起動する仕組みが必要です。 Linux環境では Supervisor を使うのが一般的です。

# /etc/supervisor/conf.d/laravel-worker.conf
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/your-app/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/your-app/storage/logs/worker.log
stopwaitsecs=3600

numprocs=2 で2つのワーカープロセスを並列起動します。設定後に Supervisor を再読み込みします。

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*

実践例: メール送信をキューで処理する

ジョブクラスを作成する

php artisan make:job SendOrderConfirmation

ジョブの処理を実装する

<?php

namespace App\Jobs;

use App\Models\Order;
use App\Mail\OrderConfirmed;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Tries;
use Illuminate\Queue\Attributes\Timeout;
use Illuminate\Support\Facades\Mail;

#[Tries(3)]
#[Timeout(30)]
class SendOrderConfirmation implements ShouldQueue
{
    use Queueable;

    public function __construct(
        public Order $order,
    ) {}

    public function handle(): void
    {
        Mail::to($this->order->user->email)
            ->send(new OrderConfirmed($this->order));
    }
}

コントローラからディスパッチする

use App\Jobs\SendOrderConfirmation;

public function store(Request $request): RedirectResponse
{
    $order = Order::create($request->validated());

    SendOrderConfirmation::dispatch($order);

    return redirect()->route('orders.show', $order)
        ->with('success', '注文を受け付けました。');
}

ワーカーを起動する

php artisan queue:work --tries=3 --timeout=30

まとめ

キューを使うべきタイミング

メール・SMS送信
画像・動画のリサイズや変換
外部APIへのリクエスト
レポートの生成やCSVエクスポート
Webhook の送信

開発時のヒント

.env で QUEUE_CONNECTION=sync にすると、ジョブはキューを経由せず即時実行されます。ワーカーを起動しなくても動作確認できるため、開発中は便利です。

QUEUE_CONNECTION=sync

よく使うコマンドまとめ

# ワーカー起動
php artisan queue:work

# ワーカー再起動(デプロイ後)
php artisan queue:restart

# 失敗ジョブ一覧
php artisan queue:failed

# 失敗ジョブをすべてリトライ
php artisan queue:retry all

# 失敗ジョブをすべて削除
php artisan queue:flush

​キューとは

​キューの設定

​config/queue.php

​.env の設定

​データベースドライバの準備

​Redisドライバの準備

​SQS Overflow Storage

​ジョブクラスの作成

​make:job コマンド

​ジョブクラスの構造

​ジョブのディスパッチ

​dispatch()

​遅延ディスパッチ

​dispatchAfterResponse()

​特定のキューへのディスパッチ

​Queue Routing

​同期実行(テスト・開発用)

​バルクディスパッチ

​ジョブの処理

​queue:work コマンド

​キューワーカーの監視オプション

​ジョブクラスにリトライ設定を書く

​ジョブのリリース（Release ミドルウェア）

​失敗したジョブの処理

​failed_jobs テーブルの準備

​失敗時のクリーンアップ

​例外によるリトライ停止

​失敗したジョブの一覧確認

​失敗したジョブのリトライ

​失敗したジョブの削除

​よく使うキュードライバ

​database ドライバ

​redis ドライバ

​Supervisorによる本番運用

​実践例: メール送信をキューで処理する

​まとめ

キューとは

キューの設定

config/queue.php

.env の設定

データベースドライバの準備

Redisドライバの準備

SQS Overflow Storage

ジョブクラスの作成

make:job コマンド

ジョブクラスの構造

ジョブのディスパッチ

dispatch()

遅延ディスパッチ

dispatchAfterResponse()

特定のキューへのディスパッチ

Queue Routing

同期実行(テスト・開発用)

バルクディスパッチ

ジョブの処理

queue:work コマンド

キューワーカーの監視オプション

ジョブクラスにリトライ設定を書く

ジョブのリリース（Release ミドルウェア）

失敗したジョブの処理

failed_jobs テーブルの準備

失敗時のクリーンアップ

例外によるリトライ停止

失敗したジョブの一覧確認

失敗したジョブのリトライ

失敗したジョブの削除

よく使うキュードライバ

database ドライバ

redis ドライバ

Supervisorによる本番運用

実践例: メール送信をキューで処理する

まとめ