chadrien/README.md

Last active August 24, 2025 21:28

Star (410) You must be signed in to star a gist
Fork (64) You must be signed in to fork a gist

Select an option

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/chadrien/c90927ec2d160ffea9c4.js"></script>
Save chadrien/c90927ec2d160ffea9c4 to your computer and use it in GitHub Desktop.

Download ZIP

Debug PHP in Docker with PHPStorm and Xdebug

Raw

README.md

Debug your PHP in Docker with Intellij/PHPStorm and Xdebug

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

Get you local IP address (ifconfig or such)
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}}

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!

darius-v commented Sep 3, 2018 •

edited

Loading

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 commented Sep 7, 2018 •

edited

Loading

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

dgershman commented Oct 28, 2018 •

edited

Loading

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"

brotherbigbao 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 commented Dec 12, 2018 •

edited

Loading

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 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.

mickambar19 commented Mar 19, 2019

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

That helped me. It's working now.

weinung-chiu commented Mar 21, 2019 •

edited

Loading

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

tobinski commented Apr 2, 2019 •

edited

Loading

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

rahilwazir commented Apr 19, 2019

@jtreminio Worked for Linux. Thanks.

lainosantos 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 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 commented Jun 7, 2019

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

patrickschur 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 commented Aug 26, 2019

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

patricknelson commented Sep 6, 2019 •

edited

Loading

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 😄

andrew-svirin commented Oct 3, 2019

Is it possible to setup connection by next chain: Windows -> Linux (host Docker) -> Docker Linux PHP with PHPUnit ?

mitogh commented Dec 25, 2019

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

This one is working for me, just replacing the "remote_host" with the value from:

docker network inspect bridge | grep Gateway

NorthenIrbis commented Feb 11, 2020

sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT

bedger commented Apr 22, 2020 •

edited

Loading

If you have problems with running it on Linux (Ubuntu in my case) & you have a firewall enabled then the solution for you may be opening firewall ports for connection to port 9000 on docker service
sudo ufw enable && sudo ufw allow in from 172.16.0.0/12 to any port 9000 comment xdebug

You can check this discussion for more information

Raistlfiren commented Dec 22, 2020

Here is a quick reference for XDebug 3 and Docker Gist.

The main change to the xdebug.ini file is:

[XDebug]
zend_extension=xdebug.so

xdebug.mode = debug
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal

chadrien/README.md

Debug your PHP in Docker with Intellij/PHPStorm and Xdebug

darius-v commented Sep 3, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

PeteFromSales commented Sep 7, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dgershman commented Oct 28, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

brotherbigbao commented Nov 8, 2018

Uh oh!

Deg5112 commented Dec 12, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

antishov commented Feb 13, 2019

Uh oh!

mickambar19 commented Mar 19, 2019

Uh oh!

weinung-chiu commented Mar 21, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tobinski commented Apr 2, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rahilwazir commented Apr 19, 2019

Uh oh!

lainosantos commented Apr 21, 2019

Uh oh!

rwese commented Jun 3, 2019

Uh oh!

brycefranzen commented Jun 7, 2019

Uh oh!

patrickschur commented Aug 9, 2019

Uh oh!

MiguelAlcaino commented Aug 26, 2019

Uh oh!

patricknelson commented Sep 6, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andrew-svirin commented Oct 3, 2019

Uh oh!

mitogh commented Dec 25, 2019

Uh oh!

NorthenIrbis commented Feb 11, 2020

Uh oh!

bedger commented Apr 22, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Raistlfiren commented Dec 22, 2020

Uh oh!

darius-v commented Sep 3, 2018 •

edited

Loading

PeteFromSales commented Sep 7, 2018 •

edited

Loading

dgershman commented Oct 28, 2018 •

edited

Loading

Deg5112 commented Dec 12, 2018 •

edited

Loading

weinung-chiu commented Mar 21, 2019 •

edited

Loading

tobinski commented Apr 2, 2019 •

edited

Loading

patricknelson commented Sep 6, 2019 •

edited

Loading

bedger commented Apr 22, 2020 •

edited

Loading