I’ve written about Eclipse and how useful it can be, with its extensible plugin-based system. It’s so useful that I use it everyday for almost any language – Java, PHP, JavaScript to name a few. It’s even great for things like CSS and XHTML.

PHP is currently my favourite “hobby” language and has been for some time. While I like PHP, one of the things that hasn’t been straightforward with it is setting up a proper debug session, where you can step through code. This contrasts heavily with a language like Java, which has always had strong developer tools. This has resulted in a mass of third-party tools aimed at facilitating PHP debugging. A while ago, a reader emailed me asking about this very topic, so I decided to put together how-to detailing my experience with the topic and how I went about learning it.

Xdebug for PHP and XAMPP

The debugger I’ll be using will be Xdebug. Because PHP provide no built-in debugging tools, there are many third-party options for debugging. (See the “Debugging Tools” section of this article for more) However, Xdebug seems to be one of the more popular ones, and Eclipse PDT already has support for it.

This guide also assumes use of XAMPP, the great all-in-one solution for quickly setting up a web development environment and to get your code running on the server. XAMPP is great for hitting the ground running, though you’ll probably not want to use it in a production environment – though you likely won’t be debugging there either. Nevertheless, the instructions provided here should work even if you’ve setup Apache and PHP separately on your own.

Getting started

The first thing you’ll want to do is head over the Xdebug page and download the appropriate Zend extension of Xdebug corresponding to the version of PHP you’re running. Save the file into your PHP extension path/folder. Now you’ll have to edit your php.ini file to begin using the plugin. The plugin basically exposes or provides an interface for the client debugger (running in Eclipse or your IDE) to attach to the server and debug/trace through the code that’s running on it. If you’re from the Java world, you’ll know this as “remote debugging”, which is provided by most J2EE application servers.

You’ll also want to have downloaded Eclipse PDT have that installed as your IDE, if you haven’t already done so. Zend Studio for Eclipse also works, since it’s based on Eclipse PDT, and offers quite a few more features, out of the box.

Setting up Xdebug

You should have already saved the Xdebug extension DLL file to your PHP extension folder. Record down the full path of it. Now, open up your php.ini file and go down to the [XDebug] section, or create it if it’s not there. Uncomment or add the following lines:

;; Only Zend OR (!) XDebug
zend_extension_ts="D:\XAMPP\php\ext\php_xdebug.dll"
xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler=dbgp

The zend_extension_ts should point to location of your Xdebug extension DLL that you downloaded earlier; modify as appropriate.

Then, you should disable the Xdebug entry in the list of dynamic extensions. This is confusing, but since we are already setting up Xdebug as a Zend extension, we don’t need another entry. Disable the Xdebug dynamic extension by ensuring the following line is commented out, like below:

;extension=php_xdebug.dll

There is one last very important step you need to do, particularly if you are running XAMPP. Current versions of Xdebug are incompatible with the Zend optimizer that is enabled by default in XAMPP, so you must disable that if you want Xdebug to work. If you don’t, you’ll notice that Apache will crash every time you try to load it with Xdebug enabled. To disable the Zend optimizer, find the [Zend] section in php.ini and comment out all of the entries under it, like so: (This is an example, there may be more to comment out)

[Zend]
;zend_extension_ts = "D:\XAMPP\php\zendOptimizer\lib\ZendExtensionManager.dll"
;zend_extension_manager.optimizer_ts = "D:\XAMPP\php\zendOptimizer\lib\Optimizer"
;zend_optimizer.enable_loader = 0
;zend_optimizer.optimization_level=15
;zend_optimizer.license_path =

You should be able to start Apache now without troubles.

Configuring Eclipse for PHP debugging

The next part will be configuring Eclipse as a debugging client. Since the code will be executing on the web server (Apache), you’ll need Eclipse to “hook in” using the Xdebug protocol. Thankfully, configuring Eclipse is fairly straightforward.

Open up Eclipse’s preferences and go to PHP -> Debug, and ensure that XDebug is selected as the PHP debugger. This sets the default for debugging sessions and lessens the configuration required for each debug session. You can also make sure that the default web server is localhost if that’s the case, which it’ll likely be for a lot of people doing development.

Note that if you are running Zend Studio, you’ll need to follow the steps in this article to enable Xdebug support. It seems that some versions of Zend Studio by default disabled support for the Xdebug plugin in lieu of their own Zend Debugger.

Now you can select a file from a project you’d like to debug. In my case, I’ve selected src/demo/index.php from my Challenge-Response PHP Login System project. Open the file, and then go to the Run Menu and select Debug Configurations… or Open Debug Dialog.

Double click the the “PHP Web Page” entry on the left side bar to create a new debug profile. Here, I’ve named it “CHAP-PHP”. You should see a dialog like the one above. Make sure the “Server Debugger” is again set to Xdebug and that the PHP Server is set to the localhost configuration you set up previously.

Then you have to select the file you want to debug. Click on “Browse”, and you’re confusingly taken to another view of your Eclipse projects; simply select the same file as before – you have to select a specific file, and not just a project or folder.

After that, you’ll need to adjust the URL mapping. You’ll probably need to uncheck “Auto Generate”, and then enter the URL that corresponds to the PHP file you’re debugging. Here, I’ve manually entered /projects/CHAP/trunk/src/demo/ as the URL fragment that triggers execution of the script.

If you want the debugger to stop right at the first line to allow you to immediately begin stepping through code, check “Break at First Line”. (It may be checked by default) Otherwise, uncheck it if you only want the debugger to stop at the breakpoints you’ve specified in Eclipse, which is the normal behaviour most developers will expect.

You should now be able to click “Debug”, and a debug session will launch, opening up the URL you’ve specified and allowing you to step through code. If you don’t like Eclipse using its own internal web browser (which appears just be a front for IE), you can configure which web browser you’d like it to launch URLs with by opening up Preferences and then going to General -> Web Browser and changing the setting to use an external web browser of your choice. Personally, Firefox is my preference.

Start your debugging engines!

You can now get acquainted with stepping through code, which in my opinion, is one of the best ways to learn! When you launch a debug session, Eclipse should prompt you to switch to a new “perspective”, which is just a different layout of Eclipse’s internal windows that many believe better suit debugging through code.

You’re provided with an informative view of the script your currently debugging, along with the highlighted line that execution has paused on. You can set debug breakpoints by double-clicking in the left margin of your source code view window; debug breakpoints show up as blue circles here. The buttons at the top (green “Play”, red “Stop” and others) provide control over execution of the code, allowing you to step through code line-by-line, step into functions/methods and return from them. I encourage you to experiment with all of the controls and get acquainted with the keyboard shortcuts.

Another panel also shows all the current variables available to the script as well as their values. This is useful since you now do not need to echo anything to output or change any of the code to see values.

When you’re done, you can just click the red “stop” button to disconnect from the server and end the debug session. If you’ve completely stepped through a script, you will not be automatically disconnected from the server. Instead, the debug client in PHP will patiently wait to debug the script again the next time it is executed. This is useful to know, since you can just go back to the URL in your web browser and reload the page to trigger the debug session to resume again.

Conclusion

I hope you found this useful, as when I was starting out trying to get a PHP debug session to work, it was somewhat frustrating. As always, I welcome your comments, suggestions and questions below via the comments form!

References

1. Why does xdebug crash apache on every XAMPP install I’ve tried?
2. Xdebug: Documentation
3. How to enable the Xdebug debugger in Zend Studio for Eclipse
4. Debugging PHP applications with Xdebug

* Sensationalist headline inspired by previous posts

Eclipse is my IDE of choice, as you’l probably have noticed from some of my previous articles. I had been wanting to write an article about why I use it (and why I switched to it), but kept putting it off. Recently, Matt Mullenweg wrote about his problems with Dreamweaver, and this perhaps prompted me to organize my notes on why I’ve chosen to use Eclipse. Don’t get me wrong – I’m not advocating that you immediately switch and throw out your current editing tool (the headline above, as noted, is purely for sensationalism) – but rather I’m just urging you to consider Eclipse for your next project.

Changing Gears

Like many, before switching to Eclipse I had been using a pure text editor, Ultraedit, for most of my web-development activities. Ultraedit seemed fine for most things, offering basic features like code highlight and autocompletion. However, it lacked a certain finesse when it came to dealing with larger projects. For example, if you’d defined a class, its members wouldn’t be available for autocompletion. Something else was needed. I finally decided to take the plunge, and switch over to Eclipse for all my development towards the end of the summer last year.

Some might wonder why I was even using a text-editor in the first place for development. For those coming from a traditional programming/development background, the idea of not using an IDE (Integrated Development Environment) is silly. This is because a lot of programming languages are compiled, and in this case, it just makes sense to use an IDE since it’s easier to write code, compile and debug using one tool instead of multiple ones.

However, for scripting languages, especially those meant to run on a web server, one can “get away” with not using an IDE quite easily. This is because the scripts are not run standalone but are almost always executed in the context of a web server; thus you’re usually editing code that you then run on a development web server, without the need for a special tool like a compiler. Additionally, it’s easy to view the output using any web browser. These reasons are what allowed me to persist in using a text-editor for so long.

No turning back

However, once I started using Eclipse, I was hooked. I downloaded Eclipse PDT (PHP Development Tools), which is basically a version of Eclipse bundled with the tools/plugins necessary for setting up a PHP development environment. Besides offering everything Ultraedit did, it also offered nice features like easy ‘Todo’ lists, (just type ‘todo’ anywhere in a comment and it’s automatically indexed by Eclipse into a list), code completion for built-in PHP functions and your own as well as a multitude of other advanced features that IDEs have. Oh, and it’s also FOSS. (Free and Open Source Software)

However, perhaps the best part about Eclipse is its robust and well-supported plugin system. This allows Eclipse to pretty much assume any feature that someone is willing to write a plugin for. This is what really sold me on Eclipse, because this almost makes its abilities endless. Some of the plugins I use are Subclipse for SVN integration, Mylyn for Trac integration and JSEclipse for JavaScript editing. This is part of the reason why Eclipse is the basis for many other IDEs out there.

Some other nice features are the ability to link the IDE in with the Zend Debugger, thus allowing for proper debugging sessions with PHP.

Spoiled

However, I’ve been pampered somewhat and have found a few things to complain about, at least when it comes to Eclipse PDT. I use Eclipse JDT (Java) a work and its advanced refactoring abilities are a feature I find myself wanting in the PDT version. Have you ever found yourself wanting to rename a variable to something more descriptive but putting it off because you’re afraid you’ll mess something up by forgetting to change the name somewhere?

With some IDEs, you’re left having to just do a search-and-replace in order to accomplish what should be a trivial name refactor. Even if your editor supports regex searches, things can still be tricky – what if you’ve used the same name, but in a different context, and thus shouldn’t change the variable there? The point is, the process still has to be human-supervised and is tedious. With Eclipse JDT’s advanced refactoring, you can rename the variable once – and the IDE is smart enough to know where else to change it to keep the code consistent – very neat, and I was amazed when I first used it. Other refactoring abilities include extracting methods out of blocks of code in order to clean up lengthy methods. All of this makes your life 10 times easier and allows you focus on real programming rather than annoying tasks.

However, Eclipse PDT doesn’t support this for PHP code, yet. I hear that it may be supported in a later release, so I have my fingers crossed. Perhaps accomplishing these refactoring tasks is easier in Java because of its compiled nature or because the JDT project has received more attention. It’s definitely possible in PHP, as some IDEs, such as the Zend Studio (which is based on Eclipse) support this ability. Zend Studio, however, is a commercial solution and I haven’t tried it out yet.

Nothing’s perfect

Eclipse does have its downsides as compared to a traditional text editor. First of all, it’s a memory hog – though most IDEs are. I have regularly seen Eclipse eat up 300-400 MB of RAM if I’ve been using it for a long time. However, it should be noted that I have not had it crash once, so it’s been rock-solid as far as stability goes. Nonetheless, I recommend you to have at least 2 GB of memory if you really want to use it properly, since you’re likely to have other programs open. This is especially important if you’re running Windows Vista. RAM is quiet cheap nowadays, and you can easily pick up 2 GB for $50 or less and upgrading is a painless process, so there’s no reason not to.

Finishing up

Eclipse has changed my life. Okay, so perhaps I’m exaggerating a bit. But, I can say that development, at least for me, would be much harder without Eclipse. If you’re still using a text editor for development, I urge you to give Eclipse a try – just for 30 days, and see how you like it. I don’t guarantee results as good as mine, but you may be pleasantly surprised.

I won’t go into too much detail about the features since I wanted to talk about integrating the Eclipse plugin Mylyn with a Trac setup on Assembla. There can be some issues getting things to work so I’ve outlined what I did to get everything running nicely.

Background: Mylyn

Mylyn is an excellent task-management plugin for the ultimate IDE, Eclipse. I have been trying it out for a variety of things, since I was trying to find something better than just text files for managing various tasks lists. However, Mylyn does much more than just task management as it helps to streamline your work environment with “context”. I haven’t started using these advanced features though, but what really caught my eye was the integration Mylyn offers with various issue-tracking services such as Bugzilla and the aforementioned Trac. This is accomplished by various “connectors”, with each connector being specific to one of the issue-tracking systems.

The Problem: XML-RPC Integration

Integration of Mylyn with Trac allows you to view, create and edit tickets in a Trac repository from within Eclipse. To accomplish this, there are two levels of integration, the first being simple web-based access. This is the more primitive of the two and has been around for longer. Basically, items are still edited from a web browser; the only difference is the web browser is spawned within Eclipse. This isn’t really ideal and doesn’t offer a real integration.

The second uses an XML-RPC interface to send/receive data and thus offers proper integration with the Eclipse environment. However, when trying to connect to my Trac setup on Assembla with this choice, I ran into a lot of intermittent 404 (not found) errors. Basically, synchronization was very flaky and by no means usable.

The Fix

I did some searching and found this page on the Assembla site where other users had experienced the same problem. Scrolling through the comments brought me to this nice fellow’s explanation of the problem, where a screencast was provided showing how it had been fixed.

Basically, these are the steps I did to get Mylyn XML-RPC integration with Trac working.

1. Enable the XML-RPC plugin

   Go to your Trac site, then click on Admin. On the left sidebar go to General > Plugins. There should be a section called TracXMLRPC; click to expand it. You might as well enable RPC access for all of the options provided, though I’m not sure if this is necessary. Here’s a screenshot.

   

2. Enable XML-RPC permissions

   After that, you need to enable permissions for XML-RPC access. Go to General > Permissions on the sidebar. In the “Grant Permissions” area, add a permission for “XML_RPC” for “@editors“. Using “@managers” for the subject might also work/be needed if you’ve setup access for those users. This is the basically what it should be:

   

3. Ensure there is at least one ticket in the system

   For some reason, I had weird errors when trying to synchronize/connect to a Trac repository with no tickets. This was corroborated by the fellow who originally found the solution to this problem. It’s a minor issue though, just click “New Ticket” and create a placeholder.

4. Add Trac to Mylyn

   This step’s simply enough; though some suggestions recommended using http://<domain_name_to_assembla_trac>/<space_url_name>/login/xmlrpc as the URL, I simply used http://<domain_name_to_assembla_trac>/<space_url_name> and it worked fine. Remember to use XML-RPC as your access type or you won’t get proper integration.

   

After that, you should be able to properly connect to your Trac repository using the XML-RPC option of Mylyn. Then, you can finally enjoy proper Trac integration in Eclipse!