📘

WSL2+Docker+VSCode（Cursor）+PHPでXdebug3を設定し、デバッグする方法

に公開
Docker
PHP
VS Code
WSL
Cursor
tech

WSL、Docker、VSCode（Cursor）でXDebugをセットアップする方法 (WSL環境でVSCodeを起動するケース)

DockerとWSL (Windows Subsystem for Linux) を利用したPHP開発環境で、VSCodeを使ってXDebugによるデバッグを行うための手順を解説します。この方法は、VSCodeをWSL上で直接起動するケースを想定しています。
※VSCodeをフォークしたCursorでも同様の設定が可能です。Cursorを使って開発されている方でも参考にしていただければと思います。

まだ経験が少ないエンジニアがCursorやCline、Claude Codeなどをつかって開発をするようになり、AIが作り出したコードを理解せずにそのまま本番環境にデプロイし、事故が発生するケースが増えてきています。
特にまだ経験が少ないエンジニア向けにデバッグ環境を整え、プログラミングの理解度を上げるために本設定手順をまとめました。

0. 実行環境

  • PHP 8.1
  • Xdebug 3.4

1. PHPのXDebug設定を更新する

PHPコンテナ内のphp.ini に、デバッグクライアントのホスト情報を追加します。

[XDebug]ブロックに以下の設定を追記してください。

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

ポイント: xdebug.client_host=host.docker.internal は、Docker Desktop環境においてホストOSのIPアドレスを自動的に解決するための特別なホスト名です。

2. Docker Composeの設定にextra_hostsを追加する

docker-compose.ymlファイル内のPHPサービス定義に、host.docker.internalをコンテナから解決できるようにextra_hostsを追加します。

PHPサービス (例: php81など、ご自身のサービス名に合わせてください) の定義に、以下のextra_hostsを追加します。下記は例です。

  your_php_service_name: # ご自身のサービス名に置き換えてください
    build:
      context: ./php # Dockerfileのパスに合わせてください
      dockerfile: Dockerfile
    container_name: your_container_name # ご自身のコンテナ名に置き換えてください
    ports:
      - "8010:80" # ポート設定に合わせてください
    extra_hosts: # これを追加
      - "host.docker.internal:host-gateway"

3. Dockerコンテナを再起動する

php.iniとdocker-compose.ymlの変更を適用するため、関連するDockerコンテナを再構築して起動し直します。

WSLのターミナルを開き、docker-compose.ymlが存在するプロジェクトのルートディレクトリに移動して、以下のコマンドを実行します。

# プロジェクトディレクトリに移動
cd [あなたのプロジェクトディレクトリ]

# サービスを停止・削除し、新しい設定で再構築・起動
docker compose down your_php_service_name # 'your_php_service_name' をご自身のサービス名に置き換えてください
docker compose up -d your_php_service_name # 'your_php_service_name' をご自身のサービス名に置き換えてください

4. VSCodeをWSLで開く

XDebugデバッグを効果的に行うためには、VSCodeをWSLのコンテキストで開くことが推奨されます。

  1. VSCodeのExtensionsから「WSL」と検索し、「VSCode Remote - WSL」（提供元: microsoft.com）拡張機能をインストールします。
  2. VSCodeの左下にあるリモート接続アイコン（><のようなアイコン）をクリックします。
  3. 表示されるメニューから「Connect to WSL」を選択し、WSL上の開発プロジェクトのルートディレクトリ（例: /home/your_user_name/[あなたのプロジェクト名]）を開きます。これにより、VSCodeがWSLのファイルシステム上で動作するようになります。

5. VSCodeのPHP Debug拡張機能をインストールする

VSCodeをWSLで開いた後、PHPのデバッグに必要な拡張機能をインストールします。

  • 拡張機能名: PHP Debug (提供元: xdebug.org)
  • インストール方法: VSCodeのサイドバーにある「拡張機能」アイコンをクリックし、「PHP Debug」で検索してインストールします。

6. VSCodeの.vscode/launch.jsonを作成する

プロジェクトのルートディレクトリ直下に.vscode/launch.jsonファイルを作成し、XDebugのリスニング設定を記述します。

対象ファイル: [あなたのプロジェクトディレクトリ]/.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}" // Dockerコンテナ内のウェブルートパスに合わせてください
      }
    }
  ]
}

ポイント: pathMappingsの左側のパスは、Dockerコンテナ内のWebサーバーのドキュメントルート（例: /var/www/htmlなど）に合わせる必要があります。右側の${workspaceFolder}は、VSCodeで開いているプロジェクトのルートディレクトリを指します。

7. デバッグを実行する

すべての設定が完了したら、実際にデバッグを開始します。

  1. デバッグしたいPHPコードの行番号の左側をクリックし、ブレークポイント（赤い丸）を設定します。
  2. VSCodeのサイドバーにある「Run and Debug（実行とデバッグ）」ビューを開きます。
  3. 上部の構成ドロップダウンから「Listen for Xdebug」を選択し、その右にある緑色の開始ボタン（▶️）をクリックしてデバッグセッションを開始します。
  4. Webブラウザでデバッグ対象のWebページにアクセスします（例: http://localhost:8080/や、docker-compose.ymlで設定したポートとドメイン名）。
  5. VSCodeのブレークポイントでPHPの実行が停止することを確認してください。これにより、ステップ実行や変数の確認などが可能になります。

Discussion