Eclipse is an open source IDE (Integrated Development Environment), that provides many tools for coding in one application... the most useful of which is probably PHP debugging. This section will provide instructions for installing and setting it up for use with Drupal.

Eclipse is a Java application so it can run on Linux, Mac and Windows, but comes with the price of a large memory footprint.

Hopefully this tutorial will help you setup smoothly. If not, stay with it. Getting debugging working is well worth the effort.

[Note: If any of this does not run smoothly for you, that's a perfect opportunity to help improve this page. Leave a comment or create an issue detailing the problem and how you solved it. You will be rewarded with a wave of karma!]

Screencast

Configuring the Eclipse IDE for Drupal Module Development and Debugging

Prerequisites

Debugging is probably the most useful feature of an IDE, so this tutorial will assume you want to set that up. To do so you will need to set up a local test server first. Without the local test server you will only be able to debug single file PHP scripts; for Drupal this is practically useless.

If you've not yet set up a test server you can find more information here. Go set it up and get it working with Drupal before you continue with this tutorial.

Installing Eclipse with Zend plugin

The Zend plugin will turn the generic Eclipse IDE into a PHP IDE. There are other options for plugins; Zend is just one of them.
In theory it should be possible to install Eclipse and then get the plugins working. In practice this may not run so smoothly! The easiest solution is to get the all in one package.

You can download the Zend bundle at the link below (it's about 100MB). It's called the 'All in one package':

http://www.zend.com/pdt

Basic installation is easy. Simply download the appropriate package, unzip the file, and place the eclipse folder somewhere convenient on your drive. You will have to create your own shortcuts, start-menu items etc., since there is no actual installer. The main program file is called eclipse.exe on Windows machines, and eclipse.app on Macintosh machines.

Now load up eclipse.exe or eclipse.app, whichever is appropriate for your platform.

If you are installing a Windows x64 version then you may run into run-time problems related to insufficient memory and/or insufficient stack size. To correct for this edit the eclipse.ini file and change the following entries:

  1. Increase XXMaxPermSize to at least 1024M
  2. Set Xms512m
  3. Set Xmx1024m

Run the eclipse program. if you encounter an error related to Java machine then you may be trying a 64-bit Eclipse version with a 32-bit Java version or the reverse. Make sure they are compatible. The easiest solution is to install an Eclipse version that matches your Java version.

Make sure everything is running by importing a simple PHP script and selecting run as script. If all is okay, we can move onto the next stage.

If you get an error that complains that it can't find the PHP executable then you need to define its path inside Eclipse as follows:

  1. Open Windows/Preferences
  2. Open PHP/PHP Executables
  3. Click 'Add' and add the path of where your PHP is. If you are using Zend this will be at c:/Zend/ZendServer/bin.

Debugging with the webserver

Now that you can run simple scripts, we can move onto setting up Eclipse for use with a webserver. Follow the steps below:

  • Step one involves downloading the server debugger from the Zend site, which requires registration and login. Go to http://www.zend.com/products/studio/downloads, register, and get the "Studio Web Debugger" for your platform and architecture. There are instructions there on how to install this as well, which should be the same as described here. (Note that the old location for this was http://downloads.zend.com/pdt/server-debugger/, which is still referred to on many places on the web. This old location has libraries only up through PHP 5.2, but if that's all you need, will work fine.)
  • Check which version of PHP you are running by executing the phpinfo() function.
  • Find the appropriate .so or .dll file and copy it to your PHP folder.
  • Open php.ini and add the following lines to the bottom of the file.

For Linux, assuming the library is in /usr/lib/php5 as it would most likely be on Debian/Ubuntu:

zend_extension=/usr/lib/php5/ZendDebugger.so
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always
zend_debugger.httpd_uid=-1

For Windows:

zend_extension_ts=/full/path/to/ZendDebugger.dll 
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always
zend_debugger.httpd_uid=-1

Make sure you search for any other instances of zend_extension or zend_extension_ts that are in you php.ini file and delete them/comment them out.

  • Restart Apache.
  • If it worked, running phpinfo() again should now include some stuff about Zend Debugger

Note: You may need to disable "eaccelerator" in your php.ini if it is defined there and it shows up in you phpinfo() listing to avoid debugging issues.

You can either add or set the following line if "eaccelerator" exists:

eaccelerator.enable="0"

or just simply comment out the "eaccelerator" lines using a semi-colon (;) in front of each statement.

;eaccelerator.enable="0"

Don't forget to review your phpinfo() to make sure eaccelerator is disabled.

Create a new project

The next stage is to create a project for your Drupal test site.

  • File -> New -> PHP Project
  • Type in a memorable project name
  • Uncheck 'Use default' under Project contents. This will stop Eclipse from from importing your files, allowing you to work with your project from different programs.
  • Browse for the location of your project
  • Click the 'Finished' button

You should now have an empty project. The next stage is to import your files:

  • Select the menu item File -> Import...
  • Select 'File System'
  • Click browse next to 'From directory' and search for the folder containing your Drupal project
  • Select the files you wish to import (probably all of them)
  • Click browse next to 'Into Folder' and select the project you just created
  • Click 'Finish'

You've now created a new project!

Run Debugger as Web Service

Once setup, each debug session is a one click operation. But first you need to run through the following steps.

  • In menu Run -> Debug... (The Debug window will pop up)
  • On the left-hand side of the window is a folding menu. Right click on 'PHP Web Page' and select New.
  • Change the name to something memorable. Bear in mind that you will be doing this for each individual site, so make sure the name relates to this specific site.
  • In the 'Server' section click the 'New' button. A window will pop up.
  • Give it a name such as your site name
  • Enter the URL that points to the document root of the server
  • Click OK
  • In the 'File/Project' section click the 'Browse' button.
  • Select the relevant project directory and click OK
  • In the 'URL' section, uncheck Auto Generate and type in the URL of your site (i.e. the same URL you would type into your web browser)
  • Click the 'Debug' button

If all is well you should now be dubugging your Drupal site! Of course you will need to add a breakpoint for it to work.

Setup for working with Drupal coding standards

Before you can happily work with a Drupal project you will need to configure Eclipse to work with Drupal coding standards.

Eclipse EGit plug-in

Details about setting up Eclipse for interacting with git

Comments

dman’s picture

To help for absolute beginners, the appropriate 'php folder' to place the ZendDebugger.so file is listed ino your phpinfo as 'extension_dir'
For me it was /usr/lib/php5/20051025 - the exact name may be different for your platform.

Your correct 'Configuration File' will also be listed there. Take care as there are sometimes a few different php.ini files on your system, but only one gets used. /etc/php5/apache2/php.ini for me

If you are not developing/serving on the same machine, your IP will have to be the client IP.
I use zend_debugger.allow_hosts=192.160.0.* to mean any machine on my LAN.
If you are trying to do this on a remote server, things will be trickier as you neet network port frowarding, as well as a high level of control of the remote host anyway, so best not to do this. Debugging is best done locally anyway.

-- I ran into many problems due to my existing Eclipse install, My existing PHP projects (not created 'new'), and my preference for the phpEclipse IDE rather than the bare-bones Zend one.
I'll see what my problems are...

.dan.
How to troubleshoot Drupal | http://www.coders.co.nz/

icesurfer’s picture

phpinfo.php can be a big help to properly configuring you php installation for debugging

Run phpinfo.php for your host For Example
http://localhost/phpinfo.php

In the second block of data, search for the Thread Safety variable. If Thread Safety == enabled, get the debug file from the folder that does NOT contain 'nts' (not thread safe)

In the Configuration | PHP Core section check the properties for the variable extension_dir
THIS is where you should place the copy of the debug .dll file

To Verify that the debugger is working

The 3rd 'block' of data displayed and icon "Powered by Zend Engine 2" Within the text for that block you should see

This program makes use of the Zend Scripting Language Engine:
Zend Engine v2.2.0, Copyright (c) 1998-2010 Zend Technologies
    with Zend Debugger v5.2.15, Copyright (c) 1999-2008, by Zend Technologies

If you don't see 'debugger' in the powered by block, check your php.ini file and make certain that you have selected to correct .dll and placed it in the correct directory.

damien_vancouver’s picture

Well I finally got it all working and WOW!!! It was worth the 4 hours (2 hours fighting with the server, 2 hours with the client). There are a lot of extra steps I found along the way... but now it is working for me, debugging with breakpoints in og2list, on a firewalled remote server, from my firewalled local workstation. Way cool!!!

Anyway to help you find your problem I have bolded some keywords here... hope that helps!

Server Side - Zend Debugger:

First things first: Zend Debugger will NOT work if you have the hardened PHP patch (suhosin) installed. It is a binary PHP extension and the hardening patch breaks those. So if you do have it installed, time to recompile PHP without it (what I did).

For me, the 5_2_x Zend Debugger would not work (or make any error messages) with PHP 5.2.1. I had to compile 5.2.3, the latest, and it worked with that.

For the Zend Debugger php.ini settings, I followed the instructions at this PDT wiki:
http://www.thierryb.net/pdtwiki/index.php?title=Using_PDT_:_Installation...

Here is what I ended up with in my PHP.ini file. Note the [Zend] header. Also note that your absolute path to ZendDebugger.so will depend on where you put it, and the other two settings to change.

; Output buffering allows you to send header lines (including cookies) even
; after you send body content, at the price of slowing PHP's output layer a
; bit.  You can enable output buffering during runtime by calling the output
; buffering functions.  You can also enable output buffering for all files by
; setting this directive to On.  If you wish to limit the size of the buffer
; to a certain size - you can use a maximum number of bytes instead of 'On', as
; a value for this directive (e.g., output_buffering=4096).
; output_buffering = 4096  <em>(MAKE SURE OLD ONE IS COMMENTED OUT WITH A ; )</em>
; TURNED OFF to see output while debugging with Zend Debugger
output_buffering = 0


; Implicit flush tells PHP to tell the output layer to flush itself
; automatically after every output block.  This is equivalent to calling the
; PHP function flush() after each and every call to print() or echo() and each
; and every HTML block.  Turning this option on has serious performance
; implications and is generally recommended for debugging purposes only.
implicit_flush = On    

;;;;;;;;;;;;;;;;;;;
; Module Settings ;
;;;;;;;;;;;;;;;;;;;

[Zend]
zend_extension=/usr/local/lib/php/ZendDebugger.so
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always

If you are using Windows you should use zend_extension_ts= instead and point to the DLL with the correct path.
ALL of this is on that PDT wiki page linked above, so follow THOSE instructions carefully, not just my paraphrased summary!

Note that if there are problems loading Zend Debugger and it's not showing up in phpinfo(), you should check your apache server's error_log file!. It was in here that I found precious clues about the hardening patch being my problem! But when PHP 5.2.1 didn't work, there was no output here.

After all that my server side was working properly. phpinfo() had Zend Debugger stuff in it! If yours doesn't, check that error_log. If you can't find a clue there, double check everything from the beginning. Repeat until it works or you can't take it any more. and give up. (that is my winning strategy by the way)

Client Side - Eclipse remote debugging from behind a firewall:

The PDT download page has several differenet versions. It worked for me using 1.0 and the version with the longer filename, i.e. http://downloads.zend.com/pdt/all-in-one/1.0/pdt-1.0.0.S20070611-M1_debu.... You should download that one (with an S and the M1_debugger in the filename) for your operating system (windows, macosx, or linux). I have no clue what the different versions are, the first one I tried worked.

I was previously running Eclipse with PHPEclipse and SubClipse (SVN). When I booted the new eclipse it showed my old PHPEclipse projects. But these weren't available to browse to when setting up the debugging dialog!

You need to remove and recreate any old PHPEclipse projects! in your workspace. First right click and delete them in eclipse, choose not to delete the local files.
Then go into your eclipse workspace dir, move or delete them as you need to.
Then back into eclipse and either create a new project and import your files, or in my case I went into SVN Repository Exploring view and checked them out again using the new project wizard (then went on to make a PHP project). You'll notice the icon is different from the PHPEclipse PHP projects, and it makes hidden settings you need for the debugging to work.

Once you have a new PHP project made, you need to tunnel port 10000 from the remote server back to your server. If there is no outgoing firewall on the server and you are connected to the internet directly (ie. without a router or firewall between you) then it should just work (as long as you put your external internet IP into the zend_debugger.allow_hosts= setting in php.ini). My workstation is behind a firewall and this is a problem because the Eclipse client tries to send my 192.168.0.6 internal IP to the server. The server can't connect to 192.168.0.6, it's outside my firewall, and nothing happens when I try and hit the Debug button in Run->Debug Dialog.... If you try and do a debug session you will see a browser tab open in eclipse and it will fill in this huge long URL trying to start the debugger on the server. If you look in that URL you will notice a couple of things. One of them is that debug_host= will have a comma separated list of your machine's IP addresses. The commas show up as %2C because they are URL encoded. For example, my machine has 2 IP's, 127.0.0.1 (localhost) and 192.168.0.6. In my URL, it says &debug_host=192.168.0.6%2C127.0.0.1&...&debug_port=10000.

That means the server is going to try and connect to both addresses, 192.168.0.6 and 127.0.0.1, both on port 10000. In order for this to work through firewalls, you must open an SSH tunnel that maps the server's port 10000 to your port 10000, via the 127.0.0.1 localhost address.

Here is the closest thing I could find to officiali docs on doing this properly.
http://www.zend.com/support/knowledgebase.php?kbid=83&view_only=1
Note that the parts about setting the debug host IP won't work as it's not Zend Studio it's eclipse. You just have to deal with waiting in eclipse (see next section) - OR edit the URL it creates in the browser tab and chop out the other IP's except 127.0.0.1.

To tunnel the debugger through the firewalls in linux, you use ssh with the -R argument. it looks like this:

# ssh -R 10000:127.0.0.1:10000 www.yourserver.com

You log in as normal.

To tunnel the debugger through the firewalls in Windows, you can also use the free PuTTY program. See http://www.cs.uu.nl/technical/services/ssh/putty/puttyfw.html for some instructions and screenshots on forwarding. You need to set up a Tunnel with Source Port 10000 and Destination address 127.0.0.1:10000, and select Remote instead of Local. Remember to hit Save to update your profile with the new tunnel!

Now connect in either of these fashions, and just leave the ssh window open. It will also create a tunnel back to you via 127.0.0.1, port 10000.

And finally, how to actually start the debugger
So now you are all set. Go into your index.php file in your Drupal project, and double click index.php and then pick a line and right click -> Toggle Breakpoint to set the breakpoint (or double click to the left of the line number).

A little blue dot will appear, meaning the breakpoint is set. Now right click the file and choose Debug as PHP Web Page. If everything is in order your debugger will start up and be stopped at that breakpoint.

Note: that if your machine has many IP's it will take a while. 127.0.0.1 gets tried last and it takes some time for each other IP to be tried before the debugger starts.

When it does start, you'll know it because it will move into the PHP Debug perspective. There will be PHP code and watches and it should automatically stop on the first line of index.php (or at least this happens for me). Now you can use the regular Eclipse debugging buttons, like step into, step over etc. You can also set breakpoints on the fly and run to get to them. And of course there are watches available so you can see what values are.

What fun!

Note that though you started on index.php, you can set breakpoints anywhere and it should stop on them. I think this is because in Drupal everything is included from index.php. My Debug profile that it created for index is set to just debug the first page.

Anwyay, that is it, it works awesome for me! Good luck to you, if you find other things I've missed here and they work for you, please post them in a comment!

And in case you are sitting here, after hours of grief, tearing your hair out, wondering to yourself, "is this REALLY worth it??",
have a look at this screenshot of it all working... appreciate how much time it will save YOU!

http://postcarbon.org/files/ZendDebugger.png

noah10’s picture

Thanks for posting all of the steps you went through. I followed some of them (fortunately I didn't have to go through all of them) and now things are working properly. Here's what I did:

  • Upgraded to PHP 5.2.3
  • Installed the Zend debugger client for PDT
  • (According to http://www.thierryb.net/pdtwiki/index.php?title=Using_PDT_:_Installation... this shouldn't be necessary for local debugging; the PDT has a built-in debugging client that should work with the Zend debugger package extension for th server but I decided to try it anyway.)

  • Removed and re-created my PHP projects (multiple times)
  • Got Eclipse to compile my entire Drupal installation as part of its project by importing all the Drupal files into the project

My guess is that that last step was the one that did the trick. I created a test case and confirmed that the debugger won't stop at a breakpoint set in an include library, which is how I had previously been referencing the Drupal files. (My thinking was that I didn't want to edit any of the core stuff so it should really be treated as an include library, not as one of the main project files.) Thanks for all of the documentation - it was a big help to me and hopefully will be to others too.

Di.’s picture

Thanks for your very useful post! I got everything working, plus found a way to overcome this problem:

You just have to deal with waiting in eclipse (see next section) - OR edit the URL it creates in the browser tab and chop out the other IP's except 127.0.0.1. [...] Note: that if your machine has many IP's it will take a while. 127.0.0.1 gets tried last and it takes some time for each other IP to be tried before the debugger starts.

Here is how:

  1. Open the Eclipse Preferences dialog from the menu bar: Window --> Preferences
  2. Within the Preferences dialog, navigate to the Installed Debuggers page (by drilling down the options that appear on the left panel): PHP --> Debug --> Installed Debuggers
  3. Double click on the line that says Zend Debugger . This will open the Zend Debugger Settings dialog.
  4. Edit the Client Host/IP entry to remove all IPs except 127.0.0.1. Select "Ok" and close all the dialogs.

Hope this helps!

orthoducks’s picture

First: the naming of the files in the Zend debugger distribution for Windows (ZendDebugger-5.2.12-cygwin_nt-i386.zip) has changed. The thread-safe version of the DLL is in a directory named 5_2_x_comp; the non-thread-safe is in 5_2_x_nts_comp.

The distribution's readme file says that the non-thread-safe version "is used only with Zend Core 2.0," but I never found a clear statement of which PHP version(s) that corresponds to. In the end I guessed that PHP 5.2.5 corresponds to some later (thread-safe) version, and that appears to have been correct.

Second: the current version of Eclipse (in Windows) does not set up as described, and my best guess at what to do did not work. I have described this in a forum topic, Difficulty setting up a project for debugging in Eclipse IDE.

hobbes_VT’s picture

I used XAMPP (with php 5.2.5) to set up my local server and ran into the following issue:

If you have to run Zend Optimizer (e.g. because you use a php-script that was encoded with Zend) you will fail to start your apache server if you also try to install the Zend Debugger.
I got the following message after I enabled both Zend optimizer and Zend debugger - even in the right order:
PHP Fatal error: [Zend Optimizer] Zend Debugger must be loaded after Zend Optimizer in Unknown on line 0

You will have to use the Zend extension manager to install your debugger - and here is the tricky part - the extension manager only expects the root directory of the debug dlls and will pick it's own subdirectory by the version of php it finds:

Here are the modified php.ini settings that made it work:

[Zend]
zend_extension_ts = "C:\xampp\php\zendOptimizer\lib\ZendExtensionManager.dll"
zend_extension_manager.optimizer_ts = "C:\xampp\php\zendOptimizer\lib\Optimizer"
zend_optimizer.enable_loader = 0
zend_optimizer.optimization_level=15
;zend_optimizer.license_path =
; Local Variables:
; tab-width: 4
; End:

zend_extension_manager.debug_server_ts = "C:\xampp\php\ZendDebugger"
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always

NOTE: my ZendDebugger directory does not contain the dll - in my case I had to put it into a sub-directory called "php-5.2.x" - in my case this was not the default directory from the zip I downloaded from Zend. So be sure to check your error.log to see which directory your installer expects.

Anonymous’s picture

See more instructions on configuring Zend Optimizer and Debugger here:
http://blog.tigeryao.com/2008/how-to-allow-zend-optimizer-and-zend-debug...

macman’s picture

Hi. I must admit I am a bit out of my depth here but it seems to me that you need to use a 5.2.x version or earlier of php to support this configuration. It seems it is to do with zend not providing a thread safe debugger yet for 5.3.x.

Apologies if what I have written is inaccurate but I found that I spent a whole day bashing my head but going back to 5.2.8 got it working for me quickly.

Cheers
Chris

bolaowoade’s picture

For non - techies here is a good tutorial to install Eclipse PDT step by step:

http://www.tanguay.info/web/tutorial.php?idCode=phpDevelopmentQuick&sect...

mikeejt’s picture

Just an update, found through google is the new location of this tutorial:

http://www.tanguay.info/web2008/tutorial.php?idCode=phpDevelopmentQuick

ginc’s picture

here you can find a tutorial that explains clearly how to setup Eclipse PDT to debug MySQL. that's cool and useful to access the database within the IDE.

http://www.64bitjungle.com/tech/eclipse-pdt-and-mysql-sql-explorer-plugin/

good luck

Liberation’s picture

If you want to use PHPEclipse rather than PDT, see http://drupal.org/node/75242#comment-945405

Nick_vh’s picture

Recently I made a tutorial for this,

http://krimson.be/en/debugging-drupal-6-using-xdebug

Also suitable for x64 systems ;-)
Please write any additional comments on that post so I can apply them and make the world a little bit better!

light-blue’s picture

I struggled with this for days due to crappy or incomplete documentation. Here are my notes for a painless setup:

1. Don't use Import. If you do, you'll need to Export again where you're ready test your changes. That is cumbersome when working on files hosted elsewhere and when you don't need the complexity of CVS, SVN, GIT, etc.

2. Instead of Import / Export, install RSE into Eclipse (Zend Studio 6.x for Eclipse already contains it, just click File, New, Remote Folder). Google ' Eclipse RSE' for the install instructions. It's (usually) painless.

3. Link to the drupal folder (e.g. /var/www/drupal) by clicking File, New, Remote Folder (Zend Studio for Eclipse), or File, New, Folder, Advanced, Link to the Folder in the File System, Choose File System (select RSE), Browse, New (select something that makes sense). Use SSH if you have shell access. I have Samba setup, so I mapped a drive to it.

This setup allows you to change the files directly on the server once you hit the Save button, similar to Zend Studio 5.x.

NOTE: I run Samba on my LAMP server, so I selected 'Default' for 'Choose File System' in #2. That is VERY FAST and avoids certain SFTP (SSH) timeout issues I'm seen.

shunting’s picture

Unlike Zend, unfortunately. Could be me, could be OS X Server, but I never did manage to debug installing the Zend debugger.

This was the only issue I encountered and how I solved it:

Aptana didn't default my apache port: 80. As a result, the drupal home page would show up in the Aptana's preview as if the install was new ("Welcome to your new Drupal website!") and the login would fail.

However this can be changed (for build 1.5.0.025655):

1. Select the drupal project (I had previously given Aptana the path to my existing installation).

2. Go to Project -> Properties -> PHP Preview.

3. Check Override workspace settings.

4. Select the Use server radio button.

5. On the same line as the radio button, look for a downward-pointing triangle to the right of the name of server being used and click it; a dropdown appears.

6. Select "Add new server" from the dropdown, and then Choose Server type from the dialog that appears; I selected Apache.

7. An "Add Local Apache Server" dialog comes up. Enter a name, say "My Local Apache Server (port 80)," and then browse to and select the httpd executable, log files, and Document Root, and check the parameters for host (in my case, localhost), port (80!), start, restart and stop.

8. OK your way out of the dialogs, and your newly annointed "My Local Apache Server (port 80)" (if that was the name you entered) will now appear in the servers listed on the downward-pointing triangle's dropdown. Select it.

9. Decide whether or not to check the "Append project name" box name to the right of the downward-pointing triangle. Because I gave my project the same name as my drupal subdirectory under DocumentRoot, I checked that, and it worked.

9. OK out of the project properties.

10. A functioning drupal home page should now appear in the Aptana preview pages. (And if you logged in to the site directly in the browser, the Aptana preview will also have you logged in. And one of the nice things about Aptana is that you get previews of multiple browsers in the IDE.)

UPDATE How to get remote debugging going.

bonn’s picture

Hi,
I use Eclipse in Windows7, and my drupal is in my fedora web server.
How can I debug my drupal (remote) using my Eclipse in win7 ?

I already installed zendDebugger in fedora, then I configure server in my win7-eclipse, but not working..
any help?
thanks