Ubuntu 12.04 PHP Apache and Xdebug

Until recently on my development machine I ran Zend server community edition inside Ubuntu. This provided a quick and convenient way to install the PHP application stack, but the biggest benefit was the simple integration with the Zend debugger. By simply clicking the "Debug" button in the Zend studio toolbar extension to Firefox, you are taken into a debug session for the current URL, usually with no or minimal configuration.

Ubuntu 12.04

When I upgraded my OS to the latest version of Ubuntu (12.04), the Zend server package no longer worked. The problem has been acknowledged by Zend and at the time of writing, a partial fix is in place but use with SSL will crash Zend server. For more information on the problem, try this Zend forum post: http://forums.zend.com/viewtopic.php.

Xdebug to the rescue

Working on a large and complex system utilising two frameworks including the Zend Framework, a debugger is a very useful tool. Having reverted to the normal LAMP stack provided from Ubuntu's repositories (I wasn't willing to restore my operating system to the earlier version), I decided to investigate Xdebug. Installing Xdebug is as simple as sudo apt-get install php5-xdebug.

The following changes are based on Zend Studio 9.0.3. First, tell Eclipse (I'll use Eclipse to mean Eclipse or Zend Studio from here on) to use an external browser instead of it's internal browser. This is not essential, but recommended. In Eclipse, choose the Window > Preferences menu, Then expand the General section and select the Web Browser entry. Select the Use external browser radio option, and (if required) use the new or edit buttons to define your external browser (in my case, Firefox). Don't forget to ensure you tick the check box next to the external browser you want to use.

 Eclipse external browser dialog

Next, we need to configure the debugger within a particular workspace and project. Open Eclipse and open the workspace and project for which you want to setup the debugger. Click the drop down arrow at the side of the debug button in the toolbar (highlighted by the red arrow in the screen shot below), and choose the Debug Configurations... entry.

 Eclipse debug configuration button

Expand the PHP Web Application section in the left hand side menu, then click the New button to create a new configuration. Give it a suitable name (or if you're lazy like me, leave the auto generated name). There are now four tabs in the main window, Server, Advanced, Deployment and Common. So far, I've only needed to make changes in the Server tab. Set the Server Debugger to XDebug. Next you need to create a new PHP Server (by clicking the New button at the end of that field).

Give your new PHP server a name that you'll recognise. Set the Base URL to the value you'd enter in your browser to go to the home page of your application. Then specify the Local Web Root for your application. Typically this will be the same as the DocumentRoot directive in the Apache configuration for the virtual host that points to your web application. Click Finish as no other changes should be required. An example configuration can be seen below.

Eclipse PHP server config

You may or may not want to enable the Break at First Line check box. I usually have it unchecked, but it may be useful to leave it checked for now so that it's easier to see if the debug session is running. Next, click the Browse button for the File field and select the file (usually index.php) that is responsible for the home page. In the URL section, you'll probably need to un-check the Auto Generate option and clear the right had text box to make the URL valid (you should know the URL of your application, and we want this value in here). When that's done, you should have something similar to below.

Eclipse debug Configuration

If all has gone well, you are now ready start a debug session for your application. Simply click the debug button from the toolbar (as above but this time not the side arrow). A new instance or tab of your browser should start and Eclipse will switch to the debug perspective. If you left the Break at first line option checked, the new browser window/tab will most likely be blank, as the debugger will have paused execution at the first line of code it encounters. You are now free to use the debugger to explore your code.