Skip to content

Instantly share code, notes, and snippets.

@patricknelson

patricknelson/- Using Xdebug in Docker.md

Last active October 15, 2023 19:59
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save patricknelson/57ae24986cb13613314fb1f3c00a95d7 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save patricknelson/57ae24986cb13613314fb1f3c00a95d7 to your computer and use it in GitHub Desktop.
Download ZIP
Using Xdebug in Docker (works with PhpStorm)
Raw
README.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:

    RUN pecl install xdebug \
  && docker-php-ext-enable xdebug \

    Note: This example is extremely generic and should work in most of the official PHP docker container images, especially if you've ensured that you have also installed phpize (necessary for building PHP extensions).

  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

Note that these examples are highly simplified. See files below for more detailed example code.

Raw
Dockerfile
FROM php:7-alpine
# This example is extremely barebones and specific to Alpine linux, however in most containers
# 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
Raw
xdebug.ini
; 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
@ericjeker
Copy link

ericjeker commented Mar 11, 2020

Thanks for the simple, clutter free, example!

@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