VSCode + Docker + XdebugでPHPのデバッグ環境を構築

概要

前回、Docker（nginx + PHP-FPM）を使ってPHPの実行環境を構築しました。
基本構文を覚えたばかりなのでコード毎に動作を追いたいと思った次第です。

Docker（nginx + PHP-FPM + Xdebug）+ VisualStudio Codeでデバッグが行える環境を構築します。

前回作成したDocker（nginx + PHP-FPM）のPHP実行環境にXdebugを追加する形で構築します。

目次

• 参考サイト様
• 環境
• デバッグ環境の構築
  • 成果物
  • ディレクトリ構成
  • nginxのconfigファイル作成
  • Dockerfileの作成
    • peclって？
  • docker-compose.ymlの作成
  • xdebug.iniの作成
    • host.docker.internalって
  • VisualStudio Code側の設定
    • VS CodeにXdebug拡張をインストール
    • デバッグ構成の追加
  • デバッグの実行
• トラブルシュート：Cannot load Xdebug - it was already loadedが発生する。
• 雑感

参考サイト様

• Installation - Xdebug: Documentation 🔗
• php - Docker Hub 🔗
• [PHP]pecl,phpize,extensionという単語を見て頭痛がするあなたへの処方箋 · DQNEO起業日記 🔗
• Remote Debugging - Xdebug: Documentation 🔗
• [PHP] Xdebug のリモートデバッグ、理解していますか？ - Qiita 🔗
• IDE debugging with Docker, nginx, PHP7-FPM and Xdebug - Stack Overflow 🔗
• Networking features in Docker Desktop for Mac | Docker Documentation 🔗
• felixfbecker/vscode-php-debug: PHP Debug Adapter for Visual Studio Code 🐞⛔ 🔗
• php - PHP7 CLI attempts to load xdebug twice - “Cannot load Xdebug - it was already loaded” - Stack Overflow 🔗

環境

• Mac OS X Mojave 10.14.4
• Visual Studio Code Version: 1.33.1

$ docker -v
Docker version 18.09.2, build 6247962
$ docker-compose -v
docker-compose version 1.23.2, build 1110ad01

デバッグ環境の構築

DockerのnginxとPHP-FPMコンテナで構成されたPHP実行環境です。
前回は、PHP-FPMコンテナに公式イメージを使用していましたが
今回は同じイメージをベースにDockerfileを作成しXdebugをコンテナにインストールします。

そしてVisualStudio Code上でデバッグが実行できるようにします。

成果物

https://github.com/Lycheejam/php-crud-sample 🔗

ディレクトリ構成

$ tree .
.
├── docker-compose.yml
├── docker-configs
│   ├── nginx
│   │   └── nginx.conf
│   └── php-fpm
│       ├── Dockerfile
│       └── xdebug.ini
└── src
    └── index.php

nginxのconfigファイル作成

nginxについては前回と変わりないので解説なしです。
confファイルのみ載せておきます。
下記の前回記事をご参照ください。

• docker-configs/nginx/nginx.conf

server {
  listen 80;
  server_name localhost;

  root  /var/phpapp;
  index index.php index.html;

  location / {
    try_files $uri $uri/ /index.php$is_args$args;
  }
  # pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
  #
  location ~ \.php$ {
     fastcgi_pass   php:9000;
     fastcgi_index  index.php;
     fastcgi_param  SCRIPT_FILENAME  $document_root$fastcgi_script_name;
     include        fastcgi_params;
  }
}

Dockerfileの作成

PHP-FPMのDockerイメージをベースにXdebugをインストールします。
インストールコマンドについては公式ドキュメントに従います。
また、DockerHubのPHPイメージのページにも記載がありました。

• 参考：Installation - Xdebug: Documentation 🔗
• 参考：php - Docker Hub 🔗

下記のパスでPHP-FPM用のDockerfileを作成します。

• docker-configs/php-fpm/Dockerfile

FROM php:7-fpm

RUN pecl install xdebug && \
    docker-php-ext-enable xdebug

コンテナ作成時にpeclコマンドでXdebugをインストールします。
そして、docker-php-ext-enableコマンドで拡張機能を有効化します。

peclって？

peclと言うコマンドを初めて見たので「んんん？？？」となりましたが下記の記事がわかりやすく参考になりました。

• 参考：[PHP]pecl,phpize,extensionという単語を見て頭痛がするあなたへの処方箋 · DQNEO起業日記 🔗

dockerコンテナでしか見てないんですがCentOSだとデフォルトでインストールされてるっぽいんですかね？

$ docker run -it centos bash
[root@5245070f6cfc /]# cat /etc/redhat-release
CentOS Linux release 7.6.1810 (Core)
[root@5245070f6cfc /]# yum provides pecl
//省略
1:php-pear-1.9.4-21.el7.noarch : PHP Extension and Application Repository framework
Repo        : base
Matched from:
Filename    : /usr/bin/pecl

docker-compose.ymlの作成

前回記事同様にdocker-compose.ymlを作成します。

• docker-compose.yml

version: "3.7"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
    volumes:
      - ./docker-configs/nginx/nginx.conf:/etc/nginx/conf.d/default.conf
  php:
    build: "./docker-configs/php-fpm"
    volumes:
      - ./src/:/var/phpapp/
      - ./docker-configs/php-fpm/xdebug.ini:/usr/local/etc/php/conf.d/xdebug.ini

前回からの変更点はphpセクションをimageからbuildに変更し、先程作成したDockerfileを使用してコンテナが作成されるように変更しました。 また、この後で作成しますがxdebug.ini（Xdebugの設定ファイル）をマウントしています。

xdebug.iniの作成

Xdebug用の設定ファイルを作成します。
公式ドキュメントの下記を参考に設定します。
また、日本語での解説記事とStackOverflowが参考になりました。

• 参考：Remote Debugging - Xdebug: Documentation 🔗
• 参考：[PHP] Xdebug のリモートデバッグ、理解していますか？ - Qiita 🔗
• 参考：IDE debugging with Docker, nginx, PHP7-FPM and Xdebug - Stack Overflow 🔗

下記のパスでxdebug.iniを作成します。

• docker-configs/php-fpm/xdebug.ini

[xdebug]
; リモートデバッグ有効化
xdebug.remote_enable = On
; ホスト指定（host.docker.internalはMac以外じゃ使えない）
xdebug.remote_host = host.docker.internal
; ホスト側のポート指定
xdebug.remote_port = 9000
; リモートデバッグの自動開始
xdebug.remote_autostart = On

host.docker.internalって

Dockerコンテナからホストに接続する際に使える便利なやつ。 ただドキュメントにはDocker Desktop for Mac以外じゃ使えないよって記載があるのでWindowsの場合はがんばってください。

• 参考：Networking features in Docker Desktop for Mac #I WANT TO CONNECT FROM A CONTAINER TO A SERVICE ON THE HOST | Docker Documentation 🔗

VisualStudio Code側の設定

次はVS Code側で操作します。

VS CodeにXdebug拡張をインストール

拡張機能から「xdebug」をインストールします。

デバッグ構成の追加

メニューからデバッグ→構成の追加...を押下すると下記画像の様に選択肢が出るのでPHPを選択します。
すると.vscode配下にlaunch.jsonが作成されるのでそれを編集します。

構成追加	環境選択	できた

launch.jsonの設定内容については下記の公式ドキュメントを参考に設定します。

• 参考：felixfbecker/vscode-php-debug: PHP Debug Adapter for Visual Studio Code 🐞⛔ 🔗

抜粋します。
編集箇所にコメントをつけてます。

• .vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      //下記を追加
      "pathMappings": {
        "/var/phpapp": "${workspaceRoot}/src"
      }
    }
    //省略
  ]
}

pathMappingsでPHPファイルのディレクトリ（コンテナ側のパスとホスト側のパス）を指定します。
${workspaceRoot}はプロジェクトのルートディレクトリになります。
※stopOnEntryをtrueにするとデバッグ開始時に自動的にコード先頭で止まってくれます。

デバッグの実行

Docker Composeでコンテナを起動します。

$ docker-compose up

VSCodeからデバッグを開始してブレークポイントを設定します。

そして、ブラウザからhttp://localhost:8080へアクセスするとブレークポイントで停止することが確認できます。

トラブルシュート：Cannot load Xdebug - it was already loadedが発生する。

docker-compose upでコンテナを起動するとコンテナ自体は上がってるっぽいですがエラーが発生していてデバッグができませんでした。
※デバッグを開始してもうんともすんとも言わない状況。

原因はxdebug.iniにzend_extensionを指定していたことが原因でした。

[xdebug]
; 下記を指定しているとエラーが発生した。
zend_extension="/usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so"
xdebug.remote_enable = On
xdebug.remote_host = host.docker.internal
xdebug.remote_port = 9000
xdebug.remote_autostart = On

このzend_extensionをxdebug.iniへ追加したのはコンテナ初回起動時のログに下記を追加してねと出力されていたので追加した次第なんですが…

zend_extension="/usr/local/lib/php/extensions/no-debug-non-zts-20180731/xdebug.so"

下記の類似のStackOverflowを参考にとりあえずパスの指定をコメントアウトしたら動きました。

• 参考：php - PHP7 CLI attempts to load xdebug twice - “Cannot load Xdebug - it was already loaded” - Stack Overflow 🔗

雑感

ホントはPHPでCRUDやってみよーと初めたんですが「え、PHPのデバッグでechoとvar_dumpのみ？？？」となってしまったので環境作ってみました。
PHPはわかんないことだらけで時間がかかりますね…