【Xdebug】Docker × IntelliJ IDEAでXdebugを利用してデバッグを行う

IntelliJ IDEAで、Docker上のプログラムをXdebugを使ってデバッグする方法を紹介します。

環境構築は複数のサイト様にお世話になりましたが、チュートリアル的な資料が欲しくなったので自分で作ってみました。
これがあればとりあえず動かせるぞ！という設定をまとめました。

対象は簡単な生PHP（メイン処理・1クラス）のみです。
デバッグはIntelliJ IDEA上、ブラウザ経由の両方で可能です。

# 動作環境
- macOS Ventura 13.6.1
- Docker Desktop 4.25.2
- IntelliJ IDEA Ultimate 2023.2.5
- Google Chrome 119.0.6045.199（Official Build）

# 目的
IntelliJ IDEAで、Docker上のプログラムをXdebugを使ってデバッグする。

# Dockerコンテナの作成
検証用のDockerコンテナを作成します。

## ディレクトリ構成
```bash
.
├── Dockerfile
├── docker-compose.yml
├── php
│   └── php.ini
└──src
    ├── Calculator.php
    └── main.php
```

## ファイル一覧
- Dockerfile
```Dockerfile
FROM php:8.2-apache
RUN pecl install xdebug && docker-php-ext-enable xdebug
```

- docker-compose.yml
```yml
version: "3"

services:
  app:
    build: .
    ports:
      # ローカルの8080番ポートにコンテナの80番ポートをフォワード
      - "8080:80"
    volumes:
    　　 # ローカルのファイルをコンテナにマウント
      - "./php/php.ini:/usr/local/etc/php/php.ini"
      - "./src:/var/www/html"
    stdin_open: true
```

- php/php.ini
```ini
[xdebug]
xdebug.mode=debug
xdebug.client_port=9003
xdebug.client_host=host.docker.internal
```

- src/Calculator.php
```php
<?php

class Calculator
{
    public int $a;
    public int $b;

    public function __construct(int $a, int $b)
    {
        $this->a = $a;
        $this->b = $b;
    }

    public function add(): int
    {
        return $this->a + $this->b;
    }

    public function multiply(): int
    {
        return $this->a * $this->b;
    }
}
```

- src/main.php
```php
<?php

require_once 'Calculator.php';

echo "xdebug test start<br>";

$a = rand(1, 10);
$b = rand(1, 10);
echo "a: $a<br>";
echo "b: $b<br>";

$calculator = new Calculator($a, $b);

$add = $calculator->add();
$multiply = $calculator->multiply();
echo "加算結果: $add<br>";
echo "乗算結果: $multiply<br>";

echo "xdebug test end<br>";
```

## コンテナ起動
コンテナを起動します。
```bash
% docker-compose up -d
```

PHPとXdebugのバージョンを確認します。
```bash
% docker-compose exec app php -v
PHP 8.2.13 (cli) (built: Nov 27 2023 21:48:49) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.13, Copyright (c) Zend Technologies
    with Xdebug v3.3.0, Copyright (c) 2002-2023, by Derick Rethans
```

ブラウザで[http://localhost:8080/main.php](http://localhost:8080/main.php)へアクセスし、プログラムの出力結果が表示できればOKです。
![スクリーンショット 2023-12-10 22.46.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/348f5130-cc92-5072-d0bc-974acf94d693.png)

# IntelliJ IDEAの設定
Dockerコンテナへの繋ぎ込みを設定します。

## 事前準備
``Settings > Pulugins``から下記のプラグインをインストールして下さい。
- Docker
- PHP Docker
- PHP Remote Interpreter

https://www.jetbrains.com/help/phpstorm/configuring-remote-interpreters.html

## 設定
### Docker
``Settings > Build, Execution, Deployment > Docker``で設定します。

``docker-compose.yml``の設定``./src:/var/www/html``を記述し（①）Apply（②）で適用した後でリロード（③）します。
リロード後に``Connection successful``（④）が表示できればOKです。
![スクリーンショット 2023-12-10 23.09.12.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/3355a8c1-55ee-75dc-971e-625e7b9aecbb.png)

### PHP
``Settings > Languages & Frameworks > PHP``で設定します。

https://www.jetbrains.com/help/phpstorm/configuring-xdebug.html

https://www.jetbrains.com/help/phpstorm/configuring-remote-interpreters.html#585a0606

1. ``PHP language level``にPHPのバージョン、``CLI Interpreter``に``<no interpreter>``を設定し、右の三点リーダーをクリックします。
![スクリーンショット 2023-12-10 20.25.58.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/6d95492b-67df-f4ea-8525-abfec035c5c4.png)

2. CLI Interpreterを追加します。種類は``From Docker~``を選択して下さい。
![スクリーンショット 2023-12-10 20.30.42.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/e38e2714-3015-2288-ab96-bcd0daf7dac9.png)

3. ``Docker Compose``を選択し、先ほど追加したDockerの設定を反映します。
![スクリーンショット 2023-12-10 23.01.58.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/25f73fe4-ea34-7bb9-3819-892e8917293b.png)

4. 反映後、PHPとXdebugのバージョンが表示されます。
![スクリーンショット 2023-12-10 20.32.14.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/1ea1b29d-5502-958a-e297-4d38638e6172.png)

5. ``CLI Interpreter``にコンテナのサービス名、``Path mappings``にパスマッピングが反映されていればOKです。
![スクリーンショット 2023-12-10 20.32.38.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/f0632ab3-e876-7796-a492-207ed37476b2.png)

### Debug
``Settings > Languages & Frameworks > PHP > Debug``でXdebugのポートを設定します。

インストールしたXdebugは3系なので、9003番ポートを使います。

https://pleiades.io/help/phpstorm/configuring-xdebug.html

![スクリーンショット 2023-12-10 21.32.31.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/5385a90c-7a87-0eac-b8ca-a2133b46ed0b.png)

### Servers
``Settings > Languages & Frameworks > PHP > Servers``で設定します。

``Host``と``Port``はローカルの設定``localhost:8080``を記述します。``Debugger``はもちろん``Xdebug``です。

さらに``User path mappings~``にチェックを入れ、パスマッピングを設定します。こちらも``docker-compose.yml``の設定``./src:/var/www/html``を記述します。

![スクリーンショット 2023-12-10 20.46.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/d3d1266a-2f13-d063-7276-54798528a6ae.png)

# Google Chromeの設定
## 事前準備
下記の拡張機能を追加して下さい。
- [Xdebug helper](https://chromewebstore.google.com/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc)

Google Chrome以外のブラウザを使う場合は、こちらを参考にして下さい。

https://pleiades.io/help/phpstorm/browser-debugging-extensions.html

# デバッグ実行
## IntelliJ IDEA上でデバッグする
1. 行数の右隣をクリックし、ブレークポイントを設定します。
![スクリーンショット 2023-12-10 21.37.43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/9584ced2-751c-489b-43a3-f8d1af2a8f4d.png)

2. 右上のデバッグ用アイコンをクリックし、ファイル名``main.php``を選択します。
![スクリーンショット 2023-12-10 22.33.15.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/580748af-7a65-4b2d-54be-cc44ad2c7a68.png)

3. デバッグが実行されブレークポイントでプログラムが一時停止します。デバッグ結果も表示できました。
![スクリーンショット 2023-12-10 22.43.39.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/42e5e11c-30a2-26c5-5739-55bc497874e1.png)

4. 後はステップイン、ステップアウトなどを実行し、デバッグを続行して下さい。
![スクリーンショット 2023-12-10 22.43.37.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/07cea696-8fab-024a-ac57-2acb06b5c136.png)

## ブラウザ経由でデバッグする
1. ブラウザで[http://localhost:8080/main.php](http://localhost:8080/main.php)を開きます。
![スクリーンショット 2023-12-10 22.46.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/348f5130-cc92-5072-d0bc-974acf94d693.png)

2. 右上のリッスン用アイコンでデバッガー接続をリッスンし、ブレークポイントを設定します。
![スクリーンショット 2023-12-10 22.54.38.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/2920e1e1-7213-193a-d55c-03641b91844e.png)

3. 1.のブラウザで``Xdebug helper``の``Debug``を有効にします。
![スクリーンショット 2023-12-10 21.43.08.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/58d1af7c-82a0-f6d6-84e5-de75a94358d7.png)

4. 3.のブラウザをリロードします。

5. デバッグが実行されブレークポイントでプログラムが一時停止し、IntelliJ IDEAにデバッグ結果が表示されます。後はステップイン、ステップアウトなどを実行し、デバッグを続行して下さい。
![スクリーンショット 2023-12-10 22.56.45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/a9047a85-cd24-51ad-823a-7ba3150bf288.png)

6. プログラムを最後まで実行すると、ブラウザに出力結果が表示されます。
![スクリーンショット 2023-12-10 22.57.35.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/654760/f90b27b0-78c5-85bf-d04c-aa808f677850.png)

# まとめ
次回はLaravel上でXdebugを使う方法を書いてみたいですね。

ご精読ありがとうございました。
皆様の開発効率が上がれば幸いです！

# 参考記事
https://zenn.dev/micronn/articles/5f3cd1d94f99fd

https://blog.shin1x1.com/entry/setup-test-and-debug-on-phpstorm-and-docker-for-mac

https://qiita.com/mrt/items/e900467758a3c14622fb

https://chichi1091.hatenablog.jp/entry/2021/10/12/003648

https://techtech-note.com/570/

https://zenn.dev/ttskch/articles/ee8298de80efbf

# 採用PR
弊社で一緒に働く仲間を募集しています。

Devトークやってます。お気軽にご応募ください(^^)

https://plus.jobs.qiita.com/dev-talk-company-pickup-vivion/

募集要項はこちらをご覧ください！

https://hrmos.co/pages/vivion/jobs?category=1687770395095928832