I think I'm pretty close (I hope) to having xdebug running in a docker container, aiming to connect via Visual Studio Code.

I think that maybe I'm supposed to add a config to the /etc/hosts file in the container, directing an IP address to the url my files are being served over, but am not sure what that IP address is supposed to correspond to.

The error:

via xdebug_info() (and in /tmp/xdebug.log):

[Step Debug] Could not connect to debugging client. Tried: localhost:9003 (through xdebug.client_host/xdebug.client_port) :-(

via telnet localhost 9003:

Trying 127.0.0.1...
Trying ::1...
telnet: Unable to connect to remote host: Cannot assign requested address

The xdebug.ini file:

zend_extension=xdebug.so

[xdebug]
xdebug.mode=debug
xdebug.start_with_request = yes
xdebug.discover_client_host = 0
xdebug.remote_connect_back = 1
xdebug.client_port = 9003
xdebug.force_error_reporting = 1
xdebug.remote_host=host.docker.internal
xdebug.idekey=VSCODE
xdebug.mode = debug
xdebug.log=/tmp/xdebug-local.log

The launch.json:

  "version": "0.2.0",
  "configurations": [
    {
      "type": "php",
      "request": "launch",
      "name": "xDebug listen",
      "port": 9003,
      "url": "http://mzmbo.test",
      "stopOnEntry": true,
      "pathMappings": {
        "/var/www/html/wp-content/plugins/my-wp-plugin": "${workspaceRoot}/my-wp-plugin"
      }
    }
  ]
}

The Dockerfile:

FROM "wordpress:${WP_VERSION:-latest}"

RUN apt-get update -y \
  && apt-get install -y \
      libxml2-dev \
      vim \
      lsof \
      ufw \
      telnet \
  && apt-get clean -y \
  && ufw allow 9003 \
  && docker-php-ext-install soap  \
  && docker-php-ext-enable soap \
  && pecl install xdebug \
  && docker-php-ext-enable xdebug

# Replace php.ini
COPY php.ini /usr/local/etc/php
COPY docker-php-ext-xdebug.ini /usr/local/etc/php/conf.d

Finally the docker-compose.yml:

version: "3"

services:
  wordpress:
    build: .
    environment:
      VIRTUAL_HOST: "myproject.test"
      WORDPRESS_DB_HOST: "mysql"
      WORDPRESS_DB_NAME: "wordpress"
      WORDPRESS_DB_PASSWORD: ""
      WORDPRESS_DB_USER: "root"
    depends_on:
      - "mysql"
    networks:
      - "front"
      - "back"
    volumes:
      - "wp:/var/www/html:rw"
      - "./my-wp-plugin:/var/www/html/wp-content/plugins/my-wp-plugin:ro"

Result of xdebug_info() shows:

Step Debugger   ✔ enabled
xdebug.client_host  localhost
xdebug.client_port  9003
xdebug.start_with_request   yes

I bet I need to add a configuration, but not sure what.

Update

From this tutorial, I see that xdebug.discover_client_host=true "tells Xdebug to attempt to extract the IP of the client from the HTTP request", falling back to client_host if that fails. (It checks $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out which IP address to use.) This is the config that replaces xDebug 2's remote_connect_back. Most of xDebug's significant configs have changed between v2 and v3.

Still getting the same connection errors, though:

Trying 192.168.16.1...
telnet: Unable to connect to remote host: Connection refused

And in the logs:

[21] [Step Debug] WARN: Could not connect to client host discovered \
 through HTTP headers, connecting to configured address/port: localhost:9003. :-|
[21] [Step Debug] WARN: Creating socket for 'localhost:9003', \ 
poll success, but error: Operation now in progress (29).192.168.16.1:9003 (from HTTP_X_FORWARDED_FOR HTTP header), \
 localhost:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(

I tried adding an /etc/hosts entry pointing 192.168.16.1 to myproject.test (in the Docker container) but haven't figured out how to flush the DNS records in the container. Maybe I need to add extra host mapping in the container?

Came across a post that suggested Lando, which appears to wrap Docker, can ease some of this pain, but I'm not ready to give up on this yet, so thank you very much if you've read this far.

Solution (gratefully) accepted below.

I also needed to make a change to the VS Code launch.json file:

"stopOnEntry": false

Because I don't have the WP codebase in my repo, just a specific plugin. With "stopOnEntry": true, the xDebug plugin was looking for an (non-existent) index.php file (starting point) in the "${workspaceRoot}, as opposed to just checking for breakpoints, which is what I required, my local codebase just being part of the entire application.

Also, I think that the # comments in the accepted answer were invalidating the .ini file, so watch out for that if it seems like your settings aren't coming up.