I fought with Xdebug and NetBeans enough to necessitate a post about it, if only so I don’t forget.
Most Xdebug/NetBeans tutorial assume that you’re doing development on your local machine. That’s a fine setup, but not what I was needed for this project.
Server: A typical Linux server — Debian, Apache2 and PHP.
Client: Firefox on Windows, etc.
IDE: NetBeans 7.1.1
Other Tools: PuTTY
Setting Up Xdebug
Install xdebug with the command:
pecl install xdebug
The final lines of output should say something like:
Build process completed successfully Installing '/usr/lib/php5/20090626/xdebug.so' install ok: channel://pecl.php.net/xdebug-2.2.
Take note of the install path, /usr/lib/php5/20090626/xdebug.so, in this case. Now add the following to your PHP configuration. I created a new .ini file at
Its contents should be as follows (change the zend_extension to match the install path found above):
[xdebug] zend_extension = "/usr/lib/php5/20090626/xdebug.so" xdebug.remote_enable = on ; Most users won't want autostart. More on this later. ; xdebug.remote_autostart = on xdebug.remote_autostart = off xdebug.remote_handler = dbgp xdebug.remote_port = 9000 xdebug.remote_server = localhost xdebug.remote_mode = req ; Most users won't want a hard coded idekey. More on this later. ; xdebug.idekey = netbeans-xdebug output_buffering = off xdebug.remote_log = "/var/log/xdebug.log"
Restart Apache to complete the installation.
xdebug.remote_server = localhost. Localhost? Wait a second, I thought this was for working with a remote server? Yes, but xdebug needs to be able to connect to your computer. The easy option is to have xdebug connect to the server’s localhost, then use PuTTY to create an SSH tunnel so that NetBeans can listen on your computer’s localhost.
The harder option is to configure your home or office router to forward port 9000 to you, be sure to never change your IP address, and open port 9000 on your Windows firewall. You could use xdebug.remote_connect_back so that xdebug would connect to whichever IP made the web request, but then someone who isn’t you could access your code.
In my opinion, the SSH tunneling is the cleanest option. You can use it anywhere that you have SSH access, xdebug access is restricted to those who have SSH access and you don’t have to worry about your IP address changing.
Creating an SSH Tunnel for Xdebug
Using PuTTY.exe create and save a new SSH session which connects to your server. In this saved session configure a tunnel. Set the source port to 9000, the destination to localhost:9000, and choose the Remove and Auto radio buttons. Click the Add button to add that port forwarding configuration, then save that session to use every time you want to use xdebug.
Go ahead and connect to that saved PuTTY session now. Once you’re connected to your server you should be able to run netstat to verify that it’s working correctly. It should show something like this:
netstat -a -n | grep 9000 tcp 0 0 127.0.0.1:9000 0.0.0.0:* LISTEN tcp6 0 0 ::1:9000 :::* LISTEN
Setting up NetBeans
Set up your NetBeans project like you usually would. Verify that the PHP Debugging Settings (In the Tools->Options menu) are set to debugger port 9000, and the Session ID of netbeans-xdebug. I had problems with the Watches and Balloon Evaluation options. YMMV.
In your project properties (Right click your project, click Properties) edit the Run Configuration’s Advanced properties. Select “Do Not Open Web Browser”.
A Note on Path Mappings
Based on the tutorials I read, most users don’t seem to need Path Mappings. NetBeans seems to figure out the path based on the upload directory, the URL and the Web Root settings. That didn’t work for me. I needed Path Mapping because I had a symlink on the server.
PHP (and so Xdebug) dereferences symlinks and NetBeans needs the mapping between the dereferenced path on the server and the local sources directory.
This is a known issue, but not very well known. Symptoms that you need to use mapping include NetBeans not breaking in symlinked files, NetBeans not opening the file or not opening the correct file when Xdebug connection is made. Or it may work only if you use “Debug File” instead of “Debug Project”.
Debugging With Xdebug and NetBeans
Here’s where you have some options. The manual way to active Xdebug is to append XDEBUG_SESSION_START=netbeans-xdebug to your query string when you request a page in the browser. With the current setup, this should work. Go ahead and test it.
Choose Debug -> Debug Project from the NetBeans menu. Then, in your browser, go to http://example.com/path/to/page.php??XDEBUG_SESSION_START=netbeans-xdebug (replacing the URL with your own, of course).
If that doesn’t work then something isn’t set up correctly. It might be NetBeans, it might be Xdebug, it might be the SSH tunnel. Figure it out, get it fixed, then keep reading (you can leave comments here, and I’ll help as I can. Google is pretty helpful too).
If that does work, then GREAT!
Now you have some options.
Always Auto-start Xdebug
If you are testing embedded webkit, or from mobile devices, or something else that’s not a normal browser, then appending XDEBUG_SESSION_START is going to be difficult. This is where I send you back to your xdebug.ini file to change some settings. If you need to debug requests from these sorts of devices, then you’re going to want to edit xdebug.ini and set:
xdebug.remote_autostart = on xdebug.idekey = netbeans-xdebug
This will cause Xdebug to attempt to connect on port 9000 on every request. The idekey setting is so that NetBeans will know that the connection is for it.
Other PHP Debugging Tools
If you are looking for good PHP debugging tools, you may also want to try out KCacheGrind which will profile your code giving you an idea what’s taking up time and memory. HipHop-PHP, a tool from Facebook of all places, compiles PHP into C++. In the process it spits out all sorts of helpful errors and notices that will help you find errors in your code.
That concludes one more NetBeans Xdebug tutorial that will hopefully get you that much closer to doing some serious PHP debugging. Happy coding!