PhpStorm と Xdebug で AWS EC2 上の PHP をリモートデバッグする

PhpStorm と Xdebug を使って EC2 上の PHP アプリケーションをリモートデバッグする方法を、サーバー側の php.ini の設定から IDE のパスマッピングまで解説します。

Takahiro Iwasa

2017-07-16

4 min read

PhpStorm と Xdebug によるリモートデバッグは、EC2 のステージング環境など、リモート環境でしか発生しない問題を調査する際に役立ちます。

🔥 Caution

パフォーマンスやセキュリティ上の問題を避けるため、本番環境で直接デバッグすることは避けてください。

構成

ブラウザーからのリクエストは、開発マシンから EC2 インスタンス上の Apache と PHP へ送られます。PHP の実行時に、Xdebug は反対方向の別の接続を開始し、TCP ポート 9000 を使って EC2 から PhpStorm へデバッグ情報を送ります。開発マシンがルーターの内側にある場合は、この着信接続を PhpStorm が動作するマシンへ転送する必要があります。

開発マシン、ルーター、EC2 インスタンス間のリモートデバッグ接続フロー

サーバー側の設定

php.ini ファイルに以下の Xdebug 設定を追加します。拡張機能のパスは Remi リポジトリからインストールした PHP 7.1 向けの例なので、対象環境に合わせて読み替えてください。

1
[xdebug]
2
zend_extension="/opt/remi/php71/root/usr/lib64/php/modules/xdebug.so"
3
xdebug.remote_enable = 1
4
xdebug.remote_connect_back = 1
5
xdebug.remote_host = "127.0.0.1"
6
xdebug.idekey = "IDE_KEY"
7
xdebug.remote_autostart=true

変更を反映するため、Apache を再起動します。

sudo service httpd restart

PhpStorm の設定

PhpStorm で Run > Edit Configurations... を開き、PHP Remote Debug を選択します。

Servers をクリックし、以下の設定で対象サーバーを追加します。

Name: リモートホストのプライベート IP
Host: リモートホストのパブリック IP
Debugger: Xdebug
Use path mappings: ON
Absolute path: /var/www/html/<YOUR_WEB_APP_ROOT>

❗ Important

パスマッピングはリモート側のパスと正確に一致させる必要があります。一致していない場合、接続には成功しても PhpStorm がブレークポイントで停止しません。

php.ini の xdebug.idekey で定義した IDE キーを設定します。

ポートフォワーディング

ローカルマシンがネットワークルーターの内側にある場合は、ポート 9000 への着信接続を許可し、ローカルマシンへ転送するようにポートフォワーディングを設定します。

デバッグの実行

PHP コードの任意の位置にブレークポイントを設置する。
PhpStorm で Listen for PHP Debug Connections モードを有効にする。
リモートサーバーにアクセスする。

ブレークポイントに到達すると PhpStorm が実行を一時停止し、コードを確認しながらデバッグできます。

まとめ

EC2 インスタンスに Xdebug をセットアップし、PhpStorm で Remote Debug を設定すると、リモートのステージングサーバー上で動作する PHP コードにも、ローカルと同じようにブレークポイントを設定してステップ実行できます。重要なのは、xdebug.idekey の値を PhpStorm に設定した IDE キーと一致させることと、絶対パスマッピングで EC2 インスタンス上の正確な Web ルートを指定することです。

xdebug.remote_connect_back = 1 を設定すると、ローカル IP アドレスを固定しなくても Xdebug から IDE に接続できます。そのため、開発マシンを複数のネットワークで使用する場合に便利です。

ブレークポイントで停止しない場合は、まずパスマッピングを確認してください。また、デバッグセッションが終わったら xdebug.remote_autostart を無効に戻します。