====== Remote debugging with PDT and Xdebug ======

This is how I got remote debugging with [[http://www.eclipse.org|eclipse]] and [[http://www.xdebug.org|XDebug]] to work on a local network. I use a single computer with Win XP as main OS and I run [[http://www.topologilinux.com/|topologilinux]] in [[http://www.colinux.org|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.

^Machine^OS^Hostname^IP^
|Desktop|Windows XP|acer|192.168.0.1|
|Server|Topologilinux|colinux|192.168.0.40|




===== Installing XDebug =====
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 [[http://pear.php.net|PEAR]] or as a pre-compiled binary.



==== Compile from sources ====

** 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.

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


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.

<code>
$ phpize
...
$ ./configure --enable-xdebug 
...
$ make 
...
$ sudo make install
</code>

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).




==== Edit php.ini ====

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.

<code>
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
</code>

  * 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

<code>
$ php -r "phpinfo();" | grep -i xdebug
</code>

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

<code>
$ php -r "phpinfo();" | grep -i php.ini
</code>

  * 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





===== Installing Eclipse with PDT =====

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 [[https://bugs.eclipse.org/bugs/show_bug.cgi?id=169408|bugzilla]]. The files at bugzilla is listed in date order, i used the '[[https://bugs.eclipse.org/bugs/attachment.cgi?id=63598|Example Mapper for XDebug 0.2.0 Support]]' and the '[[https://bugs.eclipse.org/bugs/attachment.cgi?id=66656|Prebuilt Binary of XDebug Support V0.2.1 for PDT RC3 only]]'.

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











===== A sample project ====

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.

<code>
$ mkdir ~/public_html/eclipsetest
</code>

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.

^Kind of URI^value^
|colinux|/home/daniel/public_html/eclipsetest|
|acer|Z:\public_html\eclipsetest|
|HTTP|http://colinux/~daniel/eclipsetest|
|apache|~daniel/eclipsetest|

Now I started eclipse and created a new PHP Projekt. //File->New->Project->PHP->PHP Project// The snapshots were made with Mirek's excellent [[http://www.mirekw.com/winfreeware/mwsnap.html|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//.

{{php:remote_debugging_with_pdt_and_xdebug:new_php_project_dialog.jpg|Create new PHP Project}}

{{php:remote_debugging_with_pdt_and_xdebug:create_eclipsetest.jpg|Project settings}}

Now I created a test.php file, opened it up, added two lines of code and saved it:
<code php>
<?php
echo 'Hello ';
echo 'World';
</code>

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.

{{php:remote_debugging_with_pdt_and_xdebug:add_breakpoint.jpg|Add a 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.

{{php:remote_debugging_with_pdt_and_xdebug:debug_settings_1.jpg|Debug settings, first page}}

{{php:remote_debugging_with_pdt_and_xdebug:debug_settings_2.jpg|Debug settings, second page}}

{{php:remote_debugging_with_pdt_and_xdebug:happy_debugging.jpg|Trying to figure out whats wrong...}}





==== Possible problems ====

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

=== Is XDebug running? ===


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

=== Can I debug locally? ===

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.

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

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.**

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

Waiting for debug server to connect.
</code>

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.

<code>
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]
</code>

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

=== Try to debug remote with console client ===

** !!! 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

=== What else??===
If you come up with another solution, please add a comment below.

==== Conclusion====
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@inkompetent.se|Daniel Holmström]] 2007/05/11 22:30//