概要

Xdebugを使ってみたので、分かったことや分からないままのことをまとめました。
(2021/8/18追記：Xdebugはコードリーディングが辛いときに利用したくらいで、記事を投稿した時期以降は利用していません。コードを読むのに慣れてくるとXdebugが無くてもなんとかなります。Xdebugを利用すると動作が遅くなることがあるので、導入の際には十分検討してください。)

※設定については、Dockerを利用している前提で説明します。
PhpStormの機能については、PhpStormでステップ実行するならどんな環境でも参考になると思います。
(InteliJについて書かれた記事も参考にしたので、JetBrainsのIDEを利用しているなら大体同じかもしれません)

Dockerについて

この一連の記事が分かりやすいので参考にしてください。
【Docker Compose】設定内容を1行ずつ理解しながらLaravel環境構築（PHP-FPM、Nginx、MySQL、Redis）
※とくに参考にした3番目の記事のみを貼っています。
※分かりやすいので広まってほしい。

ステップ実行ができる状態にするまでの設定

動作確認環境

(なにを記載すれば十分なのかわからないので自分の実行環境を書けるだけ書いておきます)

Windows10 Pro
PhpStorm 2019.2.1
Laravel 5.5
Docker Desktop 2.1.0.1
Docker 19.03.1
Nginx 1.12.2 (dockerコンテナ上でnginxが動作)
PHP 7.2 (dockerコンテナ上でphp-fpmが動作)
xdebug 2.7.2 (php-fpmコンテナにインストールする)

XdebugをDockerコンテナにインストール

Xdebugをインストールするためのコマンドを、Dockerfileに記載します。

Dockerfile

RUN pecl install xdebug \
   && docker-php-ext-enable xdebug

xdebugをPHPで有効にする

php.iniにxdebugを有効にするための値を記載します。

php.ini

xdebug.idekey="PHPSTORM"  // 識別しやすい値ならなんでもOK
xdebug.remote_enable = On
xdebug.remote_autostart = On
xdebug.remote_connect_back = Off
xdebug.remote_host = "host.docker.internal"
xdebug.remote_port=9001  // 何番ポートでもOK

xdebug.idekeyとxdebug.remote_portは、後述するPhpStorm側の設定で利用するだけなので、好きなkeyやポート番号を使います。

他の項目が何を設定しているかについては、この記事を参考にしてください。
[PHP] Xdebug のリモートデバッグ、理解していますか？

※xdebug.idekeyやxdebug.remote_portをPreferencesで設定せずともXdebugを使えるらしいです。再現できず、正確な方法が分からなかったため今回はxdebug.idekey等を設定する方法で説明します。

PHPアプリ開発をPhpStormでスムーズに始められるよう、設定ファイルとドキュメントを用意する

PHPアプリリポジトリに docker-compose.yml を用意しておけば、Preferences を開いて設定しなくても、PhpStormでデバッグできました。

Dockerコンテナを起動する

Dockerfile とphp.iniを記述したら、Dockerコンテナを起動します。

$ docker-compose up -d

これで、Xdebugが有効になった環境が整いました。

PhpStormの設定

次に、PhpStormでステップ実行を行うための設定をします。
ここからは画像で説明していくので、 Ctrl + Alt + S で設定画面を開いてください。
まず、先ほどphp.iniに記載したポート番号を入力します。
デフォルトの9000でもよいのですが、メモ PHP docker xdebugによると、

なんでかXdebugがデフォルトで使うport:9000と、php-fpmがデフォルトで使うport:9000とが、被っているので、どちらかを変える必要がある

そうなので、9001を指定しています。
ポート番号が他のプロジェクトやツールと被らなければ、恐らく何でもいいと思います。

Serversの設定では、
①Name, Host, Port, Debuggerを設定します。
Name, Host は識別のための名前なのでどんな名前でもOKです。
Portには先ほど設定した9001、
Debuggerには、今回使うXdebugをセットしておきます。

②Use path mappingsにチェックを入れます。

③File/Directoryにはローカルのパスが書いてあり、
Absolute path on serverには対応するDockerコンテナ側のパスを書きます。
docker-compose.ymlでマウントさせているパスが対応づけられていれば大丈夫だと思います。

ツールバーのこの部分から、Edit Configuration...をクリック。

Run/Debug Configurations ウィンドウが開かれます。
+マークをクリックしてPHP Remote Debugを選択します。

新規の設定ファイルが作成されます。

①Nameには適当な名前を入力、
②Serverには先ほど任意の名前をつけたServerを選択、
③IDE keyにはphp.iniで記入した値を入力します。

完成した設定ファイルをセットしたら、

のアイコンをクリックしての状態にします。

デバッグしたい処理の任意のコードにブレイクポイントを設定します。(x行目を表す数字の右側をクリックでON/OFFできる)
ブラウザでLaravelのアプリケーションを動かし、実際にその処理を走らせると、
Incoming Connection from Xdebugというウィンドウが表示されるので、Acceptボタンをクリックします。