Automated Xdebug Setup in LazyVim Using Ansible

Table of contents

Requirements

• Lazyvim / neovim
• Ansible
• Docker compose

This article is based on my lazyvim and .dotenv repositories.

Setup

Clone the .dotenv repository

git clone https://github.com/eerison/.dotfiles.git

Run the ansible playbook

ansible-playbook -i hosts playbook.yaml -t lazyvim -t php

Configure xdebug in your docker compose

Copy the compose.override.yaml file into your project directory:

cp ~/.config/nvim-external/xdebug-config/compose.override.yaml ./<your-project-path>

After you copy the file above, restart your containers.

Configuration notes

• Your docker work directory must be /app, If it’s different, update it in the php.lua file.
• compose.override.yaml overrides the app container. If your container has a different name, update the override file accordingly.

Troubleshooting

If you encounter issues, try the following options:

Telnet

Check if you can connect on 9003 port using Telnet, you should see:

telnet localhost 9003

# Trying 127.0.0.1...
# Connected to localhost.
# Escape character is '^]'.

type Ctrl + ] and then close to close telnet connection.

Enable logs in Lua config

To debug more deeply, enable logging in the php.lua config file.

          type = "php",
          request = "launch",
          name = "Listen for Xdebug",
+         log = true,
          port = 9003,

You can check more settings on vscode-php-debug repository