Zenn
🐞

Xdebug導入後の使い方ガイド

に公開
Laravel
VS Code
Xdebug
tech

はじめに

Xdebugをインストールしてみたものの、どう活用したいいのかと悩んだことはありませんか？
PHPの開発でバグに遭遇したとき、dd() や log::info() に頼ることも多いと思いますが、データの流れが複雑になってくると、解決できない場面も増えてきます。

本記事では、（Xdebugのインストールや設定ではなく、）利用していくイメージをするために実際に活用したいシーンを紹介します。Laravelアプリケーションで実際に起きたトラブルをもとに、Xdebugの活用がどのように問題解決につながるかを掘り下げていきます。

対象者

  • dd() や log::info() 以外のデバッグ方法を知りたいエンジニア
  • Xdebugをインストールしたものの使うイメージが湧かない方
  • Xdebugの活用パターンを知りたい方

なぜXdebugなのか？

Laravelのようなフレームワークでは、リクエストからレスポンスまでの処理が複雑化しており、データがどこで失われたのかを突き止めるのが難しいケースがあります。

Xdebugを使えば、以下のようなデバッグが可能になります。

  • 実行ステップを1行ずつ確認
  • 各変数のリアルタイムな中身をウォッチ
  • ブレークポイントで任意の場所で処理を止められる
  • プログラムの呼び出し状況を取得し（Backtrace）で流れを把握

VScode上でのXdebugの特徴

項目 内容
表示方法 変数一覧・コールスタック・関数呼び出しなどを視覚的に確認
タイミング 任意の位置で一時停止（ブレークポイント）
見える範囲 今いる関数の中だけでなく、1つ前の関数の引数やグローバル変数まで見える
操作性 ステップ実行で、処理の流れを1行ずつトレースできる
主な用途 原因特定が難しいロジックミス、条件分岐、値の流れの追跡など

ブレークポイントとは

ブレークポイントとは、プログラムの処理を一時停止させる場所のことです。これにより、その時点での変数の状態や処理の流れを確認することができます。

VSCodeでは、行番号の左横をクリックするだけで●がつけれます。これがブレークポイントの設定となります。

    // 例: コントローラー
    public function store(Request $request) {
       
●     $validated = $request->validate([...]); // ここで一時停止できる

一時停止すると、以下のような情報がGUIで表示されます。

特に有用な VSCode のパネル

パネル 内容 デバッグにどう効くか
Variables その行で定義されている変数すべて $requestの全データが見える
Watch 任意の変数を常時表示 $user->email だけ見たいときに便利
Call Stack 呼び出し順が全部出る どのコントローラー→サービス→モデルかが可視化
Breakpoints すべてのブレークポイント一覧 追跡対象をオン/オフで瞬時に切り替え

Xdebugの強みが活きるポイント

Webアプリケーション開発を進めていると、様々なバグに直面します。
Xdebugを使うとdd() や log::info() では見えなかった挙動が見えるようになり、バグ修正が“圧倒的に楽”になる場面が増えます。

例えば、簡単に言うと、こんな使い方ができます。

  1. ルート → コントローラー → サービス → モデルの各関数にブレークポイント
  2. フォーム送信すると、最初にヒットしたブレークポイントで処理が停止
  3. その時点で、変数の中身・ルートの流れ・呼び出し元がすべてGUIでわかる

よくあるバグとXdebugを用いたバグ解消の具体例

さらに具体的にXdebugの活用がどのように問題解決につながるかを掘り下げます。

例：フォーム送信がどこで止まっているか調査する手順

Laravelアプリでフォーム送信が「反応なし」「保存されない」とき、Xdebugを使えば次のように追跡できます。

手順1：ブレークポイントを設定

// web.php
Route::post('/user/store', [UserController::class, 'store']);

// UserController.php
public function store(Request $request) {
    // ブレークポイント①
    $validated = $request->validate([...]);

    // ブレークポイント②
    User::create($validated);

    return redirect('/thanks');
}

手順2：フォームを送信

VSCodeでデバッグ実行し、フォームを送信すると、処理が最初に到達したブレークポイントで停止します。

手順3：デバッグパネルで確認

  • Variables : $requestや$validatedの中身を確認
  • Call Stack : どの経路でこの関数が呼ばれたか追跡
  • Watch : 特定の値（$request->emailなど）を常時監視

この場合のよくある「止まりポイント」

症状 ブレークポイントの反応 原因
全く止まらない コントローラーに到達しない ルート未定義、method違い、CSRFミスなど
store()の前で止まる validateで例外 バリデーションエラー表示漏れ
create前で止まる $validatedにnull リクエストデータが想定と違う

補足：Xdebugが向かないシーン

dd()やdump()の方が早いケース

Xdebugは強力ですが、以下のような場合には、dd()やdump()の方が早いです。

  • LaravelのBladeテンプレートでエラーが出たとき
  • 配列やオブジェクトの全体像だけを一時的に見たいとき

Xdebugは、「ロジックの流れ・条件判定の原因」を見る時に有効ですが、
dd()は、「その値さえわかればOK」なときに便利です。

log::info() + tail -fと使用すべきケース

次のような場面では、log::info() + tail -fの組み合わせの方が有効です。

  • 非同期処理（JobやQueue）
  • 本番環境での調査（Xdebug非対応）
  • 並列処理や複数リクエストが絡むケース
  • デバッグ対象がブラウザを閉じた瞬間に消えるようなケース（JSとの連携など）
  • 外部API連携の途中経過確認
  • 複数人が同時アクセスする処理のトレース

Xdebugは、ローカル開発で「なぜここでバグる？」と悩む時に有効ですが、
log::info() + tail -f は、本番や非同期処理、複数アクセスがある処理の追跡では、こちらを採用したほうが望ましいです。

おわりに

Xdebugは最初こそとっつきにくいかもしれませんが、一度、処理の流れが目で見える便利さを知ると戻れなくなります。
私自身、dd()とログの多用してデバッグしていた頃より、明らかにバグの発見と修正のスピードが向上しました。
まず1回、ぜひVSCodeとXdebugでステップ実行してみてください。この記事が、Xdebugを使い始めるきっかけとなれば幸いです。

株式会社ONE WEDGE

【Serverlessで世の中をもっと楽しく】
ONE WEDGEはServerlessシステム開発を中核技術としてWeb系システム開発、AWS/GCPを利用した業務システム・サービス開発、PWAを用いたモバイル開発、Alexaスキル開発など、元気と技術力を武器にお客様に真摯に向き合う価値創造企業です。
https://onewedge.co.jp/

GitHubで編集を提案

Discussion