Martijn's PHP Coding Blog

This post contains my installation notes on how to setup the Eclipse PHP IDE with support for XDebug remote debugging in a mixed Windows/Ubuntu development environment.

One of the great things of writing PHP code in a modern IDE is that you can step through your code, set break points and inspect variables. No more endless print/echo statements, or including your own custom logging code every few lines.

The war to decide the best IDE is far from over. If you would like to write PHP code and are looking for a free IDE (Integrated Development Environment) then both Eclipse PHP and the Netbeans IDE are two very strong candidates. Both are written in JAVA. For this post I concentrate on my own favorite: Eclipse. If you would like to compare several other PHP IDE’s then Davey Shafik has a great table comparing IDE features on his site.

Debugging is done through a remote debugger called XDebug. It ties into the PHP runtime on your server allowing Eclipse to communicate with your scripts / web pages. As soon as you start debugging a web page, Eclipse will call your webserver but also pass a couple of parameters. On seeing these parameters (XDEBUG_SESSION_START/KEY), XDebug will start and connect to Eclipse over a TCP/IP connection. From here on Eclipse can control the execution of the script on the webserver.

My development setup

For writing PHP code I use two machines. Windows 7 as my main machine and a Linux server that runs the  LAMP development stack. (If you don’t have two machines available a very good alternative is to install VMWare Player and a Ubuntu Server Virtual Appliance on the Windows machine.) Why two machines? I guess I grew up this way. It is perfectly possible to install Eclipse for Ubuntu and do everything on a single machine.

IP Address	Machine Function	Software
10.0.0.1	Ubuntu 8.1 Server	Apache 2 / PHP 5.2.6-2ubuntu4.3
10.0.0.2	Windows 7	Eclipse Galileo for PHP Developers

My Eclipse projects are located on the Ubuntu server through a shared path to my home directory (Z:) on the Ubuntu server.

I can access my work through the webserver as http://development/~martijn by using Apache’s mod_userdir.

Step #1: Download and Install SUN Java & Eclipse

1. Ensure that you have Sun JAVA installed on your Windows machine.
2. Download Eclipse for PHP Developers from the Eclipse download site (http://www.eclipse.org/pdt/downloads/)
3. Untar the tar.gz bundle to a directory on your machine (for example c:\eclipse)

Step #2: Install XDebug on the development server

I assume that you have already installed both Apache and PHP5 on your server. If you haven’t then the following commands will make quick work of this:

# sudo apt-get install apache2 php5 php5-cli

XDebug is installed through the PHP Pear repository, but before this we need to ensure that we have both PEAR and phpize (part of php5-dev) installed.

# sudo apt-get install php-pear

# sudo apt-get install php5-dev

# sudo pecl install xdebug

Now we need to discover where the xdebug.so file was installed by PEAR:

# find / –name xdebug.so

For my Ubuntu server this was:

/usr/lib/php5/20060613/xdebug.so

Create a file named xdebug.ini in /etc/php5/apache2/conf.d, and modify this according to the location of your xdebug.so file:

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

[xdebug]
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_host=10.0.0.2

The above is a very basic setup. The “xdebug.remote_host” is important: it contains the IP address of the Windows development machine. When a web page is called with a special set of parameters XDebug will launch and try to connect to your IDE. Note that the Windows firewall might block Eclipse from listening on Port 9000, if so, then make sure that this port is opened for use by Eclipse.

Restart Apache

# sudo service apache2 restart

We need to test that xdebug was properly installed. Create a small test.php PHP script and place this in your web server root.

<?php phpinfo(); ?>

On my machine I can retrieve this file by calling: http://development/~martijn/test.php. If XDebug was succesfully installed you should see it listed as one of the PHP modules.

Step #3: Setting up Eclipse for debugging code with XDebug

Create a new PHP Project and ensure that the files are in a path that is accessible by the webserver (my Z:\ drive mapping to http://development/~martijn/). If you have done this then you are ready to debug your first PHP code. (You can of course manually copy the files back and forth, but that gets old fast if you do a lot of coding). Start Eclipse, create a new PHP Project and create a little bit of test code. Something like this:

<?php
for ($lp = 0; $lp < 10; $lp++)
echo $lp;
?>

Select Run / Debug Configurations … from the Eclipse menu. Change the Debug Server setting to “XDebug” and ensure that the Default Webserver points to your web directory. In the hope that a picture explains it all click on the screenshot to the right.

Select the line you want the code to stop at (by default it will stop at the first line) and toggle a breakpoint with CTRL-SHIFT-B. Then select Debug (F11).

And that should be it… have fun!

Tags: eclipse, php5, xdebug

This entry was posted on Friday, November 13th, 2009 at 10:47 am and is filed under PHP. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.