Making XDEBUG work with NetBeans on Windows

After spending way more time that I should like to admit trying to get XDEBUG to work with Notepad++ using the DBGp plugin in anything but the simplest of projects, I decided to look for an alternative.

I compared features of 9 different IDE's for PHP development and reading tons of reviews. There are many great IDE's out there and everyone will have their favourite. My short list ended up including:

• Eclipse (PDT) 3.5 -- Didn't bother trying it. While I'm sure it's a fine product, the website is ancient and not user friendly. Way too much work to try and find information. I'm not sure if it is even being developed anymore. PDT isn't even listed in their main list of downloads. Although I didn't try Eclipse (PDT), I did try Aptana which is built on Eclipse but I don't want to have to struggle to figure out the user interface… I want to code!
• NetBeans 8 -- Way better user interface than Eclipse in my opinion. It did take me a little to figure out the XDEBUG integration but I got it to work exactly as I expected. My problem was part technology and part learning what I wanted to do in NetBeans which was to initiate the debugging session from within my web browser without having to modify the URL.

Although both of these are free, I would not have minded paying for an IDE for PHP development since I do a fair amount of this for a living. Some of the try before you buy contenders included PhpStorm 7.13 and PHPDesigner 8.1.2.

They all have similar sets of features. PHPDesigner is even a native Windows app which is why I might still consider it.

I decided to give NetBeans a try. There are tons of stories on the Net from developers switching from Eclipse to NetBeans but very few going in the other direction. It includes almost all of the features I regularly use and plugins to fill in the gap. What was it missing? Like many of the cross-platform IDE's, it's a Java application which means it is slower than it could be on Windows. I also wish it had Timed Backups feature like in Notepad++.

Assuming you've downloaded and installed NetBeans, here's how to get it to work with XDEBUG:

Step 1 -- Configure PHP to work with XDEBUG

Modify your php.ini file. Start by commenting out anything that refers to ZEND… by adding a semi-colon in front (to the left) of the line. Zend is not compatible with XDEBUG.

Next comment out everything under the [xdebug] section. Then add the following, making sure to modify the lines that refer to your XAMPP path (doesn't work with the Lite version).

zend_extension = "c:/xampp/php/ext/php_xdebug.dll"
xdebug.idekey = netbeans-xdebug
xdebug.profiler_append = 0
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 0
xdebug.profiler_output_dir = "c:/xampp/tmp/xdebug"
xdebug.profiler_output_name = "cachegrind.out.%t-%s"
xdebug.remote_enable = 1
xdebug.remote_autostart = 0
xdebug.remote_connect_back = 0
xdebug.remote_host = "127.0.0.1"
xdebug.remote_port = 9000
xdebug.remote_handler = "dbgp"
xdebug.remote_mode = req
xdebug.remote_log = "c:/xampp/tmp/xdebug/xdebug_remot.log"
xdebug.show_local_vars = 9
xdebug.trace_output_dir = "c:/xampp/tmp"

For 64-bit WAMP, the lines would be:

zend_extension = "c:/wamp/bin/php/php5.5.12/zend_ext/php_xdebug-2.2.5-5.5-vc11-x86_64.dll"
xdebug.idekey = netbeans-xdebug
xdebug.profiler_append = 0
xdebug.profiler_enable = 0
xdebug.profiler_enable_trigger = 0
xdebug.profiler_output_dir = "c:/wamp/tmp/xdebug"
xdebug.profiler_output_name = "cachegrind.out.%t-%s"
xdebug.remote_enable = 1
xdebug.remote_autostart = 0
xdebug.remote_connect_back = 0
xdebug.remote_host = "127.0.0.1"
xdebug.remote_port = 9000
xdebug.remote_handler = "dbgp"
xdebug.remote_mode = req
xdebug.remote_log = "c:/wamp/tmp/xdebug/xdebug_remot.log"
xdebug.show_local_vars = 9
xdebug.trace_output_dir = "c:/wamp/tmp"

As you can see, the actual filename and location for the php_xdebug.dll file may vary. Check the ext or zend_ext folder to get the correct name for your version of AMP. If your version of AMP did not come with XDEBUG, Follow the instructions found on the XDEBUG Installation Wizard page.

Save your changes and restart Apache.

Step 2- Configure NetBeans to work with XDEBUG

The following instructions are for NetBeans 8 but it should be fairly similar with other versions:

1. Open your project in NetBeans. If you don't have one yet, create one.
2. Click Tools > Options > PHP.
3. Click the Debugging tab and make sure that:
   • Debugger port: 9000.
   • Session ID: netbeans-xdebug
   • Maximum Data Length: 2048
   • None of the checkboxes are checked.
4. Click OK.
5. Click File > Project Properties > Run Configuration > Advanced button.
6. Select Do Not Open Web Browser and click OK twice.

Important: You will need to repeat these last two steps anytime you create a new project.

You may need to close and restart NetBeans for the changes to take effect as I discovered that they don't always take effect right away when you save.

That's it. It should now be configured and ready to use. Next we will XDEBUG enable your web browser.

Importing Existing Source Code into NetBeans

Creating a new NetBeans project from an existing source code folder/files is easy. The following instructions describe how to create a new NetBeans project using existing source code and without storing NetBeans' own project files in your original source code directory tree. Looks like a lot of steps but it only takes about a minute to complete.

• Click File > New Project.
• For the Category, select the PHP.
• For the Projects, select PHP Application with Existing Sources.
• Click Next.
• Specify the path to the Source Folder. This is where you source code currently exists.
• Specify a project name. This can be anything as long as it is different from other existing NetBeans projects you might have.
• Specify the version of PHP you will be using. If you aren't sure, type the following at a Command prompt or verify your log files: php --version . If PHP isn't in your path, you may need to change to the directory where the PHP.exe application is located.
• The default UTF-8 should be correct for most situations.
• To prevent NetBeans from storing it's files in your source code directory, check the "Put NetBeans metadata into a separate directory" box and specify the folder where these files should be stored.
• Click Next.
• For Run As:, select Local Web Site (running on local web server) if it is not already selected.
• Project URL should be the path to the localhost that corresponds to source directory specified above. It typically looks like http://localhost/ and may include a folder name if your local website is not in the root of the server.
• For PHP, the default index file is typically called index.php unless you've changed it.
• DO NOT check the "Copy files from Source Folder to another location" checkbox if you want to work on your files where they currently reside.
• Click Finish.

NetBeans will then create the project and open the default file.

Enabling XDEBUG in Web Browsers

Chrome

There are two really useful plugins for Chrome that you should install:

XDEBUG Helper -- This will enable you to turn XDEBUG on and off from your web browser without having to modify the URL. This is essential when debugging a POST type form submission where you can't just enter a URL.

XDEBUG Output Toggler -- This extension allows you to toggle the visibility of the extremely useful stack trace messages for your PHP.

Firefox

There are also two really useful plugins for Firefox that you should install (to be tested):

easyXdebug or The easiest Xdebug -- This will enable you to turn XDEBUG on and off from your web browser without having to modify the URL. This is essential when debugging a POST type form submission where you can't just enter a URL. I don't recommend installing both of these add-ons as they might conflict with each other since they do the same function.

XDEBUG Error Togger -- This is the same as XDEBUG Output Togger for Chrome. It allows you to toggle the visibility of the extremely useful stack trace messages for your PHP.

Internet Explorer

Unfortunately I don't know of any integration tools that work with IE. If you know if any, leave a comment below. You'll always be able to debug by appending ?XDEBUG_SESSION_START=netbeans-xdebug to the URL

Using XDEBUG in NetBeans

1. Open your project.
2. Debugging a Project: Right-click on the project you want to debug. Then click on Debug to start the debugger. There is a Debug Project icon at the top of the editor that you could use however it will not work for debugging a specific file.
   Debugging a specific file in a project or standalone file: Right-click on the file either in the navigation pane or even in the source code itself and then click Debug. If the file is already open, right click anywhere in the editor window and select Debug.
3. Set a breakpoint by clicking on the line number in the margin. Otherwise your code will be executed from start to end and nothing will happen in debugger.
4. Switch to your web browser and load the page you want to debug.
5. Click the add-on/plugin icon to enable Xdebug in your browser.
6. Reload the page you want to debug and switch back to NetBeans. You should now notice that the execution of the code has paused where you set the breakpoint above.
7. You can now use the debugging controls in the toolbar to step over, step into, step out, run to cursor, run, and stop debugging.

You may notice that your PHP code runs slower when debugging. This is perfectly normal and a good reason to have a fast computer. On the positive side, you'll really notice where the slower parts of your code are.

Troubleshooting

If you can't get it to work, check to make sure that your timezone is properly set in /xampp/php/php.ini. I'm not sure why but it made a difference for me. It will also make dates appear correctly on your website.

[Date]
; Defines the default timezone used by the date functions
; Find the value for your location by visiting http://php.net/date.timezone
date.timezone = America/Toronto