Debug containerised PHP application using Xdebug with Vim and Vdebug

Sep 14, 2016 PHP 中文版

Xdebug is a powerful debug tool, which PHP developers are probably familiar with. As the number of Docker users increases, debugging becomes more difficult and complex. Thus, this post is about how to debug containerised PHP application by using Xdebug with Vim and Vdebug.

Install and set Xdebug in Docker container

Before installation of Xdebug, make sure you open the port which Xdebug needs when you create a container. Like this:

# If Xdebug needs port 9000, then add -p 9000:9000 in the command
docker run -d \
           -p 80:80 \
           -p 9000:9000 \
           ...

Let’s install Xdebug in your container:

# Enter into your container
docker exec -it <your-container-name> bash

# Install Xdebug via pecl
pecl install xdebug

Then put Xdebug settings at the end of php.ini (e.g. /usr/local/etc/php/php.ini).

# Skip some content ...

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20131226/xdebug.so
xdebug.remote_enable=1
# Put the IP of Docker container below
xdebug.remote_host=192.168.99.100
xdebug.remote_connect_back=1
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_autostart=true

Don’t forget to restart the container to make sure Xdebug can work correctly.

Install Vdebug

To install Vdebug through Vundle, open your Vim configuration (/etc/vimrc or ~/.vimrc), then add the plugin name and related settings. For example:

" Skip some content ... "

set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()

Plugin 'gmarik/Vundle.vim'
" Add Vdebug here "
Plugin 'joonty/vdebug'

call vundle#end()
filetype plugin indent on

" Skip some content ... "

" Drop Vdebug settings at the end of the file " 
let g:vdebug_options = {
\ 'break_on_open': 1,
\ 'path_maps': {'/path/to/app/in/docker': '/path/to/app/in/local'},
\ 'port': '9000',
\ 'watch_window_style': 'compact'
\ }

After modification to Vim config, let’s install Vdebug by executing the command in Vim:

:PluginInstall

Or, put the command in your terminal:

vim +PluginInstall +qall

Use Vdebug in Vim

How to debug? Open the file that you want to insert breakpoints, and press F10 to add breakpoints. After that, press F5 to start a debug session and then load the page you want to debug. You will see four windows open automatically and show values of variables or related info respectively.

You might also like:

---