PHP：WSL+DockerでのPHPデバッグ方法

公開：2026.04.19 22:06

WSL+DockerでのPHPデバッグ方法

WSL Docker上に構築したPHPコンテナをWindows上のVSCodeからデバッグする方法。

環境

◆ Windows 11 25H2 (26200.8037) + WSL + Docker
◆ WSL：
PS C:\Users\xxx> wsl --version
WSL バージョン: 2.3.24.0
カーネル バージョン: 5.15.153.1-2
WSLg バージョン: 1.0.65
MSRDC バージョン: 1.2.5620
Direct3D バージョン: 1.611.1-81528511
DXCore バージョン: 10.0.26100.1-240331-1435.ge-release
Windows バージョン: 10.0.26200.8037
◆ Ubuntu：
xxx@xxx:~$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 24.04.1 LTS
Release: 24.04
Codename: noble

PHP環境は過去記事「Docker 学習 #4：Docker Composeを学ぶ」で作成したPHPコンテナを使用する。

手順

1. PHPコンテナに接続
docker exec -it (CONTAINER ID) /bin/bash
※ (CONTAINER ID)は "docker ps" コマンドで確認。

実行結果：
xxxxxxxx@yyyy:~/docker/php$ docker ps
CONTAINER ID   IMAGE                   COMMAND                  CREATED         STATUS         PORTS                                                    NAMES
73b35c593dd3   php:8.3-apache          "docker-php-entrypoi…"   5 seconds ago   Up 5 seconds   0.0.0.0:8080->80/tcp, [::]:8080->80/tcp                  php-php-1
0fcfeb63acfd   mysql:8.0               "docker-entrypoint.s…"   5 seconds ago   Up 5 seconds   0.0.0.0:3306->3306/tcp, [::]:3306->3306/tcp, 33060/tcp   php-db-1
ee1128843dec   phpmyadmin/phpmyadmin   "/docker-entrypoint.…"   5 seconds ago   Up 5 seconds   0.0.0.0:8081->80/tcp, [::]:8081->80/tcp                  php-phpmyadmin-1
xxxxxxxx@yyyy:~/docker/php$ docker exec -it 73b35c593dd3 /bin/bash
root@73b35c593dd3:/var/www/html#

2. PHPコンテナにxdebugをインストール
PHPコンテナにて以下コマンドを実行
pecl install xdebug

実行結果：
root@73b35c593dd3:/var/www/html# pecl install xdebug
downloading xdebug-3.5.1.tgz ...
Starting to download xdebug-3.5.1.tgz (282,739 bytes)
　：
Build process completed successfully
Installing '/usr/local/lib/php/extensions/no-debug-non-zts-20230831/xdebug.so'
install ok: channel://pecl.php.net/xdebug-3.5.1
configuration option "php_ini" is not set to php.ini location
You should add "zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20230831/xdebug.so" to php.ini

続いて以下コマンドを実行
docker-php-ext-enable xdebug

実行結果：
root@73b35c593dd3:/var/www/html# docker-php-ext-enable xdebug

3. xdebug.ini作成
WSL(Ubuntu)にxdebug.iniを作成する。
保存場所は compose.yaml と同じ階層(~/docker/php)とした。
[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
 
; VSCode側へ接続する
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
 
; ログ（トラブル時）
xdebug.log=/tmp/xdebug.log

4. xdebug.iniをコンテナへコピー
WSL(Ubuntu)にて以下コマンドを実行しxdebug.iniをコンテナにコピーする。(CONTAINER ID)は "docker ps" コマンドで確認。
docker cp ./xdebug.ini (CONTAINER ID):/usr/local/etc/php/conf.d/xdebug.ini

実行結果：
xxxxxxxx@yyyy:~/docker/php$ docker cp ~/docker/php/xdebug.ini 73b35c593dd3://usr/local/etc/php/conf.d/xdebug.ini
Successfully copied 209B (transferred 2.05kB) to 73b35c593dd3://usr/local/etc/php/conf.d/xdebug.ini

5. compose.yaml修正
compose.yamlに以下記述を追加する。
extra_hosts:
  - "host.docker.internal:host-gateway"

※参考：現在のcompose.yaml
services:
  php:
    image: php:8.3-apache
    volumes:
      - ./www/html:/var/www/html
      - ./prophp_sample:/var/www/prophp_sample
      - ./php.ini-debug:/usr/local/etc/php/php.ini
      - ./prophp_sample.conf:/etc/apache2/conf-available/prophp_sample.conf
    extra_hosts:
      - "host.docker.internal:host-gateway"
    ports:
      - "8080:80"
    command: >
      sh -c "a2enconf prophp_sample && apache2-foreground"

  db:
    image: mysql:8.0
    volumes:
      - ./mysql:/var/lib/mysql
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
  
  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "8081:80"
    environment:
      PMA_HOST: db

6. コンテナ再起動
WSL(Ubuntu)にて以下コマンドを実行しコンテナを再起動する。
docker compose down
docker compose up -d --build

実行結果：
xxxxxxxx@yyyy:~/docker/php$ docker compose down
[+] down 4/4
 ✔ Container php-php-1        Removed                                                                  10.3s
 ✔ Container php-phpmyadmin-1 Removed                                                                   1.4s
 ✔ Container php-db-1         Removed                                                                   2.0s
 ✔ Network php_default        Removed                                                                   0.2s
xxxxxxxx@yyyy:~/docker/php$ docker compose up -d --build
[+] up 4/4
 ✔ Network php_default        Created                                                                   0.0s
 ✔ Container php-php-1        Started                                                                   0.3s
 ✔ Container php-phpmyadmin-1 Started                                                                   0.3s
 ✔ Container php-db-1         Started                                                                   0.3s

6. VSCodeにPHP Debug拡張機能をインストール
Windows上のVSCodeに "PHP Debug (xdebug.org)" をインストールする。

7.デバッグできない・・
WSL(Ubuntu)のIPアドレスを調べる。
ip route

実行結果：
  root@xxx:~/docker/php# ip route
  default via 172.25.0.1 dev eth0 proto kernel
  　：

8. debug.ini修正
PHPコンテナに接続し /usr/local/etc/php/conf.d/xdebug.ini を修正。
vimにて修正しようと思ったが "bash: vim: command not found" になってしまったのでvimをインストール。

実行結果：
root@05fa4e42bbcd:/usr/local/etc/php/conf.d# apt install vim
　：省略
Processing triggers for libc-bin (2.41-12+deb13u2) ...
"vim /usr/local/etc/php/conf.d.xdebug.ini" コマンドで xdebug.iniを修正
xdebug.client_host= の値を先ほど 7. で調べたIPアドレスに変更する。

9. コンテナ再起動

10. デバッグ実行
デバッグできました。

PHP WSL Docker VSCode デバッグ
-
ラベル:

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)

その他の記事

  • リモートデスクトップ：リモート側で音を出したい
    自宅には デスクトップPC(Win10Pro) と ノートPC(Win10Home) があるが、デスクトップPCのモニタが故障してしまった。 ということで、しばらくはノートPCからデスクトップへリモートデスクトップ接続し操作を行うことで代用しようと思うが、 そう...
  • ■ au Eメール受信で本体メモリ空き容量不足エラー
    au SHL23でEメールを受信しようとすると「本体メモリ空き容量不足」となり受信できない。 対処 ・他のアプリでキャッシュを大量に消費しているものがあればキャッシュを削除する。 ・不要なアプリはアンインストールする 今回はこれで受信できるようになった。 ...
  • ■ リモートデスクトップ接続で「お使いの資格情報は機能しませんでした」となる
    リモートデスクトップ接続しようとすると「お使いの資格情報は機能しませんでした」と表示され接続できない。 状況 ■ リモート側 ・Windows7 Pro：Workgroup環境 ・システムのプロパティ → [リモート]タブでリモートデスクトップの設定を「ネッ...
  • BitLocker：暗号化進捗を確認する方法
    BitLockerを有効化した際、どの程度暗号化が進んでいるのか分からない。 進捗を確認するには？ コマンドプロンプト(管理者)で "manage-bde -status" コマンドで確認できる。 C:\Windows\sys...
  • ■ iPhone PCコピー中に「デバイスに到達できません」となる
    iPhone7とPCをUSB(USB2.0)で接続し、エクスプローラにてiPhoneの写真とビデオ(Apple iPhone\Internal Storage\DCIM)をPCにコピーする。 その際、複数ファイルを選択しPCへ移動させると、高確率で「デバイスに到達できません」...