Solved: A Step-by-Step Guide to PHP Debugging in Docker with Vim and Xdebug 3

Setting up PHP debugging in Docker can feel convoluted, especially when connecting Vim on your local machine to Xdebug running inside a container. This guide cuts through the noise and provides a clear, two-part setup for configuring Vim (with Vdebug) and Docker’s Xdebug, so you can start debugging with confidence.

Part 1: Configuring the Client (Vim & Vdebug) for PHP Debugging in Docker

First, ensure you have the vdebug plugin for Vim. You can install it using a plugin manager like vim-plug

Plug 'vim-vdebug/vdebug'

Next, add the following configuration to your .vimrc. The most critical part is path_maps, which translates file paths from the container to your local filesystem.

" ============================================
" Vdebug Configuration
" ============================================
if !exists('g:vdebug_options')
    let g:vdebug_options = {}
endif

" The port must match Xdebug's xdebug.client_port setting in the container.
let g:vdebug_options.port = 9500

" Map server paths (in Docker) to local project paths.
let g:vdebug_options.path_maps = {
    \ "/var/www/project-path-inside-docker-container/legacy" : "/home/jespinal/Projects/YourCompany/foolegacy",
    \ "/var/www/project-path-inside-docker-container/cms/current" : "/home/jespinal/Projects/YourCompany/foocms",
    \ "/var/www/local.srv.foobar/current/" : "/home/jespinal/Projects/YourCompany/foobar",
    \ "/var/www/local.srv.barbaz/current/" : "/home/jespinal/Projects/YourCompany/barbaz",
\ }

" Other useful settings.
let g:vdebug_options.break_on_open = 0
let g:vdebug_options.debug_file = "/tmp/vdebug.log"
let g:vdebug_options.debug_file_level = 4

 

Part 2: Configuring the Server (Docker & Xdebug) for PHP Debugging

Now, configure Xdebug inside the running PHP-FPM container.

1. Connect to your container

docker exec -it your_php_container-fpm-74 bash

Create a new Xdebug config file.

Using a zz- prefix helps ensure it’s the last .ini file loaded, overriding any defaults. Create the file /usr/local/etc/php/conf.d/zz-xdebug.ini with the following content.

[xdebug]
; Enable development helpers and step debugging.
xdebug.mode=develop,debug

; Start the debugger on every request.
xdebug.start_with_request=yes

; Have Xdebug automatically detect the IP of your IDE.
; It checks variables like $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'].
xdebug.discover_client_host=true

; Fallback host if discovery fails. This should be your local machine's
; IP on the Docker network.
xdebug.client_host=10.0.0.1

; The port Xdebug connects to. This MUST match the port in your .vimrc.
xdebug.client_port=9500

; The IDE key to identify your debugging client[cite: 49, 57].
xdebug.idekey=vim

Part 3: Verification of Your PHP Debugging Setup in Docker

 

To apply the new settings, you must restart the container so PHP-FPM can load the new configuration.

docker container start your_php_container-fpm-74

 

To verify that PHP-FPM is using the new settings, you can create a simple info.php file in one of your project’s web-accessible directories.

<?php
phpinfo();

When you access this file in your browser, inspect the “xdebug” section. You should see your custom settings from zz-xdebug.ini reflected. You should also see zz-xdebug.ini listed under the “Additional .ini files parsed” section.

With this setup, you can set breakpoints in Vim, press <F5> to start listening, and any incoming web request to your application will trigger the debugger, pausing execution at your breakpoint.

Tagged connect Vim to Xdebug in Docker, debug PHP in Vim, step debugging PHP Docker, Vdebug path_maps, Xdebug Docker setup