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

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

Takahiro Iwasa

2017-07-16

4 min read

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

🔥 Caution

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

サーバー側の設定

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への着信接続を許可し、それをlocalhostへ転送するようポートマッピングを設定してください。

デバッグの実行

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

ブレークポイントがトリガーされると、PhpStormが実行を一時停止し、コードの検査とデバッグが行えるようになります。

まとめ

EC2インスタンス側にXdebugをセットアップし、PhpStormのRemote Debug設定をそこに向けることで、リモートのステージングサーバー上で動くPHPコードに対しても、まるでローカルであるかのようにブレークポイントを設置してステップ実行できるようになりました。ここで重要なのは2点あります。xdebug.idekeyの値がPhpStormのサーバー設定で構成したIDEキーと一致していること、そして絶対パスマッピングがEC2インスタンス上の正確なWebルートを指していることです。xdebug.remote_connect_back = 1を設定しておけばローカルIPをハードコードしなくてもXdebugがIDEへの経路を見つけてくれるので、ネットワークを移動することが多いマシンでは特に助かります。ブレークポイントが何も反応せずに素通りしてしまう場合はまずパスマッピングを疑うべきですし、デバッグセッションが終わったらxdebug.remote_autostartを無効に戻しておくのも忘れずに。