Using Xdebug in Docker (works with PhpStorm)

- Using Xdebug in Docker.md

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:

• These examples are very generic and should work in most of the official PHP docker container images for PHP 7.3 and below. However, starting with PHP 7.4, the pecl command will no longer be available. See: Installing PHP extensions from source in your Dockerfile
• For Alpine linux variants, ensure that you have also installed phpize (necessary for building PHP extensions).

Dockerfile

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

xdebug.php5.ini

; 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

xdebug.php7.ini

; 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

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

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