Skip to main content

Debugging PHP in Docker with Xdebug, Neovim and DAP

I've been a full-time Neovim user for a year at the time of writing this post and whilst I was a semi-regular Xdebug user, it's something that I've managed to work around and have mostly resorted to var_dump(), dump(), or dd() instead for debugging.

This week though, whilst working on some particularly tricky PHP code, I decided to spend some time and get Xdebug working and be able to use a step debugger within Neovim.

Installing Xdebug

Installing Xdebug itself within Docker was straight forward. I was able to add two lines to my existing RUN command - pecl install xdebug to install the extension and docker-php-ext-enable xdebug to enable it.

Now when I run php -v inside my container, I can see that it mentions Xdebug.

Configuring Xdebug


Installing DAP plugins

I use Packer for managing my Neovim plugins so I needed to install some additional ones to add the DAP (debug adapter protocol) functionality.

use "mfussenegger/nvim-dap"
use "rcarriga/nvim-dap-ui"
use "theHamsta/nvim-dap-virtual-text"
use "nvim-telescope/telescope-dap.nvim"

Installing DAP dependencies

There's also a prerequisite for install the vscode-php-debug adapter.

I configure my laptop with Ansible, so I added a new debugger role that is responsible for cloning this repository and installing its contents:

Configuring DAP for Xdebug

dap.adapters.php = {
  type = "executable",
  command = "node",
  args = { os.getenv("HOME") .. "/build/vscode-php-debug/out/phpDebug.js" }

dap.configurations.php = {
    type = "php",
    request = "launch",
    name = "Listen for Xdebug",
    port = 9003,
    pathMappings = {
      ["/var/www/html"] = "${workspaceFolder}"

I first needed to configure the adapter to use vscode-php-debug and then add a DAP configuration.

The default port for the step debugger is now 9003 rather than 9000 so I changed this from the default, and as I'm working with PHP inside a container, I also added a path mapping so that my code could be found.

Testing the connection

[Step Debug] Creating socket for 'host.docker.internal:9003', getaddrinfo: Invalid argument.

      - "/tmp/xdebug:/tmp/xdebug"
      - "host.docker.internal:host-gateway"


Comments or questions? I'm @opdavies on Twitter.