Docker コンテナ内の設定

まず、 Docker コンテナ内に PHP と Xdebug を導入しておく必要がある. Xdebug は pecl コマンドが使えれば簡単にインストール可能. PHP をソースからビルドする場合、 configure 実行時に --with-pear フラグを付けておかないと pecl コマンドがインストールされないため要注意.

# PHP 8.0.10 をソースからインストールする場合は Dockerfile の記述は以下のような感じ.
RUN wget https://github.com/php/php-src/archive/refs/tags/php-8.0.10.tar.gz \
 && tar xvzf php-8.0.10.tar.gz \
 && cd php-src-php-8.0.10 \
 && ./buildconf --force \
 && ./configure \
    --enable-fpm \
    --enable-gd \
    --with-zip=/usr/lib64 \
    --with-mysqli \
    --with-pdo-mysql \
    --with-curl \
    --with-zlib \
    --with-openssl \
    --with-pear \
 && make \
 && make install \
 && cp php.ini-development /usr/local/lib/php.ini

RUN pecl install xdebug

インストール完了後、 php.ini ファイルに Xdebug を使用するための設定を記述しておく必要がある. PHP をソースから入れた場合 /usr/local/lib/php.ini を読み込むようになっているようだが、これは環境によって異なる可能性がある. コマンドラインから php を実行する場合には php --ini 、 Nginx/Apache から PHP を実行する場合には以下のような phpinfo() 関数を実行するだけの PHP ファイルを Nginx が fastcgi 経由で 実行できるようにし、ブラウザからアクセスして php.ini の場所を確認するとよい.

<?php

echo phpinfo();

php.ini の場所が確認できたら、そのファイルを編集して Xdebug モジュールを読み込むように設定する. 同時に、ホスト OS 上で動作している PhpStorm に Xdebug からデバッグ情報を渡せるようにホスト名やポート番号などを指定する. IDE キー (xdebug.idekey) は良くわからないが、 PhpStorm 上で正しくデバッグできるようにするためには必要らしい…​ これらの設定項目は Xdebug 2 と Xdebug 3 では大きく変更されているので注意が必要である (https://zenn.dev/k_tabuchi/books/5c03f59c00d4dc/viewer/53c98e).

なお zend_extension では Xdebug のライブラリのパスを指定するが、これは pecl install xdebug のインストール後にターミナルに出力されているはずである.

# php.ini
[xdebug]
zend_extension="/usr/local/lib/php/extensions/no-debug-non-zts-20200930/xdebug.so"
xdebug.mode = debug,develop
xdebug.start_with_request = yes
xdebug.client_port = 9003
xdebug.client_host = host.docker.internal
xdebug.idekey = phpstorm

PHP から Xdebug が正しく認識されていると、 php -m や php --version を実行した際に以下のように Xdebug の表示も増えるはずである.

$ php -m
[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
gd
hash
iconv
json
libxml
mysqli
mysqlnd
openssl
pcre
PDO
pdo_mysql
pdo_sqlite
Phar
posix
Reflection
session
SimpleXML
SPL
sqlite3
standard
tokenizer
xdebug
xml
xmlreader
xmlwriter
zip
zlib

[Zend Modules]
Xdebug

$ php --version
PHP 8.0.10 (cli) (built: Aug  2 2024 06:20:57) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.10, Copyright (c) Zend Technologies
    with Xdebug v3.3.2, Copyright (c) 2002-2024, by Derick Rethans

PhpStorm 側の設定

PhpStorm 側ではプロジェクトのフォルダを開いた後、 PhpStorm → 設定 から設定ウィンドウを開いて以下の設定を行う.

  • 左側のペイン上で ビルド、実行、デプロイ のサブメニュー内にある Docker をクリックし、以下のように設定を行う.

    • + ボタンをクリックして設定を追加し、 名前 を Docker 、 Docker デーモンへの接続方法 を Docker for Mac に設定する.

    • Docker for Mac の項目は default unix:///var/run/docker.sock で OK.

  • 左側のペイン上で PHP をクリックし、以下のように設定を行う.

    • PHP 言語レベル (P) を目的の PHP のバージョンに設定.

    • CLI インタープリター には Docker コンテナ内の PHP インタプリタの設定を行う.

      • …​ をクリックして CLI インタープリター ウィンドウを開き、 + ボタンをクリックして設定を追加.

      • サーバー を Docker に設定し、 イメージ名 に目的の Docker コンテナのイメージを指定する.

      • PHP 実行可能ファイル は php コマンドのパスを指定するようだが、とりあえず単に php としておけばよい.

      • 構成ファイル にはコンテナ内の php.ini ファイルの場所 (/usr/local/lib/php.ini など) を指定する.

      • 入力後、 PHP 実行可能ファイル の入力欄の右側にある phpinfo の再ロード ボタンをクリックしてデバッガーとして Xdebug が適切に認識されれば OK.

      • ウィンドウ右下の OK ボタンをクリック.

    • パスマッピング にはホスト OS 側のプロジェクトフォルダとコンテナ側のフォルダの対応関係を設定する.

      • (つまり、コンテナに対してはボリュームマウントでホスト OS 内のプロジェクトフォルダをコンテナ内にマウントしていることを前提としている.)

      • 右端のアイコンをクリックして プロジェクトパスマッピングの編集 ウィンドウを表示し、 + アイコンをクリックして ローカルパス (ホスト OS 側) と リモートパス (コンテナ側) のフォルダパスの対応関係を記述して OK をクリックする.

    • Docker コンテナー にはコンテナに対するボリュームマウントの設定を書くようだ.

      • 既にコンテナが動作している場合にこの設定が必要になるのかは不明…​

      • とりあえず、右端のアイコンをクリックして Docker コンテナー設定の編集 ウィンドウを表示し、 ボリュームバインディング 内の + ボタンをクリックして ホストパス と コンテナーパス を設定しておく. 読み取り専用 にはチェックは入れないでおく.

      • 右下の OK ボタンをクリックしてウィンドウを閉じる.

  • 左側のペイン上で PHP のサブメニュー内にある サーバー をクリックし、以下のように設定を行う.

    • + ボタンで設定を追加し、 名前 を localhost 、 ポート を 80 、 デバッガー を Xdebug に設定.

      • コンテナ内での Nginx のポートを指定するようだ.

    • パスマッピングを使用する にチェックを入れ、 ファイル/ディレクトリ 内の プロジェクトファイル に対応する サーバー上の絶対パス にコンテナ内のパスを入力しておく.

  • 左側のペイン上で PHP のサブメニュー内にある デバッグ をクリックし、以下のように設定を行う.

    • Xdebug 項目内の デバッグポート にポート番号 9003 が (必要に応じてカンマ区切りで) 入力されていることを確認する. その横の 外部接続を受け入れる にチェックを入れておく.

  • 一通り設定できたら、画面右下の OK ボタンをクリックしてウィンドウを閉じる.

デフォルトでは PhpUnit によるユニットテストのための実行構成しか登録されていない可能性があるため、リモートデバッグのための実行構成を設定しておく.

  • メニューから 実行 → 実行構成の編集…​ をクリックし、 実行/デバッグ構成 ウィンドウを表示する.

  • 左上の + ボタンから PHP リモートデバッグ を追加し、 名前 (N) に適当に名前を設定しておく.

  • IDE キーでデバッグ接続をフィルターする にチェックを入れ、 サーバー (E) に localhost 、 IDE キー (セッション ID) (K) に phpstorm と入力しておく.

  • 画面右下の OK ボタンをクリックしてウィンドウを閉じる.

これにより設定が完了したため、後はメインウィンドウ上部に表示されている虫のアイコン PHP デバッグ接続のリッスンを開始 ボタンをクリックし、 適当な行にブレークポイントを指定してからウェブブラウザからアクセスを行うと、 PhpStorm 上で指定したブレークポイントでプログラムの実行が停止するようになる.

References