Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Using Xdebug in Docker (works with PhpStorm)

Using Xdebug in Docker

Getting setup and running with Xdebug in a docker container these days is now fairly simple and is composed of two main steps:

  1. Ensure you've got XDebug installed and enabled in your PHP docker image, for example:

    # Installing Xdebug with PHP 7.3 images:
    RUN pecl install xdebug \
      && docker-php-ext-enable xdebug
  2. Ensure the remote_host is referencing host.docker.internal (Docker for Windows or Docker for Mac circa 18.03 and later, see docs: Windows and Mac) or 10.0.2.2 for VirtualBox when using Docker Toolbox. For example, here's part of my xdebug.ini:

    ; Allow remote hosts to enable debugging, causing Xdebug to explicitly connect back to the workstation that Docker is running on.  
    
    [XDebug]
    xdebug.remote_enable = true
    xdebug.remote_host = host.docker.internal
    
    ; Or, for workstations using Docker Toolbox (VirtualBox), use: 
    ;xdebug.remote_host = 10.0.2.2

For more detailed example code, please see the files below!

Notes:

FROM php:7.3-fpm-alpine
# This example is extremely barebones and specific to Alpine linux, however in most containers at/below
# php 7.3, you can just run pecl + docker-php-ext-enable (see below) after you've ensured that you have
# also installed phpize (necessary for building PHP extensions).
RUN apk add --no-cache --virtual .phpize-deps $PHPIZE_DEPS \
# Important part:
&& pecl install xdebug \
&& docker-php-ext-enable xdebug \
# Clean up...
&& apk del .phpize-deps
# Copy over our custom xdebug INI configuration which will coexist with the automatically generated
# $PHP_INI_DIR/conf.d/docker-php-ext-xdebug.ini created by the "docker-php-ext-enable xdebug" command above.
COPY ./xdebug.ini $PHP_INI_DIR/conf.d
; For PHP 5.6 and Xdebug 2
; This file is intended to supplement the auto-generated "docker-php-ext-xdebug.ini" that gets created by the
; "docker-php-ext-enable xdebug" command. That ini file will contain the path to the dynamically built extension file
; (which is why they should remain separate).
[XDebug]
; Allow remote hosts to enable debugging, in this case connecting back to the automatically maintained DNS
; name referencing our workstation: host.docker.internal
xdebug.remote_enable = true
xdebug.remote_host = host.docker.internal
xdebug.remote_port = 9000
xdebug.remote_handler = dbgp
; Profiling (enable via cookie or GET/POST variable: XDEBUG_PROFILE=1).
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = /tmp/xdebug-profiling/
; var_dump() settings.
xdebug.overload_var_dump = 1
xdebug.cli_color = 1
; For PHP 7 and Xdebug 3
; This file is intended to supplement the auto-generated "docker-php-ext-xdebug.ini" that gets created by the
; "docker-php-ext-enable xdebug" command. That ini file will contain the path to the dynamically built extension file
; (which is why they should remain separate).
[XDebug]
; General config
;xdebug.remote_enable = true ; Replaced by xdebug.mode=debug, see https://xdebug.org/docs/upgrade_guide and https://xdebug.org/docs/all_settings#mode
xdebug.mode = debug
xdebug.client_host = host.docker.internal
xdebug.client_port = 9000
; Profiling (enable via cookie or GET/POST variable: XDEBUG_PROFILE=1).
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 1
xdebug.profiler_output_dir = /tmp/xdebug-profiling/
; var_dump() settings.
xdebug.cli_color = 1
@patricknelson
Copy link
Author

patricknelson commented Mar 16, 2020

Very welcome @ericjeker! Just wanted to boil it down to bare necessities, since everyone is going to have their own needs.

@patricknelson
Copy link
Author

patricknelson commented Oct 18, 2021

Important: For everyone landing here, the settings changed for XDebug 3. See above and here: https://xdebug.org/docs/upgrade_guide and https://xdebug.org/docs/all_settings#mode

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