Skip to content

Instantly share code, notes, and snippets.

Forked from chadrien/
Last active Sep 2, 2021
What would you like to do?
Debug PHP in Docker with PHPStorm and Xdebug

Debug your PHP in Docker with Intellij/PHPStorm and Xdebug

  1. For your local dev, create a Dockerfile that is based on your production image and simply install xdebug into it. Exemple:
FROM php:5

RUN yes | pecl install xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name" > /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini
  1. Get you local IP address (ip -o -4 addr list ${MY_NETWORK_INTERFACE:-eth0} | awk '{print $4}' | cut -d/ -f1)
  2. Start your container with the following environment variables: XDEBUG_CONFIG="remote_host={{YOUR_IP_ADDRESS}}"
  • Simple docker run: docker run -e XDEBUG_CONFIG="remote_host={{YOUR_IP_ADDRESS}}" your-image

  • With docker-compose:

    # docker-compose.yml
      build: path/to/Dockerfile
        XDEBUG_CONFIG: "remote_host={{YOUR_IP_ADDRESS}}"
        PHP_IDE_CONFIG: "serverName=my.local"
  1. In Intellij/PHPStorm go to: Languages & Frameworks > PHP > Servers > and set the following settings:

  • Name: name of your server, should be equal to value in PHP_IDE_CONFIG variable

Then you're all set and can start listening for PHP Debug connections from your IDE.

Happy debugging!


This comment has been minimized.

Copy link

@martinbutt martinbutt commented Jun 17, 2016

If you are using docker-machine with VirtualBox, you can skip step two and just use

XDEBUG_CONFIG: "remote_host="

This comment has been minimized.

Copy link

@mitramejia mitramejia commented Aug 10, 2016

Followed steps to the letter, I've been spinning my head against this for hours. I'm using Docker for Mac.


This comment has been minimized.

Copy link

@Magarusu Magarusu commented Sep 9, 2016

I am getting the same error as mitramejia. For some reason I think that server name is not used in the xdebug request.
Did anyone found a solution for this?


This comment has been minimized.

Copy link

@sorinstanila sorinstanila commented Sep 25, 2016

The path from your docker files is /var/www/html and not /var/www. Change in Phpstorm and will be fine.


This comment has been minimized.

Copy link

@bscheshirwork bscheshirwork commented Oct 16, 2016

for the CLI application use a similar way and set HOST to "localhost" (of course PHP_IDE_CONFIG: "serverName=localhost")


This comment has been minimized.

Copy link

@brice brice commented Jul 20, 2017


I followed your tutorial but i'm stuck. I start to listening PHP Debug Connection, i add a key with XDEBUG_SESSION_START on my host (ex : http://localhost/?XDEBUG_SESSION_START=phpstorm-xdebug) with breakpoint on my code and nothing happens.

I even add a die(); near my breakpoint to be sure code is evaluated and it is.

What can i do to debug things and find why it's nor working.

Edit : I get it. So i add a remote_log option in order to find what happened. I saw a timeout error. After a while, i realised that i have a firewall on my system. After opening the TCP port 9000 it works perfectly.


This comment has been minimized.

Copy link

@firecentaur firecentaur commented Nov 29, 2018

I need someone to help we with this, can you please reach me on skype at (thats my skype id)


This comment has been minimized.

Copy link

@oscarnascimento oscarnascimento commented Dec 12, 2018

Worked for me! Thanks!


This comment has been minimized.

Copy link

@lucasctd lucasctd commented Jul 1, 2019

Love you so much. I have been struggling a lot trying to make it working. Finally I got it working haha thx.


This comment has been minimized.

Copy link

@mbaric mbaric commented Jul 25, 2019

Thank you for this tutorial.

I just want to help out a bit how I managed to set it up with my client's docker. Just a few points on the above tutorial.

To get the IP I used this syntax:

    docker-composer exec <container-name> hostname -I

Real example on my computer:

mbaric@i7 /var/www/html/jobsoutsource (dev) $ docker-compose exec fpm hostname -I 

I started changing files fpm.docker:

FROM php:7.1.18-fpm

# Set to keep file permissions same as host for mounted volume
RUN useradd -m -u 1000 ubuntu

#RUN printf "deb jessie main\ndeb-src jessie main\ndeb jessie/updates main\ndeb-src jessie/updates main" > /etc/apt/sources.list

# Install GD
RUN apt-get update && apt-get install -y libfreetype6-dev libjpeg-dev libpng-dev libfontconfig1 libxrender1 git libmcrypt-dev  zip mysql-client && \
    docker-php-ext-configure gd \
          --enable-gd-native-ttf \
          --with-freetype-dir=/usr/include/freetype2 \
          --with-jpeg-dir=/usr/lib \
    && docker-php-ext-install gd

# Install MySQL
RUN docker-php-ext-install pdo_mysql

# Install Other Dependencies
RUN docker-php-ext-install bcmath
RUN docker-php-ext-install zip
RUN docker-php-ext-install exif
RUN docker-php-ext-install mbstring
RUN docker-php-ext-install mcrypt

# Install Composer
RUN apt-get install -y curl && \
    curl -sS | php && \
    mv composer.phar /usr/local/bin/composer && \
    composer self-update && \
    apt-get remove --purge curl -y && \
    apt-get clean

# Install Xdebug
RUN yes | pecl install xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name" > /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_enable=on" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_autostart=off" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.idekey=PHPSTORM" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_port=9000" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && echo "xdebug.remote_connect_back=1" >> /usr/local/etc/php/conf.d/xdebug.ini \
    && docker-php-ext-enable xdebug

WORKDIR /var/www

Take a note at the _ Install Xdebug_ section.

In the end, I went straight to docker-compose.yml and changed this:

      context: ./
      dockerfile: fpm.docker
      - mysql
      - memcached
      - beanstalkd
      - slanger
      - ./:/var/www
      - "DB_PORT=3306"
      - "DB_HOST=mysql"
      - XDEBUG_CONFIG="remote_host="
      - PHP_IDE_CONFIG="serverName=jo"
    user: ubuntu

In the PHPStorm small changes were required the server needed to be renamed to jo and the mappings to /var/www/ since we are in the container not on my local machine anymore.

Finally for all of you guys there when you make changes to docker files or docker-compose.yml you need to rebuild it with this:

docker-compose up --build

Just one more thing, on all of you curios how I debug xdebug is with simple phpinfo().

Here are those images that I wanted to share:


Hope it will help somebody.

Thanks again to all for this.


This comment has been minimized.

Copy link

@patricknelson patricknelson commented Sep 6, 2019

Actually the solution is extremely simple now: Just set remote_host to the new special DNS name host.docker.internal. For example:

xdebug.remote_host = host.docker.internal

This now works with Docker for Windows or Docker for Mac (not Docker Toolbox) starting from version 18.03 and later. I just tried it and it worked perfectly for me. See documentation: Windows and Mac.

The nice thing about this elegant solution is that it fully abstracts away the magic behind the scenes associated with figuring out the IP address of your host development machine. IMHO, it should be Docker's responsibility to figure that out for you anyway, not the other way around.

EDIT: I've created my own Gist outlining this in detail from scratch here:


This comment has been minimized.

Copy link

@jmossetc jmossetc commented Mar 16, 2020

@mbaric answer made it work for us. Thank you for helping us!


This comment has been minimized.

Copy link

@mbaric mbaric commented Mar 16, 2020

No problem @jmossetc. Glad I could help.


This comment has been minimized.

Copy link

@patricknelson patricknelson commented Mar 16, 2020

Was it working for you guys because of the manual binding in the compose configuration to the environment variable XDEBUG_CONFIG="remote_host="? What happens when you change that IP to host.docker.internal?

If it works, I think it can be dramatically simplified by just hard-coding that hostname (either host.docker.internal or using10.0.2.2 if you're using Docker Toolbox with Virtualbox). The full hard-coded XDebug INI configuration can be found in my gist (also linked above) which doesn't need to be modified in environment variables, hopefully centralizing and de-cluttering things a bit.


This comment has been minimized.

Copy link

@jmossetc jmossetc commented Mar 17, 2020

@patricknelson my remote_host parameter is set to


This comment has been minimized.

Copy link

@lunfel lunfel commented May 20, 2020

I had trouble configuring xdebug. According to an old issue, you need to remove double quotes from the environment variable as follow

changed to

And that made it work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment