var_dump()とprint_r()という名の悪夢
PHPエンジニアなら、数千行のコードの中に潜むnull値の変数を追跡するためだけに徹夜した経験が一度はあるはずです。最も「伝統的」な手法は、至る所にvar_dump(); die();を挿入し、ブラウザを何度もリロードすることでしょう。運が良ければ数分でバグが見つかりますが、そうでなければ「挿入・削除・挿入」の無限ループに陥ります。
私もキャリアの初期はこの手動の方法を忠実に守っていました。しかし、プロジェクトが大規模になり、Dockerを基礎から学ぶ段階を終えて実際に動かすようになると、目視でのデバッグはまさに苦行となりました。かつて20以上のコンテナが同時に稼働するシステムを管理していた際、ログからロジックのバグを追跡するだけで、開始点を見つけるまでに4時間以上を費やしたことがあります。その瞬間, 私は悟りました。「何としてもXdebugを使いこなさなければならない」と。
XdebugとDocker：仕組みを正しく理解する
設定を成功させるには、一つの重要な原則を理解する必要があります。よくある勘違いは「VS CodeがXdebugに接続する」というものですが、実際はその逆です。Xdebug側がVS Codeを探しに行くのです。
PHPアプリケーションがDocker内で実行されると、Xdebugはポート9003を介してホストマシン（PC）に信号を送信します。この時、VS Codeは「待機中」のサーバーの役割を果たします。両者が接続されれば、コードの任意の場所で実行を停止（ブレークポイント）させ、変数の隅々まで調査し、一行ずつ神のように実行できます。もう推測に頼る必要はありません。すべてが明確に見えるようになります。
実際の設定に取り掛かる
ここでは、コードが./srcディレクトリにある、シンプルなDocker ComposeのPHPプロジェクトを例に説明します。
ステップ1：Dockerfileの編集
素のPHPイメージを使わず、デバッグ機能を有効にするためにXdebugエクステンションをインストールする必要があります。以下はDebian/Ubuntuベースのイメージ用の標準的なDockerfileの書き方に基づいた設定例です：
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y \
git \
unzip \
&& pecl install xdebug \
&& docker-php-ext-enable xdebug
# 個別の設定ファイルをコンテナにコピー
COPY ./docker/php/xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.iniステップ2：xdebug.iniファイル – 接続の「魂」
以下の内容でxdebug.iniファイルを作成します。client_hostの行に特に注意してください：
zend_extension=xdebug
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.logヒント： host.docker.internalは、Windows/Mac上でコンテナからホストマシンを指し示すためのキーワードです。Linuxの場合は、このキーワードを定義するためにdocker-compose.ymlにextra_hostsを追加する必要があるかもしれません。
ステップ3：VS Codeの設定 (launch.json)
VS Codeのデバッグタブを開き（ショートカット Ctrl+Shift+D）、以下の内容でlaunch.jsonファイルを作成します：
{
"version": "0.2.0",
"configurations": [
{
"name": "Xdebugの待機",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceRoot}/src"
}
}
]
}注意：pathMappingsは、エンジニアの90%が設定を間違えやすい場所です。これは、Docker内の/var/www/htmlにあるindex.phpと、ローカルマシンのsrcディレクトリ内にある同じファイルをVS Codeが紐付けるのに役立ちます。
実践から得た教訓
この設定を実際のプロジェクトに適用したところ、作業効率が飛躍的に向上しました。特に印象に残っているのは、APIの決済ループ内でのロジックエラーを解決した時です。var_dumpを使っていたら、何十ものネストされた関数呼び出しの中で$balance変数がいつ誤って減算されたのかを特定することは不可能だったでしょう。
Xdebugのおかげで、ブレークポイントを一つ置いて、ステップごとに値の変化を観察するだけで済みました。結果、誰も気づかなかった2年前の古いコードの一行に原因があることがわかりました。これにより、バグ修正時間を40%削減でき、その時間をコーヒーを飲んだりサーバーを最適化したりする時間に充てることができました。
アドバイス： 開発環境で常にxdebug.mode=debugをオンにしないでください。ウェブの動作が少し遅くなるためです。本当にバグを「調査」する必要がある時だけ有効にしましょう。
結論
DockerでのXdebug設定は、最初はネットワーク面で少し面倒に感じるかもしれません。しかし、これはあなたのキャリアにとって非常にリターンの大きい投資です。見苦しいdumpコードは卒業して、今日からプロフェッショナルなデバッグを始めましょう。皆さんのバグ修正が電光石火のごとく終わることを願っています！
