Tech Starlog

Laravel Artisan Commandでプログレスバーを使う方法

投稿日：2026/01/20

LaravelのArtisan Commandでは、CLI上で処理の進捗を可視化できるプログレスバー機能が標準で用意されています。

大量データを扱うバッチ処理では、

  • 処理が止まっていないか確認したい
  • どれくらいで終わるのか目安を知りたい
  • 実行中の不安を減らしたい

といったニーズがあり、プログレスバーは非常に有効です。

本記事では、Laravelでのプログレスバーの基本的な使い方から、実務での活用ポイントまでを解説します。

プログレスバーとは？

プログレスバーとは、処理の進捗状況をバー形式で表示するUIです。

CLIでは次のように表示されます。

  0/120 [>---------------------------]   0%
 45/120 [==========>-----------------]  37%
 89/120 [===================>--------]  74%
120/120 [============================] 100%

処理件数・進捗率・完了状況をリアルタイムで確認できます。

基本的な使い方

サンプルシナリオ

「Sampleテーブルのレコードを1件ずつ処理するバッチ」を例にします。

サンプルコード

use App\Models\Sample;

public function handle(): int
{
    $total = Sample::count();
    $samples = Sample::cursor(); // メモリ消費を抑える

    $this->output->progressStart($total);

    foreach ($samples as $sample) {
        // 実際の処理
        $this->process($sample);

        $this->output->progressAdvance();
    }

    $this->output->progressFinish();

    return Command::SUCCESS;
}

表示イメージ

  0/500 [>---------------------------]   0%
120/500 [=======>--------------------]  24%
300/500 [================>-----------]  60%
500/500 [============================] 100%

総件数が分からない場合

APIストリームや逐次処理など、事前に件数が取得できない場合もあります。

その場合は、件数を指定せずに開始できます。

$this->output->progressStart();

foreach ($items as $item) {
    $this->process($item);
    $this->output->progressAdvance();
}

$this->output->progressFinish();

この場合は、進捗率は表示されず、カウンタのみ表示されます。

ログと併用する設計

プログレスバーはターミナル表示専用であり、ログファイルには残りません。

そのため、本番運用ではログと併用する設計が重要です。

サンプルコード

use Illuminate\Support\Facades\Log;

Log::info('バッチ処理開始');

$total = Sample::count();
$this->output->progressStart($total);

foreach (Sample::cursor() as $sample) {
    $this->process($sample);
    $this->output->progressAdvance();
}

$this->output->progressFinish();

Log::info('バッチ処理完了', [
    'total' => $total,
]);

出力されるログ例

[2026-01-17 02:00:01] production.INFO: バッチ処理開始  
[2026-01-17 02:05:12] production.INFO: バッチ処理完了  
{"total":500}

チャンク処理と組み合わせる

大量データを一括取得すると、メモリ不足の原因になります。

その場合は、chunk() と組み合わせます。

サンプルコード

$total = Sample::count();
$this->output->progressStart($total);

Sample::chunk(100, function ($samples) {
    foreach ($samples as $sample) {
        $this->process($sample);
        $this->output->progressAdvance();
    }
});

$this->output->progressFinish();

よくある注意点

✅ cron実行では表示されない

cronから実行した場合、プログレスバーは表示されません。

  • 手動実行 → プログレスバー
  • 自動実行 → ログ

と役割を分けましょう。

✅ 高速処理では一瞬で終わる

処理が軽い場合、バーが一瞬で100%になります。 無理に表示する必要はありません。

✅ トランザクションとの相性

1トランザクションで大量更新すると、進捗が見えません。

進捗表示したい場合は、

  • レコード単位処理
  • チャンク分割処理

を検討します。

✅ 例外発生時の終了処理

例外発生時に progressFinish() が呼ばれないと、表示が崩れることがあります。

try {
    // 処理
} finally {
    $this->output->progressFinish();
}

実務でのおすすめ設計

シーン おすすめ
開発・手動実行 プログレスバー表示
本番・自動実行 ログ中心
大量データ chunk / cursor 使用
長時間処理 開始・終了ログ必須

まとめ

  • プログレスバーはCLI処理の進捗可視化に非常に有効
  • progressStart / Advance / Finish の3点セットで使う
  • ログと併用して運用設計する
  • 大量データではメモリ対策を忘れない
⬅️ 記事一覧へ戻る