Docker + Laravel Sail環境でのXdebug導入手順

## はじめに

こんにちは！

Laravel Sailを使用した開発を進める中で、効率的にデバッグを行いたいと考え、調べたところ Xdebug というツールが有効だとわかりました。そこで導入を試みましたが、様々な記事を参照しても、自分の環境に適したものが中々見つからず、導入に苦労しました。そのため、今回導入した手順を備忘録として記事にまとめました。

また、これから Xdebug を導入しようとしている方の一助になれば嬉しいです。

## 環境
 * macOS Sonoma 14.4.1
 * Docker version 24.0.7
 * Docker Compose version v2.23.3
 * Laravel Framework 10.48.20
 * PHP 8.2.22
 * Xdebug v3.3.2

## 前提
* VS Codeがインストールされていること
* Docker Desktopがインストールされていること
* Laravel Sailが入ったプロジェクトディレクトリがローカルにあること
* そのプロジェクトディレクトリのdocker fileにXdebugをインストールする旨の記述があること

## 導入手順

- 元になるLaravelのプロジェクトディレクトリをローカルに作成しておきます。
プロジェクトがない場合はLaravel公式ドキュメントを参考にするとサンプルプロジェクトの作成と**sail**のインストールができます。

https://laravel.com/docs/11.x/installation

https://laravel.com/docs/11.x/sail#installing-sail-into-existing-applications

- cdコマンドなどでターミナル上でそのディレクトリに移動します。
- publicディレクトリ直下に`info.php`と言うファイルを生成します。
- そのファイル内のコードを以下の通りにします。

    ```php
    <?php
    phpinfo();
    ```
    <br>
- Dockerを起動します。
    ```bash
    sail up -d
    ```
    <br>

- ブラウザ上で `http://localhost:3000/info.php` を入力し、以下のページを表示します。
    
    ![スクリーンショット 2024-08-01 21.22.02.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/3f1f6363-58e9-3b6c-02a3-25e9c3fc4aa0.png)
    
- ctrl + Fで検索窓を表示し、**Xdebug** を入力します。
- 以下のようにバージョンが表示されていればOKです。表示されていれば、Xdebugがプロジェクトに入っていることになります。

    もしも表示されていなければ、DockerのphpコンテナにXdebugをインストールするよう、docker fileにその旨追記する必要があります。
    
    ![スクリーンショット 2024-08-01 21.24.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/9568ff2b-02e1-db45-84ed-5227d38bd0f9.png)

- 上記のページから少し下にいくと、以下の **xdebug.client_port** という項目があります。ポート番号を確認して、メモしておきます。（あとで使います）
    
    ![スクリーンショット 2024-08-01 22.36.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/f8a8004b-8344-7401-b718-9cd117818002.png)


- DockerをOFFにします。

    ```bash
    sail down
    ```

*  `.env`ファイルがプロジェクトディレクトリ内にない場合は作成します。

    ※ `.env`ファイルにlaravelのappキーを設定していない場合は設定しておきます。ターミナルで以下を実行します。

    ```
    sail artisan key:generate
    ```
<br>

- `.env`ファイルに以下を追加
    
    ```bash
    SAIL_XDEBUG_MODE=develop,debug,
    SAIL_XDEBUG_CONFIG="client_host=host.docker.internal"
    ```
    
    ↓公式ドキュメント
    [10.x Laravel Sail Laravel](https://readouble.com/laravel/10.x/ja/sail.html#debugging-with-xdebug)
<br>

- 以下のディレクトリの直下に `xdebug.ini` というファイルを追加
    
    `vendor/laravel/sail/runtimes/8.2` 
    
    ※上記パスの末尾：`8.2`はdocker-compose.ymlの以下の数字に合わせる
    
    ```bash
    services:
        laravel.test:
            build:
                context: ./vendor/laravel/sail/runtimes/8.2 ← これ
    ```
<br>

- `xdebug.ini`に以下のコードを記載
    
    ```bash
    zend_extension=/usr/lib/php/20220829/xdebug.so
    xdebug.mode=debug
    xdebug.start_with_request=yes
    ```
<br>

- 以下ディレクトリ内のDockerファイルに以下を追加
    
    * ディレクトリ
    
        `vendor/laravel/sail/runtimes/8.2`
        <br>
    
    * Dockerファイル追記内容
    
    ```bash
    RUN pecl install xdebug
    
    COPY xdebug.ini /etc/php/8.2/cli/conf.d/20-xdebug.ini
    ```
<br>

- `docker compose build --no-cache` をターミナルに入力し、イメージをビルドする。
    
- `info.php`の画面より以下赤枠の **step debugger** が **enabled** になっていればOKです。
    
![スクリーンショット 2024-08-31 0.31.05.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/86c1e8d3-06c7-a8b7-9bcb-c714967bbd90.png)

    
- 拡張機能をインストール
    
    vscodeの拡張機能のアイコンをクリックし、検索窓に **php debug** と入力する。
    
    図の赤枠部の通り、1行目：**PHP debug** 、3行目：**Xdebug** と記載されたものを選択。
        右側の画面で「インストール」をクリック。

    ![スクリーンショット 2024-08-01 22.40.17.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/f7c37aa8-e27e-b87d-482e-694d11119c4a.png)
<br>
    
- vscode左端のサイドバーの「三角形と虫」のようなマークをクリックし、
    下図の **create a launch.json file** をクリック

    ![スクリーンショット 2024-08-31 0.44.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/83c53782-e472-b73c-0c6f-73bacec22056.png)
<br>

- vscode画面中央上部の検索窓からいくつか選択肢が出てきたら「php」をクリック

    ![スクリーンショット 2024-08-31 0.51.04.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/86cc02f1-d0c4-39fa-f5c6-aa83470662a3.png)
<br>

- `launch.json`に以下の設定をします。
    - **port** に先ほどメモしたポート番号を設定します。
    - **pathMappings** を指定します。
     **：** の左側・・・Dockerコンテナ内の標準的なディレクトリのパス
         **：** の右側・・・プロジェクトディレクトリの絶対パス（ご自身の環境に合わせて変更）   

    ![スクリーンショット 2024-08-31 1.02.23.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/848dd146-88c0-b315-9999-0b7c5387c535.png)

**設定完了！**

## 操作方法

1. 下図の通り、処理を止めたい場所にブレークポイント（赤い丸）を設定し、三角のボタンを押します。

    ![スクリーンショット 2024-08-31 1.16.06.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/0fc998b4-eec7-fe53-6d00-9ccde629a045.png)

2. ブラウザにブレークポイントを通過する処理が走るURLを入力して押下します。今回の例では **localhost:3000/info.php** をブラウザに入力しました。


3. 下図の通り、プログラムの処理がブレークポイントを通るときに、ブレークポイントの行が黄色になればOKです。

    ![スクリーンショット 2024-08-31 1.35.21.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3670922/32b17486-1fcb-bc23-20a9-82a4ac19eec4.png)



※動作確認が完了したら、`info.php`は削除して大丈夫です。

以上です！