今日か昨日あたりに docker image をリビルドした環境で、急に PHP のブレークポイントで止まらなくなる事象が発生しました。先日は VS Code のブレークポイントが張れなくなる問題があったので VS Code の拡張の問題かと思いましたが、今回はどうやら新しい XDebug がリリースされた影響のようです。

今回の環境は Docker + PHP 7.3 + XDebug 3 + VS Code の構成です。

バージョン指定なしで常に最新の XDebug を入れるようになっていたので、Docker イメージをリビルドしたタイミングで XDebug 2 ではなく 3 が入ったのが原因でした。

XDebug 2 に戻す案も考えましたが、せっかくなのでアップグレードガイドを読みながら設定し直してみることにします。

大きな変更としては、デフォルトのポートが 9000 から 9003 に変更されているという点です。さらに、各オプションの名前も変更されています。要するに php.ini にがんばって書いた設定が反映されなくなります。

いままでの設定

xdebug.remote_enable=1
xdebug.remote_autostart=0
xdebug.remote_host=host.docker.internal
xdebug.remote_port=9000

これからの設定

xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

ポート番号を変えた場合は VS Code の launch.json も忘れずに書き換えましょう。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/srv/html": "${workspaceRoot}"
            }
        }
    ]
}

追記：コマンドラインでも動かない

上記でブラウザ経由ではうまくいったのですが、 CLI だとステップ実行できませんでした。

今までは xdebug.remote_autostart=0 を設定して手動で開始する場合は XDEBUG_CONFIG 環境変数を設定してデバッグを開始していたのですが、Xdebug 3 からは XDEBUG_SESSION 環境変数を使用するようになったようです。

export XDEBUG_SESSION=1

また、 Xdebug v3.0.0 と v3.0.1 はこの XDEBUG_SESSION を上手く認識してくれないようです。v3.0.2 で修正されていました。

デバッグを止める場合は環境変数を削除します。

unset XDEBUG_SESSION