Xdebug 3の「機能制限モード」をCIパイプラインで自動判定する仕組みの作り方
こんにちは。テックリードの私だ。
日々のPHP開発において、ブレークポイントを使ったステップデバッグはもはや呼吸をするのと同じくらい不可欠なものだ。しかし、ここで一つの深刻なジレンマに直面する。「ローカルでの神ツールであるXdebugが、CI（継続的インテグレーション）環境において巨大なパフォーマンスの足枷になる」という問題だ。
何も考えずにCIコンテナ内でXdebugを有効なままにしておくと、PHPUnitのテスト実行速度が最大で数倍〜数十倍にまで膨れ上がり、プルリクエストごとのフィードバックループが致命的に遅延する。かといって、CIのたびに手動で拡張機能を無効化するビルドスクリプトを書くのは、DevOpsの美学に反する。
今回は、Xdebug 3が持つ隠れたキラー機能「機能制限モード（Function Restricted Mode）」を軸に、ローカル開発環境とCIパイプラインの挙動を環境変数一本で完全自動制御する、実務直結のアーキテクチャを伝授する。
—
なぜXdebug 3の「機能制限モード」なのか？
Xdebug 3以前、私たちはCI環境でのパフォーマンス劣化を防ぐために、以下のような泥臭いハックをしていた。
1. `php.ini` の中で `zend_extension=xdebug.so` をコメントアウトする。
2. CIのセットアップ時に `pecl uninstall xdebug` を走らせる。
これは無駄なオーバーヘッドを生むだけでなく、「ローカルとCIでPHPの拡張機能構成が異なる」という、環境差異に起因するバグ（いわゆる「私のマシンでは動く」の逆）を引き起こす温床となる。
機能制限モードの内部挙動とメリット
Xdebug 3では、モード（`xdebug.mode`）の概念が導入された。通常、私たちは `debug` や `profile` を指定する。しかし、このモードに `off` を指定すると、メモリ上からほぼ完全に機能がデタッチされ、オーバーヘッドを極限までゼロに近づけることができる。
ここで重要なのが、CI実行時に「特定のトリガー（例えばカバレッジ計測時のみ）以外では、Xdebugの機能を最小限のトレース・ステップ制限に抑え、かつJITやブレークポイントの監視コストを完全にシャットダウンする」というアプローチだ。
Xdebug 3.2以降、`xdebug.mode=off` または環境変数による動的制御を組み合わせることで、拡張機能自体はロードしつつ、CPUサイクルを全く消費させない状態を作ることが可能になった。この仕組みをCIに組み込む。
—
現場で即効性を発揮する全体アーキテクチャ
今回の設計の肝は、以下の3点だ。
1. 環境変数（`XDEBUG_MODE`）による一元管理：Dockerイメージを分けず、同一イメージのまま環境変数だけで挙動をスイッチ。
2. PHPUnit実行時の動的オーバーライド：カバレッジ（Xdebug不可避）を取得するジョブと、純粋な高速テスト実行（Xdebug完全無効）のジョブを賢く分離。
3. IDE（PhpStorm）とのシームレスな統合：ローカルではキー一つでデバッグをトグルし、CIでは一切のノイズを出さない。
—
実践：設定ファイルとコードのベストプラクティス
言葉を尽くすより、実際にプロダクション環境で動いている設定を見せる方が早いだろう。
1. `php.ini` （または `docker/php/conf.d/xdebug.ini`）の決定版設定
まず、Xdebugのベース設定だ。ここではモードをハードコーディングせず、環境変数から動的に拾うように設計する。
[xdebug]
; 拡張機能のロード（CIでもローカルでも共通してロードするが、モードで制御する）
zend_extension=xdebug.so
; デフォルトのモードは環境変数から取得。未設定の場合はオフにする
xdebug.mode = ${XDEBUG_MODE}
; IDE連携用のホスト自動検出（Docker環境での鉄板設定）
xdebug.client_host = “host.docker.internal”
xdebug.client_port = 9003
; 開発時の利便性向上（例外発生時に自動でブレークしないようにし、スローログのみ記録など）
xdebug.log_level = 0
2. CIパイプライン設定（GitHub Actionsの例）
次に、CI（GitHub Actions）のワークフロー定義だ。ここで環境変数を使い分け、通常のテスト実行時はXdebugを無効化（`off`）、カバレッジ測定時のみ有効化（`coverage`）する。
name: CI Pipeline
on:
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Setup PHP with Extensions
uses: shivammathur/setup-php@v2
with:
php-version: ‘8.2’
# あえて xdebug をプレインストールに含めることで、ローカルとの差異を排除
extensions: mbstring, xml, intl, xdebug
coverage: none # 初期状態ではカバレッジドライバーとしての有効化を抑制
- name: Validate Composer Dependencies
run: composer validate –strict
- name: Run Unit Tests (Xdebug OFF for Maximum Speed)
# 【超重要】ここで明示的に off を指定し、Xdebugのオーバーヘッドを完全に消し去る
env:
XDEBUG_MODE: “off”
run: vendor/bin/phpunit –testsuite=Unit
- name: Run Feature Tests with Coverage (Xdebug Enabled)
# カバレッジが必要なジョブやテストスイートでのみ ‘coverage’ モードに切り替える
env:
XDEBUG_MODE: “coverage”
run: vendor/bin/phpunit –testsuite=Feature –coverage-text
この構成により、CPUバウンドなユニットテスト群は、Xdebugの監視コストを一切受けずに、ネイティブPHPと同等の速度で爆速実行される。
—
チーム開発を加速させるPhpStormの神設定とショートカット
サーバーサイドの準備ができたら、次は開発者の手元（クライアントサイド）の最適化だ。チームメンバー全員がこの恩恵を受けるためのルール化を行う。
絶対入れるべきPhpStormプラグイン & 設定
1. Xdebugコンフィグレーションの自動監視
- PhpStormの `Settings > PHP > Debug` において、「Can take a long time to process…」の警告が出る場合、最大接続数を適切に調整しておく。
2. 「Start Listening for PHP Debug Connections」のショートカット化
- デフォルトではマウス操作が必要だが、これをキーボードショートカット（例: `Ctrl + Alt + Shift + D` / `Cmd + Shift + Option + D`）に割り当てる。
チーム共有のための `.idea/php.xml` ルール化
チーム開発において、個人のIDE設定ミスでデバッグが動かないというトラブルを防ぐため、プロジェクトルートの `.idea/php.xml`（またはDocker環境設定）をGit管理下に置き、全員が同一のパスMappings（Path Mappings）を持てるようにする。
—
トラブルシューティング：現場で陥る「あるある」と解決策
最後に、この仕組みを導入した際、現場のエンジニアから確実に出てくるトラブルと、その瞬殺ソリューションを共有しよう。
- Q: 「Xdebugを `off` にしているのに、なぜかPHPUnitの実行が遅い気がする…」
- A: `setup-php` などのアクションで、内部的にComposerがXdebugの存在を検知して警告を出しているか、あるいは他の拡張機能（PCOVなど）が競合している可能性がある。`php -m` を実行し、Xdebugがちゃんとロードされているが機能していない（`XDEBUG_MODE=off`）状態になっているかをコンソールログで確認せよ。
- Q: ローカルでブレークポイントで止まらない！
- A: ローカルの環境変数 `.env` またはシェル側で `export XDEBUG_MODE=debug` が正しく設定されているか確認すること。また、PhpStorm側の「Phone debugging（電話のアイコン）」がリスニング状態になっているかも併せて確認ポイントだ。
—
テックリードからの総括
開発効率の向上とは、派手な新しいフレームワークを導入することではない。「誰もがストレスに感じている微小な待ち時間や環境の不整合」を、エンジニアリングの力で根本から根絶することだ。
今回紹介した「Xdebugの環境変数によるモード制御とCIでの完全自動切り替え」は、コード量は少ないが、チーム全体のCI待ち時間を年間換算で数十時間、数百時間単位で削減する破壊力を持つ。
今すぐあなたのプロジェクトの `php.ini` とCIワークフローを見直し、この仕組みを組み込んでほしい。チームの生産性が跳ね上がる音が聞こえるはずだ。