Skip to content

Instantly share code, notes, and snippets.

Embed
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

This comment has been minimized.

Copy link

commented Nov 20, 2015

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

@cudacoder

This comment has been minimized.

Copy link

commented Dec 3, 2015

The IP of the machine running your IDE.

@atrigub

This comment has been minimized.

Copy link

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?

@veloriba

This comment has been minimized.

Copy link

commented Jan 22, 2016

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

@boussou

This comment has been minimized.

Copy link

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

@ghost

This comment has been minimized.

Copy link

commented Apr 4, 2016

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

@jehaby

This comment has been minimized.

Copy link

commented Apr 29, 2016

@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

@zeroleaf

This comment has been minimized.

Copy link

commented May 13, 2016

This work for me, thanks a lot.

@martinbutt

This comment has been minimized.

Copy link

commented Jun 17, 2016

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

XDEBUG_CONFIG: "remote_host=10.0.2.2"
@jonniedarko

This comment has been minimized.

Copy link

commented Jul 7, 2016

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

@TuningGuide

This comment has been minimized.

Copy link

commented Jul 11, 2016

Can't I use 127.0.0.1 as remote_host?

@patrick-mota

This comment has been minimized.

Copy link

commented Jul 15, 2016

@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

This comment has been minimized.

Copy link

commented Jul 19, 2016

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 :)

@hernandanielg

This comment has been minimized.

Copy link

commented Aug 2, 2016

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

@samlangdon

This comment has been minimized.

Copy link

commented Aug 19, 2016

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

This comment has been minimized.

Copy link

commented Sep 7, 2016

Thank you, @chadrien

@damien-biasotto

This comment has been minimized.

Copy link

commented Sep 8, 2016

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

This comment has been minimized.

Copy link

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?

@digitalit

This comment has been minimized.

Copy link

commented Sep 24, 2016

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

@ericjeker

This comment has been minimized.

Copy link

commented Oct 2, 2016

@digitalit: Thank you ! Worked for me ! 👍

@bscheshirwork

This comment has been minimized.

Copy link

commented Oct 16, 2016

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

This comment has been minimized.

Copy link

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.

@damien-biasotto

This comment has been minimized.

Copy link

commented Oct 20, 2016

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

@seblepers

This comment has been minimized.

Copy link

commented Nov 28, 2016

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

This comment has been minimized.

Copy link

commented Dec 1, 2016

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

@anaelChardan

This comment has been minimized.

Copy link

commented Dec 2, 2016

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

@jamescowie

This comment has been minimized.

Copy link

commented Jan 1, 2017

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.

@jgutsche

This comment has been minimized.

Copy link

commented Jan 30, 2017

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

commented Feb 16, 2017

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

This comment has been minimized.

Copy link

commented Feb 22, 2017

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
`

@aqwAntonio

This comment has been minimized.

Copy link

commented Mar 14, 2017

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

@leolandotan

This comment has been minimized.

Copy link

commented Apr 5, 2017

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

This comment has been minimized.

Copy link

commented Apr 11, 2017

XDEBUG_CONFIG: "remote_host=192.168.45.432 idekey=PHPSTORM"

@A----

This comment has been minimized.

Copy link

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.

@georaldc

This comment has been minimized.

Copy link

commented Apr 19, 2017

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

@mikenk2010

This comment has been minimized.

Copy link

commented May 30, 2017

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 !!!
@thyagoluciano

This comment has been minimized.

Copy link

commented Jun 5, 2017

@digitalit: Thank you! Worked for me!

@phpguru

This comment has been minimized.

Copy link

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

This comment has been minimized.

Copy link

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

@ikerlin

This comment has been minimized.

Copy link

commented Aug 29, 2017

@Takeno thanks share

@yuklia

This comment has been minimized.

Copy link

commented Sep 13, 2017

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

@pshanoop

This comment has been minimized.

Copy link

commented Nov 27, 2017

docker network inspect bridge |awk '/"Gateway"/ {gsub ("\"","") ;print $2} To get host docker bridge ip.

@dekuyper

This comment has been minimized.

Copy link

commented Jan 17, 2018

You can get the host ip address by running this command: ifconfig en0 | awk '/ *inet /{print $2}'

@Ryangr0

This comment has been minimized.

Copy link

commented Feb 5, 2018

THE SOLUTION

run yes | pecl install xdebug-2.5.5 instead of yes | pecl install xdebug. Support for PHP 5.6.x and under seems to have been removed in the latest release (2.6.0) and up.

Source: https://pecl.php.net/package-changelog.php?package=xdebug&release=2.6.0

THE PROBLEM
This does not seem to work anymore. I just ran a docker-compose build --no-cache on a dockerfile with a change that was unrelated to xdebug, and this happened.

Step 5/25 : RUN yes | pecl install xdebug
 ---> Running in f14a14dee07c
WARNING: channel "pecl.php.net" has updated its protocols, use "pecl channel-update pecl.php.net" to update
pecl/xdebug requires PHP (version >= 7.0.0), installed version is 5.6.32
No valid packages found
install failed
ERROR: Service 'web' failed to build: The command '/bin/sh -c yes | pecl install xdebug' returned a non-zero code: 1

I then removed my changes to the dockerfile and ran the build command again, same result. Tried running pecl channel-update pecl.php.net before pecl install xdebug and again, the same result.

Tried looking for the error message on google, the only similar one is this: https://build.webdevops.io/build/1d8a753154ca3762481e79d85a712321

@Klizzy

This comment has been minimized.

Copy link

commented Feb 20, 2018

here is also a good video, where he is adressing the issue with the remote host: https://serversforhackers.com/c/getting-xdebug-working
thanks for some links and suggestions, it took me quite some time to get it running

@sylvainraye

This comment has been minimized.

Copy link

commented Feb 23, 2018

For me the followings works on Docker for Mac:

xdebug.remote_autostart=0
xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.remote_host=docker.for.mac.host.internal
xdebug.remote_port=9000
xdebug.remote_connect_back=0
xdebug.profiler_enable=0
xdebug.remote_log="/tmp/xdebug.log"

The docker.for.mac.host.internal host prevent scratching the head regarding IP alias or no network at all on host side. The source comes from the docker documentation https://docs.docker.com/docker-for-mac/networking/#use-cases-and-workarounds

No needs for extra configuration or environment variable in docker compose.

@helman

This comment has been minimized.

Copy link

commented Mar 2, 2018

Hi guys, I was struggling with configuring Docker and XDebug.
The main point is you will need to restart the XDebug Session listener on PHPStorm every time you change the configuration!

@hbt

This comment has been minimized.

Copy link

commented Mar 18, 2018

I set up a quick howto repo with example + step by step guide here https://github.com/hbt/howto-docker-xdebug with screenshots

@joelataylor

This comment has been minimized.

Copy link

commented Mar 19, 2018

Thank you to all the comments here! I was able to get Atom working w/ php-debug + xdebug + docker!

@Kill0p

This comment has been minimized.

Copy link

commented Mar 29, 2018

When I debug wordpress with this configuration everything seems to work but one thing.
I got 2 requests in every debug request. First request is good one which stops php scripts in normal debug session ( web server is paused and waiting for script to die or continue ). Second request seems to do nothing with web server, but xdebug client is working on breakpoint.

@albertski

This comment has been minimized.

Copy link

commented Mar 31, 2018

When I run the command sudo ifconfig en0 alias 10.254.254.254 255.255.255.0 I can't access my site anymore through browsers. Do you guys know how to get around this?

@jtreminio

This comment has been minimized.

Copy link

commented Apr 1, 2018

MacOS:

[xdebug]
xdebug.remote_host = "docker.for.mac.host.internal"
xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000

Linux:

[xdebug]
xdebug.remote_host = "172.18.0.1"
xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000

Windows:

[xdebug]
xdebug.remote_host = "docker.for.win.host.internal"
xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000
@BramDriesen

This comment has been minimized.

Copy link

commented Apr 20, 2018

We can confirm that the last comment by @jtreminio is working for us. Tested on MacOS and Linux.

@asadovkamran

This comment has been minimized.

Copy link

commented May 3, 2018

I followed instructions and got xdebug listed in my phpinfo(). But connection times out when trying to connect the website.

@MikeDevs

This comment has been minimized.

Copy link

commented May 8, 2018

I think for Linux, MacOS, and Windows you should now use host.docker.internal for remote_host with Docker 18.03.0-ce+. That should simplify shared environments.

[xdebug]
xdebug.remote_host = "host.docker.internal"
xdebug.default_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_connect_back = 0
xdebug.remote_enable = 1
xdebug.remote_handler = "dbgp"
xdebug.remote_port = 9000
@hernandev

This comment has been minimized.

Copy link

commented May 8, 2018

Hello everyone, here is how I've included support for XDebug on Ambientum:

considering the image start file is start.sh:

#!/usr/bin/env bash

if [[ $XDEBUG_ENABLED == true ]]; then
    # enable xdebug extension
    sudo sed -i "/;zend_extension=xdebug/c\zend_extension=xdebug" /etc/php7/conf.d/00_xdebug.ini

    # enable xdebug remote config
    echo "[xdebug]" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.remote_enable=1" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.remote_host=`/sbin/ip route|awk '/default/ { print $3 }'`" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.remote_port=9000" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.scream=0" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.cli_color=1" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo "xdebug.show_local_vars=1" | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null
    echo 'xdebug.idekey = "ambientum"' | sudo tee -a /etc/php7/conf.d/00_xdebug.ini > /dev/null

fi

# run the original command
exec "$@"

This allows automatic host IP detection, using the /sbin/ip route|awk '/default/ { print $3 }'

Also notice the ide key is defaulted to ambientum on the example, and the 00_xdebug.ini may have another path.

If you want to check it out implemented on a image, here is the sources for Ambientum:

https://github.com/codecasts/ambientum/tree/master/php/7.2

@hernandev

This comment has been minimized.

Copy link

commented May 8, 2018

@MikeDevs one way to have the host.docker.internal on ANY Docker version is to include it on the /etc/hosts manually upon start (entry point script):

echo -e "`/sbin/ip route|awk '/default/ { print $3 }'`\tdocker.host.internal" | sudo tee -a /etc/hosts > /dev/null

Doing that line, you can now easily check docker.host.internal by doing

ping docker.host.internal

:)

@stefanosaittamrf

This comment has been minimized.

Copy link

commented May 22, 2018

When I debug wordpress with this configuration everything seems to work but one thing.
I got 2 requests in every debug request. First request is good one which stops php scripts in normal debug session ( web server is paused and waiting for script to die or continue ). Second request seems to do nothing with web server, but xdebug client is working on breakpoint.

Same happen to me @Kil0p did you manage to solve? Also, i have an issue debugging a plugin, since in my dev environment i just expose the plugin directory and hide inside the docker container the wordpress code, the issue happens when my debugger try to step into the actual implementation but since the code is not there it fails. I Don't know if i explain it clearly, if not let me know.

@vjaro

This comment has been minimized.

Copy link

commented Jun 27, 2018

@jtreminio the linux part worked for me. Thank you!

@swashata

This comment has been minimized.

Copy link

commented Jul 16, 2018

Hi,

I've found that simply defining xdebug.remote_host=host.docker.internal works just fine.

@paslandau

This comment has been minimized.

Copy link

commented Aug 6, 2018

The problem is usually that there is some bug in the networking setup for Docker for Mac / Docker for win that causes the container not to "see" the host machine . The host.docker.internal DNS entry solves this issue for both systems, although we noticed that it does not exist for native Docker under unix.

To make this work for PhpStorm, the xdebug.ini file should contain at least two entries:

xdebug.remote_host=host.docker.internal
xdebug.remote_connect_back=0

(that is, if you want a debugging session triggered from the browser).

For CLI script debugging I suggest to override xdebug.remote_host in the CLI Interpreter settings:

Xdebug CLI Interpreter settings

Source: Fix Xdebug on PhpStorm when run from a Docker container

@darius-v

This comment has been minimized.

Copy link

commented Sep 2, 2018

I tried by the video https://serversforhackers.com/c/getting-xdebug-working, but I am getting error:

Step 3/12 : RUN locale-gen en_US.UTF-8 ---> Running in 0cef4abb96cb /bin/sh: 1: locale-gen: not found ERROR: Service 'app' failed to build: The command '/bin/sh -c locale-gen en_US.UTF-8' returned a non-zero code: 127

when building. How to fix that? I am using xubuntu 16

@darius-v

This comment has been minimized.

Copy link

commented Sep 3, 2018

Found what fixes the problem: nerves-project/nerves#112

Adding

RUN apt-get update && apt-get -y install locales
before
RUN locale-gen en_US.UTF-8

But now getting anotehr error:

ERROR: Service 'app' failed to build: COPY failed: stat /var/lib/docker/tmp/docker-builder196897509/start-container: no such file or directory

Update:

Found that start-container is a file. And thought it has to have ending .sh but its the opposite - it had not to have .sh ending. So after fixing this, it built.

@darius-v

This comment has been minimized.

Copy link

commented Sep 3, 2018

After that I still got error

docker-compose up -d
Recreating 4_try_app_1 ... error

ERROR: for 4_try_app_1  Cannot start service app: b'driver failed programming external connectivity on endpoint 4_try_app_1 (42786abb4be0850f5f801240d69aaa1d76b7de3e10aaad89be0b23a27c2a8181): Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use'

ERROR: for app  Cannot start service app: b'driver failed programming external connectivity on endpoint 4_try_app_1 (42786abb4be0850f5f801240d69aaa1d76b7de3e10aaad89be0b23a27c2a8181): Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use'
ERROR: Encountered errors while bringing up the project.

But tried to changing ports in docker-compose.yml to - "8080:80" and now error is gone. To load page have to go to http://localhost:8080/

And after fixing those errors, I can confirm - that works :) I have not tested with curl, but I have tested running in chrome.

@darius-v

This comment has been minimized.

Copy link

commented Sep 3, 2018

Tested the performance when listening and when not listening. Both times it lasted 2-3 seconds on my machine. So that is not optimal, probably it works always with xdebug mode even when turning off listening in php storm.

echo date('H:i:s') . '<br>';
for($i=1; $i<10000000; $i++) {
    $three++;
}
echo date('H:i:s');

Would be good to find a quick way to turn xdebug off.

I tried commenting this line
#COPY xdebug.ini /etc/php/7.0/mods-available/xdebug.ini
and rebuild

docker-compose build.

And executed again. But still same those 2-3 seconds. So not sure what is causing this. Maybe thats is not xdebug, need to try.

Interesging - tried same script on php 7.1 where I have setup without docker. When turning on listening in phpstorm, then it loads in 4-5 seconds. When turning off - 2-3 seconds. So how in this docker setup it has constantly 2-3 seconds?

@PeteFromSales

This comment has been minimized.

Copy link

commented Sep 7, 2018

@jtreminio 's config worked for me on OSX (Sierra 10.12.6) & Docker CE (18.06.1-ce-mac73 (26764)). However, I'm using Intellij IDEA 2018.2, so despite the xdebug.remote_handler = "dbgp" line, in Intellij I just use the normal Xdebug settings and port (you can probably use port 9000 as well, just check if it's already in use by another service first):

screen shot 2018-09-07 at 9 46 51 am

@radius314

This comment has been minimized.

Copy link

commented Oct 28, 2018

This worked for me:

FROM php:5.6.38-apache

RUN apt-get update &&\
    apt-get install --no-install-recommends --assume-yes --quiet ca-certificates curl git telnet iputils-ping net-tools &&\
    rm -rf /var/lib/apt/lists/*

RUN pecl install xdebug-2.5.5 && docker-php-ext-enable xdebug \
    && echo "zend_extension=$(find /usr/local/lib/php/extensions/ -name xdebug.so)" >> /usr/local/etc/php/php.ini  \
    && echo "xdebug.remote_port=9000" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.remote_enable=1" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.remote_connect_back=0" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.remote_host=docker.for.mac.localhost" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.idekey=IDEA_DEBUG" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.remote_autostart=1" >> /usr/local/etc/php/php.ini \
    && echo "xdebug.remote_log=/tmp/xdebug.log" >> /usr/local/etc/php/php.ini

My docker-compose.yml

version: '2'
services:
  apache_with_php:
    build: .
    volumes:
    - ./src:/var/www/html/
    ports:
    - "8082:80"
@liuyibao

This comment has been minimized.

Copy link

commented Nov 8, 2018

For me the followings works on Docker for Mac:

xdebug.remote_autostart=0
xdebug.remote_enable=1
xdebug.default_enable=0
xdebug.remote_host=docker.for.mac.host.internal
xdebug.remote_port=9000
xdebug.remote_connect_back=0
xdebug.profiler_enable=0
xdebug.remote_log="/tmp/xdebug.log"

The docker.for.mac.host.internal host prevent scratching the head regarding IP alias or no network at all on host side. The source comes from the docker documentation https://docs.docker.com/docker-for-mac/networking/#use-cases-and-workarounds

No needs for extra configuration or environment variable in docker compose.

Great!

@Deg5112

This comment has been minimized.

Copy link

commented Dec 12, 2018

always end up coming back to this post

the main issue i always have is executing a command/php file directly inside of a docker container.

Having the following env variable living directly in the docker container instance, pointing back to the literal name of the server block, solves the problem. Typically when xdebug first creates a connection, it'll give the server name a default name of _ . you can go change that to whatever you want

PHP_IDE_CONFIG=serverName= ie: name of the server name located in preferences -> languages -> php -> servers

@antishov

This comment has been minimized.

Copy link

commented Feb 13, 2019

Great post.
Please note that PHP 7.3+ is not compatible with xdebug 2.6 or lower. You should install at least 2.7.0RC1 version.

@amjimenez

This comment has been minimized.

Copy link

commented Mar 19, 2019

xdebug.remote_host=docker.for.mac.host.internal

That helped me. It's working now.

@marmot00

This comment has been minimized.

Copy link

commented Mar 21, 2019

@jtreminio 's mac os config works!
you save my life, thank you!

@tobinski

This comment has been minimized.

Copy link

commented Apr 2, 2019

Be aware of firewall configuration. Maybe the connection to phpstorm on port 9000 is blocked.

@rahilwazir

This comment has been minimized.

Copy link

commented Apr 19, 2019

@jtreminio Worked for Linux. Thanks.

@lainosantos

This comment has been minimized.

Copy link

commented Apr 21, 2019

Hi,
On linux with firewalld enabled, the container hasn't route for host, so it not attach to host port 9000 (xdebug). The route can be add by:
firewall-cmd --zone=public --add-rich-rule='rule family="ipv4" source address="172.17.0.0/16" accept'

Where 172.17.0.0 is docker container's subnet (check it with ifconfig).

@rwese

This comment has been minimized.

Copy link

commented Jun 3, 2019

This will need to be updated for php 7.4, see: https://olvlvl.com/2019-06-install-php-ext-source , pecl won't be available in the php base image.

@brycefranzen

This comment has been minimized.

Copy link

commented Jun 7, 2019

@digitalit Thank you!!! Your alias method worked perfectly!

@patrickschur

This comment has been minimized.

Copy link

commented Aug 9, 2019

Here is my Dockerfile using PHP 7.4 and the newest version of Xdebug. Because PEAR is no longer enabled by default and may be removed in the future.

FROM php:7.4-rc-apache

ARG XDEBUG_VERSION=2.8.0beta1

RUN mkdir -p /usr/src/php/ext/xdebug && \
    curl -fsSL https://xdebug.org/files/xdebug-${XDEBUG_VERSION}.tgz | tar xz -C /usr/src/php/ext/xdebug --strip 1 && \
    docker-php-ext-install xdebug && \
    echo "xdebug.remote_enable=1" >> /usr/local/etc/php/php.ini
@MiguelAlcaino

This comment has been minimized.

Copy link

commented Aug 26, 2019

the linux solution given by @jtreminio works for me like a charm

@patricknelson

This comment has been minimized.

Copy link

commented Sep 6, 2019

The key here is to now start using host.docker.internal in your remote_host configuration moving forward. Also, I think remote_connect_back is not necessary and should be removed. I've consolidated a simplified but generic explanation where I try to focus strictly on configuring Xdebug to work in Docker, if anyone is interested:

Using Xdebug in Docker (gist)

I did this because even though the core solution for Docker-specific setups is pretty simple (i.e. remote_host=host.docker.internal), any extra code, configuration details or unrelated bugs can start to make things very confusing for beginners who are diving into Docker for the first time. If anything, it'll at least help me for future reference 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.