Thursday, July 26, 2007

Local workstation xampp/Eclipse PDT/xdebug on Ubuntu Linux from start to end

These instructions are for (specifically) Ubuntu Linux. You can find the Windows XP instructions here. All the instructions under here should be executed as the non-root user.

Step 1: Download xampp
You can download xampp for Linux here:
http://www.apachefriends.org/en/xampp-linux.html
Also, there may be packages available within your distro. If there are, I recommend you use them.

Step 2: Install xampp
Uncompress the file you downloaded. Inside you will find a 'lampp' directory. Use sudo to move this into /opt on your machine. This is where xampp is pre-configured to go. If you do not place it in /opt you will need to use a command like this:

# sudo find <xamppHome> -type f -exec fgrep /opt/lampp {} /dev/null \;

To root out all the config files that need to have their path altered.


Step 3: Start xampp and test

Execute <xamppHome>/lampp start

Swing a browser on your xampp machine to 'http://localhost' to test the installation. You should see a flashy splash screen.

You might also want to put a file called phpinfo.php in your htdocs directory. You'll want it to have the following contents:

<?php phpinfo() ?>

Hit the page 'http://localhost/phpinfo.php' and you've just executed a php script that tells you all about your php installation.

Step 4: Download Eclipse PDT

Note: For Eclipse PDT to work on Ubuntu, I had to install the actual Sun JRE (package sun-java6-bin). Select it in Synaptec package manager, apply it, logoff, login, and Eclipse will work.

Eclipse PDT is a version of Eclipse that is bundled specifically for PHP developers. It's a good place to start when you're a PHP developer. The latest version is M1. You can download the latest integration build at:
http://europa-mirror1.eclipse.org/tools/pdt/downloads/?release=I20070712

You want the 'all-in-one' package for your platform. It's Java, so at it's heart it is platform independent, but it uses widgets that are platform specific.

Step 5: Install Eclipse PDT
Uncompress the file you just downloaded. Somewhere inside there you will find a directory called 'eclipse'. Move that into the home directory of the non-root user you will be developing under, or some directory under that home. From here on in I will refer to this directory as <eclipseHome>.

Step 6: Download xdebug server install and configure in php.
Download at: http://www.xdebug.org

Linux users may need to do the following:
  • Download the file
  • Install phpize (may need to install package php5-dev to get it)
  • Uncompress the file and navigate to the directory
  • $ phpize
  • $ ./configure --enable-xdebug
  • $ make
  • $ cp modules/xdebug.so /lib/php/extensions
In both etc/php.ini, make the following configuration changes:

- set 'implicit_flush = On'
- Add the following to the end of the file:
[xdebug]
xdebug.remote_enable=1
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler="dbgp"
zend_extension="/lib/php/extensions/xdebug.so"


Step 7: Restart xampp and test xdebug

$ sudo /opt/lampp/lampp restart

Now browse to http://localhost/phpinfo.php. You should see a section for xdebug. This means that the xdebug extension is running properly.

Step 8: Download Eclipse xdebug plugin

You want the 'Prebuilt Binary V0.2.3'. Here's the download link:
https://bugs.eclipse.org/bugs/attachment.cgi?id=74296

Extract the file and move the two jar files within into the <eclipseHome>plugins directory.

Step 9: Point Apache into the Eclipse workspace

If this is to be purely an Eclipse/xdebug workstation, it's best to change the xampp Apache DocumentRoot so that it will look to the Eclipse workspace for any web page that you open. Edit <xamppHome>/etc/httpd.conf and change the following:

From:
User nobody
Group nogroup
To:
User <yourDevUser>
Group <yourDevUsersGroup>

Note: This is really insecure. Do not use this in an environment that is open to the internet. I'm also working with the assumption you will be the only user accessing this webserver and so it will only have permission to see your files with this setting.

Also,
From:
DocumentRoot /opt/lampp/htdocs
To:
DocumentRoot <eclipseHome>/workspace

Also,
From:
<Directory "/opt/lampp/htdocs">
To:
<Directory "<eclipseHome>/workspace">

Because you have changed httpd.conf, you should restart xampp now.

$ sudo <xamppHome>/lampp restart

Step 10: xdebug configuration within Eclipse
Fire up Eclipse by executing the appropriate binary in <eclipseHome>.; When it asks you about the workspace, change it to <eclipseHome>/workspace. You can check the "Don't ask me later" mark; it's really easy to change again later.

When Eclipse starts, go to Window->Preferences.. PHP->debug. The pane should contain a section for xdebug preferences at the bottom.

Step 11: Create a PHP Project

You're finally ready to debug a web-based PHP script. Without further ado, within Eclipse select File->New->Project.. Now PHP->PHP Project.

For 'Project Name', enter 'debugtest' and then select 'Finish'. You will see the project pop up in the PHP Navigator. Highlight the project. Select File->New->PHP File and name it phpinfo.php (ok I'm not feeling very original here).

In the editing pane, make sure the file contents are:

<?php phpinfo() ?>

Note: Newlines get ignored.

Save the file.

Navigate to http://localhost/debugtest/phpinfo.php in your browser. You should see the same info you saw before but now it is coming from your eclipse workspace.

Step 12: There ain't no more.
Now for one last, momentous step. You must now go into Eclipse and tell the xdebug plugin how to start a debug session so that you can catch a breakpoint in your new script. Select Run->Open debug dialog.. and double-click on 'PHP Web Page with Xdebug'.

NOTE: There must be menu items 'PHP Exe script with XDebug' and 'PHP Web Script with XDebug'. If these aren't there then something has gone wrong with the plugin installation.

Under Script and Server, browse to the file phpinfo.php in project debugtest.

Make sure the url field has http://localhost/debugtest/phpinfo.php. If it doesn't, uncheck the box and edit it manually. This is important because it is the site that Eclipse will go to when you start your debug session. I had to do this on my laptop just now when I tested it.

Select 'Apply' and 'Debug'.

You should have seen your phpinfo output come up in the internal Eclipse browser. If it came up in an external browser don't sweat it, because that will work to. With some playing around with the configuration you can get it the way you want.

Now select the tab for phpinfo.php and right-click on the vertical bar between your phpinfo.php line numbers and the edge of the edit pane and select 'Toggle Breakpoints'. You will see a blue circle appear, indicating that there is a debug breakpoint at that location.

Click on the down-arrow next to the bug in the top toolbar and select the debug test session that you just created.

You should now have caught your first breakpoint. If so, your install is complete and functional.


Please stay tuned... I hope to soon write the following articles:
  • Supercharging your Eclipse configuration with Subclipse and Quantum DB
  • How To Roll With Eclipse + Symfony

1 comment:

boyhowdy said...

Just an heads-up: with the current version of Eclipse PDT you no longer need to use the xdebug plugins from bugzilla. In fact, if you try to use them, you'll get an error when attempting to debug. You can use the standard Debug As > PHP Web Page now . See: http://www.64bitjungle.com/tech/debugging-php-applications-with-xdebug-and-eclipse-pdt/
for configuration details.

About Me

I currently work designing infrastructure for websites representing a large insurance firm. I webdev in my spare time. If you're into hockey, check out my hobby site: nhlhockeypool