Xdebug

From OpenComputing
Jump to: navigation, search

Contents

Setting up a debugging tool

Eclipse PDT plugin supports two debuggers: the Zend debugger and the XDebug debugger. Either one provides good debugging support.

A useful resource to learn about PHP debugging is Nathan Good's tutorial at http://www.ibm.com/developerworks/opensource/tutorials/os-php-eclipse-pdt-debug/. The tutorial was written a few years back in 2008 and refers to Eclipse Europa. However, the lessons apply very well to Helios or future Eclipse releases.

XDebug installation

To use XDebug as a debugger for Eclipse PDT, you need to download and install it by following instructions at XDebug extension for PHP]. Binaries for Windows (see Precompiled Windows Modules section) or source code for Linux and Mac OS are used to do the installation.

For Windows installation, follow the instructions at http://www.xdebug.org/find-binary.php. Those instructions state that you should paste the full php -i output into the scrolling text box form. In order to accomplish this, you need to be familiar with the PHP engine described on the PHP wiki, paying specific attention on how to use the php -i command. The pasted output of php -i is analyzed by the xdebug.org site after clicking the "Analyze my phpinfo() output" button. The purpose of this analysis is to check your system's OS, PHP, and Apache settings in order to recommend which Xdebug dll file should be downloaded, and as to the directory location the file should be moved. Important: Before continuing to the next step, make sure to add the correct zend_extension to the php.ini file. For more info on this last step, see PHP.ini Configuration

To test that the installation was successful

  • Run php -m at the command prompt. Make sure that the path to the php interpreter is listed in the PATH system variable.
  • The output of this command should display Xdebug module at the end of a long list:

C:\Documents and Settings\mcs>php -m
[PHP Modules]
bcmath
bz2
calendar
com_dotnet
Core
...
[Zend Modules]
Xdebug

XAMPP configuration for XDebug

  • Open php.ini in Notepad++
  • Locate the XDebug module (at approximately line 2140) and edit/uncomment the following directives:

xdebug.remote_enable=1
xdebug.remote_handler="dbgp"
xdebug.remote_host="localhost"
xdebug.remote_log="e:\xampp\tmp"
xdebug.remote_mode="req"
xdebug.remote_port=9000

    • The "localhost" is the host on which Eclipse PDT software runs, and to which PHP will try to connect when debugging is enabled.
  • Write a comment above each line of code you have changed. It helps with learning what you've done.
    • Use ; as the first character to designate the the line as comment
    • Enter your name and the date when you made the change
    • Follow up with a brief description of the action taken. For example

;
; Mihaela June 12, 2011: switched remote_enable from 0 to 1
;
xdebug.remote_enable = 1

  • Restart Apache web server application (use XAMPP control panel).

PDT configuration for XDebug

  • Go to Window->Preferences->PHP->Debug to see the PHP Debug configuration view.
  • In the PHP Debugger text field, select XDebug form the pull-down menu and click on the "Configure..." link.
    • Zend Debugger and XDebug are listed in the Installed Debuggers view. Select XDebug and click Configure.
      • Accept default settings for port (9000), max array depth (3), and max children (31), unless you have to change the port to another value (which is also used in the php.ini's Xdebug module).
      • For the Accept remote session(JIT) select any and click OK
Eclipse-xdebug-settings.png


    • Back in the Installed Debuggers view, click Apply.
  • Back in the PHP Debug view, the Server text field lists Default PHP Web Server. If not, click PHP Servers... and select the Default PHP Web Server.
  • For the PHP Executables text field, click PHP Executables... If no executable is listed, click Add... to add a PHP executable definition:
    • Enter PHP 5.3.5 for the Name text field. If the version of your PHP installation is different, it's wise to use the version of your installation.
    • Browse to the executable path and select the PHP interpreter from the php directory. If you have XAMPP installed on C:, then the path is probably c:\xampp\php\php.exe. IMPORTANT NOTE: I strongly recommend that you use the "Details" view in Windows Explorer and you always show the extension of the file. This way you'll know if the php file name corresponds to php.ini or php.exe.
    • PHP ini file text field is optional. However, you can browse to the php directory and select the php.ini file.
    • From the PHP debugger drop down list, select XDebug.
Eclipse-xdebug-config.png


  • PHP Executables view shows your newly added definition.
Eclipse-php-executables.png


  • If the PHP Executable text field (in the PHP->Debug view from the Preferences view) shows None Defined, click again on the "PHP Executables..." link and select the definition you just added.
  • The configuration settings shows:
Eclipse-php-debug.png


XDebug Install and configuration for Macs

If you are running Mac OS X and have XAMPP installed on your computer, then XDebug has already been installed on your computer and all you need to do to get Apache to use it is to enter:

  • [xdebug]
  • xdebug.default_enable=1
  • xdebug.remote_enable=1
  • xdebug.remote_handler=dbgp
  • xdebug.remote_host=localhost
  • xdebug.remote_port=9000
  • xdebug.remote_autostart=1zend_extension="/Applications/XAMPP/xamppfiles/lib/php/php-5.3.1/extensions/no-debug-non-zts-20090626/xdebug.so"

into your php.ini file (XAMPP > Xamppfiles > etc) on the last line.

Next, you need to check to make sure Eclipse can see that it is installed (Eclipse menu> Prefs > see image for rest of pathway): Eclipsezenddebug2.png

and make sure that it can access both the IP addresses (client/host IP textbox) of where you will run the debugger from: Zenddebug2.png

Other references

A useful resource that illustrates the installation and configuration steps of XDebug is a blog post by Bogdan Albei, PHP debugging with Xdebug and Eclipse PDT. After a full day of reading various resources and experimenting with all sorts of settings, I was finally able to debug PHP web pages after following Bogdan's ultra important instruction that Accept remote session(JIT) XDebug setting should be "any".

Troubleshooting

There is a compatibility issue with the most recent releases of the Xdebug .dll and the 64 bit version of Windows 7. When debugging a PHP script as a webpage, launched from within Eclipse PDT, the Apache webserver will crash. The reason for this crash is the Xdebug module.

The solution to this problem is to revert to using the Xdebug .dll version 2.0.5, which was released on June 22, 2011. The direct download link is http://xdebug.org/files/php_xdebug-2.0.5-5.3-vc6.dll. Save this .dll to the \xampp\php\ext location.

Next, open xampp\php\php.ini in Notepad++ (first remember to stop Apache in XAMPP-control). Scroll down to line 1983 (approximately), and replace the zend_extension directive so that it reads zend_extension = X:\xampp\php\ext\php_xdebug-2.0.5-5.3-vc6.dll. Note: X: is the drive location of your XAMPP USB storage device. If you are using a drive letter independent version of the XAMPP stack, then copy and paste zend_extension = \xampp\php\ext\php_xdebug-2.0.5-5.3-vc6.dll, which references a relative location.

Restart Apache, and try to debug again :)

Using XDebug

To run the debugger, go to the "Run" tab at the top of the screen. Find the "Debug As" subsection and select the PHP Web Application. Your default web browser should open, or if the internal web browser option was selected an internal browser will open in the bottom panel. If XDebug was configured correctly, a prompt should appear asking the user to go to Debug Perspective. Say yes and the Eclipse perspective should change. Note: nothing should appear in the browser at this time. This is normal.

Take a moment to look over the various panels on the screen. At the top of the screen below the main panel there are icons used to perform commands with XDebug. The top left pane on the screen is the Debug pane. Here you will see the stack of applications running. The pane to the right of that contains important information about the application. The most important tab here is the variables tab, which contains information about what variables are currently stored.

To debug, look for the step into and step over commands. These can be found below the menu at the top of the screen. Stepping over a line jumps to the next line but does not go inside any calls that are made. The Step inside command allows you to run the next line and then proceed to enter any functions that are called. Note: Step In does not step inside library functions, and will only enter user defined functions.

Breakpoints:

Breakpoints are an important aspect in debugging code. While in the PHP editor, double click in the leftmost column and a small circle will appear in the margin. This is a breakpoint. Breakpoints are used to stop execution of code. When debugging, execution will halt at a breakpoint, even if you specify to step over the function which contains the breakpoint. One special use of breakpoints is the ability to go straight to them. Press the F8 key to jump to the next breakpoint. You can then resume execution from that specific point.

For more information, read: Working with the Debugger.