PHP - (Debug|Debugger) with Xdebug in Docker

Card Puncher Data Processing


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


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


Idea Firewall Public Allow



  • 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 $(pwd):/var/www/html \
cd YourApplication
docker run ^
    --name myapp ^
    -d ^
    -p 80:80 ^
    -v %cd%:/var/www/html ^

Host IP

The docker host IP (ie the IP of the laptop seen from Docker) is hard coded in the docker image.

This IP should match with yours.

The IP in your docker image can be found in the php.ini

# connect to the docker container
docker exec -it doku bash
# cat the php.ini
cat /usr/local/etc/php/php.ini | grep -i xdebug.remote_host

host.docker.internal is the default name given in a docker windows. If this property does not math your environment, you should change it.

How to find the IP can be seen here: docker host IP

Example if you use your own subnet such as below, the IP is something like

Docker Network Settings

If you want to get more information on the configuration of Xdebug. See How to install Php Xdebug ?

IDE Client Start listening

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

Example Intellij:

Intellij Xdebug Settings

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

Intellij Start Listening Php Debug Connection

  • Verify that the Client Xdebug port (9000 xdebug version2, 9003 xdebug version 3) is listening on the IDE host. Example with tcpview.

Idea Listening Client Xdebug 9000

Verify the connection from the container

  • 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
  • Get the host and port configuration
cat /usr/local/etc/php/php.ini | grep -i xdebug
xdebug.remote_port=9000 # client_port in version 3
xdebug.remote_host=host.docker.internal # client_host in version3

apt-get install -y nmap
# scan the port 9000 (xdebug version 2) or 9003 (xdebug version 3)
nmap -Pn -p T:9000 host.docker.internal
# or when nat
# nmap -Pn -p T:9000
  • The output should show that the port open is (not filtered)
Starting Nmap 7.40 ( ) at 2018-06-10 19:58 UTC
Nmap scan report for host.docker.internal (
# NAT: 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


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:

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)

Intellij Start Listening Php Debug Connection

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

Firefox Easy Xdebug Enable

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

Intellij Incoming Xdebug Connection

  • 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

Intellij Map Server Path Local Path

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

Intellij Debugger Variable Stack



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'])'

Cannot Evaluate 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

Documentation / Reference

Discover More
Firefox Easy Xdebug Profile Cookie
How to profile with the PHP Xdebug Profiler

The profiler in Xdebug outputs profiling information in the form of a cachegrind compatible file. Install xdebug and set the profiler...
Card Puncher Data Processing
PHP - Configuration (php.ini)

The whole configuration of PHP is done within the file The php home directory must be in the PATH. The following components need a configuration:

Share this page:
Follow us:
Task Runner