--- title: "Laravel Debugbarの使い方｜導入・APP_DEBUG設定・SQL確認とv4改称対応" url: "https://www.issoh.co.jp/tech/details/4473/" published: 2024-12-11 updated: 2026-08-07 categories: ["Laravel"] publisher: "株式会社一創" --- # 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` には、実際の挙動を左右する値が並んでいます。 | キー | 既定値 | 意味 | | ------------------- | ----- | -------------------------- | | soft\_limit | 100 | 超過後はパラメータと呼び出し元を取得しない | | hard\_limit | 500 | 超過後はクエリ自体を記録しない | | only\_slow\_queries | true | slow\_thresholdを超えたクエリだけ記録 | | slow\_threshold | false | しきい値（ミリ秒）。falseは未設定 | | with\_params | true | 値を埋めたSQLで表示 | | backtrace | true | クエリの呼び出し元を付与 | | explain | true | EXPLAIN実行を許可 | | timeline | false | クエリをタイムラインへ表示 | | show\_query\_result | false | SELECTの再実行と結果表示 | `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の全体像と導入判断の前提知識](/tech/details/11482/)と併せて追うと、どのタブに何が出るかを把握しやすくなります。 ## 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とは何か？その機能と重要性を徹底解説](/tech/details/3386/)で扱うTelescopeは、リクエスト外の処理を時系列で溜めて後から検索できるため、非同期処理の常時監視はこちらに寄せた方が早く終わります。両方入れる場合でも、Debugbarの `except` に `telescope*` が既定で入っているので画面の干渉は起きません。 変数の値を1行ずつ確かめたい、条件分岐のどちらへ入ったか見たい、という段階まで降りるとDebugbarでは足りません。ブレークポイントを置いて実行を止められる[Xdebugとは？PHPデバッグの使い方・インストール・php.ini設定・VSCode連携を解説](/tech/details/7515/)のステップ実行が必要になります。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連携を解説](/tech/details/7515/) - [Laravel Telescopeとは何か？その機能と重要性を徹底解説](/tech/details/3386/) - [Laravel 13で正式安定版になったAI SDKの全体像と導入判断の前提知識](/tech/details/11482/) --- 出典: [Laravel Debugbarの使い方｜導入・APP\_DEBUG設定・SQL確認とv4改称対応]()（株式会社一創）