状況
- Remote – Containers – Visual Studio Marketplace は使わない。
- ホスト側にデバッグしたい PHP コードがあり、同じコードが Docker コンテナにもある状況。ボリューム共有はしていない。
- 本当は Remote – Containers を使いたいが、古い Docker イメージでは使えない場合がある。そしてそのようなケースでは大抵 PHP も古く、 Xdebug も最新のバージョン 3 は使えず、バージョン 2 を使うことになる。この投稿では Xdebug 2 を取り扱う。
Xdebug ステップデバッギング (ステップ実行) を理解するために
- Xdebug そのものを理解するために、公式ドキュメントを読むのが良い。ページの初めから 1/4 くらいまで読めば必要な情報は手に入る。残りの部分は設定等の記述で、読まなくても良い。
- Xdebug: Documentation » Step Debugging
- Xdebug 2 を使う場合は、次のページを読んで Xdebug 設定を読み替える必要がある。 Xdebug: Documentation » Xdebug 2 から 3 へのアップグレード
- VS Code の設定をするためには、エクステンションの公式ページを読むのが良い。Xdebug の公式ページからもリンクがある。特に Remote Host Debugging の章が大事。
Xdebug を理解するために覚えておきたい Xdebug 公式ページからの抜粋と翻訳
日本語訳は Google 翻訳です。抜粋、翻訳ともに2022年2月10日(木)時点のものとなります。 抜粋した部分以外の部分を読んでみても、 Xdebug の設定は難しくないよ〜、怖くないよ〜、と説明しようとする意志が感じられて、良かったです。
Xdebug: Documentation » Step Debugging からの抜粋です。
If PHP/Xdebug run on a different machine, virtual host, or in a Docker container, you need to tell Xdebug where to make the debugging connection to, as it is Xdebug that initiates the communication to the IDE, and not the other way around.
PHP / Xdebugが別のマシン、仮想ホスト、またはDockerコンテナーで実行されている場合、IDEへの通信を開始するのはXdebugであり、その逆ではないため、デバッグ接続を確立する場所をXdebugに指示する必要があります。
In more complex set-ups you need to configure the host and port that Xdebug connects to yourself. With xdebug.client_host you can select the IP or hostname of the machine that runs your IDE, and with xdebug.client_port the TCP port. Make sure that the host running PHP/Xdebug can connect to your IDE with the configured IP address and port, and that there is no firewall or other software blocking an incoming connection.
より複雑な設定では、Xdebugが自分自身に接続するホストとポートを構成する必要があります。 xdebug.client_hostを使用すると、IDEを実行するマシンのIPまたはホスト名を選択でき、xdebug.client_portを使用するとTCPポートを選択できます。 PHP / Xdebugを実行しているホストが、構成されたIPアドレスとポートを使用してIDEに接続できること、および着信接続をブロックするファイアウォールやその他のソフトウェアがないことを確認してください。
続いて、 PHP Debug – Visual Studio Marketplace からの抜粋です。
To make VS Code map the files on the server to the right files on your local machine, you have to set the pathMappings settings in your launch.json. VS Codeでサーバー上のファイルをローカルマシン上の適切なファイルにマップするには、launch.jsonでpathMappings設定を設定する必要があります。
PHP/Xdebugが別のマシン相当（Docker）で実行されている場合、 Visual Studio Codeと通信してステップ実行するための Xdebug 設定と Visual Studio Code 設定まとめ
php.ini 等で読み込まれる Xdebug 設定
そもそもステップデバッギングするための Xdebug 2 の設定 (Xdebug: Documentation » Xdebug 2 から 3 へのアップグレード より) 。
xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.profiler_enable=0
xdebug.auto_trace=0
xdebug.coverage_enable=0
PHP/Xdebug 、 Visual Studio Code が同じマシン上にある場合は大体これで OK だそうです。 ですが、異なるマシンです。 ですので、ここが重要な点となるのですが Xdebug から通信を開始して Visual Studio Code に接続するための設定も追加 します。
xdebug.remote_host=host.docker.internal
xdebug.remote_port=9000
また、 Visual Studio Code にブレークポイントを設定した場合は自動的に止まって欲しいので、そのような設定も追加します。さらに、 Xdebug のログ出力先も追加します。
xdebug.remote_autostart=1
xdebug.remote_log=/tmp/xdebug.log
以上の設定をすべて合わせたものが、 Xdebug の設定となります。
Visual Studio Code でのデバッグ用設定
別マシン (Docker) から VS Code に接続してもらうための設定となります。
大体は VS Code でデバッグを開始しようとデバッグボタンを押したときに自動的に作成を尋ねられ、許可するとプロジェクトルートディレクトリに作成される .vscode/launch.json が設定を書くファイルとなります。
{
// IntelliSense を使用して利用可能な属性を学べます。
// 既存の属性の説明をホバーして表示します。
// 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "PHP 5.3.29 Xdebug 2.2.7",
"type": "php",
"request": "launch",
"port": 9000,
"pathMappings": {
"/var/www/html": "${workspaceFolder}/src"
}
}
]
}
別マシン (Docker) から VS Code に接続してもらうためのポイントは pathMappings です。
別マシンに居る Xdebug は VS Code のどこにステップデバッギング対象の PHP コードがあるのかを知りませんので、それを特定するためにソースのルートディレクトリを指定する必要があります。
ステップデバッギングが行われる時のブラウザ、 PHP/Xdebug 、 Visual Studio Code の接続の図
ポイントはやはり、 Xdebug から IDE (VS Code) に接続しに行く、という点と思います。私は逆だと勘違いしておりました。
コード例
Docker ビルドする際、 PHP ソースコードは COPY してイメージに含めるようにしています。ボリューム共有としていないので、別マシン (Docker コンテナ) の中に PHP コードが閉じ込められていることが保証されます。
一方で、 VS Code 側にも同じ PHP ソースコードも存在しています。
VS Code の launch.json の pathMappings にて別マシン (Docker コンテナ) の PHP コードのルートディレクトリと、 VS Code の PHP コードのルートディレクトリをマッピングすることで、リモートデバッギングが可能となっています。
おわりに
Xdebug をなんとなく使っておりました。 今回、公式のページをしっかりと読み込んで、設定するために理解するべき点が明確になったと感じました。 今後、今回理解したことを覚えている間は、ステップデバッグがうまく開始できなくてもどこをチェックしたら良いのかをある程度自信を持ってみることができるようになったと思います！
また、他に参考になったページも最後にメモしておきます。
- PHPの開発効率化！VSCode+DockerでXdebugを使ってみよう
- VS Code での Xdebug 利用例として参考にさせていただきました、PHP のコードのもここから拝借しました。
- [PHP] Xdebug のリモートデバッグ、理解していますか？ – Qiita
- 本投稿でもポイントとして挙げた、 Xdebug から見た通信先、をわかりやすく解説しています。
以上です。