突然ですがphperの皆さん、Xdebugは使っていますか？

PHPで開発する際、Xdebugを使うと時折便利にデバッグでき開発効率が上がります。

しかし、Xdebugの導入は割と手間がかかり、毎回設定方法を忘れてしまうものです。

そこで今回は備忘録として、PhpStormユーザーがDocker環境でXdebugを使う際の設定方法についてご紹介します（フレームワークはLaravel9で進めていきます）。

バージョン情報

  • Xdebug v3.1.3
  • PhpStorm 2021.2.3
  • PHP 8.1.4 (cli)
  • Laravel Framework 9.5.1
  • Mac Book Pro (OS:Monterey)

【事前準備】DockerでLaravelプロジェクトの導入

DockerでのLaravel環境の構築は以下の記事を参考に導入したものとします。

最強のLaravel開発環境をDockerを使って構築する

当記事ではこの環境を元に紹介していきます。
構築が異なる場合でも流れは同じだと思うので、必要な箇所は適かつ設定を変更してみてください。

php.iniの設定とXdebugの導入

php.iniにXdebugを使うための設定を記述をしていきます。

php.iniに以下のコードを追加してください。
（上記のLaravel環境の場合はinfra/docker/php/php.development.iniファイルへ）

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.idekey = PHPSTORM

そしてアプリケーションのコンテナ(app)でxdebugを導入するため、Dockerfileに以下のコードを追加してください。

# infra/docker/php/Dockerfile

FROM php:8.1-fpm-bullseye AS base

WORKDIR /data

# timezone environment
ENV TZ=UTC \
  # locale
  LANG=en_US.UTF-8 \
  LANGUAGE=en_US:en \
  LC_ALL=en_US.UTF-8 \
  # composer environment
  COMPOSER_ALLOW_SUPERUSER=1 \
  COMPOSER_HOME=/composer

COPY --from=composer:2.2 /usr/bin/composer /usr/bin/composer

RUN pecl install xdebug && docker-php-ext-enable xdebug # ←こちらを追加

RUN apt-get update \
  && apt-get -y install --no-install-recommends \
    locales \
    git \
    unzip \
    libzip-dev \
    libicu-dev \
    libonig-dev \
    nodejs \
    npm \
  && apt-get clean \
  && rm -rf /var/lib/apt/lists/* \
  && locale-gen en_US.UTF-8 \
  && localedef -f UTF-8 -i en_US en_US.UTF-8 \
  && docker-php-ext-install \
    intl \
    pdo_mysql \
    zip \
    bcmath \
  && composer config -g process-timeout 3600 \
  && composer config -g repos.packagist composer https://packagist.org

FROM base AS development

COPY ./infra/docker/php/php.development.ini /usr/local/etc/php/php.ini

FROM base AS deploy

COPY ./infra/docker/php/php.deploy.ini /usr/local/etc/php/php.ini
COPY ./src /data

RUN composer install -q -n --no-ansi --no-dev --no-scripts --no-progress --prefer-dist \
  && chmod -R 777 storage bootstrap/cache \
  && php artisan optimize:clear \
  && php artisan optimize

これでdockerをbuildしてみてください。

$ docker-compose up -d --build

dockerコンテナを起動したら中にはいってxdebugがインストールされたか確認してみましょう。
with Xdebugと表示されれば問題なくインストールされています。

$ make app

root@45e96d159759:/data# php -v

Cannot load Xdebug - it was already loaded
PHP 8.1.4 (cli) (built: Mar 18 2022 18:25:47) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.4, Copyright (c) Zend Technologies
    with Xdebug v3.1.3, Copyright (c) 2002-2022, by Derick Rethans

PhpStormの設定

次にPhpStorm側の設定をしていきます。

PhpStormでプロジェクトを開くディレクトリに関して、今回私はLaravelプロジェクトがある１つ上のdocker環境のディレクトリから開いています。Laravelのプロジェクトルートのディレクトリで開いても問題ありません。

phpstormを開く

PhpStormでプロジェクトを開いたら、Preferences（Macの場合Command + ,）＞PHPを開きます。

①PHP language levelをdocker環境のバージョンに設定します。

次に②でCLI Interpreterの設定をしていきます。「…」をクリックしてください。

phpstormのxdebug設定2

「+」ボタンを押し、Docker Composeにチェックを入れます(docker-composeを使用している場合)。以下のように設定します。

Server：Docker（もしない場合は、「New」にて作成。下の2枚目の写真）
Configuration files：./docker-compose.yml（pathは適かつ変更してください）
Servise：app（アプリケーションコンテナのコンテナ名。docker-compose.ymlに書いてあるとおりに。）

phpstormのxdebug設定3
phpstormのxdebug設定4

設定したら「OK」を押してください。

phpstormのxdebug設定5

正しく設定されているか確認し、問題なければ「Apply」を押下してください。

次に、Path mappingsを設定します。フォルダーアイコンを押下してください。

Local Pathにはホスト側のLaravelプロジェクトルートのパス(…/src)を設定、Remote Pathにはコンテナ内のLaravelプロジェクトルートのパス(/data)を設定します。

phpstormのxdebug設定6

続いて、Preferences＞Debugを開きます。

Debug portに9003が設定されていることを確認します。

phpstormのxdebug設定7

続いて、Preferences＞Serversを開きます。

Host、Port、Debuggerを設定します。

Use path mappingsにチェックを入れ、ホスト側のLaravelプロジェクトルートのPathに対応するFile/Directoryに対応するAbsolute path on the serverにコンテナ内のLaravelプロジェクトルートパスを記述します。

phpstormのxdebug設定8

ここまで設定できたら「OK」をクリックし、Preferenceを閉じます。

最後に、Debug実行設定をしていきます。

「Add Configuration」を押下します。「+」を押下し、PHP Remote Debugを選択します。

phpstormのxdebug設定9

Nameは適当に「Xdebug」とし、Filter debug connection by IDE keyにチェックを入れ、以下のように設定します。

Server：Xdebug
IDE key：PHPSTORM

設定したら「OK」ボタンを押して設定は完了です。

phpstormのxdebug設定10

Xdebugの実行

それでは実際にXdebugを使ってみましょう。

処理を止めたいところの行番号の右側をクリックし、ブレークポイントをつけます。

次に、虫マークをクリックすると準備完了です。この状態でブラウザなどでアクセスしてここの処理を通るように実行してみましょう。

phpstormのxdebug設定11

するとブレークポイントで止まり、変数の中身などが確認できるようになります。

下記の例では$requestの中身を確認しています。

phpstormのxdebug設定12

ここで止まらなければ何かしたら設定がうまくいってないかもしれません。

エラーがないか見直してみてください。

そして軽く使い方もご紹介⇩

phpstormのxdebug設定13

まとめ

さて、どうでしたか？うまく設定できましたか？
もしかしたら環境によってうまく設定できないかもしれません。その場合は他のサイトの記事も参考にしてみてください。

Laraveの場合はdd()でデバッグができるので基本的にはddを使えばいいと思います。
個人的なXdebugの使いどころでいうと、例えばforeachの中でループごとに変数の中身を確認したい場合やAPI開発でデバッグするときなどに便利かなと感じています。また、処理の流れも確認できるので過去にはログイン処理の流れを確認したいときなどに便利でした。

Xdebugはphperにとってはいざという時便利なので使っていない方は1度ぜひ導入してみてください。そして、導入したらしばらくの間慣れるまで使ってみてくださいね。

久々の技術寄りの投稿となりましたが、今後は技術寄りの記事もどんどん書いていこうと思います。

この記事をシェアする