Introduction

I found out there are many outdated setup articles which may not work for the Xdebug 3.1.X version. Therefore I jot down the setup of PHP with Xdebug and docker.

Setup

edit dockerfile to install xdebug

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

copy xdebug config to php config folder

[xdebug]
xdebug.mode=off
xdebug.start_with_request = yes
xdebug.client_host = "host.docker.internal"
xdebug.idekey="VSCODE"

In docker-compose.yml, add host.docker.internal to extra_hosts as follow

services:
    app:
      extra_hosts:
        - host.docker.internal:host-gateway

open vscode and create a launch.json file
make sure the attribute pathMappings is set correctly.

If you have installed the Remote Development extension from Microsoft, you may face an issue that the breakpoint does not work because of the wrong pathMappings.

"the path of project in container":"${workspaceFolder}"

After you Attach to Running Container, your vscode is "working" inside the container and your pathMappings should be like this.

"${workspaceFolder}":"${workspaceFolder}"

Things should be working right now and you can try adding breakpoints to check whether the process is broken correctly.

Explaination

extra_hosts:

it adds hostname mappings to the container network interface configuration. Entries will be added to the container /etc/hosts file

host.docker.internal:

Docker has defined a special magic DNS, host.docker.internal, that every service on the host can be accessed from the container at host.docker.internal

host-gateway:

A special string which points to the host gateway.

Now we know host.docker.internal:host-gateway in extra_hosts is going to map host.docker.internal to the host's gateway which the container can connect the services running from outside.

To sum up

It seems that there are not many articles and blogs discussing the Xdebug with docker, so it is a memo to remind myself if I need to have the same setup in the future.