Installing Xdebug and webgrind on Ubuntu to debug and profile PHP

Xdebug is a PHP extension that allows us to debug and profile PHP scripts. Its a very handy tool that allows you to profile PHP scripts to figure out the performance bottlenecks or to trace/debug the script. Below is the procedure to install Xdebug and use the information generated by Xdebug for the purpose of profiling and debugging.

In this post I will be discussing the basic installation of Xdebug on Ubuntu and then using 'webgrind' front end to view the profiling data generated by Xdebug. You can install Xdebug in two ways. The first one works if you are using older versions of Ubuntu (below 8.0) and the other one works with Ubuntu 8+. When using the older method of installation, Xdebug is installed through PEAR/PECL. If you have Ubuntu 8+, you can still install Xdebug through PEAR/PECL.

Installing Xdebug through PEAR/PECL:

First install the 'php5-dev' package. This package provides php5 source files, needed to compile additional modules.

sudo apt-get install php5-dev

Next install the 'pear' package.

sudo apt-get install php-pear

Now install Xdebug.

sudo pecl install xdebug

Now find where Xdebug extension is, so the path could be included in the 'php.ini' file as a zend extension.

sudo find / -name 'xdebug.so'

Output: /usr/lib/php5/20090626+lfs/xdebug.so

Now open the 'php.ini' file from the location given below:

/etc/php5/apache2/php.ini

In 'php.ini', you add the path to 'xdebug.so'. Below are minimal configuration option that you can use to get started. A complete list can be found at: http://xdebug.org/docs/all_settings

;xdebug

// ADD XDEBUG AS A ZEND EXTENSION

zend_extension="/usr/lib/php5/20090626+lfs/xdebug.so"

// ENABLE PROFILING OF SCRIPTS. TO TURN OFF PUT 0 OR COMMENT THE LINE

xdebug.profiler_enable=1

// DIRECTORY WHERE THE PROFILING DATA FILES ARE GENERATED
xdebug.profiler_output_dir="/tmp"

// IN CASE THE PROFILE NAME IS SAME, OVERWRITE THE FILE. 0 WILL APPEND DATA
xdebug.profiler_append=0

// THE PROFILE FILE NAME %t = TIMESTAMP, %p = PROCESS ID
xdebug.profiler_output_name = "cachegrind.out.%t.%p"

Now restart the 'Apache' server.

sudo service apache2 restart

New installation method:

First install Xdebug.

sudo apt-get install php5-xdebug

Now find where Xdebug extension is, so the path could be included in the 'xdebug.ini' file as a zend extension.

sudo find / -name 'xdebug.so'

Output: /usr/lib/php5/20090626+lfs/xdebug.so

Now open the 'xdebug.ini' file from the location given below:

/etc/php5/conf.d/xdebug.ini

In 'xdebug.ini', you add the path to 'xdebug.so'. Below are minimal configuration option that you can use to get started. A complete list can be found at: http://xdebug.org/docs/all_settings

;xdebug

zend_extension="/usr/lib/php5/20090626+lfs/xdebug.so"

xdebug.profiler_enable=1

xdebug.profiler_output_dir="/tmp"

xdebug.profiler_append=0

xdebug.profiler_output_name = "cachegrind.out.%t.%p"

Note: These are the same configuration settings as mentioned in installation method above. For explanation of each configuration refer to the previous method.

Now restart the 'Apache' server.

sudo service apache2 restart

After installation:

Now that you have successfully installed Xdebug, its time to test your installation. Execute any of the PHP scripts you have, or just write a simple php script and execute it. After execution, you will see that there is a Xdebug Profile file in the "/tmp" directory. Hence the installation was successful.

Now that the profiles are being generated, lets switch on to 'webgrind', which is a web-based tool to provide profile information in a meaningful fashion.

First download 'webgrind' from the location below:

http://code.google.com/p/webgrind/downloads/list

Extract the compressed files to "/var/www/webgrind" or any location you want (should be served by Apache)

Now open the 'webgrind' config file from the location below:

"/var/www/webgrind/config.php"

Or any location where you have extracted the 'webgrind' package.

In 'config.php', change the following variables:

static $storageDir = '';  // DIRECTORY WHERE YOU WANT TO STORE webgrind FILES

static $profilerDir = '/tmp'; // DIRECTORY WHERE THE Xdebug PROFILE FILES ARE

Now you can run 'webgrind', by executing the index.php file. It can be found in the following location:

"/var/www/webgrind/index.php"

Or any location where you have extracted the 'webgrind' package.