Remote debugging with PDT and Xdebug

This is how I got remote debugging with eclipse and XDebug to work on a local network. I use a single computer with Win XP as main OS and I run topologilinux in coLinux as a development server. However this should work on most os:es. For file-transfer between the server and the desktop I use samba.

My server is running Apache 1.3.37, the Topologilinux standard install. I've compiled PHP Version 5.2.2 myself.

I compiled XDebug from the sources but there are other ways to install XDebug, with PEAR or as a pre-compiled binary.

DO NOT do this as root!!!

You need to have write privileges to /usr/local/src for doing this, if you don't, put yourself in an admin group (I use the group 'adm') and change group on /usr/local/src.

I downloaded 2.0.0RC3 from xdebug.org and unpacked it in /usr/local/src.

$ cd /usr/local/src
...
 $ wget http://xdebug.org/link.php?url=xdebug200rc3
...
 $ tar -zxf xdebug-2.0.0RC3.tgz
 $ cd xdebug-2.0.0RC3

Then I run phpize, configure and make+make install. Make sure that both configure and make works before continuing to the next step. configure might fail in php-config isn't in your path, then make sure to add –with-php-config=/path/to/php-config to configure.

$ phpize
...
$ ./configure --enable-xdebug 
...
$ make 
...
$ sudo make install

It says in the README that one should copy xdebug.so to your php extension directory, but make install worked fine for me(and yes I do use sudo).

This is what I put in my php.ini. Check which php.ini is used with a phpinfo-page. Apache might not use the php.ini you think it does.

zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20060613/xdebug.so
[xdebug]
xdebug.remote_enable=1
xdebug.remote_handler=dbgp
xdebug.remote_mode=req
xdebug.remote_port=9000
xdebug.remote_host=192.168.0.1
xdebug.remote_log=/var/log/apache/xdebug_remote

• I'm using zend_extension since I use apache 1.3. If you use Apache 2 you probably should try zend_extension_ts. This may also depend on thread/no thread support.
• The remote_port and remote_mode options isn't required it seems like, but I used them anyway. They are set to their default values.

The real important thing here is to get remote_host right. This should be the address, hostname or ip, of the computer running eclipse. I used the ip because I wanted to be absolutely sure there wasn't anything fishy going on somewhere with hostnames and stuff. I also added a logfile, just for laughs.

After this was done I restarted apache and checked for the xdebug entry in phpinfo().

If it isn't there you should try these things:

Don't forget to restart apache everytime you alter php.ini

If the php intepreter uses the same php.ini as apache you can check for xdebug with the command

$ php -r "phpinfo();" | grep -i xdebug

You get the location of php.ini that the intepreter uses by running

$ php -r "phpinfo();" | grep -i php.ini

• Does xdebug.so exist? If not, reinstall xdebug
• Make sure that zend_extension is set to the full path to xdebug.so, NOT relative to your extension-dir
• Try both zend_extension_ts AND zend_extension
• Get drunk

This was very straight forward, so I'm not going to comment very much on this. I downloaded PDT from http://www.eclipse.org/pdt/index.php and the debugger plugin from bugzilla. The files at bugzilla is listed in date order, i used the 'Example Mapper for XDebug 0.2.0 Support' and the 'Prebuilt Binary of XDebug Support V0.2.1 for PDT RC3 only'.

1. Get PDT 200704 RC3, I downloaded the all-in-one version
2. Extract pdt to somewhere
3. Get the pdt xdebug extensions(0.2.0) and the samplemapper(0.0.1)
4. Put the xdebug and samplemapper .jar-files in the eclipse plugin directory

I first made a sample project to check if the setup was working. I made a directory in my linux-users public_html, which is where I do all my work.

$ mkdir ~/public_html/eclipsetest

This is my users public html directory so the url to this folder is 'http://colinux/~daniel/eclipsetest'. My home-directory is also connected as a network drive in XP with the label 'Z' so the path to this directory in windows is 'Z:\public_html\eclipsetest'. This gives us three different addresses to this directory.

Now I started eclipse and created a new PHP Projekt. File→New→Project→PHP→PHP Project The snapshots were made with Mirek's excellent MWSnap.

I named the project eclipsetest, unchecked the Use Default box in Project contents and browser to the eclipsetest directory created above. I didn't care about any other settings for now, just wanted to see if debugging worked so I clicked Finish.

Now I created a test.php file, opened it up, added two lines of code and saved it:

<?php
echo 'Hello ';
echo 'World';

I set a breakpoint at the 'Hello' line, you cat set a breakpoint by just double-clicking on the gray bar at the left by the rownumbers. A blue dot will turn up indicating the breakpoint.

I opened the Debug dialog, Run→Debug, and choose PHP Web Script With XDebug→New Configuration. Here I choose my test.php, set the server URL to 'http://colinux' and Context Root to '~daniel/eclipsetest'. Note that the Context Root is the files location on the webserver. 'Generate URL' worked fine so I just used that url.

I switched to the HTDoc tab and put in the colinx path to my file. since the project has the same name as the directory it's in I checked the Include project directory in mapping. This means that when eclipse sends a breakpoint location to xdebug it will prepend '/home/daniel/public_html' to the files path in eclipse, in this case 'eclipsetest/test.php'. That will enable xdebug to find the file and break at that point.

Finally I pressed Apply and then Debug. And voila, the debugger started and halted at the first breakpoint.

If this doesn't work this is probably the steps one should take to try to find the source of the problem.

Is XDebug visible in the output of phpinfo();? If not, go to the top and try again.

Try to debug on the server first before trying to fix things on the client. You need to install the console client first. The sources are in the subdirectory 'debugclient', There's also a binary download at http://www.xdebug.org. For some reason configure wasn't executable so I had to chmod it.

$ cd /usr/local/src/xdebug-2.0.0RC3/debugclient
$ chmod 755 configure
$ ./configure
$ make
$ sudo make install

Now change remote_host in php.ini to 'localhost'. Then start the xdebug client and request test.php from the server, adding '?XDEBUG_SESSION_START=SOMETHING&KEY=1' to the url. If the client puts out some xml it means it works locally.

!!! Don't forget to restart apache.

$ debugclient
Xdebug Simple DBGp client (0.9.1)
Copyright 2002-2006 by Derick Rethans.

Waiting for debug server to connect.

Fire up your browser with the url to the page on your remote server, in my case 'http://colinux/~daniel/eclipsetest/test.php?XDEBUG_SESSION_START=SOMETHING&KEY=1', and look for output in the console. Kill the client with CTRL-C.

Connect
<?xml version="1.0" encoding="iso-8859-1"?>
<init fileuri="file:///home/daniel/public_html/eclipsetest/test.php" language="P
HP" protocol_version="1.0" appid="594" idekey="SOMETHING"><engine version="2.0.0
RC3"><![CDATA[Xdebug]]></engine><author><![CDATA[Derick Rethans]]></author><url>
<![CDATA[http://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2007 b
y Derick Rethans]]></copyright></init>
(cmd)

[CTRL-C]

If this doesn't work it won't work from the remote host either.

!!! Don't forget to restart apache after altering your php.ini

• Make sure you set remote_host to your computers ip. Hostname should probably work, but ip WILL work, so use that instead
• Get the client for your computer, download a binary or compile it the same way as above
• Close Eclipse - VERY IMPORTANT
• Do the same as on the server above

If you come up with another solution, please add a comment below.

Setting up PDT to work with XDebug was quite straight forward, however I felt that this information should be at one place and with screenshots from the latest PDT and plugin-version.

All the people involved in the tools used, slackware/colinux/topologilinux, apache, bash, vim, eclipse, PDT, xdebug and the xdebug-plugin are worth huge applauses for their work, it is much appreciated. Thanks!

— Daniel Holmström 2007/05/11 22:30