Introduction

I wanted to create a PHP debug environment using Xdebug in the docker (windows) + VSCode development environment. Since the version of xdebug has increased from 2 to 3, the description method of php.ini has changed a lot, so I will share it as a memo.

environment

Docker Desktop (OS:Windows 10 Home) I noticed that Docker Desktop can be used on windows 10 Home. If you haven't tried it yet, we recommend installing it. Thanks to this, you can create a development environment in much the same way as on a Mac.

Visual Studio Code VS Code is popular these days. It is convenient because it has many extensions.

Xdebug 3 (installed in Docker container)

Create a PHP + Apache container and install Xdebug in it. It is convenient because you do not need to install any PHP other than the above two in the local environment.

If you install Xdebug without specifying a version, version 3 is now installed. Along with this, the way of writing php.ini has changed. (Details will be explained below)

Various installations

1. Install Docker Desktop

Install Docker Desktop on Windows Home (https://docs.docker.jp/docker-for-windows/install-windows-home.html)

I think that there is no problem if you follow the procedure on the following page. (Windows 10 Home)

2. Install Visual Studio Code

VSCode Download Page

Download and install from here.

3. Install VS Code extension

Install "PHP Debug" as an extension of VS Code. Procedure: Install "PHP Debug"-> "PHP Debug" in the sidebar "Extensions"-> Search field

Please restart VS Code after installation.

Install Xdebug in Docker container

0. Directory structure

This time it was a sample, so I configured it easily.

1. Description of DockerFile, docker-compose.yml

This time, to make it easier, create a Dockerfile to install Xdebug with a command in a PHP + Apeche container.

`DockerFile`


FROM php:7.3-apache

RUN apt-get update && apt-get install -y \
    git \
    unzip \
    vim

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

Also describe docker-compose.yml as follows according to the directory structure.

`docker-compose.yml`


version: '3'

services:
    app:
        build:
            context: ./docker
        container_name: app
        stdin_open: true
        tty: true
        ports:
            - '5000:80'
        volumes:
            - ./src:/var/www/html
            - ./docker/php.ini:/usr/local/etc/php/php.ini

2. Create and describe launch.json

VS Code sidebar "Run"-> Click "Create launch.json file"-> Select "PHP" from the environment selection At this stage, launch.json will be automatically generated and the directory structure will be as shown in the image below. Add pathMappings to the automatically generated launch.json and do as follows.

`launch.json`


{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9000,
            "pathMappings": {
                "/var/www/html/": "${workspaceRoot}/src"
            }
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

3. Description of php.ini (main subject)

This is the part that made me decide to write this article. I wrote it as follows.

`php.ini`


[xdebug]
;Enable remote debugging
xdebug.mode=debug
;Automatic start of remote debugging
xdebug.start_with_request=yes
;Host designation
xdebug.client_host=host.docker.internal
;Specifying the port on the host side
xdebug.client_port=9000
;Specify VSCODE as IDE
xdebug.idekey="VSCODE"

It was necessary to change the writing style when the version of Xdebug changed from 2 to 3.

Official Document: Upgrading from Xdebug 2 to 3

With the settings described this time, the following changes are required. In addition to this, it seems that the writing style has changed in various ways, so please refer to the official document for details.

Enable remote debugging

Xdebug 2: xdebug.remote_enable=1 Xdebug 3: xdebug.mode=debug

Automatic start of remote debugging

Xdebug 2: xdebug.remote_autostart=1 Xdebug 3: xdebug.start_with_request=yes

Host designation

Xdebug 2: xdebug.remote_host=host.docker.internal Xdebug 3: xdebug.client_host=host.docker.internal

Previously, "host.docker.internal" was limited to Mac, but now it can be used on Windows.

Specifying the port on the host side

Xdebug 2: xdebug.remote_port=9000 Xdebug 3: xdebug.client_port=9000

4. Create index.php

Try it at the sample level.

`index.php`


<?php
    echo 'Hello World';

5. Build and launch a Docker container

After starting Docker Desktop, execute the following command from View Windows PowerShell or VS Code-> Terminal.

`Terminal`


$ docker-compose up -d --build

Run debug

1. Set breakpoints, debug execution

Click to the left of the row you want to place to set a breakpoint. In this state, press the F5 key or press the green triangle mark "Start Debugging" to execute debugging.

2. Connect with browser

I set port number 5000 with docker-compose, so connect from the browser.

3. Check with VS Code

If you execute steps 1 and 2, it will stop at the breakpoint as shown in the image below. This is a success!

in conclusion

Due to the changes that accompany the version change of Xdebug, I took time to identify the cause of the debug environment not working. I hope there is a similar person and it helps.

[Be careful about changing the version of Xdebug! ] Create a development environment with Xdebug3 + docker + VS Code