PHP - (Debug|Debugger) with Xdebug in Docker

> Procedural Languages > Php

1 - About

How to debug a PHP application running in a docker container.

This articles is split in two:

  • a configuration part that you need to perform only ones
  • a debug part that you must perform each time you want to debug your script

3 - Environment

  • Browser: Firefox
  • IDE: Intellij
  • Docker with php 7.2, Xdebug 2.6 and Apache

4 - Prerequisites

5 - Configuration

5.1 - Docker

  • go to the directory of your application and create a container with the image gerardnico/php-dev image. Example in DOS:
cd YourApplication
docker run ^
    --name myapp ^
    -d ^
    -p 80:80 ^
    -v %cd%:/var/www/html ^

The image use the default internal switch ip of docker. Be sure to have the same one, otherwise the Apache server would not find the IDE.


If you want to get more information on the configuration of Xdebug. See xdebug


5.2 - IDE Client Start listening

The IDE by default listen to the port 9000 but you can change it.

Example Intellij:

  • Start listening incoming connection with you IDE (below is an Intellij snapshot)

  • Verify that the Client Xdebug port (9000) is listening on the IDE host. Example with tcpview.

Optional verify that you have a connection from the container to your IDE host with nmap

  • Start bash into the container
docker exec -it myApp bash
  • Determine the Docker Windows host IP by listing the vEthernet (DockerNAT) interface (By default, this is
netsh interface ip show addresses "vEthernet (DockerNAT)"
Configuration for interface "vEthernet (DockerNAT)"
    DHCP enabled:                         No
    IP Address:                 
    Subnet Prefix:               (mask
    InterfaceMetric:                      15
  • Install nmap and make a prob
apt-get install -y nmap
# scan the port 9000
nmap -Pn -p T:9000
  • The output should show that the port open is
Starting Nmap 7.40 ( ) at 2018-06-10 19:58 UTC
Nmap scan report for
Host is up (0.0012s latency).
9000/tcp open  cslistener

Nmap done: 1 IP address (1 host up) scanned in 0.37 seconds

5.3 - Browser

In order to activate the debugger, a special GET/POST or COOKIE parameter must be set.

It can be easily done through a browser plugin:

6 - Start Debug

Now that the whole system is set up, we can start a debug session with the help of the following steps.

I use and you can see the dokuwiki application on the snapshot.

  • Start listening incoming connection with you IDE (below is an Intellij snapshot)

  • Add a breakpoint in your script
  • Enable Xdebug in your browser

  • Refresh the php page
  • Accept to debug the page in your IDE (Intellij)

  • Normally, it can't map the php script server path with the local script, you need to help him. If the same server is used for the IDE and the Web Server, you can just uncheck the blue checkbox on Intellij

  • After reaching the breakpoint the debugger is suspended and you can see the script stack and the value of the variables


7 - Annexe

7.1 - Xdebug

Xdebug configuration section for docker.

In a docker environment, the host ip can be found in docker network settings:

zend_extension= D:\xampp\php\ext\php_xdebug-2.4.0-5.6-vc11.dll
xdebug.remote_host =
xdebug.profiler_output_dir=  D:\xampp\php\tmp/

8 - Support

8.1 - Cannot accept external Xdebug connection: Cannot evaluate expression 'isset($_SERVER['PHP_IDE_CONFIG'])'

You may see this error when an XDebug Session start.

Cannot accept external Xdebug connection: Cannot evaluate expression 'isset($_SERVER['PHP_IDE_CONFIG'])'

The environment variable PHP_IDE_CONFIG is used to define the debug server name. See Configuring path mappings in Zero Configuration Debuggin

This is because as the incoming connection doesn't match any server in your server definition, the IDE will try to read this variable.


  • Suppress all servers. The IDE will make one for you

9 - Documentation / Reference