Setup XDebug 3 In WordPress Dev Env (Docker + WSL 2)

Question

I can't make the step debugging work with XDebug 3 on WP Dev Env inside Docker + WSL 2

Here is my folder structure

Ignore the references.txt file, it has no use here.

The wordpress folder will contain all wordpress files. It is an empty folder at start but will be populated with WordPress files upon setting up the dev env via docker-compose up.

Note: All these files are inside ubuntu 20.04 installed via WSL 2.

---

docker-compose.yml file

version: "3.9"

services:
  db:
    image: mysql:5.7
    command: --default-authentication-plugin=mysql_native_password
    restart: always
    environment:
      MYSQL_DATABASE: "wordpress"
      MYSQL_USER: "wp"
      MYSQL_PASSWORD: "secret"
      MYSQL_ROOT_PASSWORD: "secret"
    volumes:
      - db_data:/var/lib/mysql
    ports:
      - 4406:3306

  wp:
    build: 
      context: ./build
      dockerfile: Dockerfile
    image: wp-local
    restart: always
    depends_on: 
      - db
    environment:
      WORDPRESS_DB_HOST: db:3306
      WORDPRESS_DB_NAME: "wordpress"
      WORDPRESS_DB_USER: "wp"
      WORDPRESS_DB_PASSWORD: "secret"
      WORDPRESS_DEBUG: 1
      WORDPRESS_CONFIG_EXTRA: |
        define( 'WP_DEBUG_LOG', true );
        define( 'WP_DEBUG_DISPLAY', false );
        /* https://gist.github.com/dianjuar/1b2c43d38d76e68cf21971fc86eaac8e */
        define( 'FS_METHOD', 'direct' ); // Required to allow installing of plugins without the need for ftp access
    volumes:
      - ~/local_wp/wordpress:/var/www/html
    ports:
      - 8888:80

  phpmyadmin:
    image: phpmyadmin
    restart: always
    depends_on:
      - db
    ports:
      - 9999:80
    environment:
      MYSQL_USER: "wp"
      MYSQL_PASSWORD: "secret"
      MYSQL_ROOT_PASSWORD: "secret"

volumes:
  db_data:

Note: yes I intentionally mapped ~/local_wp/wordpress instead of ./wordpress here in the wp service as I have noticed if I used the later, it is a bit slow? I don't know why? It's slow like installing wp plugins, takes over a minute if I used the later but for the former its like 9-10 sec only.

---

build/Dockerfile

FROM wordpress:5.7.2-php7.4-apache

COPY ./php.ini /usr/local/etc/php/php.ini

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

# Copy our xdebug.ini into the location the container's xdebug.ini
COPY ./xdebug.ini /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini

ENTRYPOINT ["docker-entrypoint.sh"]

CMD ["apache2-foreground"]

---

The php.ini file really has just the default contents I copied here https://github.com/php/php-src/blob/master/php.ini-development , nothing special here.

---

xdebug.ini

zend_extension=xdebug

[xdebug]
xdebug.mode = debug
xdebug.start_with_request = yes
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000

---

Again I can't seem to make the step debugging work. I used php debug extension for VS Code btw and followed its intructions, still no good.

I also got this on debug.log of WordPress

[30-May-2021 02:34:11 UTC] Xdebug: [Step Debug] Time-out connecting to debugging client, waited: 200 ms. Tried: host.docker.internal:9000 (through xdebug.client_host/xdebug.client_port) :-(

I tried exposing port 9000 on docker-compose.yml file, it does not work.

I tried removing the xdebug.client_host = host.docker.internal from xdebug.ini, it does not work.

I tried exposing port 9000, 9001, 9002, 9003 on docker-compose.yml file as I notice sometimes it uses port 9000, sometimes 9003, still does not work.

Any help is much appreciated.

Thanks in advance.

Answer 1

I managed it to work but not sure what helped.

Modify php.ini as in https://veselin.dev/blog/xdebug-3-in-docker leave only those 4 lines for xdebug it's enough.

It works without ports and hostnames in launch.json.

It works without exposing 9003 port or adding extra_hosts for php contaner.

Shut down all firewall. Maybe it is worth to start from. Actually you may just open 9000 port but it is not that easy on windows...

PS You can always check routes by pinging you actual ip from php image.

cd your/project/dir
docker-compose exec wp "bash" # wp is php container name. If bash didn't work use sh instead
apt-get update && apt-get install iputils-ping
ping 192.168.0.147 # your local ip goes here. It should be accessible

If you can't even ping your PC from debug server you can't go further.

Answer 2

The php.ini file really has just the default contents I copied here https://github.com/php/php-src/blob/master/php.ini-development , nothing special here.

I would advice against doing that. Just leave the file empty, and only put in the changes that you want to make from the default. PHP doesn't need a filled in php.ini file.

I tried exposing port 9000 on docker-compose.yml file, it does not work.

Exposing any Xdebug port in docker-compose.yml would not work, because it is Xdebug that makes the connection, and exposed ports are for incoming connections only.

In this case it is trying to connect to host.docker.internal on port 9000, and it can't.

I tried exposing port 9000, 9001, 9002, 9003 on docker-compose.yml file as I notice sometimes it uses port 9000, sometimes 9003, still does not work.

Again, exposing it wouldn't do anything. It is true that Xdebug sometimes uses port 9000 or port 9003 by default, with the first one the default for Xdebug 2, and the second one the default of Xdebug 3. But you've configured xdebug.client_port to use port 9000, so that doesn't matter.

Do make sure that the VS Code configurations do mention port 9000 too though.

I tried removing the xdebug.client_host = host.docker.internal from xdebug.ini, it does not work.

Xdebug needs to know to which host to connect, and that host needs to be visible and contactable from the same (docker internal?) network.

host.docker.internal doesn't work on Linux (which is what WSL2 is). You either need to configure the real IP of the machine of where your IDE is running, or, if you're running a new enough Docker Engine (20.10.x) you can make an additional extra-hosts entry in your wp service:

wp:
  …
  image: wp-local
  extra_hosts:
    - "host.docker.internal:host-gateway"
  …