How to set up Xdebug with webgrind for PHP Performance Profiling on Mac OS X 10.5 (Leopard)

This is a straightforward guide on how to setup and use Xdebug 2.0.4 with webgrind 1.0 for PHP Performance Profiling on Mac OS X 10.5 (Leopard). Xdebug is a powerful debugging and profiling tool for PHP. While, webgrind is a web-based alternative to kCacheGrind, which allows you to see bottlenecks in your code represented by how much time is spent on each function either in percentages or milliseconds. Basically this will help you figure out which functions are sucking up your resources.

Preparation
This tutorial assumes that you setup PHP using the directions in my article, How to setup Apache, PHP, & MySQL on Mac OS X 10.5 (Leopard). Though it should still work for other setups if you correct the paths used in my examples below; if this is you make sure you know what you’re doing. And, as always make sure to backup any and all files I have you modify!

Open up the Terminal application in /Applications/Utilities

I will be using the GNU nano text editor in my examples since it already comes with the Mac, but if you’d like to use TextMate or BBEdit just replace nano with mate or bbedit respectively and remove any nano specific options (e.g. +n or -w).

Whenever I ask you to type something into Terminal you have to hit the return key for the command to go through. Alternatively, for you lazy ones out there, you can just copy and paste these commands.

Installing Xdebug
Go to the Terminal window and type:
curl -O http://downloads.activestate.com/Komodo/releases/5.2.1/remotedebugging/Komodo-PHPRemoteDebugging-5.2.1-34168-macosx.tar.gz
tar xzvf Komodo-PHPRemoteDebugging-5.2.1-34168-macosx.tar.gz


Now we need to change directories, go back to Terminal and type:
cd /usr/lib/php/extensions/no-debug-non-zts-20060613/

If the /usr/lib/php/extensions/no-debug-non-zts-20060613/ directory does not exist type /usr/lib/php/extensions/no-debug-non-zts- and hit tab and then return.

In the Terminal window type:
sudo mv Komodo-PHPRemoteDebugging-5.2.1-34168-macosx/5.2/xdebug.so xdebug.so

When you put sudo in front of a command you’ll need to enter your root/administrator password if prompted to do so. (Please note this is a pre-compiled copy of Xdebug so if you’re not using PHP 5.2 please move the copy of xdebug.so contained in the folder that corresponds to your version of PHP into the extensions directory. You can find out what version of PHP you’re running by typing php -v into Terminal.)

It’s time to tell PHP to use the Xdebug extension. In Terminal type:
sudo nano -w /private/etc/php.ini

Hold control vuntil you reach the end of the php.ini file, and then copy and paste the text below:
[xdebug]
zend_extension=/usr/lib/php/extensions/no-debug-non-zts-20060613/xdebug.so
xdebug.remote_enable=1
xdebug.profiler_enable_trigger=1

Please note Xdebug has a lot of configuration options. The options above are meant to work with the Firefox Xdebug Helper add-on and webgrind, which we’re going to guide you through setting up next. For more on available config options and what they do check out Xdebug’s Documentation. The documentation is also good if you don’t know how to use Xdebug to debug PHP .

Something extra… If you have TextMate you might want to add this text to the end of the php.ini file:
xdebug.file_link_format = "txmt://open?url=file://%f&line=%l"

This makes error messages clickable and furthermore when you click on one of the links it will open up the problem file and go to the line number containing the error in TextMate.

When you’re finished making changes to the php.ini file hit control x to exit, then type y, and hit return to save your changes.

To complete the setup of Xdebug all you have to do is restart Apache. So, go to Terminal and type:
sudo apachectl restart

Finally, lets make sure Xdebug is installed. Create a file called phpinfo.php (or something similar) and put the following code in it:

<?php phpinfo(); ?>

Now visit the newly created PHP file in your web browser (it should be somewhere like http://localhost/phpinfo.php) and it should have a section that reads something like this:
This program makes use of the Zend Scripting Language Engine:
Zend Engine v2.2.0, Copyright (c) 1998-2009 Zend Technologies
with Xdebug v2.0.4, Copyright (c) 2002-2008, by Derick Rethans

Can’t find it? Here’s a screenshot:

If you really can’t find the text above do a search for “Xdebug” in your browser (normally you can do this by hitting command f.

You should delete the phpinfo.php file you created after you confirm Xdebug is installed.

Installing webgrind
The way we have Xdebug configured we’ll have to use webgrind in conjunction with a Firefox ad-on called Xdebug Helper, so go ahead and install/add it to Firefox. And yes, you’ll have to use Firefox with webgrind. Make sure you restart Firefox before proceeding.

Now, this next part is super easy. Go back to your Terminal window and type:
cd ~/Sites/
curl -O http://webgrind.googlecode.com/files/webgrind-release-1.0.zip
unzip webgrind-release-1.0.zip


Installed. I told you it was super easy.

Now, webgrind should be accessible at: http://localhost/webgrind/ or something like http://localhost/~ariadoss/webgrind/ depending on how Apache is setup on your Mac. In this particular example ariadoss would be your computer’s short name. So replace ariadoss with whatever yours happens to be, you can easily tell what it is from the Terminal cause it’s the name right before the dollar sign (e.g. danilo-stern-sapads-macbook-pro:~ ariadoss$).

To start the Xdebug profiler and a new Xdebug session click on the gray P and the white X on the bottom right of Firefox respectively. The P and X once activated will be surrounded by purple and green circles respectively. The P is to the right of the X, its a bit hard to see so I include some before and after screenshots:

Once you’ve done this visit a site on your localhost and then refresh/update webgrind. Oh, and if you want you can learn more about the webgrind at the official webgrind project page (obviously).

Thanks for reading my tutorial and please don’t hesitate to comment if you found this helpful!