【テクニカル・上級編】Xdebug 3 vs Xdebug 2：何が変わった？バージョン移行時に知るべき変更点まとめ – デバッグ・コード品質・テストツール生産性向上バイブル

Xdebug 3の全貌と移行戦略：数倍のパフォーマンス向上を引き出す内部アーキテクチャとDocker完全自動化の極意

開発環境アーキテクトとして数多くのプロダクトコードベースを診断してきたが、未だに「Xdebug 2時代の遺物」を引きずった重厚長大な設定ファイルや、JIT（Just-In-Time）トリガーの不備によってCI/CDやローカル環境のCPUを無駄に焼き尽くしている現場に遭遇する。

Xdebug 3は単なるメジャーバージョンアップではない。内部アーキテクチャの根本的な見直しにより、設定の複雑怪奇さを一掃し、かつての「重いから本番はもちろん、開発でも普段はオフにするデバッガー」という悪名を返上するほどの劇的な軽量化を果たした。

本稿では、Xdebug 3への完全移行を果たすために知るべき内部メカニズム、旧設定（Xdebug 2）からの無傷のマイグレーション、そしてDocker環境における完全自動構成とパフォーマンスの極限までの引き出し方を、妥協なき実務的視点で解説する。

—

1. Xdebug 2から3への進化：なぜ内部アーキテクチャの理解が不可欠なのか

Xdebug 2から3への移行において最も重要な変更点は、「モード（Modes）」という概念の導入と、設定ディレクティブの統合・整理にある。

モード（Modes）によるリソースの動的制御

Xdebug 2では、拡張機能がロードされた瞬間から、プロファイリング、トレージング、リモートデバッグの各機能が潜在的にオーバーヘッドを生み出していた。これを制御するためには、細かなフラグ（`xdebug.remote_enable`, `xdebug.profiler_enable`など）を複雑に組み合わせる必要があった。

Xdebug 3では、`xdebug.mode` ディレクティブによって、必要な機能だけを明示的に、かつ排他的または複合的に有効化する設計に変更された。

; 開発時はデバッグとプロファイリングを同時有効化
xdebug.mode = debug,profile

このアーキテクチャの利点は明確だ。「使わない機能のコードパスは実行されない」。これにより、リモートデバッグ待ち（コネクション確立のタイムアウト）によるリクエストの遅延や、意図しないプロファイルデータの生成によるディスクI/Oの圧迫が根底から解消される。

—

2. 旧設定からの完全マイグレーション：マッピングテーブルと移行の罠

まずは、Xdebug 2と3のディレクティブの対応関係を正確に把握する必要がある。曖昧な移行は、IDEとの通信断や予期せぬパフォーマンス劣化を招く。

主要設定の置換マッピング

移行における最大の罠：「ポート 9000」の衝突

Xdebug 3で最も多くの開発者がハマるのが、デフォルトポートの変更（`9000` -> `9003`）だ。
特にDocker環境やPHP-FPM環境において、ポート `9000` はPHP-FPM自身のリスニングポート（`php-fpm:9000`）として常時使用されている。Xdebug 2時代に `xdebug.remote_port = 9000` と設定していた環境をそのままXdebug 3にアップグレードすると、ポートのバインド競合を引き起こすか、FPMへのリクエストがデバッガーに誤認されるトラブルが発生する。Xdebug 3では潔くデフォルトの `9003` を採用するか、明確にポートを分離すべきである。

—

3. Docker環境における完全自動構成とCI/CD連携

モダンな開発において、Xdebugはローカルコンテナ環境だけでなく、CI/CDパイプラインでのカバレッジ収集や静的解析の補助としても不可欠なピースとなる。ここでは、Docker ComposeとDockerfileを用いた、環境依存のない完全自動構成を構築する。

最適化された Dockerfile の実装例

以下のDockerfileは、マルチステージビルドを前提とし、開発環境（Dev）と本番環境（Prod）でXdebugのオーバーヘッドを完全に切り離すアーキテクチャを採用している。

—- ベースイメージの選定 —-
FROM php:8.2-fpm-alpine AS base

必要なシステム依存関係のインストール
RUN apk add –no-cache \
$PHPIZE_DEPS \
linux-headers

—- 開発環境ステージ —-
FROM base AS development

PECLを介して最新安定版のXdebugをインストール
RUN pecl install xdebug-3.2.2 \
&& docker-php-ext-enable xdebug

開発用カスタムphp.iniの配置
COPY ./docker/php/conf.d/xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

—- 本番環境ステージ（Xdebugを物理的に排除） —-
FROM base AS production
本番ステージではpeclコマンドやxdebug.soを含めないことで、
攻撃表面積（Attack Surface）を最小化し、メモリフットプリントを極限まで削減する。

洗練された `xdebug.ini` の設計

次に、Docker環境でシームレスに動作する `xdebug.ini` の決定版を示す。

; 1. 稼働モードの定義
; 開発時はデバッグ(debug)とカバレッジ計測(coverage)を有効化
xdebug.mode = debug,coverage

; 2. リクエスト開始時の挙動制御
; ‘yes’にすることで、ブレークポイントがヒットしなくても常にデバッグセッションをスタンバイ
xdebug.start_with_request = yes

; 3. クライアント（ホストマシンのIDE）の接続先自動解決
; Xdebug 3の真骨頂。Dockerホストを自動検知する特殊ホスト名を使用
xdebug.client_host = host.docker.internal

; 4. 通信ポートの指定
; Xdebug 3の標準ポートである9003を指定（PHP-FPMの9000ポートと明確に分離）
xdebug.client_port = 9003

; 5. ログ出力設定（接続トラブルシューティングの命綱）
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 7

> アーキテクトの知見：`client_host = host.docker.internal` の罠
> Linux環境のDockerにおいては、`host.docker.internal` がデフォルトで名前解決できない場合がある。その場合は、Docker Compose側で `extra_hosts` を定義するか、以下のようにゲートウェイIPを直接指定するアプローチが堅牢である。
>
> extra_hosts:
> – “host.docker.internal:host-gateway”
>

—

4. API / CLI を叩く独自自動化スクリプトによるデバッグの極限効率化

「ブラウザからリクエストを送る場合」や「IDEのGUIから操作する場合」だけでなく、CLI上で実行されるバッチ処理やPHPUnitのテスト実行時に、ピンポイントでXdebugを起動・制御したいシーンは数多い。

Xdebug 3では、環境変数（Environment Variables）を用いて、設定ファイルを書き換えることなく動的に挙動をコントロールできる。

環境変数による動的オーバーライド

Xdebug 3のすべてのディレクティブは、`XDEBUG_CONFIG` または `XDEBUG_MODE` という環境変数によって上書き可能である。

以下は、CI環境やCLIバッチ実行時に、特定のテストケースのみプロファイリングとデバッグを有効化して実行するシェルスクリプトの例である。

!/usr/bin/env bash
==============================================================================
冗長な設定変更を排除し、CLIから動的にXdebugを制御してPHPUnitを実行するスクリプト
==============================================================================

set -euo pipefail

echo “==> [DevOps Pipeline] Initializing targeted debugging session…”

1. 実行時のみXdebugのモードをdebugとprofileに強制変更
export XDEBUG_MODE=”debug,profile”

2. クライアント接続先およびIDEキーの動的注入
export XDEBUG_CONFIG=”client_host=127.0.0.1 client_port=9003 idekey=VSCODE_CLI_DEBUG”

3. プロファイル出力先の指定（コンテナ内の特定ボリュームへ退避）
export XDEBUG_PROFILE_OUTPUT_DIR=”/var/www/html/storage/profiler”

echo “==> Executing PHPUnit with active Xdebug…”

4. ユニットテストの実行（特定のテストケースに絞ることでパフォーマンスを最適化）
php vendor/bin/phpunit –filter=UserAuthenticationTest

echo “==> Debugging session completed. Cleaning up environment variables.”
unset XDEBUG_MODE
unset XDEBUG_CONFIG

このアプローチを導入することで、普段の高速なCLI実行速度（Xdebug無効状態）を維持したまま、障害調査時やCIのデバッグビルド時のみ、ピンポイントで高精度な診断データを回収することが可能になる。

—

5. パフォーマンス最適化とトラブルシューティングの極意

Xdebug 3は劇的に軽量化されたとはいえ、開発者が不適切な設定を行えば、PHPの実行速度は数分の一にまで低下する。最後に、現場で実践すべき最適化ハックを提示する。

1. `xdebug.discover_client_host` の無効化によるレイテンシ削減

`xdebug.discover_client_host = 1` を有効にすると、Xdebugはリクエスト送信元のIPアドレス（`$_SERVER[‘REMOTE_ADDR’]`）に向かってデバッグ接続を試みる。これはローカル開発環境でチームメンバーと踏み台サーバーを共有するような特殊な構成では便利だが、すべてのリクエストで逆引きやIP判定のオーバーヘッドが発生するため、単体開発環境では必ず `0`（デフォルト）に設定し、`client_host` を静的にルーティングすべきである。

2. ログを用いたコネクション確立の高速診断

IDEでブレークポイントがヒットしない場合、勘で設定をいじるのは時間の無駄だ。前述の `xdebug.log` を有効にし、以下のコマンドでリアルタイムに通信ログを監視せよ。

docker exec -it tail -f /tmp/xdebug.log

正常に接続が確立している場合、ログには以下のようなハンドシェイクの痕跡が綺麗に出力される。

[61214] Time: 0.000213
[61214] Initializing Ray/DBGp connection to: host.docker.internal:9003.
[61214] Connected to client.

もしここで `Timed out` が発生している場合は、ホスト側の防火壁（UFWやWindows Defender等）がポート `9003` をブロックしているか、IDE側のリスナー（Listen for Xdebug connections）がオフになっていることが一目瞭然で判明する。

—

結びにかえて

Xdebug 3への移行は、単なる「古いバージョンのサポート終了に伴う作業」ではない。それは、コンテナネイティブでスケーラブルな現代のPHP開発パイプラインにおいて、「可観測性（Observability）」と「開発者体験（Developer Experience）」を最高レベルで両立させるためのアーキテクチャ刷新である。

設定の構造化、環境変数による動的制御、そしてモード分離による無駄なオーバーヘッドの排除。これらを体系的に理解し、コードベースとインフラストラクチャの双方に深く落とし込むことこそが、真のハイパフォーマンス・エンジニアリングの姿である。