queue:restart — キューの再起動を行うコマンド

php artisan queue:restart は、現在稼働中のキューワーカー（queue:work・queue:listen）に対し、「現在のジョブが終わったら自動的に再起動する」 という指示を与える Artisan コマンドです。
実際にはキャッシュにタイムスタンプを格納し、ワーカーはその値を監視して再起動を検知します。

使い方
実装の裏側
実務例
よくある落とし穴
関連API・コマンド
Pest テスト例
参考リンク
関連記事

使い方

php artisan queue:restart

ポイント

コマンドは引数やフラグを受け取らない

ワーカー自体は停止のみを指示し、再起動は Supervisor などのプロセスマネージャに委ねられる

実装の裏側

項目	内容
キャッシュキー	`laravel_queue_last_restart`（デフォルト）
値	`Carbon::now()->timestamp`（整数）
ワーカー挙動	`queue:work`・`queue:listen` は実行中にキーを確認し、更新されていれば「次のジョブへ進む前に停止」
再起動	Supervisor 等でワーカーが停止すると自動で再起動するように設定する必要がある

実務例

# ① コードデプロイ
git pull origin main
composer install --no-dev --optimize-autoloader
php artisan migrate --force

# ② キューワーカー再起動
php artisan queue:restart

Supervisor 設定例（/etc/supervisor/conf.d/laravel-worker.conf）

[program:laravel-worker]
command=php /var/www/html/artisan queue:work --sleep=3 --tries=3
process_name=%(program_name)s_%(process_num)02d
numprocs=4
autostart=true
autorestart=true
stopasgroup=true

queue:restart を実行すると、ワーカーは現在のジョブを完了した後に停止し、Supervisor が自動で再起動します。

よくある落とし穴

問題	原因	対策
ワーカーが再起動しない	Supervisor の `autorestart` が無効	`autorestart=true` を設定
タイムスタンプが競合	複数環境で同一キャッシュドライバーを共有	キー名を環境別に設定
ジョブが長時間走っている	`queue:restart` はジョブ完了後に停止	`--timeout` オプションでタイムアウトを調整
Redis クラスタを使用	キーが一貫して更新されない	Redis Cluster 用にスレッドセーフな設定を行う

コマンド	用途
`php artisan queue:work`	ワーカーを手動起動
`php artisan queue:listen`	1つのプロセスで継続的にジョブを取得
`php artisan queue:flush`	キューを全削除
`Cache::forget('laravel_queue_last_restart')`	タイムスタンプを手動で削除
`Queue::stop()`	ワーカーを即時停止

Pest テスト例

<?php

use Illuminate\Support\Facades\Cache;
use Tests\TestCase;

uses(TestCase::class);

it('queue:restart updates the restart timestamp in cache', function () {
    // 初期状態ではキーは存在しない
    expect(Cache::has('laravel_queue_last_restart'))->toBeFalse();

    // コマンド実行
    $this->artisan('queue:restart');

    // キーが設定され、整数が格納されていることを確認
    expect(Cache::has('laravel_queue_last_restart'))->toBeTrue();
    expect(Cache::get('laravel_queue_last_restart'))->toBeInt();
});

使い方

実装の裏側

実務例

よくある落とし穴

関連API・コマンド

Pest テスト例

参考リンク

関連記事