Easy PHP Debugging in Ubuntu (using Xdebug and Vim)

by Liam McDermott, 1 August 2007 - 11:54am

A debugger helps greatly when testing or bug fixing in PHP, when working with complicated code, or fixing difficult problems: a debugger is an invaluable tool. This article shows how to set up a PHP debugger in Ubuntu (tested on both Feisty 7.04 and the upcoming Gutsy 7.10) using Xdebug and Vim. This is aimed at developers who may be good at coding but are not necessarily familiar with GNU+Linux in general, therefore everything is explained simply and step-by-step.

Installing LAMP (Linux, Apache, MySQL, PHP)

Firstly open a terminal by clicking Applications -> Accessories -> Terminal. Do not be frightened of the terminal though, it is one of GNU+Linux's most powerful tools; in this case it makes working through the article easy, all the reader has to do is copy and paste from article to the terminal. Firstly select then click Edit -> Copy on the line below:

sudo apt-get install apache2 php5 php5-gd mysql-server php5-mysql apache2-dev php5-dev php-pear make vim-full python2.5

Then click Edit -> Paste in the terminal. Note: when the tutorial says Copy or Paste, Ctrl-c (for copy) and Ctrl-v (for paste) can be used as well. Just as in other operating systems, middle-click also works for copy/paste operations.

Press Enter and fill-in the administrator password. This will install the software required for later steps. Next open the /etc/php5/apache2/php.ini file by selecting, then clicking Edit -> Copy on the text below:

gksu gedit /etc/php5/apache2/php.ini &

Edit -> Paste this into the terminal and press Enter, opening a text editor. Do not do anything with this yet, return to the terminal, it will be required later.

Download and Install Xdebug

Select then Edit -> Copy the following:

sudo pecl install xdebug-beta

Then click Edit -> Paste to download and install Xdebug (the PHP debugger). This last command will spew lots of data into the terminal, in the last few lines is a note showing where Xdebug has been installed. It will look similar to:

Installing
'/var/tmp/pear-build-root/install-xdebug-2.0.0RC4//usr/lib/php5/20060613+lfs/xdebug.so'

Or:

Installing '/usr/lib/php5/20060613+lfs/xdebug.so'

Select the /usr/lib/php5/20060613+lfs/xdebug.so part in the terminal with the cursor, then click Edit -> Copy. This line may vary for different versions of XDebug, particularly the part which is a date, if in doubt select from /usr/lib/ up to (and including) xdebug.so.

Bring back the text editor opened earlier, search through the file (pressing Ctrl-f then entering ‘module settings’ works) and find the section marked:

;;;;;;;;;;;;;;;;;;;
; Module Settings ;
;;;;;;;;;;;;;;;;;;;

Click the empty line beneath it (or create one) and enter:

zend_extension=

Then click Edit -> Paste to paste the location of Xdebug into the file. The zend_extension line should look similar to:

zend_extension=/usr/lib/php5/20060613+lfs/xdebug.so

Having done this press Enter afterwards to create a new line (there are more settings to be pasted into the file).

Select the text below, and Edit -> Copy:

[debug]
; Remote settings
xdebug.remote_autostart=off
xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_host=localhost
xdebug.remote_port=9000

; General
xdebug.auto_trace=off
xdebug.collect_includes=on
xdebug.collect_params=off
xdebug.collect_return=off
xdebug.default_enable=on
xdebug.extended_info=1
xdebug.manual_url=http://www.php.net
xdebug.show_local_vars=0
xdebug.show_mem_delta=0
xdebug.max_nesting_level=100
;xdebug.idekey=

; Trace options
xdebug.trace_format=0
xdebug.trace_output_dir=/tmp
xdebug.trace_options=0
xdebug.trace_output_name=crc32

; Profiling
xdebug.profiler_append=0
xdebug.profiler_enable=0
xdebug.profiler_enable_trigger=0
xdebug.profiler_output_dir=/tmp
xdebug.profiler_output_name=crc32

Return to the php.ini file in the text editor. Edit -> Paste beneath the zend_extension line, this should put the lines copied above into the php.ini file. Next click File -> Save, and close the text editor. Select then Edit -> Copy the following and Edit -> Paste into the terminal to restart Apache:

sudo /etc/init.d/apache2 restart

Configure Vim for PHP Debugging

Now a plugin for Vim which enables PHP debugging is required . Firstly Vim needs a directory for plugins: from the main menu click Places -> Home Folder, this should open a new file browser window. From this window, click View -> Show Hidden Files and check whether a directory named .vim exists (note the full stop at the start of the directory name), if not right-click, select Create Folder (and enter ‘.vim’) to create it.

Open a Web browser and go to this address:

http://www.vim.org/scripts/script.php?script_id=1929

Download this script—currently named debugger.zip—to the .vim directory (hidden files can be shown in the save as box by right-clicking in the file list and selecting Show Hidden Files). From the file browser opened earlier double-click the zip file, then in the window that appears right-click the plugin directory and click Extract. Click Extract to extract the plugin to the .vim directory (check the extract file selection box has defaulted to the .vim directory before extracting, if the files are not in that directory the plugin will not work). The PHP debugging script for Vim should now be installed.

To check the plugin is where it should be, navigate to the: .vim/plugin/ directory using the file browser. Inside this directory should be two files:

debugger.py
debugger.vim

PHP Debugger Testing

To test the debugger start Vim by pressing Alt-F2 on the keyboard, type gvim in the box provided, then press Enter. Note: there is a main menu entry for Vim, but it is hidden by default. Right-click on the main menu (top-left of the screen) and click Edit Menus to rectify this. Also required is a PHP script (on the local machine). Open the script in a Web browser but add ?XDEBUG_SESSION_START=1 on the end of the URL (as usual Edit -> Copy/Paste can be used to copy/paste from this article). For example, the URL might look similar to:

http://localhost/test.php?XDEBUG_SESSION_START=1

Press F5 in Vim, then quickly switch to the Web browser and press the Reload button. This must be done within five seconds or Vim will display an error. Don't worry if it does though, just press F5 again. When successfully debugging Vim should stop on the first line of PHP code in the file, it also shows help on how to step-over, step-into, and run etc. use that to learn the commands.

The screenshot below shows Vim debugging PHP. Note: if Vim does nothing when F5 is pressed, it has not been setup correctly, check that the plugin has been installed correctly.