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


Comments

Making XDEBUG work with NetBeans on Windows — 13 Comments

  1. Michael. After attempting to get xdebug working using every step-by-step I could find, your post worked first time. Thank you for taking the time to document this.

  2. Thanks so much – I’ve nearly tried every possible variation in php.ini without success. And then I tried your suggestion: Perfect – it works!

  3. Hi Michael, I followed your instructions very carefully, but no positive result.
    The message “Waiting For Connection (netbeans-xdebug)” appears and no connection is made.
    Please advise.

  4. I did as explained above. While debugging the project,it’s directing me to “http://localhost/xxxx/?XDEBUG_SESSION_START=netbeans-xdebug” where i’m finding a page internal server error. Please help me solving it.

    • Hi Shiva, thank you for your question. I’ve had trouble with the XDEBUG_SESSION_START=netbeans-xdebug parameter too not always working. Without troubleshooting, I am not sure I can solve the problem for you. However, here is what I recommend.

      With NetBeans running:

      1) Make sure to set a breakpoint in your PHP file.
      2) Start the debugger in Netbeans.
      3) Reload your web page, but not with XDEBUG_SESSION_START=netbeans-xdebug appended to the URL. Nothing should show up in your browser.
      4) Switch back to Netbeans. If you have everything configured properly, the like with the breakpoint should be highlighted and the execution of the script paused.

      Hope this helps.

  5. I followed the instructions precisely and it does not work. Netbeans shows “Waiting For Connection (netbeans-xdebug)”. This tutorial seems to miss important steps.

    • Hi Eddcapone, what important steps do you think might be missing? If there are indeed missing steps, I would be happy to add them to the instructions.

  6. I’ve tried everything you recommended and everyone else’s recommendations on the internet.
    Still no success…

    In the following bullet point #6 you only mention this:

    Step 2- Configure NetBeans to work with XDEBUG

    5. Click File > Project Properties > Run Configuration > Advanced button.
    6. Select Do Not Open Web Browser and click OK twice.

    But on that page at the bottom there is the “Debugger Proxy” with a port address of 9001 which will not allow a change unless something is put into the empty box labeled “Host:”. I put 127.0.0.1 so that I could change the port to 9000. I am still having no luck getting this thing working. I am seriously considering changing to another IDE that doesn’t use xDebug. Any more thoughts?

    • Hi Gary,

      You are so close to getting it working. I see what you mean about not being able to change the port to 9000 unless you specify a host. It doesn’t even give you an error message. It just ignores the change. Is there a reason you don’t want to add a hostname? Is there a reason you need to change the port?

      As for alternatives to XDEBUG, there aren’t many. Even commercial IDE’s like phpStorm use XDEBUG. However, you might try Zend Debugger. Haven’t tried it myself but I hear that it works with Eclipse PDT and phpStorm. I’ve been using phpStorm lately and found it pretty easy to setup, even with XDEBUG. Haven’t tried Zend at all.

Leave a Reply to Elke Cancel reply

Your email address will not be published. Required fields are marked *