こんにちは！日々のPHP開発、本当にお疲れ様です。
突然ですが、皆さんはPHPのデバッグと聞いて何を思い浮かべますか？
「あちこちに `var_dump()` や `dd()` を埋め込んで、ブラウザ画面をリフレッシュして確認する……」
もし、いまだにそんな泥臭いデバッグを繰り返しているなら、今日でそのスタイルとはお別れしましょう。
今回解説するのは、PHP開発者なら誰もが知る最強のデバッガーツール「Xdebug」です。
特に今回は、Xdebugの心臓部である `xdebug.mode` に焦点を当てます。
「Xdebugを入れるとPHPが遅くなるから嫌だ」「本番環境には絶対に入れたくない」――そんな誤解や悩みを一刀両断し、開発フェーズに合わせて必要な機能だけを秒速で切り替え、メモリ消費を極限まで抑えるプロフェッショナルな運用術を伝授します。
これをマスターすれば、あなたの毎日のコーディングとバグ調査は劇的に、そして圧倒的に楽になりますよ。さあ、一緒に扉を開けましょう！
—
1. なぜ Xdebug の「モード切替」がプロの開発現場で絶対に必要なのか？
Xdebugは、単なる「ステップ実行（ブレークポイントで止める機能）」だけのツールではありません。
内部には、以下のような複数の強力なエンジン（モード）を内蔵しています。
- `debug`: ブレークポイント、変数ウォッチ、ステップ実行（これぞ王道のデバッガ）
- `profile`: 関数ごとの実行時間やメモリ消費を「Callgrind形式」で記録し、重い処理を特定する
- `trace`: 関数呼び出しの全履歴をファイルに書き出し、処理の流れを丸裸にする
- `develop`: 綺麗なエラー画面（スタックトレース）の表示や、`var_dump()`の視認性向上
「全部入り」が引き起こす悲劇と、その解決策
かつてのXdebug（v2系）は、有効化した瞬間にすべての機能が常時ONになっていました。そのため、以下のような悪影響がありました。
1. すべてのリクエストでメモリとCPUを大量消費し、アプリが体感で遅くなる
2. 本番環境でうっかり有効にしたままだと、セキュリティリスクやパフォーマンス低下を招く
しかし、v3系以降のXdebugでは、`xdebug.mode` という設定によって、必要な機能だけをピンポイントで起動できるようになりました。
つまり、「普段は超軽量モードで動かし、ブレークしたい時やプロファイリングしたい時だけ、環境変数で即座にモードを切り替える」というスマートな開発環境が作れるのです。この仕組みを理解することが、モダンなPHPエンジニアの第一歩です。
—
2. 基礎セットアップ：Xdebugのインストールと最小構成
まずは、あなたのローカル環境（DockerやローカルPC）にXdebugを導入し、正しく動く状態を作りましょう。
インストール（PECLを使用する場合）
お使いのPHPのバージョンに合わせて、PECL経由でインストールします。
PECLを使って最新の安定版Xdebugをインストール
pecl install xdebug
インストール成功後、php.iniがある場所を確認
php -i | grep “Loaded Configuration File”
必須の基礎設定 (`php.ini`)
`php.ini`（または `xdebug.ini`）の末尾に、以下の設定を追加してください。
[xdebug]
; 1. 拡張モジュールのロード（環境に合わせてパスや拡張子が変わります）
zend_extension=xdebug.so
; 2. 【超重要】デフォルトのモードは「最小限の開発支援」に絞る
; ここで debug や profile を最初から入れないのが、パフォーマンスを落とさないコツです。
xdebug.mode=develop
; 3. IDE（PhpStormやVS Codeなど）と通信するためのポート設定（デフォルトは9003）
xdebug.client_port=9003
; 4. 自動でデバッグセッションを開始せず、トリガー（URLパラメータ等）があった時だけ起動する
xdebug.start_with_request=yes
—
3. 開発フェーズ別・おすすめ構成プロファイル
ここからが本記事のメインディッシュです。
開発フェーズ（通常コーディング・バグ調査・パフォーマンスチューニング）に応じて、`xdebug.mode` をどのように切り替えるべきか、具体的な設計思想と設定例を解説します。
プロファイル A：普段のコーディング・軽量モード（`develop`）
- 目的: 高速なページ表示を維持しつつ、エラー時の綺麗なスタックトレースや、見やすい `var_dump()` だけ恩恵を受けたい時。
- 推奨設定: `xdebug.mode=develop`
; 普段はこの設定のみ。デバッガのオーバーヘッドがほぼゼロになり、快適に開発できます。
xdebug.mode=develop
プロファイル B：デバッグ・ステップ実行モード（`debug` + `develop`）
- 目的: 複雑な条件分岐や、ORM（EloquentやDoctrineなど）が発行するクエリの動き、変数の変化を1行ずつ追いたい時。
- 推奨設定: `xdebug.mode=develop,debug`
; 開発サーバー起動時や、このタスクだけデバッグしたい時はモードを追加
xdebug.mode=develop,debug
プロファイル C：パフォーマンス測定・プロファイルモード（`profile`）
- 目的: 「なんかこのAPI遅いな？」という時に、どの関数がボトルネックになっているかをミリ秒単位で特定したい時。
- 推奨設定: `xdebug.mode=profile`
; プロファイリング結果の出力先を指定
xdebug.output_dir = “/tmp/xdebug_profiles”
xdebug.mode=profile
※このモードを有効にしてリクエストを送ると、`/tmp/xdebug_profiles` に巨大なバイナリファイル（`cachegrind.out…`）が生成されます。これを `KCacheGrind` や `WebGrind` などのビューアで読み込むと、どこが遅いかが一目瞭然になります。
—
4. 動的切替の真髄：環境変数でシームレスにコントロールする
「じゃあ、デバッグしたい時と、プロファイルしたい時で、わざわざ `php.ini` を書き換えてWebサーバーを再起動するの？」
……いいえ、そんな面倒なことはしません。
Xdebugは、環境変数 `XDEBUG_MODE` が設定されている場合、`php.ini` の設定を動的に上書きする仕様を持っています。
これを利用して、プロジェクトのルートにある `.env` ファイルや、シェルスクリプトからモードを自在に操りましょう。
1. ターミナルから一時的にデバッグモードでスクリプトを動かす場合
CLIでPHPスクリプト（ArtisanコマンドやPHPUnitなど）を実行する際、以下のように環境変数をインラインで渡します。
XDEBUG_MODEに debug を指定してPHPUnitを走らせ、ブレークポイントで止める
XDEBUG_MODE=debug php artisan test
2. Docker環境（docker-compose.yml）での優雅な切り替え
Dockerを使っている場合、サービスごとに環境変数を定義しておくと非常にスマートです。
services:
app:
image: my-php-app:latest
environment:
# デフォルトでは軽量な develop のみに設定し、アプリを爆速で動かす
- XDEBUG_MODE=develop
- XDEBUG_CLIENT_HOST=host.docker.internal
- XDEBUG_CLIENT_PORT=9003
もし、本番さながらの環境で徹底的にデバッグしたいコンテナを立ち上げる場合は、別途 `.env.debug` などを用意し、`XDEBUG_MODE=develop,debug` に書き換えてコンテナを再ビルド（または再起動）するだけでOKです。
—
5. 精度高い「HelloWorld」的動作確認：正しくブレークするかテストしよう
設定が正しく行われているか、実際にPhpStormやVS CodeなどのIDEを使ってテストしてみましょう。
動作確認用のPHPスクリプト (`debug_test.php`)
プロジェクトの公開ディレクトリ等に、以下の簡単なスクリプトを配置します。
1, “name” => “Alice”],
[“id” => 2, “name” => “Bob”],
];
// 2. 配列をループさせながら、内部の変数の動きを確認します
foreach ($userList as $user) {
$message = sprintf(“%sさん、%s”, $user[‘name’], $greeting);
// ここにブレークポイントを置くのがおすすめ
echo $message . PHP_EOL;
}
// 正常にプログラムがここまで到達するか確認
echo “デバッグテスト完了！” . PHP_EOL;
動作確認の手順（VS Codeの場合の例）
1. VS Codeで `PHP Debug` などの拡張機能をインストールする。
2. デバッグタブを開き、リスナー（Listen for Xdebug）を起動（F5キーなど）。
3. ブラウザ、またはターミナルからスクリプトを実行。
- ターミナルから実行する場合のコマンド：
XDEBUG_MODE=debug php debug_test.php
4. 結果: プログラムが `$greeting` の行、またはループ内の指定した行でピタッと止まり、IDEの画面左側に `$userList` や `$user` の中身がツリー状に展開されて表示されます！
この瞬間、「あ、ちゃんと繋がった！」という快感を味わえるはずです。
—
まとめ
今回は、Xdebugの心臓部である `xdebug.mode` の使い分けと、環境変数を駆使したプロフェッショナルな運用手法について解説しました。
- 普段は `develop` モードでメモリを節約し、アプリを快適に動かす。
- いざという時だけ `XDEBUG_MODE=debug` や `profile` を環境変数でシュッと有効化する。
この運用を身につければ、「Xdebugを入れると重い」というストレスから完全に解放され、開発スピードは何倍にも跳ね上がります。
ぜひ今日の開発から、この動的なモード切替を取り入れてみてください。あなたのPHPライフが、より一層楽しく充実したものになることを応援しています！