Docker PHP Xdebug CLI debugging

I use Docker for development and for my website too. Now it's time to throw away var_dump and to use Xdebug for PHP Docker container. It's quite easy, because I have created a Docker PHP Xdebug Image on Docker Hub. You have only to set your path mappings in your IDE. This image can also be used to generate the code coverage with PHPUnit. Ok, let's go step by step.

Pull the PHP Xdebug image from Docker Hub

Ensure Docker is installed and then run the following command:

$ docker pull sandrokeil/php:5.6-cli-xdebug

This can take some minutes. In the meantime, you can configure your IDE path mappings.

Configure path mappings in PhpStorm

Important is the server name application. PhpStorm uses the serverName to determine the right server. xDebug is automatically enabled in the configuration. If you run this Docker container and listen to incoming connections, it stops on the activated breakpoints. Open the settings File -> Settings -> Languages & Frameworks -> PHP -> Server and enable path mappings. Fill out the name with application and set /app to the absolute path mapping on the server of the root folder. Your project files will be mounted there.

PhpStorm Path Mappings

Start the PHP Xdebug Docker container

You have configured your path mappings and enabled listen for incomming Xdebug connections, then you can start the container with the following command from the root of your project.

$ docker run --rm -it --volume $(pwd):/app -e PHP_IDE_CONFIG="serverName=application" sandrokeil/php:5.6-cli-xdebug php [your file]

It's important that your path mapping has the name application and to pass the environment variable PHP_IDE_CONFIG with the name of the server. It is recommended to create a simple bash file which works with every project. Create a file in your ~/bin folder and put the following lines to it.

docker run --rm -it --volume $(pwd):/app -e PHP_IDE_CONFIG="serverName=application" sandrokeil/php:5.6-cli-xdebug php $@  

Make this file executable with chmmod +x ~/bin/ and you can start a new Xdebug session with:

$ docker-xdebug [your PHP file]

Breakpoints doesn't work?

Don't expose the Xdebug port 9000

At default, Xdebug's remote host is configured with xdebug.remote_host=, but it can be different to your Docker gateway IP address. To check your Docker gateway IP run the command $ ifconfig and look for the docker0 network adapter. Since Docker 1.9, the Docker gateway IP for me is You can override the default Xdebug configuration with the php -d xdebug.remote_host= parameter. If you are using Docker Machine and VirtualBox, use the IP of the VirtualBox network interface. Here is an example how to override the default Xdebug remote_host option.

$ docker run --rm -it --volume $(pwd):/app -e PHP_IDE_CONFIG="serverName=application" sandrokeil/php:5.6-cli-xdebug php -d xdebug.remote_host= [your PHP file]

Other PHP Versions

The PHP build on Docker Hub includes also the following PHP versions.

  • php:5.6-cli - docker pull sandrokeil/php:5.6-cli
  • php:5.6-cli-blackfire - docker pull sandrokeil/php:5.6-cli-blackfire
  • php:7.0-cli - docker pull sandrokeil/php:7.0-cli


Docker is a perfect match for PHP development. Note that these Xdebug settings also work with a web server like nginx and php-fpm. Interested in profiling? Read more about profiling.

Vagrant users can read Vagrant remote PHP & CLI debugging with PHPStorm.

Discuss (0 Comments)