Create a gist now

Instantly share code, notes, and snippets.

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 xdebug.so)" > /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 (ifconfig or such)
  2. Start your container with the following environment variable: 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
    foo:
      build: path/to/Dockerfile
      environment:
        XDEBUG_CONFIG: remote_host={{YOUR_IP_ADDRESS}}
  1. In Intellij/PHPStorm go to: Languages & Frameworks > PHP > Debug > DBGp Proxy and set the following settings:
  • Host: your IP address
  • Port: 9000

Then you're all set and can start listening for PHP Debug connections from your IDE. On the first run it will ask you to map your local directoryies to the docker directories, but after that nothing will be required anymore!

Happy debugging!

ScreamZ commented Nov 20, 2015

I must get My local ip (eth0), or my container IP ?

The IP of the machine running your IDE.

atrigub commented Dec 11, 2015

Maybe should be use xdebug.remote_connect_back=1 ?

Do you have any idea how debug cli command in docker container?

To atrigub
Type export XDEBUG_CONFIG="idekey=PHPSTORM" in terminal session

boussou commented Feb 22, 2016

just to mention that you don't need to restart your docker to enable it
you can also add

[Xdebug]
xdebug.remote_enable=true
xdebug.remote_host=172.17.0.1
xdebug.remote_port=5902

here 172.17.0.1 is your host ip, you can find it with ifconfig in your host
then restart your webserver

Don't you have to expose or map ports in your docker compose file? How can your IDE otherwise listen to?

jehaby commented Apr 29, 2016 edited

@chadrien, thanks for your manual. Unfortunately, I couldn't make it work, so I changed it a little with descriptions of steps which worked for me: https://gist.github.com/jehaby/61a89b15571b4bceee2417106e80240d

This work for me, thanks a lot.

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

XDEBUG_CONFIG: "remote_host=10.0.2.2"

I'm having issues with this using the new docker beta, if anyone can assist I would very much appreciate it, the details are posted on stackoverflow.com

Can't I use 127.0.0.1 as remote_host?

@TuningGuide You can't since it will be used inside your container.

It will be like doing a query to the container itself.

That's why you have to use the ip of your host.

peric commented Jul 19, 2016 edited

This still works for you?

I have Phpstorm 2016.2 and I went through all the steps of setting this up - but I get no signal from the xdebug. Docker sees my machine as 172.18.0.1 so this is what I set as remote_host on docker.

How do you setup remote debug in the last step? I have server named docker, where I have set host localhost and port to 9000. My ide key is PHPSTORM.

image

I think I have already tried all the possible options - nothing works :)

I will name my first son in your honor bro! thanks!

I'm trying to get this to work using VSCode with the XCode extension, with the Docker configuration mentioned in this article, but not having much luck. I'm not seeing XDebug as being enabled in the phpinfo output running in my container; should it be mentioned in there? Note XDebug appears to install correctly when building from my Dockerfile, but I notice the above config doesn't add anything to php.ini.

KIVagant commented Sep 7, 2016

Thank you, @chadrien

damien-biasotto commented Sep 8, 2016 edited

If you're using Docker for Mac (I don't know if this issue exists on Windows) you need to alias your local IP to something else : sudo ifconfig lo0 alias 10.254.254.254 in order to use XDebug properly (source https://forums.docker.com/t/ip-address-for-xdebug/10460/26).

Do not forget to add 10.254.254.254 in DBGp Proxy > Host setting.

triadev commented Sep 12, 2016

@damien-biasotto: could you explain why i need to put the ip in the hosts file? What host name do I need to use?

FINALLY :)

This is how i solved this using Mac Sierra, Docker Native Version 1.12.1, PhpStorm 2016.3 EAP, https://github.com/shincoder/homestead-docker:

n provision.sh

# Enable Remote xdebug
echo "xdebug.idekey = PHPSTORM" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.default_enable = 0" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.remote_enable = 1" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.remote_autostart = 0" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.remote_connect_back = 0" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.profiler_enable = 0" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini
echo "xdebug.remote_host = 10.254.254.254" >> /etc/php/7.0/fpm/conf.d/20-xdebug.ini

in docker-compose.yml

expose:
        - "9000"
    ports:
        - "8080:80" # web
        - "2222:22" # ssh
        - "35729:35729" # live reload
        - "9876:9876" # karma server
    environment:
        PHP_XDEBUG_ENABLED: 1 # Set 1 to enable.
        XDEBUG_CONFIG: remote_host=10.254.254.254

The IP i used everywhere is for my local mac, the one with phpStorm installed on. The IP is not 10.254.254.254 but since the IP could change i made an alias that points to 127.0.0.1.

For some reason i didn't work with 127.0.0.1 in all settings, i guess Docker container sees it at it self?

Anyway, to create the alias i did:

sudo ifconfig en0 alias 10.254.254.254 255.255.255.0

in phpStorm i used all default settings but added this:
skarmavbild 2016-09-24 kl 14 10 18

@digitalit: Thank you ! Worked for me ! 👍

bscheshirwork commented Oct 16, 2016 edited

for the CLI application use a similar way and set HOST to "localhost" (of course add PHP_IDE_CONFIG: "serverName=localhost" such as https://gist.github.com/jehaby/61a89b15571b4bceee2417106e80240d)

IDE setting like the https://gist.github.com/chadrien/c90927ec2d160ffea9c4#gistcomment-1829282

more info
https://sandro-keil.de/blog/2015/10/05/docker-php-xdebug-cli-debugging/

silasb commented Oct 17, 2016

@digitalit worked for me as well.

One thing that helped me was setting a xdebug.remote_log="/tmp/xdebug.log and I kept seeing it trying to connect to 172.x.x.1, essentially I needed to turn off remote_connect_back and then do sudo ifconfig en0 alias 10.254.254.254 255.255.255.0 trick.

@triadev My bad no need to put it in your /etc/hosts ….

One more thing, if you are using Nginx + PHP-FPM containers, and having the following error message :
Cannot accept external Xdebug connection: Cannot evaluate expression '$_SERVER['SERVER_PORT']'

Make sure you have the following in your Nginx config:
fastcgi_param SERVER_PORT $server_port;

vilewish commented Dec 1, 2016

@digitalit thanks for this tip with alias! Works for me.

anaelChardan commented Dec 2, 2016 edited

Some one tried to setup these tools together ?

  • PHPStorm 2016.3
  • XDebug
  • Docker
  • MacOS

I can't have my xdebug working :/

Here is my config :

RUN php5enmod xdebug &&
echo "xdebug.remote_enable=1" >> /etc/php5/apache2/conf.d/20-xdebug.ini &&
echo "xdebug.idekey=PHPSTORM" >> /etc/php5/apache2/conf.d/20-xdebug.ini &&
echo "xdebug.profiler_enable=0" >> /etc/php5/apache2/conf.d/20-xdebug.ini &&
echo "xdebug.max_nesting_level=700" >> /etc/php5/apache2/conf.d/20-xdebug.ini &&
echo "xdebug.remote_host=192.168.7.165" >> /etc/php5/apache2/conf.d/20-xdebug.ini

EDIT : I'll try the @digitalit answer

I had the same issues and eventually got it working with apache + PHP7 + PHPStorm 2016.3 + Xdebug My writeup incase it helps anyone. The networking command was key to getting it all working fine.

James got the point: use your host ip, no docker ip, nor localhost or 127.0.0.1 neither. I have 2 env up and running with php-5.6 and php-7.0, both with xdebug working in PHPSTORM.
Downside is: I may have different IPs at work or at home. I have not got connect_back working.

georaldc commented Feb 1, 2017

@jgutsche @jamescowie Is the IP retrieved by running ifconfig inside the docker instance you want to run xdebug on? Because the IP value there did not work for me. The only way I have been able to get xdebug to trigger on my setup (which is a windows host by the way) is to use the IP assigned to my docker virtual ethernet adapter (DockerNAT, use ipconfig to easily find IP).

One unrelated question of mine though is why for some reason, xdebug always wants to attempt a connection despite having remote_autostart set to false.

mrtuvn commented Feb 14, 2017

Anyone using docker in windows have same problem xdebug while run with phpstorm
Tried but can't connect to xdebug inside docker

jorge07 commented Feb 16, 2017 edited

I added some doc in a personal project (used in my company too) about how to integrate with xdebug. Can be useful for someone maybe: https://github.com/jorge07/alpine-php/blob/master/doc/IDE.md

optimum-web commented Feb 22, 2017 edited

You have also to mention to install phpize by sudo apt-get install php-dev.

Here is my version of dockerfile: ubuntu 14 + php5 + apache2 + xdebug

`
RUN apt-get update &&
DEBIAN_FRONTEND=noninteractive apt-get -yq install
curl
apache2
libapache2-mod-php5
php5-mysql
php5-mcrypt
php5-gd
php5-xdebug
php5-curl
php-pear
php5-memcache
php-apc &&
rm -rf /var/lib/apt/lists/*

RUN echo zend_extension="$(find / -name 'xdebug.so')"
RUN echo -e "zend_extension="$(find / -name 'xdebug.so')"\nxdebug.remote_enable=1\nxdebug.max_nesting_level=500\nxdebug.remote_connect_back=1\nxdebug.remote_port=9000" >> /etc/php5/apache2/conf.d/xdebug.ini
`

thank you very much for your comments!!! I finally set up my environment

Hi guys, any idea why xdebug is looping in the index.php file on my end? It's like when I try to access my site, it triggers xdebug in the index.php file then I resume the debugger to go to my next breakpoint inside my site but it starts at index.php again.

Mwalima commented Apr 11, 2017

XDEBUG_CONFIG: "remote_host=192.168.45.432 idekey=PHPSTORM"

A---- commented Apr 12, 2017

Or yeah, you can just use xdebug.remote_connect_back=1 and it'll guess the IP address from the headers.

Beware though, and read carefully this: https://xdebug.org/docs/all_settings#remote_connect_back
Especially this:

Please note that there is no filter available, and anybody who can connect to the webserver will then be able to start a debugging session, even if their address does not match xdebug.remote_host.

@A---- xdebug.remote_connect_back won't work for Windows hosts because the IP returned would be 127.0.0.1.

Worked like a charm !!!, I still don't understand why !!!

  • Step 1: Create IP alias, run on your machine, not on docker container
    sudo ifconfig en0 alias 10.254.254.254 255.255.255.0
  • Step 2: Config xdebug.so as usually, depended on what is your server (Apache2, Nginx, etc.) and add xdebug.remote_log="/tmp/xdebug.log" to watch.
  • Step 3: xdebug.remote_host=10.254.254.254, I have tried with other IP (also change alias following my new IP) but it does not work...???
  • Step 4: Config your PHPStorm
    • Servers: Mapping your source files on docker
    • DBGp proxy: IDE key = based on your configuration, Host = 10.254.254.254, port = based on your configuration
  • Step 5: Edit configurations => Add PHP remote debug and select server as Step 4 and IDE key same as Step 4
  • Step 6: Click listening for PHP Debug Connections
  • Step 7: hold my beer !!!

@digitalit: Thank you! Worked for me!

phpguru commented Jul 19, 2017

Sounds silly but if it is not working for you, restart your Docker containers and your IDE. I had all the settings correct and it didn't work until restarting the IDE.

Takeno commented Aug 22, 2017

Hi guys!

In Docker for Mac 17.06+, it works using docker.for.mac.localhost hostname to reach host machine.

You can find finalized solution here: https://github.com/ImprontaAdvance/docker-compose-symfony

hyt7212 commented Aug 29, 2017

@Takeno thanks share

yuklia commented Sep 13, 2017

@digitalit Why don't you just leave localhost in remote_host?

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