この記事ではPHPやPHPフレームワークでアプリケーション開発する際のデバッグツールとしてベストセレクト（と思っている）のXdebugをLaravel × Docker環境に導入してVSCodeで動かす方法をまとめます。
まずはじめに
- 記事執筆時点の最新バージョンであるXdebug3.xの導入方法です。
- M1 Macでも動作を確認できました！！
- Windowsは動作検証していませんm(__)m
Xdebugは外部ツール（Laravelに内蔵されていません）なので導入するために色々なファイルをイジる必要がありますし、Xdebug自体の使い方も知らなければなりません。
プログラミング初心者の方でLaravel学習中の方は、まずはdd()というヘルパー関数やLogファサードを使った難易度の低いデバッグができるようになることをオススメします。
上記デバッグ方法についてはこちらの記事にまとめています。
現役PHP/Laravelエンジニアの方でも、使ったことない方はぜひこの記事を読んで欲しいです！
というわけで、Xdebugを導入する方法を解説していきます。
Xdebugのことを知っている、手元にLaravelを動かすDocker環境が既にある方は「Laravel × Docker環境にXdebug3を導入する手順」からご覧いただいて問題ありません。
Xdebugとは
Xdebugの公式サイトの冒頭には以下のように書いています。
Xdebug is an extension for PHP, and provides a range of features to improve the PHP development experience.
https://xdebug.org/
日本語訳は
XdebugはPHPの拡張機能であり、PHP開発エクスペリエンスを向上させるためのさまざまな機能を提供します。
です。
PHPを用いた開発を助けるデバッグ用の拡張機能です。
Xdebugを使うメリットにはこちら。
- dd()やLog::debug()をコードに埋めることなく処理を途中で止めることができる
- 止めた段階でも変数の値を確認することができる
- デバッグした地点からステップ実行など色々できる（適当ですみません）
PHPを使ってアプリケーションを開発する時には入れておいて損はないツール（拡張機能）です。
ゆーたろーというか僕はもうこれ無しでの開発はツライですw
Docker環境のサンプルコード
Laravel × Docker環境はこちらのGitHubリポジトリにコードをあげています。
Macの方向けですが、詳しい構築手順はこちらの記事にまとめています。
Intel製チップのMac
M1チップのMac
Laravel × Docker環境にXdebug3を導入する手順
ここから実際の導入方法を解説します。
PHPイメージにXdebugをインストール
まずは、PHPのイメージにXdebugをインストールします。
追加するのは以下の2行です。
pecl install xdebug
docker-php-ext-enable xdebug追記したDockerfileはこちらです。
FROM php:7.4.1-fpm-alpine
# COPY php.ini
COPY ./docker/php/php.ini /usr/local/etc/php/php.ini
# Composer install
COPY --from=composer:2.0 /usr/bin/composer /usr/bin/composer
# install Node.js
COPY --from=node:10.22 /usr/local/bin /usr/local/bin
COPY --from=node:10.22 /usr/local/lib /usr/local/lib
# alpine ベースのイメージでなければ autoconf gcc g++ make は不要
RUN apk update && \
apk add \
git \
zip \
unzip \
vim \
autoconf gcc g++ make && \
docker-php-ext-install pdo_mysql bcmath && \
pecl install xdebug && \
docker-php-ext-enable xdebug
WORKDIR /var/www/htmlベースイメージにAlpineは使わない場合（php:7.4.1-fpmなど）を使う場合、は以下の記述は不要です。
apk add autoconf gcc g++ makeDockerfileの修正はこれでOK。
php.iniにXdebugの設定を追加
次にPHPの設定ファイルであるphp.iniにXdebugの設定を追加します。
以下のコードを追加します。
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log
xdebug.log_level=0Xdebugのバージョン2.x → 3.x で設定内容が異なるので記事を調べる時は注意です（この記事は3.xの導入方法です）。
【不要です】docker-compose.ymlの編集
最近判明したのですが、docker-comose.ymlの修正は不要です。
ポートの定義をすることでこのファイルに書いたポートと後で修正するlaunch.jsonのポートが競合してしまい、VSCodeでXdebug起動時にlisten EADDRINUSE: address already in use :::9003となってしまい、起動することができません。
また、この状態でコンテナを停止→再起動すると、Ports are not available: listen tcp 0.0.0.0:9003: bind: address already in useとなってしまい今度はコンテナ起動エラーになってしまいます。
なお、docker-compose.ymlを修正しなければXdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(となってしまうと書きましたが、再度確認すると表示されませんでした。（これは理由不明）
以下は飛ばしてください。（個人の軌跡として残しておきます）
以下のとおり編集してください。（修正箇所のみ抜粋）
app:
build:
context: .
dockerfile: ./docker/php/Dockerfile
volumes:
- ./src/:/var/www/html
environment:
- DB_CONNECTION=mysql
- DB_HOST=db
- DB_PORT=3306
- DB_DATABASE=${DB_NAME}
- DB_USERNAME=${DB_USER}
- DB_PASSWORD=${DB_PASSWORD}
# ここから追記
ports:
- 9003:9003この修正を行わないと、Dokcerコンテナ内でartisanコマンドを実行した際に以下のメッセージが出力されます。
Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003 (through xdebug.client_host/xdebug.client_port) :-(この編集を行わなくてもXdebug自体は問題なく動作するのですが、編集しておくのが無難かと思います。
インストール確認
イメージのビルド、コンテナの起動を行います。
$ docker-compose up -d --build
こんな感じの出力が出たらOK
Creating docker-laravel-vuejs-sample_app_1 ... done
Creating docker-laravel-vuejs-sample_db_1 ... done
Creating docker-laravel-vuejs-sample_web_1 ... done$ docker-compose exec app php -v
こう出力されたらOK
PHP 7.4.1 (cli) (built: Jan 18 2020 02:38:26) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
with Xdebug v3.0.4, Copyright (c) 2002-2021, by Derick Rethanswith Xdebug v3.0.4が付いていたらXdebugのインストール完了です。
VSCodeでの作業
Docker環境にXdebugをインストールできたので、ここからはXdebugをVSCodeで動かすための作業です。
拡張機能の追加
PHP Debugという拡張機能（プラグイン）を入れます。
インストールのボタンを押してインストールしましょう。
launch.jsonの作成＆修正
VSCodeのデバッグ機能を使うための設定を定義するファイルを作成・修正します。
以下の画像の通り、ポチポチしてください。
- 虫みたいなタブを選択
- 「launch.json ファイルを作成します。」をクリック
- 「PHP」を選択
.vscode/launch.jsonが作成されます。
続いて.vscode/launch.jsonを以下の通り修正します。
{
// IntelliSense を使用して利用可能な属性を学べます。
// 既存の属性の説明をホバーして表示します。
// 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"pathMappings": {
"/var/www/html": "${workspaceRoot}/src"
},
},
]
}pathMappingsは以下の形式で書きます。
Dockerコンテナのドキュメントルート: ローカルのドキュメントルートこれで設定作業は全て完了です。
実際にVSCodeでXdebugを使ってみる
Xdebugを起動する
まずは以下の方法でXdebugを起動します。
- Listen for Xdebugをクリック
- F5をクリック（僕はこっちを使っています）
上画像のようにボタン群があるバーが表示されたら起動完了です。
デバッグ用のサンプルコードを記述
今回は超簡易的なコードでデバッグします。
routes/web.phpを以下の通り修正します。
Route::get('/test', function () {
$test = "テスト";
$debug = "デバッグ";
$testOfDebug = "${debug}の${test}用です！！！";
return view('welcome');
});実際の開発ではルーティングにロジックを書くことはほぼなく、ControllerやServiceに書きますがこれは簡易的にするためです。
ブレークポイントの設定＆デバッグ実行
最後にどこで処理を止めるかを設定します。
処理を止める地点をブレークポイントと言います。
画像の通り、22行目に設定します。（赤い丸がブレークポイントです）
22行目にブレークポイントを置くと21行目まで実行されます。
（ブレークポイントの行のコードは実行されません）
この状態でブラウザからlocalhost:80/testにアクセスします。
（ポート番号はこの記事では80にしていますがご自身の設定により変更ください）
すると自動的にVSCodeの画面に移動し、以下の画像のような表示になります。
（SuperglobalsタブとUser defined constantsタブが開きました）
まず、routes/web.phpファイルを見ると22行目で処理が止まっていることがわかります。
左側を見ると、
- 定義した変数の名前と値
- グローバル変数（Superglobals）
- 定数（User defined constants）
がわかります。
Xdebugを使うことでデバッグする度にいちいちdd();やvar_dump();die;などのデバッグ用コードを埋め込まなくて済みます！
ゆーたろー初めてXdebugを使った時はめちゃくちゃ感動しましたw
もう離れられません。
Xdebguを停止するときはバーの1番右にある赤い四角ボタンを押せば停止できます。
申し訳ありませんが、他のボタン（処理続行、ステップ実行、再起動など）の使い方はこの記事では割愛しますm(__)m
これで説明は終わりです。
Xdebugさん、超便利。
最後に
Xdebugは冗談抜きでPHPでの開発効率が上がるツール（拡張機能）です。
僕はもうPHPで開発するうちはずっと離れられないと思います（笑）
まだXdebugを使ったことがない現役PHP/LaravelエンジニアやLaravelでの開発に少し慣れた初学者の方々はぜひXdebugを導入して快適なデバッグライフを楽しみましょう！
コメント