Laravel Debugbarの使い方｜導入・APP_DEBUG設定・SQL確認とv4改称対応

Laravel Debugbarは、画面下部のバーにSQLクエリ・実行時間・ビュー・ログをまとめて表示する開発用パッケージです。2026年1月23日のv4.0.0でパッケージ名が fruitcake/laravel-debugbar へ、名前空間が Fruitcake\LaravelDebugbar へ変わったため、以前の手順書のまま vendor:publish を実行しても設定ファイルは発行されません（該当プロバイダが見つからず、何も出力されずに終わります）。導入から表示条件の切り分け、SQLの読み方までを最新版v4.4.1の実装に沿ってまとめます。

まとめ

• 最新はv4.4.1（Packagist公開は2026年8月3日）。PHP 8.2以上、Laravel 11・12・13が対象で、Laravel 10以前はv3.16.5系を使う
• インストールは composer require fruitcake/laravel-debugbar --dev。旧名の barryvdh/laravel-debugbar でも同じv4.4.1が入る
• 設定ファイルの発行は --provider='Fruitcake\LaravelDebugbar\ServiceProvider'。v3の Barryvdh\Debugbar\ServiceProvider クラスはv4のパッケージに存在しない
• 表示条件は「APP_DEBUG=true かつ APP_ENV が production・testing 以外」で、例外は force_allow_enable のみ。DEBUGBAR_ENABLED=true を書いてもこの条件は覆らない
• クエリは既定で500件までしか記録しない。100件を超えると呼び出し元とパラメータの取得が止まる
• JSONレスポンスやリダイレクトでバーが出ない場面は、v4で新設された php artisan debugbar:find 系のコマンドで保存済みの記録を読む

v3時代の手順書との差分は、パッケージ名・名前空間・グローバルヘルパーの3点に集約されます。以下、導入手順から順に見ていきます。

Debugbarで確認できる情報と動作要件

Debugbarはリクエストごとに各コレクタがデータを集め、レスポンスのHTMLへバーを差し込みます。v4系の config/debugbar.php における collectors の既定は次のとおりです。

• 既定で有効（19種）：db / views / messages / time / memory / exceptions / log / gate / cache / models / mail / laravel / symfony_request / livewire / inertia / jobs / pennant / http_client / ai
• 既定で無効（7種）：session / route / auth / events / logs / config / phpinfo

セッションの中身やルート情報は既定では出ません。旧バージョンの解説記事に沿って「Sessionタブが見当たらない」と悩む場合は、DEBUGBAR_COLLECTORS_SESSION=true を .env に足すか、設定ファイルの該当行を true にします。

動作要件はv4.4.1でPHP 8.2以上、illuminate/support は ^11|^12|^13.0 です。Laravel 11のリリースが2024年3月12日、12が2025年2月24日、13が2026年3月17日なので、それ以前のLaravel 10で運用しているプロジェクトはv4に上げられません。その場合は2026年1月23日に出たv3.16.5（PHP 8.1以上、Laravel 10・11・12対応）が最終版になります。

インストールとパッケージ名の変更への対応

–dev付きcomposer requireとvendor:publish

開発環境限定で入れるため --dev を付けます。パッケージ検出が働くのでサービスプロバイダの手動登録は不要です。

composer require fruitcake/laravel-debugbar --dev
php artisan vendor:publish --provider='Fruitcake\LaravelDebugbar\ServiceProvider'

2行目で config/debugbar.php が作られます。設定を変えないなら発行しなくても動きますが、コレクタの取捨選択やクエリ収集の上限を触るなら先に出しておいた方が早いです。Octaneを使っている場合、v4は追加設定なしで動作します（v3から移行するときは config/octane.php のflush設定からDebugbarの記述を消します）。

v4.0.0改称の影響範囲

v4.0.0で配布名が barryvdh/laravel-debugbar から fruitcake/laravel-debugbar へ変わりました。とはいえ旧名がすぐ使えなくなるわけではありません。v4.4.1のcomposer.jsonには "replace": {"barryvdh/laravel-debugbar": "self.version"} が入っており、旧名のまま composer require してもv4.4.1が入ります。2026年8月7日時点の月間ダウンロードは旧名が約306万件、新名が約66万件で、名前を変えていないプロジェクトでも中身はv4に上がっている可能性があります。公式が案内する移行手順は次のとおりです。

composer remove barryvdh/laravel-debugbar --dev --no-scripts
composer require fruitcake/laravel-debugbar --dev

名前空間 Barryvdh\Debugbar のクラスはv4のパッケージに1つも残っていません。ただし公式UPGRADE.mdは「サービスプロバイダやファサードを手動登録している場合を除き、通常は変更不要」と明記しており、影響が出るのはクラス名を直接書いている箇所に限られます。UPGRADE.mdの非互換のうち、一般的なアプリケーションで踏みやすいのは次の5点です。

• 名前空間が Fruitcake\LaravelDebugbar へ変更（vendor:publish のprovider指定もこれに追随）
• start_measure() stop_measure() add_measure() measure() のグローバルヘルパーを削除。debugbar()->startMeasure() 形式へ
• SocketStorage・Lumen対応・FileCollectorを削除
• クエリ表示の bindings パラメータが params へ、設定の hiddens が masked へ（masked はキー名で指定し、配列パスは使わない）
• Inertiaが専用コレクタと専用設定に分離

このほか、依存が php-debugbar 3.x へ上がってjQueryとFont Awesomeが外れています。カスタムコレクタを自作している場合だけ確認してください。ファサードの Debugbar エイリアスはv4でも自動登録されるため、\Debugbar::info() のような呼び出し方をしているコードは変更不要です。

Debugbarが表示されないときの確認順序

APP_DEBUGとAPP_ENVで決まる有効化条件

表示可否は LaravelDebugbar::canBeEnabled() が判定します。設定の force_allow_enable がtrueなら無条件に許可、そうでなければ hasDebugModeEnabled() && !environment('testing', 'production') という条件で、APP_DEBUG がtrueであることと APP_ENV が production・testing のどちらでもないことの両方を満たす必要があります。

APP_ENV=local
APP_DEBUG=true
DEBUGBAR_ENABLED=true

見落としやすいのが DEBUGBAR_ENABLED の位置づけです。この値が効くのは上の条件を通過した後で、APP_ENV=production のまま DEBUGBAR_ENABLED=true を書いてもバーは出ません。本番同等の環境で意図的に動かしたい場合だけ force_allow_enable をtrueにして条件を迂回します。認証で保護された管理画面などに限った例外措置で、公開エンドポイントで使う設定ではありません。

2つの条件を満たしてもバーが出ないときの確認順序は次のとおりです。.env を書き換えた直後なら php artisan config:clear（設定キャッシュを作っている場合は config:cache の再実行）。レスポンスがJSONやリダイレクトなら、そもそもHTMLへ差し込めないので後述のコマンドで記録を読みます。Livewireやajaxのリクエストは capture_ajax が既定で有効なため、バー右上のドロップダウンに履歴として溜まります。

除外パスと一時無効化の使い分け

常時は不要でも管理ツールの画面だけ邪魔になる、というときは except にパスを足します。既定でTelescopeとHorizonの画面は除外済みです。

'except' => [
    'telescope*',
    'horizon*',
    'api/*',
],

丸ごと止めるなら .env に DEBUGBAR_ENABLED=false。HTMLへの差し込みだけを止めて記録は残したい場合は DEBUGBAR_INJECT=false を使います。パフォーマンス測定の最中にDebugbar自身のオーバーヘッドを外したいときは、差し込み停止ではなく DEBUGBAR_ENABLED=false で収集ごと止めるのが確実です。

SQLクエリの確認とN+1の切り分け

Queriesタブで見る3つの箇所

Queriesタブには実行されたSQL・実行時間・呼び出し元ファイルが並びます。N+1を疑うときに見るのは、同じ形のSQLが連続していないか、1本あたりの時間が突出していないか、呼び出し元が意図した場所かの3点です。重複クエリ群の機械的な検出は、後述の debugbar:find --issues が担当します。

既定で with_params が有効なため、プレースホルダに値を埋めた形でSQLが表示されます。そのままコピーしてDBクライアントへ貼れる状態です。backtrace も既定で有効で、各クエリの発行箇所（vendor配下を除いたアプリ側のファイル）が付きます。Eloquentのどのリレーション読み込みが原因かを追うときはここが起点になります。

加えて explain が既定でtrueになっており、記録ストレージが開いている状態であればバー上からEXPLAINの結果を確認できます。ストレージが閉じているとEXPLAINのリクエストはHTTP 400で弾かれ、「set debugbar.storage.open to true in your config」という趣旨のメッセージが返ります。ボタンが反応しないように見えたら後述の storage.open を確認してください。

収集件数の上限と既定値の実像

設定ファイルの options.db には、実際の挙動を左右する値が並んでいます。

only_slow_queries が既定でtrueなので「遅いクエリしか出ない」と読めますが、実際は違います。収集判定は !$onlyThreshold || !$threshold || $query->time > $threshold という式で、slow_threshold がfalse（未設定）の間は全クエリが記録されます。絞り込みが働き始めるのは、しきい値をミリ秒で入れた時点です。

'db' => [
    'only_slow_queries' => true,
    'slow_threshold' => 100,
    'soft_limit' => 100,
    'hard_limit' => 500,
],

この設定なら100ミリ秒を超えたクエリだけが残ります。逆に、管理画面の一覧など1リクエストで数百本のクエリが飛ぶ画面では、100本目以降は呼び出し元が付かず、500本目以降は記録すらされません。Queriesタブの件数が実際より少ないと感じたら、まずこの2つの上限を疑ってください。

Debugbarを介さずSQLを取り出す方法

バッチ処理やテストなど、バーが出ない場所でSQLだけ見たい場面もあります。Laravel 10.15以降のクエリビルダには、プレースホルダのままの toSql() と、値を埋め込んだ toRawSql() の両方があります。

use App\Models\User;
use Illuminate\Support\Facades\DB;

$sql = User::where('active', 1)->toSql();     // select * from `users` where `active` = ?
$raw = User::where('active', 1)->toRawSql();  // 値を埋めた SQL

DB::listen(function ($query) {
    logger()->debug($query->toRawSql(), ['time_ms' => $query->time]);
});

DB::listen() に渡されるイベントオブジェクトの toRawSql() はLaravel 11.17以降で使えます。それ以前のバージョンでは $query->sql と $query->bindings を自分で組み立ててください。実行時間 time（ミリ秒）と併せてログへ落とせるので、画面を持たないコンソールコマンドの調査ではこちらが確実です。すぐ捨てる調査なら dumpRawSql() と ddRawSql() でその場に出力する手もあります。

メッセージ出力と処理時間の計測

Debugbarファサードによるメッセージ送信

ファサードはPSR-3のログレベル（debug・info・notice・warning・error・critical・alert・emergency）に対応しています。ラベルを自分で付けたい場合は addMessage() を使います。

\Debugbar::info($user);
\Debugbar::error('決済APIの応答が空でした');
\Debugbar::addMessage($payload, 'payment');
\Debugbar::addThrowable($e);

debug($request->all());

グローバル関数の debug() は引数をそのままMessagesコレクタへ送るヘルパーで、dd() と違って処理を止めません。画面遷移を止めずに値を追いたいときに使い分けます。メッセージには既定で発生元のトレースが付き（options.messages.trace がtrue）、どのファイルの何行目から送ったかがバー側に出ます。

startMeasureによる区間計測

Timelineタブはブート時間とアプリケーション時間を自動で表示しますが、任意の区間を足せます。v4でグローバルヘルパーが削除されたため、debugbar() 経由での呼び出しに書き換えます。

debugbar()->startMeasure('import', 'CSV取り込み');
$service->import($file);
debugbar()->stopMeasure('import');

debugbar()->measure('集計処理', function () use ($service) {
    return $service->aggregate();
});

v3のコードで start_measure('import') と書いていた箇所は、v4では未定義関数エラーになります。移行時にまとめて置換してください。クエリをタイムライン上に並べて全体の内訳を見たい場合は、options.db.timeline（既定false）をtrueにします。

例外・セッション・リクエストの確認

失敗クエリを含む例外の表示

Exceptionsコレクタは既定で有効で、捕捉されなかった例外に加え、\Debugbar::addThrowable($e) で明示的に送った例外もタブに並びます。try-catchで握りつぶしている箇所の中身を、レスポンスを壊さずに確認したいときに使います。クエリ例外には専用の経路があり、QueryCollector::addFailedQuery() によってQueriesタブ側へ失敗クエリとして積まれ、集計値 nb_failed_statements に反映されます。ビュー内で発生したクエリ例外も、元の例外にさかのぼって同じ扱いになります。

セッションと設定値の確認

Sessionコレクタは既定で無効です。DEBUGBAR_COLLECTORS_SESSION=true で有効化すると、そのリクエスト時点のセッションの中身が一覧表示されます。ログイン状態やフラッシュメッセージの受け渡しを追う用途です。トークンなど見せたくないキーがあれば options.session.masked にキー名を並べます（v3の hiddens は廃止され、配列パスではなくキー名で指定します）。同様に config コレクタも既定で無効で、有効化すると設定値の一覧が読めます。

リクエストとレスポンスの内容

Requestタブは symfony_request コレクタが担当し、既定で有効です。ヘッダー・クエリ文字列・POSTデータ・レスポンスのステータスとヘッダーがまとまって見えます。マスクしたいキーは options.symfony_request.masked に指定します。

SSEやStreamedResponseなどのストリーミング応答は、Debugbarの識別子を返すレスポンスヘッダーを失うため通常は追跡できません。v4.4.0（2026年7月4日）で追加された DEBUGBAR_CAPTURE_STREAMED=true は、同一オリジンのfetch/XHRにリクエストIDを付け、記録ストレージ側からデータセットを引き当てる仕組みです（ストレージとopenハンドラの有効化が前提。対象は既定で text/event-stream のみ）。同じv4.4.0では laravel/ai を導入している場合のAIタブも既定で有効になりました。生成AI関連の実装調査はLaravel 13で正式安定版になったAI SDKの全体像と導入判断の前提知識と併せて追うと、どのタブに何が出るかを把握しやすくなります。

artisan debugbar系コマンドによる記録参照

Debugbarは各リクエストの収集結果を storage/debugbar 配下へ保存しています（storage.enabled が既定true）。この保存済みデータをCLIから読むコマンドはv3では debugbar:clear だけでしたが、v4で3本が新設されて計4本になりました。バーが表示できないAPIレスポンスやリダイレクト後の調査で効く部分で、ブラウザ画面を前提とした競合記事ではまず触れられていません。

debugbar:find –issuesでの問題リクエスト抽出

php artisan debugbar:find --issues
php artisan debugbar:find --uri='/admin/*' --method=POST --max=50

--issues を付けると、クエリ50本以上・実行1000ミリ秒超・重複クエリ群2組以上のいずれかに該当するリクエストだけが残ります（しきい値は --min-queries --min-duration --min-duplicates で変更可）。URIパターン・HTTPメソッド・IPでの絞り込みも同じコマンドで指定します。

debugbar:queriesとdebugbar:getでのデータ取得

php artisan debugbar:queries latest
php artisan debugbar:queries latest --statement=3 --explain
php artisan debugbar:get latest --collector=queries --raw
php artisan debugbar:clear

IDの代わりに latest と書けば直近のリクエストが対象になります。debugbar:queries は指定リクエストのSQL一覧を出し、--statement で選んだ1本に対して --explain でEXPLAIN、--result で再実行と結果表示ができます。debugbar:get はコレクタ単位の生データ取得用で、CI上のログや別ツールへ流すなら --raw でJSONのまま受け取れます。溜まった記録は debugbar:clear で消します。

キューワーカーの処理も記録できます。DEBUGBAR_COLLECT_JOBS=true（既定false）にすると JobProcessing で収集が始まり、保存されたリクエストは JOB というメソッド名と「ジョブ名@接続名」のURIで一覧に並びます。一方、素のartisanコマンドは isEnabled() が runningInConsole() を除外するため収集されません。コンソールコマンドの調査は前述の DB::listen() やログ出力で行います。

公開環境に出さないための設定

公式READMEは「公開サイトでDebugbarを使わないこと」を明示しています。理由は設計上、保存済みリクエストの内容が読める点にあります。特に注意すべきが storage.open です。trueにすると誰でも過去のリクエスト記録へアクセスできます。未設定（null）のままでも「localhostだけ」ではなく、クライアントIPがプライベートIP（127.0.0.1のほか10系・172.16〜31系・192.168系）であれば開く実装（IpUtils::isPrivateIp() 判定）なので、Dockerやリバースプロキシ経由でクライアントIPがプライベート帯に見える構成では開いたままになります。公開環境では明示的にfalseを入れてください。

'storage' => [
    'enabled' => true,
    'open' => env('DEBUGBAR_OPEN_STORAGE', false),
],

'force_allow_enable' => false,

本番で APP_DEBUG=true のままにしないことは、Debugbar以前にLaravel本体の運用として必須です。デバッグモードが有効なままだと、例外画面に環境変数や接続情報が出ます。ステージング環境をproduction相当の APP_ENV で動かしているなら、Debugbarは force_allow_enable を触らない限り自動的に無効になるので、この既定に乗るのが最も事故が少ない構成です。composer require の --dev 指定と、本番デプロイでの composer install --no-dev を組み合わせれば、そもそも本番へ配布されません。

TelescopeやXdebugとの使い分け

3つとも「開発時に中身を見る」道具ですが、見える範囲と持続時間が違います。Debugbarは今開いているページ1リクエストの内訳を即座に見る用途に最も適していて、ここでTelescopeを選ぶ理由はほとんどありません。バーがその場に出る速さが価値だからです。

一方、スケジューラやメール送信など画面を持たない処理を横断的に追うならDebugbarは向きません。Laravel Telescopeとは何か？その機能と重要性を徹底解説で扱うTelescopeは、リクエスト外の処理を時系列で溜めて後から検索できるため、非同期処理の常時監視はこちらに寄せた方が早く終わります。両方入れる場合でも、Debugbarの except に telescope* が既定で入っているので画面の干渉は起きません。

変数の値を1行ずつ確かめたい、条件分岐のどちらへ入ったか見たい、という段階まで降りるとDebugbarでは足りません。ブレークポイントを置いて実行を止められるXdebugとは？PHPデバッグの使い方・インストール・php.ini設定・VSCode連携を解説のステップ実行が必要になります。Debugbarで「どのSQLが遅いか」まで絞り、原因コードの内部ロジックはXdebugで追う、という分担が現実的です。

よくある質問

Laravel Debugbarが表示されないときは何を見ればよいですか？

APP_DEBUG=true と APP_ENV が production・testing 以外であることをまず確認します。この2つは DEBUGBAR_ENABLED より優先され、片方でも外れているとバーは出ません。.env を直したのに変わらない場合は設定キャッシュが残っているので、php artisan config:clear を実行します。それでも出ないときはレスポンスがHTMLかどうか、except に該当パスが入っていないかを順に見ます。

Debugbarを一時的に無効化するにはどうしますか？

.env に DEBUGBAR_ENABLED=false を追加して設定キャッシュを作り直します。特定のURLだけ止めたい場合は config/debugbar.php の except にパスパターンを足します。表示だけ止めて記録は残すなら DEBUGBAR_INJECT=false です。

Debugbarでデバッグログはどこに表示されますか？

アプリケーションが出力したログは log コレクタ（既定で有効）がMonolog経由で拾い、Messagesタブに統合して表示します。storage/logs/laravel.log の末尾そのものを見たい場合は別のコレクタで、DEBUGBAR_COLLECTORS_LOGS=true にすると logs コレクタが有効になります。名前が似ていますが役割が違うので、「ログが出ない」ときはどちらを期待しているかを先に切り分けてください。

barryvdh/laravel-debugbarとfruitcake/laravel-debugbarはどちらを使いますか？

新規は fruitcake/laravel-debugbar です。旧名にはcomposer.jsonの replace 指定があるため現時点ではv4.4.1が入りますが、公式は旧名を削除してから新名でインストールする手順を案内しています。既存プロジェクトも、名前空間を直接参照している箇所がある場合は移行時に合わせて置き換えてください。

キューやコンソールコマンドの処理もDebugbarで追えますか？

キューは DEBUGBAR_COLLECT_JOBS=true で収集でき、debugbar:find に JOB として並びます。素のartisanコマンドはコンソール実行時に無効化されるため収集されません。こちらは DB::listen() やログ出力で確認します。

Laravel 10以前のプロジェクトでも使えますか？

v4系はPHP 8.2以上・Laravel 11以上が要件のため使えません。Laravel 10では barryvdh/laravel-debugbar のv3.16.5（2026年1月23日リリース、PHP 8.1以上）が最終版です。この場合は名前空間も従来の Barryvdh\Debugbar のままで、vendor:publish のprovider指定も旧来の文字列を使います。

関連記事

• Xdebugとは？PHPデバッグの使い方・インストール・php.ini設定・VSCode連携を解説
• Laravel Telescopeとは何か？その機能と重要性を徹底解説
• Laravel 13で正式安定版になったAI SDKの全体像と導入判断の前提知識