Hey guys! I’m pretty sure most of you uses xdebug each day, if not I highly recommend it. But have you tried to run it on docker container and catching requests with PhpStorm? In this short post you can check how to quickly combine those three. I’m working on Ubuntu but this was also tested on Mac.

NOTE: this post does not explain how docker or xdebug works, it’s only about combining them together. There are lots of materials about those topics on the internet, but if you have any question fell free to ask 😉

Docker & Xdebug

Lately I moved all of my server software to docker containers – it keeps my computer clean and I can reinstall all of the containers easily without loosing any data, pretty awesome. So I have a container with php-fpm (besides that I have other ones like apache or mariadb) and on this container I’ve installed xdebug extension. To do this, I had to create a custom Docker file and put this code in it:


FROM php:7.1-fpm

RUN pecl install xdebug \
    mkdir /usr/local/xdebug \
    cp $(find /usr/local/lib/php/extensions/ -name xdebug.so) /usr/local/xdebug/xdebug.so

This just simply uses the php:7.1-fpm image and installs the php extension on it. Of course you can use whatever image you want, there are lots of them on docker hub, for example some php + apache package.


Next we have to put the xdebug configuration in php.ini. Again, there are few options for this but I use the volumes to link a file from my host to the container in the docker-compose file.


version: "2"

    build: ./php71fpm
    image: local_php71fpm:latest
    container_name: local_php71fpm
      PHP_IDE_CONFIG: "serverName=local"
      - /private/var/xdebug:/tmp/xdebug
      - ${SITES_DIRECTORY}:/var/www
      - ./php71fpm/conf/php.ini:/usr/local/etc/php/php.ini

NOTE: this is only part of my file, as I wrote earlier I also have other containers like apache or mariadb

I will not get into the details of docker-compose file configuration but shortly – first of all pay notice to the environment setting, we set the serverName var to local. We will use this setting later in PhpStorm configuration. As for the rest of the file, in build param we place the path to our custom Docker file and with volumes we are sharing files from the host (our disk) to the container. As you can see I link a tmp folder for some xdebug logs, sites directory (where all my projects are) and concrete php.ini file in which I have following configuration


date.timezone = "Europe/Warsaw"

zend_extension = /usr/local/xdebug/xdebug.so

xdebug.max_nesting_level = 8192

Please pay attention to the remote_host configuration, I’ve put there, because all of my docker containers by default have set this IP as a gateway.

NOTE: if you are on MAC you probably will need to create an alias sudo ifconfig lo0 alias and configure this host in PHPStorm -> Settings -> Languages & Frameworks -> PHP -> Debug -> DBGp Proxy

Before we proceed to setting up PhpStorm we first need to launch the docker container. I am using docker-compose so in my case

docker-compose up

is the way, but you can just run single container with

docker run



After container is launched, we can go to PhpStorm settings. First go to Languages & Frameworks -> PHP -> Debug


You can click the Validate link to check if the xdebug is working but you will have to type the project url – I’m using vhosts for all of my projects so in my case it was http://test71.local.


As you can see, PhpStorm fetched all the info and it looks like everything is ok. The next thing to watch out is the port, by default it’s set to 9000 in our IDE and also if we don’t change anything in php.ini it’s also 9000. If you want to change this setting you have to edit php.ini and add


Ok, we are almost done. The last part is to map our project files in PhpStorm (on host) and the ones on the “server” (in Docker container). To do this we have to go to settings again Languages & Frameworks -> PHP -> Servers and add a Server with a + sign.


Next we need to fill the name, host and absolute path on the server fields, optionally port if you use other port than 80 for browser connections. The name field should have the same value as we set in docker-compose.yml file in serverName var. Apply the settings and click Start listening for Php Debug Connection button, I have it in the right top corner of IDE.


The last this is to set the breakpoints in our IDE and… refresh the page 🙂


Tada! We can proceed with our debugging 🙂

I know that there are many ways of implementing this but I’ve found this configuration pretty quick and easy and most of all working 😉

Thanks for reading!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.