This guide shows, how to setup Netbeans (edition for PHP developers) and local PHP interpreter with Xdebug — a world famous on-line debugging tool for PHP.
Since I’m using XAMPP package as my server in development environment, you may find some references to it in this text. But most of it should be clearly readable to anyone using Netbeans and Xdebug.
Double or even tripple check, if you have correct Xdebug configuration (see below)! I was fighting with some stupid bug for nearly two days only to find out, that it was caused by incorrect configuration. During that time I’ve read more than a dozen guides and each time I run into “Configuration” section or “check your configuration” statement I was always automatically assuming: “yes, yes — it is correct“. As it turned out (after two days), I was wrong and configuration was not correct. Don’t repeat my mistakes and don’t waste your time so stupidly!
Also, keep in mind, that if you’re using Windows 7 or newer version and you’re running your webpage locally, you should definitely use
127.0.0.1 address everywhere, instead of
localhost. This will give you a much faster performance, speed and server response times. Follow to Stack Overflow, to this answer to find out a detailed explanation, why this is happening.
Which Xdebug for me?
First of all, get correct version of Xdebug for your PHP environment. As you go to Xdebug’s download page you will notice, that list of available editions is long enough to get a headache.
You must closely match version of Xdebug to:
- your PHP version (
- your system / platform version (either
- version of compiler used to compile your PHP version (not Xdebug itself), for example
- and finally, whether your PHP was compiled in thread-safe mode (
TS) or in non-thread-safe mode (Xdebug version without
And this can be a hard task.
To make it easy, Xdebug author has provided us with tailored Installation Instructions.
Installing Xdebug in your PHP is easier than most guides shows.
Locate and open
php.ini in your editor. Remember, that PHP is Linux/Unix software at first, only ported to Windows, so pay attention to use text editor that supports Linux line endings (
LF). Make sure, that you don’t write changed
php.ini with Windows line endings (
LF&CR). If you see everything in this file bloated in one line (for example after opening in Notepad), then this is clear evidence that you’re using wrong editor.
Locate extensions part of
php.ini and after last
extension= add a new line with
extension=xdebug.dll. Supply correct filename, you’ve copied to
Then hit Ctrl+F to locate
[Xdebug] group and do some Xdebug configuration changes there. List of options is quite long, some of them may already be selected other are commented-out (ignored). After robsnotebook.com, a fairly good, but bloaty and poorly written article I cite, that you should consider at least these settings:
zend_extension = C:xamppphpextxdebug.dll xdebug.remote_enable=true xdebug.remote_host=127.0.0.1 xdebug.remote_port=9000 xdebug.remote_handler=dbgp
Make sure, that
zend_extension points to correct location of your Xdebug DLL.
Consult above mentioned article for more details on each option, you enable here. I only wanted to have Xdebug working and to be honest I didn’t much care what am I setting here.
If you’re using Zend Optimizer, you have to disable it, by commenting out any
zend_optimizer settings in
php.ini. Consult above article for more details on this. I don’t have Zend and all, I don’t like it (too heavy) and I don’t care.
Restart Apache and carefully check, if there are any errors reported during startup. Either as message box or in Apache’s logs. Correct anything that looks wrong or suspicious.
Run any PHP script with
phpinfo() command to display environment information and use Ctrl+F to determine, if your installation of Xdebug is OK. If you find
xdebug group, followed by
xdebug support -- enabled information, then you’re fine. Congratulations!
Run Netbeans, if it is not running yet and open your project inside.
Tools > Options and go to
General > Web Browser to set your prefered web browser, that will be used in debug process. The best option seems to be selecting internal browser, to not get crazy of pressing Alt+Tab all the time to switch between browser and Netbeans. But see some side notes on this below.
Configure debugger in Netbeans, by opening
Tools > Options and going to
PHP > Debugging. You should leave most options in default states. The only thing you may consider is unchecking
Stop at First Line checkbox.
And… you’re done! :]
Note, that Netbeans powered by Xdebug can easily debug simple websites and pure-PHP applications as well as complex apps written basing on any framework.
Debugging with Xdebug and Netbeans
Set some breakpoints and click proper toolbar icon or hit Ctrl+F5 to start debugging your currently selected Netbeans PHP project.
Debugging of your project should start. And your webpage or application should be opened in external or internal browser, according to your selection in Netbeans configuration. If there are any problems at this stage, you can always click your project (in projects tree) with a right mouse, select
Properties from context menu and go to
Run Configuration section. Check, if everything is OK there, at first place.
When your application or webpage start in debug mode, Netbeans will switch to selected browser (either internal or external). If execution flow is halted by an error or breakpoint, you’ll be switched back to your code only in case of using internal browser. In you’re debugging in external one, you have to manually switch back to Netbeans.
Once your debug starts, you get access to all debug information, Xdebug can get out of your webpage or application and provide to Netbeans. You can see all variables available in current context. If debug stops on any of your breakpoints or run into an exception, you can see entire call stack of your current context.
After stopping on a breakpoint you have access to all standard execution flow control functions like Step Into (
F7), Step Over (
F8), running to cursor etc.
To end current debug session, press Shift+F5.
Some browser side-effects
For debugging process (as well as for simple running your project) you can use either internal (based on WebKit) or external browser. You set it in configuration, in
Tools > Options > General > Web Browser. There are some side-effects depending on what you actually choose.
When choosing external browser, you can test your application in any environment you would like. But you have to switch manually between Netbeans and that browser, each time something change in execution flow (an error, a breakpoint etc.) or each time, you want to check a variable, stack trace etc. You can also end up bloated with browser’s tabs (or even windows), because Netbeans opens up new one for each debug session initiated and second one with “DEBUG SESSION ENDED” message, once your done in current debugging session (this is most initiating).
I don’t know, why it (or Xdebug or browser itself) can’t take over existing tab, especially because it uses the same Xdebug token (
netbeans-xdebug) all the time. Opening new tabs or windows for each new debug session was understandable in Eclipse, because that IDE uses different token for each debug session. In Netbeans this has to be some bug, especially that when using internal browser, it can always work on one and only tab. As I said, I don’t know, why this is happening. But this is stupid, annoying and was key factor for me to choose internal browser instead.
If you do the same and choose internal browser, you have to suffer the fact, that altough it is based on a WebKit (not ugly, pesky, standard-less IE), but it still far from general browsers development stream. Which means, that your website or application will lack some newest solutions and in general may look a bit different than in external browser. I think, this is acceptable, as we’re using internal browser only to catch-up bugs and fix them. And once they’re fixed, we finally test application in external browser, so everything is fine at the end.
Using internal browser is also convenient, because Netbeans will automatically switch you to code tab, once it reaches a breakpoint or an error.
Netbeans opens up internal browser window (tab) automatically, after you press Ctrl+F5 to start the debug process, but it can’t close it after debug session ends. Probably another stupid bug in IDE. So, in current version (7.3) you always end with
_DEBUG SESSION ENDED_ message once you’re done with debugging and there is no auto-going back to code. But, in case of internal browser, it can be easily worked around. Simply learn yourself to press Shift+F5 (terminate debug session) followed immediately by Shift+W (close internal browser tab).
I must admit, that I was quite surprised on how good Netbeans and Xdebug works together in debug process of a PHP application. After all, PHP is a scripting language, where general application execution flow is request-reply based. But these two binded together lets you debug it nearly the same as you would debug any standard application. I.e. allowing to stop on breakpoints, giving you full flow control (including fabulous
Run to Cursor) and even working perfecly on complex, framework-based applications.
Xdebug is a famous debugging tool for PHP. Maybe even the most famous. The other one is ZendDebugger. I haven’t got chance to check it out, because Zend and Microsoft agreed some time ago that the only stable way of running PHP on Windows is NTS mode (non-thread safe mode). Zend followed that and since PHP 5.2 started to publish only NTS versions of ZendDebugger. Unfortunately my server package (XAMPP) was not invited into that Microsoft-Zend meeting, was not part of that agreement and does understand, that running PHP on Windows in thread safe mode is the same as in non-thread safe. And continues to publish PHP in TS mode only. In other words, I haven’t got chance to check out ZendDebugger, because it is not available for me. But since Xdebug does the job perfectly and since I don’t like Zend at all, I’m fine and happy with that.