MediaWiki-Docker/Configuration recipes/Xdebug



To use XDebug with MediaWiki running inside a docker container, you have to tell the PHP environment running inside the container to connect to the IDE on the host machine. To do this, set the XDEBUG_CONFIG variable in your .env file.

IMPORTANT: The following values likely have to be adjusted for your system in the configuration examples below (especially where it says CHANGEME in the snippet).

  • client_host or remote_host: this has to be the IP address of the host system (your laptop) as seen from inside the container. Generally, this will just the IP address assigned to the host in the local network. On Linux, you can use ifconfig or ip -o -4 addr list to list these addresses. Caveat: if you are running docker in a virtual machine, additional configuration may be necessary. If you are using Docker Desktop (on Mac or Windows), set client_host to host.docker.internal.
  • client_port or remote_port: adjust this to the port the IDE is listening on (or a port that is configured to forward to the IDE). For XDebug 3.0 and up, the default port is 9003; for XDebug 2 port 9000 is the default.
  • idekey: the key to use when connecting to the IDE. This has to match the key configured in the IDE. For PhpStorm, the default is PHPSTORM, for VS Code it's VSCODE
  • serverName : the server name to use by PhpStorm to apply path mappings when manually running command line scripts (see PhpStorm documentation ).

Caveat: as of November 4 2020, PHP_IDE_CONFIG needs a patch for docker-compse.yaml . And it still didn't quite work for me .

Latest Version (3.0+)


Starting in version 3.0, XDebug's default port is 9003.

# Use idekey=VSCODE for VS Code
# If you are using Docker Desktop (Windows/Mac), set client_host=host.docker.internal
XDEBUG_CONFIG='mode=debug start_with_request=trigger client_host= client_port=9003 idekey=PHPSTORM' 

# Only needed for PHPStorm

Older Versions (2.x)


Older versions of XDebug (< 3.0) use a different syntax for XDEBUG_CONFIG, and use port 9000 by default:

# Use idekey=VSCODE for VS Code
# If you are using Docker Desktop (Windows/Mac), set client_host=host.docker.internal
XDEBUG_CONFIG='remote_enable=1 remote_mode=req remote_host= remote_port=9000 idekey=PHPSTORM'

IDE Integration


For integration with VS code, see the Xdebug config for VS Code recipe.

For integration with PhpStorm, see the blog post on Debugging MediaWiki with PhpStorm. If you use PhpStorm to run the code, you may not need the above configuration, since PhpStorm will set the appropriate environment variables automatically.



Debugging your debugger? Here are some tips if things are not working.

1. Shell into your running Docker container for MediaWiki PHP (docker compose exec mediawiki /bin/bash) and ensure that the proper environmental variables have been set using the env command.

2. Ensure that XDebug is present in your PHP installation: php -i | grep 'xdebug'

3. Try running the XDebug CLI from inside your container; if this works, then the problem likely lives at the level of IDE configuration or a firewall which blocks the request (on Linux, you may take a look at your iptables or ufw rules).

See also