PHPでデバックするときに一番手っ取り早いのはver_dump関数ですが、見たい内容を毎回記述する必要があったり、画面表示しない処理(CSVダウンロードなど)だとデバックしにくい面もあります。
そこでXdebugです。 公式:https://xdebug.org/
IDEでブレークポイントをつけた箇所で処理が止まってくれて、変数の中身などを確認することが出来ます。 例えば次の画像のように$idの内容が確認できます。
xdebugの仕組みの概要は以下です。
IDEは特定のportでWebサーバーにインストールされたXdebugからの通信を待機する
Xdebugは特定のportにコールバックする
デバックセッションを開始して、DBGPプロトコル(デバッグ用の特別なプロトコル)を介してデータを転送
IDEによってWebサーバーが「呼び出される」のかと思っていましたが、実際は逆で Xdebug(Webサーバー)がIDE に接続しに行くようです。
この辺りは以下の動画が分かりやすかったので、気になる方はご視聴をお勧めします。 #03 – PHP Advanced Debugging With Xdebug- How Xdebug Works
とても便利なのですが、設定が少しややこしいので、今回は現時点で最新のEccube4.3をローカルに構築して、Xdebugの導入してみました!
手順1:ローカルにEccube4.3環境を立ち上げる
まずはEccubeのコードを用意します。 EccubeはOSS(オープンソースソフトウェア)で、以下のGitHubから取得できます。
https://github.com/EC-CUBE/ec-cube
コードを適当なディレクトリの配置後、初回インストールを実施するのですが、今回はXdebugの起動を確認すれば良いだけなので、初回インストール状態を残すべく、以下の変更を加えます
docker-compose.yml
volumes:
html-app: # ← ソースコードが含まれるボリューム(初回インストール後も残す)
services:
ec-cube:
volumes:
- html-app:/var/www/html
この状態で初回インストールを行います。 参考:Docker Composeを使用してインストールする
#初回インストールコマンド
# コンテナの起動 (初回のみビルド処理あり)
docker-compose up -d
# 初回はインストールスクリプトを実行
docker-compose exec -u www-data ec-cube bin/console eccube:install -n
ローカルにアクセスできたらOK。 http://localhost:8080/
手順2:Xdeugをインストールする
ルート直下にあるDockerfile、docker-compose.yamlを変更します。
1.Dockerfileの修正 PECLでインストールします。以下を追記します。
RUN pecl install xdebug \
&& docker-php-ext-enable xdebug ## 追記
以下をコメントアウトします。(2度目立ち上げ時に失敗してしまうのでコメントアウト)
#COPY dockerbuild/docker-php-entrypoint /usr/local/bin/
2.php.iniにxdebugの設定を追加 ビルド時に「dockerbuild/php.ini」のファイルをphp.iniに読み込んでいるので、ここに以下の設定を追記します。
[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_port = 9003
xdebug.client_host = host.docker.internal
mode=debug:ステップデバッグが出来るようになります。 それ以外の値はこちら
start_with_request:いつデバッグを開始するかを指定する。yesを選択 それ以外の値はこちら
client_port:PhpStormのデバッグポートで指定する値を設定します。※後述
client_host:Xdebug接続するIP アドレスまたはホスト名
個人的にclient_hostが毎回ハマるポイントです。 Macでは上記の「host.docker.internal」で問題ないらしいのですが、 私の環境(WLS2)だとうまくいきませんでした。 ※最近のバージョンではWLS2でも「host.docker.internal」で出来る、という記事もみたのですが、残念ながら私の環境では出来ませんでした。 色々試行錯誤した結果以下の値を設定することで成功しました。 ・コマンドプロンプトや PowerShell でipconfigを実行した後の「イーサネット アダプター vEthernet (WSL):IPv4 アドレス 」の値 ※ただしこの値は固定ではない(再起動などで変更される可能性がある)ので、他の方法が出来る場合は他の方法を採用した方が良いと思います。
> ipconfig
イーサネット アダプター vEthernet (WSL):
IPv4 アドレス . . . . . . . . . . : 172.**.***.***
手順3:IDE(今回はPhpStorm)にXdebugの設定を行う
仕組みの概要で触れた通り、IDEはXdebugからの通信を待機して受け取る必要があるので、設定が必要です。
1.設定->PHP->サーバ でサーバーを追加する プラスマークから追加します。 ここでは主にパスマッピングが重要です。 パスマッピングの設定によって「Xdebug 経由でやってくる“/var/www/html/はローカルではこのパスですよ」と伝えることが出来ます。
名前 : 何でも良い。 ホスト : localhostで設定しているがそれ以外の値でも成功する。 ポート : 80で設定しているがそれ以外の値でも成功する。 デバッガー : Xdebug を選択 パスマッピングを使用する : オンにして対応するパスを設定する
設定値を入れたら適用する
2.設定->PHP->デバッグ でXdebugの設定を確認する
デバッグポート: 9000、9003の2つがデフォルトで指定されていますが、これは Xdebugのポートのデフォルトが、Xdebug2では9000だったのが、Xdebug3で9003に変更されたためのようです。 今回はPHP8でXdebug3になるので、9003のみにして、 あとは「外部接続を受け入れる」にチェックが入っていることを確認して、適用保存します。 ※9000,9003の2つが設定されたままでも問題ありません。
3.実行 / デバッグ構成 を設定する PhpStormヘッダ部に「現在のファイル」となっている部分をクリックすると 「実行構成の編集」というメニューが表示されるのでそれをクリック。 プラスマークから「PHPリモートデバッグ」を追加します。
名前に何でも良いので値を設定し、適用します。 ※「IDEキーでデバッグ接続をフィルターする」にチェックを入れる記事が多いですが、今回はチェック無しで出来たのでOFFのまま進めます。
手順4:ビルドを実施して再度コンテナを立ち上げ
手順1で立ち上げた環境ですが、一度
docker-compose down で削除
docker build -t ec-cube –no-cache –pull –build-arg TAG=8.1-apache . でビルドして
docker tag ec-cube ghcr.io/ec-cube/ec-cube-php:8.1-apache でタグ付けし、
docker-compose up -d で再度立ち上げます。
ec-cube_1コンテナに入り、 php -v で表示される情報の中に「Xdebug」の文字があればインストールされています。
手順5:デバッグを実行
1.PhpStormのヘッダ部にある電話のようなマークをクリックしてリッスンを開始します。 2.PhpStormのヘッダ部にある虫のようなマークをクリックしてデバッグを開始します。 3.ステップさせたいところにブレークポイントを設定して、ブラウザからリクエストを実行。
ステップデバッグが出来るようになると、初回のダイアログが表示されます。
承認し、最初の画像のようにブレークポイントで停止してくれるようになれば設定完了です!
いかがだったでしょうか。 開発を助けてくれるXdebugですが、EccubeだけではなくてPHPであれば利用できますので、 PHPで開発されている方はローカル環境に入れてみてはいかがでしょうか。
※Xdebugはあくまで開発専用の機能なので、本番環境には絶対に入れてはいけません。