Laravel Sail でXdebugを有効にする方法
自己学習でlaravel Sailで環境構築を行った際に、VSCodeでXdebugを有効にするのに少し苦戦したので振り返りのためにXdebugを有効にする方法をメモします！
WSL上にLaravel Sailの環境を構築する
ローカル環境の各サービスのバージョン
- OS：Windows 11 Home
- WSL：2.4.12.0
- Docker：27.3.1
- Docker compose：2.30.3
- Visual Studio Code：1.98.2
※Laeravel Sailを使用するには、WSLとDockerをインストールする必要があります。
Laravel Sailのプロジェクトをダウンロードする
Laravel公式サイトのインストレーションページに記載されている通り、WSLの任意のディレクトリで下記コマンドを実行することで、Laravel Sailの環境構築に必要なソースコードをダウンロードすることができます。
curl -s https://laravel.build/{任意のプロジェクト名} | bash
lsコマンドを実行に{任意のプロジェクト名}のディレクトリが表示されたらOKです。
エリアスの設定
任意です。しなくてもXdebugを有効にできます。
sailコマンドについて
Laravel SailにはSail専用のコマンドが提供されており、sailコマンドを使用することで、コンテナを意識することなく開発をすることができます。
sailコマンドは「vendor/laravel/sail/bin/sail」というシェルファイルで管理されており、「/vender/bin/sail」を経由してシェルファイル内に記載されているコマンドを実行できます。
ただ、シェルファイルを毎回ファイルパスで指定するのは面倒なので、.bashrc に下記エリアスを設定します。そうすることで、sailコマンドを実行をファイル名を省略してすることができます。
alias sail="./vender/bin/sail"
動作確認
プロジェクトのルートディレクトリで下記コマンドを実行し、コンテナを立ち上げます。
sail up -d
コンテナがすべて起動すれば、Laravel Sailの環境構築は完了です。
情報の取得元となる公式ドキュメント
環境構築が終わったので早速Xdebugを導入したいのですが、導入方法を紹介する前に今回Xdebugを有効化するために参照した一時情報である下記の公式ドキュメントを一覧で記載しておきます。
Laravel Sailの公式ドキュメント
Xdebugの公式ドキュメント
Xdebugを導入したいのでXdebugの公式ドキュメントを確認するのはともかく、ネットで調べてたらLaravel Sailの公式ドキュメントにもXdebugの導入方法が記載されていると記事あったので確認しました。Laravel Sail親切ですね。
上記の公式ドキュメントを基にXdebugを有効にするために各種システム設定の修正を行います。
システム設定を修正する
Xdebugとサポート対象のPHPバージョンを確認する
Dockerのコンテナ内に構築されたアプリケーションサーバーの各サービスのバージョンを確認します。
Xdeubugの公式ドキュメントを確認したところ、XdebugにはPHPのサポート対象外のバージョンがあるようです。
システム環境の確認
publicディレクトリ直下に info.php ファイルを作成します。
info.phpに下記コードを記述します。
<?php
phpinfo();
http://localhost/info.php にアクセスして、各サービスのバージョンを確認します。
info.phpの出力結果から下記検索ワードを検索し、検索結果が取得できればOKです。
- PHPのバージョン
- 検索ワード：PHP Version
- 説明：アプリケーションサーバーにインストールされているPHPのバージョン
- Xdebugのバージョン
- 検索ワード：Xdebug v
- 説明：アプリケーションサーバーにインストールされているXdebugのバージョン
- Xdebugの解放ポート
- 検索ワード：xdebug.client_port
- 説明：アプリケーションサーバー側でXdebugの接続のため解放しているポート番号。後のVscodeの設定で使うので確認しておきます。
PHP設定ファイルの修正
Xdebugのインストールページを確認したところ、「Configure PHP #」に下記の記載がありました。
どうやらXdebugを有効にするためにはphp.iniを修正する必要があるそうです。
また、Laravel Sailの公式ドキュメントを確認していたところ、.envとphp.iniについて下記の記載がありました。
公式ドキュメントの指示にしたがって、.envとphp.iniに下記を追記します。
.env
SAIL_XDEBUG_MODE=develop,debug,coverage
.php.ini
[xdebug]
xdebug.mode=${XDEBUG_MODE}
zend_extension=xdebug
php.iniの配置場所は下記になります。
{プロジェクト名}/vendor/laravel/sail/runtimes/{info.phpで確認したPHPのバージョン}/php.ini
ステップデバッグの有効化
拡張機能機能のインストール
今度はVSCodeの設定を行います。
Xdebugの公式ドキュメントを確認すると、VScodeなどのIDEにはXdebugのステップデバッグ機能がサポートされているようです。
コマンドラインでもステップデバッグを実行できるらしいですが、公式をIDEが提供しているステップデバッグを使用するのを推奨しているので、大人しくVScodeでステップデバッグを行います。
Vscodeに「PHP Debug」 という拡張機能を追加します。この拡張機能は、VScode上でプログラムのステップ実行を可能してくれる拡張機能です。
php.iniの修正
PHP Debugの「詳細」を確認するとphp.iniに下記の記載がありました。
どうやらPHP Debug側の設定でも、php.iniを修正する必要があるようです…。
私の環境では Xdebug v3がインストールされていたので、php.iniに「For Xdebug v3.x.x:」の方を追記します。
ただし、xdebug.mode の方は先ほど修正したので、xdebug.start_with_reques のみ追加します。
さらに説明を読み進めていくと下記も記載されていました。
以上のことを踏まえてphp.iniに下記を追記します。
xdebug.start_with_request=yes
xdebug.client_host=${XDEBUG_CONFIG}
PHP Debugの「詳細」に記載されている内容と少々記載を変えています。
${XDEBUG_CONFIG}とは、Laravel Sial側が定義している環境変数です。dockercompose.ymlを確認すると上記二つの環境変数が定義されています。
${XDEBUG_CONFIG}はデフォルトで「client_host=host.docker.internal」が定義されています。
また、先ほど.envで「SAIL_XDEBUG_MODE」を定義した理由は、値を定義してあげないととデフォルト値でoffが設定されて、ステップ実行が有効にならないからなんですね。
launch.jsonの記載
「PHP Debug」のインストールが完了したら、今度はステップ実装を行うのための設定ファイルを作成します。サイドバーのデバッグアイコンを押下して、「launch.jsonファイルを作成します」のリンクをクリック。
デバッガー選択プルダウンから「PHP」を選択し、.vscodeフォルダ配下に「launch.json」が作成します。
引き続き、PHP Debugの「詳細」を確認していたらリモートホストの場合は「launch.json」にパラメータ「pathMappings」を追加する必要があるそうです。
今回はDocker上でアプリケーションを起動しているので、それに該当します。
上記を踏まえて、「launch.json」を修正します。
launch.jsonの「configurations」の中身を下記のようにします。
"configurations": [
{
"name": "Listen for Xdebug",
"type": "php",
"request": "launch",
"port": 9003,
"hostname": "localhost",
"pathMappings": {
"/var/www/html": "${workspaceFolder}"
},
}
]
各パラメータの説明
- name：デバッカーの名前
- type：言語の種類
- request：リクエスト名
- port：Xdebug側のリッスンポート。先ほど確認した xdebug.client_port のポートをここに記載します。
- hostname：ローカル側でXdebugの接続をリッスンするアドレス。
- pasthMappings：
- 左側：Dockerのドキュメントルート
- 右側：アプリケーションサーバーのドキュメントルート
設定ファイルの修正が終わったら、Dockerイメージのリビルドを実施します。
sail down // コンテナの停止
sail build --no-cache // Dockerイメージのリビルド
sail up -d // コンテナを再度起動
ステップ実行の動作確認
いよいよXdebugの動作確認を実施します。
サイドバーのデバッグアイコンを押下して、緑色の▷ボタンを押下します。
info.php ファイルにブレークポイントを設定します。
http://localhost/info.php にアクセスして、ブレークポイントを追加した箇所でプログラムの実行が止まればステップ実行の成功です。
感想
私は英語が苦手なので今まで公式ドキュメントを見るのを毛嫌いしていたのですが、意を決して公式ドキュメントを見たところ、とてもスムーズにXdebugの導入に成功しました。
今後は個人ブログだけでなく積極的に公式ドキュメントを見る癖を付けていきたいです。
参考にさせていただいた本・サイト
本
サイト
Discussion