Skip to content Get in touch

Contact form

Developing with NetBeans (Part IV): Debugging PHP

NetBeans’s built-in debugger tool can be used for debugging Java, C/C++ and PHP applications. In this article I’ll focus on using the debugger tool for PHP which, although not as full-featured as its Java and C/C++ equivalent, is still very powerful.

About debugging and Xdebug

Xdebug is a PHP extension that provides debugging and profiling capabilities. As a PHP extension, it executes in the web server. NetBeans provides the support for communicating with xdebug and uses its debugging capabilities.

When debugging, Xdebug controls the execution of the PHP application and sends this control to NetBeans. So by using the UI provided by NetBeans, we’ll be able to:

  • Control the executing flow, so you order when you execute the next line or until it gets out of the current function.
  • Set breakpoints, so the execution will stop in the desired line(s).
  • Check variable values, including arrays and objects.
  • Execute expressions (even functions) so you can see the value they return.
  • Check the call stack, so you will know which function calls which function, and browse back to them.

By using this tool, there will not be any bug that would resist to be found. It’s extremely useful and easy to use.

How to configure

Xdebug is not hard to configure but it can be a bit challenging if it does not behave as it should. For configuring it, you should:

1.- Installation

Download and install Xdebug in your web server machine.

2.- Configure Xdebug

Add this section to your /etc/php.ini. Some Linux distributions could include a /etc/php.d/xdebug.ini which is the same but in different files:

xdebug.remote_enable = 1
xdebug.remote_port = 9000
xdebug.remote_host =
xdebug.remote_log = /tmp/xdebug.log

A few comments about that configuration:

  • remote_enable is for activating it, so it is mandatory.
  • remote_port and remote_host refers to the machine that is executing NetBeans. Typically this will be the same machine, localhost. However it can be any other machine on the internet. You could set the IP address there, but then you would have to configure the firewalls accordingly. This is why I recommend that, instead, you just set this values as localhost and then start an SSH tunnel between your machine and the web server, so the data sent by Xdebug to will be received by NetBeans by the tunnel.
  • remote_log is just optional, useful specially if you cannot connect to Xdebug.

3.- Configure NetBeans

On NetBeans, go to its Preferences, PHP tab and Debugging tab. There you can set the port where NetBeans will be listening. So this port will have to be the same as the xdebug.remote_port configured earlier.

These are the general settings. You can overwrite them for each one of your projects, so it’s a good idea also to review them. So click with the right button of your mouse over the project (in the Project window), select Properties and then select ‘Run Configuration’.

I usually select ‘Do not select Web Browser’ because I prefer to control which tabs are going to be debugged using a browser plugin.

4.- Configure your browser (OPTIONAL)

For indicating to Xdebug that we want to debug a selected tab, the browser must send the argument ‘XDEBUGSESSIONSTART=netbeans-xdebug’ in all requests. Since this can be annoying, or easy to forget, there are a few browser plugins available that will do the work for you:

  • For Firefox, I use The Easiest Xdebug
  • For Google Chrome, I use Xdebug helper
    Just install them, and do not forget to configure them for using NetBeans (among other IDE’s they support).

How to use the debugger tool

On NetBeans editor, select one of the files that belongs to the project you want to debug. Then, click on the ‘Debug Project’. At this point, NetBeans will act as a server awaiting for the connection from the browser. You will see a “Waiting for Connection” message at the bottom.

On the browser, make sure the Xdebug plugin is activated (clicking on it) or that the XDEBUGSESSIONSTART argument is correctly set in the URL. Then, make the request.

On NetBeans, check that “Waiting for Connection” message at the bottom is still there. If it is, NetBeans did not listen any data from Xdebug so, most likely, you will have a problem in your configuration. At this moment, checking the log you defined in xdebug.remote_log could be very useful.

If it is not, and instead the name of the registered connection is there (by default, netbeans-xdebug) and the bar is showing a ‘running’, then NetBeans successfully captured the Xdebug data and is able to start the debugging.

For example, open the index.php file and set a breakpoint by clicking in the left of the line where the counting numbers are. A red bar will appear over the line. That’s the breakpoint. Do this for the first line.

Then, start the debug session and send the request from the browsers. NetBeans will capture it and will show a green line instead of the red one. That means that the execution has been interrupted at that particular line.
Open the debugging windows (if they have not opened automatically when starting the debugging session) by going to Window, Debugging. The most useful are:

  • Variables: you can check the value of all variables in that scope until just before the execution of the stopped line.
  • Call Stack: You can check which function called the function or method you are currently in. By clicking on any of the antecesors, you can go to that function and check the value of the variables it had.
  • Watches: Create custom expressions and see which value they have at that moment.

The flow control has 6 options:

  • Stop: Stops the debugger session. No data will be sent back to browser.
  • Continue: Continue execution until next breakpoint, or until the end.
  • Step over: If the current debugging line is a function, do not get into it.
  • Step into: If the current debugging line is a function, get into it.
  • Step out: Jump out the current fuction so the execution will stop right next after the call to the current function.
  • Run to cursor: it’s a way of creating breakpoints that will be used only once.

Happy debugging!

More about this topic

Other thoughts

More thoughts