WindowsでDockerとVSCodeでWordpressをデバッグする時の始め方

WindowsでDockerでWordpressのテーマを作るとき等にデバッガを使いたいことがあります。そこで Visual Studio Code(VSCode) で Xdebug を使ってWordpressをリモートデバッグできるようにする設定をします。

準備
- WSL2のインストール
Dockerfile の作成
docker-compose.yml の作成
Visual Studio Code の設定
Dockerコンテナを立ち上げてデバッグ

準備

WSL2のインストール

WSL2をインストールして、Docker Desktop on Windowsをインストールしてください。

WSL2のインストールはこちらの公式サイトがわかりやすいかと。
なんと日本語で解説してくれます。

docs.microsoft.com

まずは下記リンクから Docker Toolbox for Windows をダウンロードして、インストールします。
(Windows 10 Homeの場合です。Proの場合はDocker for Windowsがいいでしょう。

~~https://docs.docker.com/toolbox/toolbox_install_windows~~

下記リンクからDocker Desktop on Windowsをダウンロードして、インストールします。

docs.docker.com

次にプロジェクトのフォルダに以下のファイルとフォルダを作ります。
Dockerfile docker-compose.yml
wp-content(フォルダ)

（2020.11.08）
WSL2を使う場合はDockerがやたらと遅くなるという問題があります。
普通にCドライブ下にプロジェクトを作った場合、WindowsとWSL2(Ubuntu)のファイルシステムでいちいち変換処理がかかるためです。
我慢できない場合はWSL2(Ubuntu)の管理下のフォルダにプロジェクトを移してください。

コマンドプロンプトでwslコマンドを使用するとWSL2のシェルに入れます。
Windows側のフォルダは/mnt/以下にあるので、そこからプロジェクトのフォルダをmvコマンド等で適当な場所(home/<username>/とか)に移してください。
あるいはWindowsのエクスプローラーのアドレス欄に\\wsl$を入れると、ネットワークフォルダとして表示させられるので、そこで操作するのもいいと思います。

Dockerfile の作成

Dockerfileの内容を次のようにします。

FROM wordpress:latest
    
RUN pecl install xdebug \
    && docker-php-ext-enable xdebug \
    && echo 'xdebug.mode = debug\n' \
            'xdebug.start_with_request = yes\n' \
            'xdebug.client_port= 9003\n' \
            'xdebug.client_host = "host.docker.internal"\n' >> /usr/local/etc/php/conf.d/xdebug.ini

（2021.09.04）Xdebugのバージョンが3になったので、設定内容を修正しました。

docker-php-ext-enable xdebugで/usr/local/etc/php/conf.d/docker-php-ext-xdebug.iniのファイルが作られます。

Xdebugの設定は以下の通りです。

設定	役割	初期値
xdebug.mode=debug	ステップデバッグを有効にします。	develop
xdebug.start_with_request =yes	ステップデバッグは、 PHP要求の開始時に起動します。	default
xdebug.client_port=9003	Xdebugがリモートホストで接続を試みるポート	9003
xdebug.client_host =host.docker.internal	デバッグ接続を開始するときにXdebugが接続を試みるIPアドレスまたはホスト名。host.docker.internalはホストが使用する内部IPアドレスに解決される特別なDNS名です。	localhost

Xdebug公式ドキュメントはこちら
Xdebug: Documentation » Step Debugging

host.docker.internalについてはこちら
Explore networking features on Docker Desktop | Docker Documentation

docker-compose.yml の作成

docker-compose.yml の内容を次のようにします。

version: "3"
services:
  wordpress:
    build: .
    depends_on:
      - db
    ports:
      - "8080:80"
    volumes:
      - ./wp-content:/var/www/html/wp-content
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: database
      WORDPRESS_DB_USER: user
      WORDPRESS_DB_PASSWORD: password
  db:
    image: mysql:5
    ports:
      - "3306:3306"
    environment:
      MYSQL_DATABASE: database
      MYSQL_USER: user
      MYSQL_PASSWORD: password
      MYSQL_ROOT_PASSWORD: password
volumes:
  db_data:

mysqlのバージョンを固定しているのは、最新版ではセキュリティが強化されているので、実行時にエラーが出るためです。

Visual Studio Code の設定

下記リンクからVisual Studio Codeをインストールします。

code.visualstudio.com

ワークスペースの作成

ファイルメニューのワークスペースにフォルダーを追加でDockerfileのあるフォルダーをワークスペースに追加して、名前を付けてワークスペースを保存しておきます。

デバッグ用の拡張機能の追加

キーボードのCtrl + Shift + xを押すと拡張機能の追加画面が出ので、
PHP Debugを検索してインストールします。

launch.json の設定

デバッグメニューの構成を追加を選択して、

PHPを選択します。

すると次のようなlaunch.jsonができるので、

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

pathMappingsを追加してwp-contentフォルダをデバッガで追えるようにしておきます。

{
    // IntelliSense を使用して利用可能な属性を学べます。
    // 既存の属性の説明をホバーして表示します。
    // 詳細情報は次を確認してください: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "pathMappings": {
                "/var/www/html/wp-content": "${workspaceFolder}/wp-content"
            },
            "port": 9003
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9003
        }
    ]
}

Dockerコンテナを立ち上げてデバッグ

Visual Studio Code のメニューのターミナル > 新しいターミナル（ショートカットCtrl + Shift + `）でターミナルを表示させます。

コマンド$ docker-compose up -dでコンテナを立ち上げます。
Visual Studio Code のデバッグメニューのデバッグの開始でデバッグできるようになっているはずです。