Configuring Eclipse for Remote Debugging with Zend
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!]
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':
Basic installation is easy. Simply download the appropriate package, unzip the file, and place the eclipse folder somewhere convinient 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
Now load up eclipse.exe
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.
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. At last try even this was more complicated than should be possible. Officially you should be able to download it from http://www.zend.com/de/pdt, but you may find this doesn't work even after signing up for an account. So try this page instead http://downloads.zend.com/pdt/server-debugger/ and grab the tarball appropriate for your operating system, taking note to get the latest release.
- 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.
zend_extension_ts=/full/path/to/ZendDebugger.dll (on Linux or Mac it will be .so instead of .dll)
zend_debugger.allow_hosts=<ip address>
zend_debugger.expose_remotely=alwaysExample 1:
(Thanks to this site http://mprobst.de/SherlockWeb/?postid=2&replyto=3 for help with this) This is what he put.
; Zend Debugger madness
zend_extension=/usr/local/php/ZendDebugger.so
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always
zend_debugger.connector_port = 10013
; Zend Debugger madness endExample 2:
This is what I put:
; Zend Debugger
zend_extension_ts=ZendDebugger.dll
zend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always- Place dummy.php from the Debugger download into your document root of your localhost
- Restart Apache.
- If it worked, running phpinfo() again should now include some stuff about Zend Debugger
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. Bare 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 it to work with Drupal coding standards.
To help for absolute
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.inifor meIf 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/
Stopping at breakpoints outside of index.php?
Thanks for the tutorial - it helped keep the Eclipse/PDT struggle to mere hours rather than days. I'm still not satisfied that I have the debugger fully functional, however. I've got it to the point where it will stop at a breakpoint in index.php and from there I can step into, over and out of things to my heart's content. What I'd like it to do, however, is stop at breakpoints in other modules/include files. For example, I set a breakpoint on db_query in database.inc. I've tried getting it to stop there two different ways:
1. Set a breakpoint in index.php. When the debugger hits it, click resume.
2. Don't set a breakpoint in index.php - trust the debugger to stop on the dq_query breakpoint when it hits it.
Neither of these techniques works - the debugger never stops at the breakpoint in db_query.
Any ideas or suggestions of other things to try? I've tried similar tests with third-party modules and got the same results.
You have to set the Drupal Coding Standards
noah10, did you follow the step to configure eclipse for the coding standards from http://drupal.org/node/75242 ?
The settings you need are listed under "For PHPEclipse - PHP editing" so maybe you didn't run them.
Make sure you've done the following in eclipse:
Make the following changes under Window -> Preferences
1. Expand the left-hand menu to General -> Content Types
Under "Content types" on the right, click Text -> PHP Source File
Add the *.engine, *.theme, *.install, *.inc, and *.module file types
2. On the left again, find PHP -> Formatter
Choose "Indent using Spaces"
and use the little scroller up arrow to get the Indentation Size value to 2.
Press Apply.
With that in place I was able to set breakpoints in any of the proper file types.
Note that it didn't work until I exited eclipse and restarted it... so make sure you do that.
Thanks, but that wasn't it
I had already set up the file types, but not the indenting. I set that up and restarted Eclipse, but it didn't help. Just to clarify, I can set breakpoints in any file, it's just that the debugger doesn't stop at them. I've put them into variable_get and db_query, two functions which must be called dozens of times per page, and as far as the debugger is concerned it's like the code is never being called.
hmm!
Hmm! I had it run without stopping once while stumbling around, I had tried to debug a .module file directly and the site just ran without debugging in the browser window. It never switched over to the PHP Debug perspective.
Did you try fiddling around with the settings in Debug->Debug Dialog... ? There is some stuff under Advanced that might help, you can tell it to debug all pages, just the first page, or a specific page and continue from there. But it works for me with it set on "just debug first page". Kind of weird. And the site doesn't show at all until the debugger gets going... which usually takes a while. One thing that did happen a few times is I caught it busily compiling all my PHP files locally. I kept stopping this with the stop buttons (under the Progress tab) but maybe it compiled the files I was debugging and that's why they worked? That is something else to try, set it to Debug All files, hit Debug and it should madly start compiling (you'll see it doing this in the Progress tab). Then go for lunch and hope it works the next time you try!
I only got it to run by trial and error, I have to right click index.php, choosing Run as PHP Web Page, and index.php has no breakpoints in it. What happens is it loads the debugging perspective automatically and stops on the first line of index.php. I hit the Play button to make it run and then it hits my og2list breakpoint (as shown in http://postcarbon.org/files/ZendDebugger.png). Are you seeing it switch into that PHP Debug perspective that looks like that? Or is it still in the regular PHP perspective?
And are you using a local or remote server?
I'm going to try setting it up on my workstation at the office next, if I figure out any new steps i"ll reply but nothing off the top of my head other than those things, and you probably already tried them all. Good luck, you will need it!
My debugging PEBKAC error
I finally got the whole debugging stack set up and configured as directed in this thread and other, similar ones online, and spent about 1/2 an hour wondering why my breakpoints weren't working.
It was because I kept clicking the 'Run' button, not the 'Debug' button.
some extra steps - Remote Drupal Debugging with Zend Debugger
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_debugger-5.2.6.v20070507-all-in-one-linux-gtk.tar.gz. 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
Thanks for all the details - got it working!
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:
(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.)
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.
I've got couple of issues:
I've got couple of issues:
* Breakpoints do not work. When I set a breakpoint (even in the node.module or any other cron.php script) and hit the Debug button, Eclipse opens a browser window and display the same page as if I hit the Run button. The debugger is not started, execution is not suspended at the breakpoint. The only way to make it work, is to check the "Break at first line" option in the Debug options. If I do so, I can step through the script. However, Breakpoints are still disregarded.
* If i have checked the "Break at first line" in the debug dialog and start to debug with breakpoint set in node.module ... the browser opens and the debugger gets suspended at line 11 (ie., the first line after the comments) in the index.php and then when i keep stepping over till it ends with session.close and the session terminates and browser shows up the drupal homepage. Well it totally neglected the breakpoint set in node.module. When i refresh the browser the debugger starts off again but this time pressing step into/ step over basically hops over every function acting wierdly.
Port Numbers
I have recently tried Zend Studios for Eclipsed and found your post very very informative! Thank you for taking the time to post in great detail.
One small addendum is that the Zend port number seems to have been changed (or at least it did for me) to 10137. Either way, when you actually kick off the debugging session, you can find the debug port from the string which is passed to your server. I got this to show up by mousing-over the status bar at the bottom of my eclipse window while it was debugging. Look for 'debug_port=xxxx', and note that unlike http parameters, the key=value pairs are separated by '%'.
Important note!
This page recommends using the Zend all-in-one package which turned out to be a costly (in terms of man-hours) mistake for me. Do not download the Zend version, instead you should get the latest stable build from http://www.eclipse.org/pdt/
More details are here http://drupal.org/node/75242#comment-265395
I, and apparently many/most/all
...other people cannot fully get pdt with the zend debugger to work correctly on an intel mac. This has been the case for a very long time, and is still true today. The problem is that the debugger will not stop on any manually selected breakpoints. Now if only I could have the last 36 hours of my life back.
Small catch when trying this on Ubuntu.
Ubuntu places the sites folder under /etc/drupal/5.1/sites and then symlinks it under the drupal installation folder (when you use apt to install drupal that is). This means that if you then proceed to follow the "Creating modules" tutorial chances are good that your module code will actually end up under /etc/drupal/5.1/sites. And then your breakpoints wont work. No sir they sure wont. Just remove the symlink, copy the /etc/drupal/5.1/sites folder to your /usr/share/drupal-5.1/ folder and try again. Now Bob should be your uncle.
Don't ask me why.
Some for Windows
Hi. Read post and comments threat, but still have problems. Nothing worked.
I use latest version from zend.com "Download the all in one package":
http://downloads.zend.com/pdt/all-in-one/pdt-1.0.2.S20071213-M1_debugger...
I have read PDT Wiki... Here's result for Windows. But it tested only on small scripts:(
Windows (WAMP) user have to:
1. Use quotes in path to ZendDebugger.dll
2. Use zend_extension_ts NOT zend_extension
[Zend]; Full path to expansion with quotes
zend_extension_ts = "D:\path\to\eclipse\plugins\org.zend....\php5\ZendDebugger.dll"
; Comma separated addresses
; You can use masks * / 32
zend_debugger.allow_hosts = 192.168.0 .* 127.0.0.1
; The default is "always", but we will do some like that:
zend_debugger.expose_remotely = allowed_hosts
Works ^_^
absoulte path for dll
I've been trying for hours to get the debugger worked on server side. The main problem was I didn't put absolute path to the dll file, after changing it works. And, this is for Windows.
Zend Firefox Extension
If you've tried the eclipse-based Zend Neon IDE (I've tried beta) and want to go back to using plain Eclipse, don't forget to disable the FF extension it installs as it will break your Eclipse debugging with no apparent symptoms.
A report of a change, and a problem
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.
Thanks for the guides
Thanks for the guides above.
I've managed to RUN the Debugger.
Below are my configurations:
Windows XP SP2
pdt-all-in-one-S20080505_RC1-win32
Apache/2.2.8 (Win32) DAV/2 mod_ssl/2.2.8 OpenSSL/0.9.8g mod_autoindex_color PHP/5.2.5
Zend Debugger from http://downloads.zend.com/pdt/server-debugger/ZendDebugger-5.2.12-cygwin... (5_2_x_comp used)
php.ini
zend_extension_ts=D:\xampplite\php\ext\ZendDebugger.dllzend_debugger.allow_hosts=127.0.0.1
zend_debugger.expose_remotely=always
Question...
How to debug user input, forms, session based pages, etc. trough IDE UI ?
Zend Optimizer AND Debugger
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.