EC-CUBEのデバッグで今まで使用していたのは、主に以下でした。
- 開発モードでdumpの出力
- 開発モードでSymfonyのデバッグツールである Profiler を使用
ただ
- dump出力の場合、ソースに記述しないといけないので消し忘れが不安・・・
- 本番（prod）モードだとdumpがエラーで落ちる
- EC-CUBEの場合、ソースによってはdump出力できない場合があり、ログに出力したりしないといけない
というようなことがあります。
そのため、デバッグツール（Xdebug）を使用したほうがいいのではないかと考え、今回手順をまとめようと思った次第です。
今回のテスト環境について以下に記載します。
Vagrant：2.4.7
VirtualBox：7.1.8
OS：Rocky Linux 9.6
PHP：8.2.28（PHP-FPM）
DB：MariaDB 10.5.27
EC-CUBE：4.3.0環境構築と設定等について、順番に書いていきます。
１）Webmin / Virtualmin で仮想ホストを作成
→ 既出のため割愛します・・・
２）remiリポジトリをインストールし、EC-CUBE4.3.0のシステム要件を満たすためにPHP8.2をインストール
→ Virtualminのサイトに複数のPHPインストールについて記載があるので、自分はここを参照しています。
３）Vagrantの共有ディレクトリの設定を行い、EC-CUBEのzipファイルを入れる
→ Vagrantの共有ディレクトリの設定については、これも既出のため割愛します・・・
４）zipファイルをゲストOSのドキュメントルートに展開して、EC-CUBEをWebインストールでインストール
画像で端折っていますが、Webインストールが完了した状態です。phpinfoを確認します。
PHP8.2で動作していることが確認できました。今の時点では当然ながらXdebugはインストールされていません。
５）Xdebugをインストール
→ remiリポジトリからインストールするとXdebug3がインストールされました。
インストール後にApacheとPHP-FPMを再起動します。
再起動後にXdebugがインストールされていることを確認してみます。まずはphpinfoです。
次に、コマンドでも確認してみます。仮想ホストの管理ユーザに切り替えしてから
Xdebugが有効化されていることが確認できます。
６）Xdebugの設定を行う
→ remi でインストールした際のXdebugの設定ファイルは以下にあります。
/etc/opt/remi/php82/php.d/15-xdebug.iniこれの設定をしていきます。最初に以下です。
xdebug.client_hostxdebug.client_host は、Xdebugがデバッグセッションを開始する際に、どのIPアドレスのマシンに接続するかを指定する設定項目です。今回はVagrantを使用していますので、ゲストOS（仮想マシン）から見たホストOSのIPアドレスを指定する必要があります。自分は以下を参照しました。
phpinfoにある、＄_SERVER[‘REMOTE_ADDR’] がそれにあたります。
次に、以下です。
xdebug.modexdebug.mode は、Xdebug3以降で導入された設定項目で、Xdebugのどの機能を有効にするかを指定します。複数のモードをカンマ区切りで指定することができます。動作モードには以下があります。
- develop：開発者向けのエラー情報やスタックトレースを表示
- debug：ステップ実行やブレークポイントなど、リモートデバッグ機能の有効化
- trace：関数呼び出しや変数の値の変化をトレースファイルに記録
- coverage：ユニットテストなどでコードカバレッジ情報を収集
- profile：プロファイリング情報（実行時間やメモリ使用量など）を記録
今回はVSCodeでリモートデバッグを行いたいと考えていますので、以下としました。
xdebug.mode = debug最後に、以下の設定を行います。
xdebug.start_with_requestxdebug.start_with_request は、「どのタイミングでXdebugがデバッグセッションを開始するか」を制御します。設定値には以下があります。
- default：デフォルト動作。XDEBUG_SESSIONクッキーや GET/POST パラメータ、または IDE Key がある場合のみデバッグセッションを開始
- yes：すべてのリクエストで必ずデバッグセッションを開始（常時デバッグ状態）
- no：デバッグセッションを自動では開始しない
- trigger：特定のトリガー（XDEBUG_TRIGGER 環境変数やリクエストパラメータ）がある場合のみデバッグセッションを開始
自分は最初ローカル環境なので
xdebug.start_with_request = yesとしていたのですが、この場合、常時デバッグセッションが開始されてしまうのであまりよろしくないという意見がありましたので、以下にしました。
xdebug.start_with_request = trigger設定が完了したら、ApacheとPHP-FPMを再起動します。
7）VSCodeに拡張機能（PHP Debug）をインストール
→ 今回の最終目標であるリモートデバッグを行うために、VSCodeにPHP Debugという拡張機能をインストールします。
インストール後に設定を行います。デバッグボタンを押下すると以下の画面が表示されますので、『launch.jsonファイルを作成します。』のリンクを押下します。ちなみに前後しますが、デバッガーの選択は『PHP』を選択します。
『launch.jsonファイルを作成します。』のリンクを押下すると、以下のようにファイルが作成されますので修正を行います。
修正箇所は以下のマーカー部分になります。
{
// IntelliSense を使用して利用可能な属性を学べます。
// 既存の属性の説明をホバーして表示します。
// 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/home/debug-test/public_html": "${workspaceRoot}"
}
},
・
・
・ディレクトリは、デバッグ対象のソース（今回はEC-CUBEのディレクトリ）が存在するディレクトリを指定します。
８）デバッグを実行してみる
→ まずはデバッグするディレクトリをVSCodeで開きます。
今回はお試しということで、EC-CUBEのTOPページが開くところにブレークポイントを設置してみます。TOPページ表示のControllerは以下ですね。
src/Eccube/Controller/TopController.php表示する前のreturnにブレークポイントを設置します。
ブレークポイントを設置したら、ブラウザでEC-CUBEのTOPページを表示させます。
ここで、６）Xdebugの設定を行う の最後の方に書きました、以下についての補足です。
xdebug.start_with_request = trigger単純にブラウザにTOPページのURLを指定しても、デバッグセッションは開始されません。デバッグセッションを開始するためにはURLパラメータに以下を指定してあげます。
例）TOPページURLが以下の場合
https://debug-test.com/
↓
https://debug-test.com/?XDEBUG_TRIGGER=1URLパラメータでトリガーを指定することで、デバッグセッションが開始されて、ブレークポイントで停止します。
今後はXdebugでのデバッグも使用していきたいと思います。
最後に、ローカル環境ではいいですが、本番環境では以下理由から導入しないようにしましょう。
-
パフォーマンス低下
Xdebugはデバッグやプロファイリングのために多くの処理を追加するため、アプリケーションの実行速度が大幅に低下します。 -
セキュリティリスク
Xdebugのリモートデバッグ機能などが有効になっていると、外部からコードの実行や情報漏洩のリスクが高まります。 -
不要な情報の露出
エラー時に詳細なスタックトレースや変数情報が出力されることがあり、攻撃者にとって有用な情報を与えてしまう可能性があります。 -
リソース消費の増加
XdebugはメモリやCPUの消費量が増えるため、本番環境の安定稼働に悪影響を及ぼします。
++++++++++++++++++++++++++++++++++++++++++++++++++++++
2025/06/27 追記
題名にはEC-CUBEと記載していましたが、PHPであれば同様にデバッグ可能かと思います。
例えばLaravelで行いたい場合は、Xdebugの設定は上記と同じで、 launch.json の pathMappings ディレクトリをLaravelのプロジェクトディレクトリにすることで可能であることを確認しました。
