How to setup XDebug and PHP with Eclipse 3.4 to debug your website code

This time we’re attacking a relatively tougher challenge – to setup a good debugger in your Eclipse IDE for debugging your PHP website or scripts at runtime. A good debugging tool that allows setting breakpoints in your code, helps you step into the code and watch variable values can be so handy and makes you more productive. If you are familiar with Microsoft Visual Studio debugger, you know how powerful a debugger can be. However, when it comes to PHP, we do not see the same trends towards using a powerful debugger. People manage without a debugger, mostly echo’ing variable output and using self made debug and log calls. This does not really have to be the case with PHP.

During the course of this tutorial, you’ll learn how to setup a very good debugging environment for PHP using XDebug, that allows just-in-time debugging and site-wide breakpoints. This tutorial is written based on a Microsoft Windows XP based installation, but the steps are same for any other platform as well.

This tutorial assumes you have Eclipse + PDT2.0 configuration setup. If you do not have, click here to read my previous post on how to set it up. Also, you’ll require a working Apache+PHP installation, possibly WAMP or XAMPP.

Step 1: Install and configure XDebug with PHP

This is the first and foremost step, also the toughest in the whole setup. Most people go wrong here, and there are a lot of ways you can screw up this portion if you don’t do it right. So please make sure you follow this section, step by step.

XDebug is usually built for a specific version of PHP. I.e., the library for PHP 5.2 will not work with 5.1 or 5.3. So when you download the debugger library, make sure you are downloading the version that matches your PHP version.

Find your PHP version

If you’re using WAMP:

1. Go to the installation directory of WAMP
2. Inside `bin/php` you can see the actual PHP directory, named something similar to `php5.2.8`.
   The first two major versions are what is important to us, i.e., `5.2` in this case. Please make a note of this number.

If you’re using XAMPP:

1. Go to the installation directory of XAMPP
2. Open `php` folder
3. Right click on `php.exe` and choose `Properties`.
4. Click the “Version” tab and make note of the first two digits of the `File version`.
   For example, if the PHP version is 5.2.1.1, we need to download XDebug library for PHP version 5.2. Please make a note of this number.

Fine, so we know which version of PHP we have. Let’s go to XDebug homepage and get the library.

Get yourself a copy of XDebug library

1. Click http://www.xdebug.org/ to go to XDebug homepage
2. Once you’re at XDebug homepage, click the link “Obtaining” on top and look for the release that matches with your PHP version. At the time of writing this tutorial, I have Xdebug 2.0.4 that works with my PHP version 5.2. You might see two variants, thread-safe and non-thread-safe. If thread-safe is available (usually it’s not mentioned in the name if it’s thread safe), download that one. I chose 5.2 VC6 (php_xdebug-2.0.4-5.2.8.dll).
3. Save it to the `ext` directory inside your PHP directory. If you are not sure where `ext` comes, go to the PHP directory as per the steps mentioned above, and look for the `ext` directory inside it.

Edit your PHP.ini to enable XDebug

You need to tell PHP to load XDebug library at runtime by editing PHP.ini configuration.

A special note for XAMPP and WAMP users: The `php.ini` that is inside your php home folder might not be the one that apache uses for serving web pages. Most probably in the apache directory you’ll have another `PHP.ini`. So first make sure you have the right `PHP.ini` file at hand. If you’re confused, it’s recommended to create a `phpinfo.php` script that contains the following code and access it from your browser to see which INI file is in use.

If you’re confused which `php.ini` is in use, create a `phpinfo.php` file in the document root of your website, with the following contents:

<?php
// phpinfo.php
phpinfo();
?>

And access it via:

http://localhost/phpinfo.php

Look for the `Loaded Configuration File` and you’ll get the complete path to the `php.ini` configuration file in use.

NOTE: If you want to use XDebug to debug your commandline scripts as well, you might want to add the configuration to the PHP.ini inside the php home directory as well.

For my configuration setup, the `php.ini` file in use is `D:\bin\wamp\bin\apache\apache1.3.35\php.ini`.

Now once you have the right file open for editing, either uncomment or add the following lines to it. Recent versions of XAMPP have this in `php.ini`, but it comes commented by default. Make sure you substitute the right path/filename to your XDebug library file and the temporary directory.

[XDebug]
; Modify the filename below to reflect the .dll version of your xdebug
zend_extension_ts="D:\bin\wamp\bin\php\php5.2.8\ext\php_xdebug-2.0.4-5.2.8.dll"
xdebug.remote_enable=true
xdebug.remote_host=127.0.0.1  ; if debugging on a remote server, put client IP here
xdebug.remote_port=9000
xdebug.remote_handler=dbgp
xdebug.profiler_enable=0
xdebug.profiler_output_dir="D:\bin\wamp\tmp"

Note that `xdebug.profiler_enable` is set to `0` above instead of `1`. This is not the default in the XAMPP `php.ini`, but it’s recommended to change it to `0` to disable it.

Also, comment out any Zend Optimizer in php.ini because it is not compatible with XDebug. For example, all of this should be commented out (using `;`):

[Zend]
; zend_extension_ts = "C:xampp\php\zend\Optimizer\lib\ZendExtensionManager.dll"
; zend_extension_manager.optimizer_ts = "C:\xampp\php\zend\Optimizer\lib\Optimizer"
; zend_optimizer.enable_loader = 0
; zend_optimizer.optimization_level=15
; zend_optimizer.license_path =

Remember to restart your webserver for the `php.ini` to take effect.

Verify XDebug is installed and configured properly

Once you’ve restarted the web server, verify that you have XDebug installed correctly by calling the script with `phpinfo()` that we created before. You should see the XDebug line in the footer as you see in the picture below.

If you cannot see this, then there’s something wrong in your setup. Please start over and make sure you follow the guide step by step.

Step 2: Set up your PHP servers in Eclipse IDE

You need to configure a web server so you can debug PHP web pages on your local computer or remote site.

To configure your local web server in Eclipse:

1. Go to Window > Preferences
2. Navigate to PHP > PHP Servers. If you have a default PHP server listed, click Edit for that server, otherwise click `New`
3. In Configure a PHP Server, type a name you would like to call this server in the Name field — I’m calling it `WAMP`.
4. Type the base URL (for example, `http://localhost`) of your website in the URL field.
5. Click the `Path Mapping` tab.
6. Click `Add` to add a new path mapping. You can click Browse to select a location from your workspace, then make sure the full path to the resources appears in the Path on Server field. For example, in my project, I have `/myapp` in `Path on Server` and `/myapp` in `Path in workspace`. The path on server indicates the directory prefix that will be used to access the website. In my case, the URL will thus be `http://localhost/myapp`. It is very important to have this configured properly, otherwise your breakpoints will not work.
7. Click OK thrice to save and close the settings.

NOTE: If your webserver is on a remote machine (other than `localhost` or `127.0.0.1`), do the following instead:

1. Go to `Window` > `Preferences`
2. Navigate to `PHP` > `PHP Servers`. Click `New`
3. `Name:` Provide a name to refer to this server in eclipse
4. `URL:` Enter the URL of the document root of the remote server
5. Click `Next`
6. Server Path Mapping Window: Click `Add:`
7. Path on Server: if the docroot on the server is at `c:\xampp\htdocs` on the server machine, then put that here, otherwise put the docroot path of the server (remember, `C:` is the server’s `C:` drive)
8. Click on the radio for `Path in Workspace` and press the `Browse` button. Select the workspace resource corresponding to the docroot, and click `OK`
9. Click “OK” thrice to save and close the settings.

Set up the PHP executables

Before using the debugger, you must verify that the PHP executables are set up properly. Open the Eclipse preferences, expand `PHP`, then click `PHP Executables`.

To add and configure a new executable, click `Add`. The `Add new PHP Executable` window appears. Type a descriptive name (the name can include spaces) in the `Name` field, then click `Browse` to locate the PHP executable path (For example, `D:\bin\wamp\bin\php\php5.2.8\php.exe` if you are using WAMP and it’s installed `D:\bin\wamp`. If you’re using XAMPP, it might be `c:\xampp\php\php.exe`) and the `php.ini` file (choose the one that you configured with XDebug).

Finally, choose the correct PHP debugger, i.e., XDebug in our case. It matters: If you choose the incorrect debugger, your project might not execute at all or could execute, but not stop at breakpoints.

Click Finish and OK to save and close the setting dialogs.

Step 3: Setup a Debug Configuration for your project

A debug configuration tells Eclipse IDE which is the start file of your project, how to generate paths and which debug and server configuration to use for debugging.

1. First, change to “PHP Debug” perspective by clicking “Window” > “Open Perspective” > “PHP Debug”.
2. Go to “Run” > “Debug Configurations…”
3. Click PHP Web page in the left tree and click New button on the top of the dialog. (You can right click PHP Web page and click New as well).
4. Name the configuration something. I chose “Localhost Debug Config”
5. Make sure you have “XDebug” selected in the Server Debugger combo box
6. Select the appropriate server (that you previously setup) in the PHP server box. If you wish to make some changes to the server entry or create a new one at this point, you can do it by clicking the “Configure…” or “New” buttons to the right.
7. Click the Browse button right to the file prompt to select the file you would like to start debugging with. Now, this requires some detail.(a) If you would like to debug a specific file only, you can click Browse and select that file. Debugging will always start with that file in the browser.(b) In normal cases, when you would like to do site-wide debugging, you can choose the index.php or the start page of your site here. I usually give index.php, so that the index page is loaded on start of debugging and I can navigate away from that page and continue debugging.
8. Once you select a file from the project path through the Browse dialog, the path that is autogenerated might be different from what you would expect on the server side. For example, if your project name is different from that of the URL directory prefix, then you need to manually edit the path to suit your need.WARNING: If the path doesn’t match exactly, your debugging session will start, but breakpoints will not work.
9. There’s a “Break at First line” checkbox, which is ticked on by default. This causes an automatic breakpoint to be set to the first line of each file. So each time you change pages on the server side, the debugger will break on the first line and let you debug. However, this can get annoying if you have a lot of include files and your page switch is frequent. I prefer to keep this turned off and set manual breakpoints wherever I would like to debug. However, for testing purposes, you can keep it on if you would like.
10. Click “Apply” followed by “Close” to save and close the debug configuration.

Once you’ve setup the debug configuration, switch to PHP Debug perspective and just hit F11 or select “Run” > “Debug” to start debugging. Eclipse will launch a new browser window (or if you have an existing browser open, it will open up a new tab). If you have the “Break at first line” turned on, the execution will be suspended and the debug will prompt you at the first line of your page. If you have it turned off, it will suspend on executing your breakpoint. You can set a breakpoint by double clicking on the left margin, by pressing CTRL+SHIFT+B or by selecting Run > Toggle Breakpoint.

As the screenshots show, you can see the source code of the debugged file, with the line being executed highlighted and marked with an arrow to the left of the line number. The Variables tab shows the current values of all variables in the current scope. The superglobal variables are valid in every scope, so they are always displayed. The Breakpoints tab lets you view and edit all breakpoints in your script. Eclipse will remember any breakpoints you have set on the code, even if you close and restart the IDE.

You can now continue program execution until the next breakpoint is reached (F8), execute just one step (F6), or step into the next function (F5), or out of the next function scope by clicking the appropriate icons in the Debug top left area of the window, or from Run menu. Stepping is useful when you have located the problem area in your code and want to watch closely what is happening. You will see the variable values change with each step.

Changing Variables at Runtime

You can change variable values during script runtime. It is useful to provoke certain errors without modifying the source code, or to see if a certain assignment fixes an issue. To change a variable, click the current value, modify it and press Enter.

Breakpoints

A breakpoint pauses script execution and allows you to inspect variable values, then continue the program. The program execution is also paused if an exception occurs in your PHP code. To set a breakpoint, right-click a line number in the source code, then choose Toggle Breakpoints from the context menu. You can remove breakpoints in the same way, or remove them in the Breakpoints tab by right-clicking a breakpoint and selecting Remove from the context menu.

Conditional breakpoints are also easy to setup, they pause the execution only when a given condition is met. This is can be very useful when the same piece of code is executed multiple times with different parameters and you want to check the code only for a particular combination of parameters. To add a condition to a breakpoint, right-click the breakpoint icon to the left of the line number in the source code view. Choose Breakpoint Properties. You can remove conditions in the same way or by right-clicking a breakpoint and selecting Set Condition from the context menu in the Breakpoints tab. CheckEnable Set Condition and enter a condition in PHP code into the text field.

To end a debugging session, highlight Remote Launch in the top left pane, then click the Terminate icon which is located between the Run and the various Step icons. If you had Eclipse run the script in an external browser, you need to close the browser window manually.

Some common problems and how to get around them

1. I can’t see XDebug configuration or XDebug copyright line in phpinfo().Your XDebug DLL library is not being detected by PHP, or perhaps it’s incompatible. Please go to step 1 and make sure you’ve followed the instructions correctly. Also make sure you are editing the right PHP.ini file. If you still can’t get it to work, please post a comment with details of your configuration and I can look into it.
2. A browser opens with my website when I start debugging, but it’s not breaking on the first line of the script.If you have “Break at first line” turned off, the execution will continue as normal, until it encounters a manually set breakpoint. So if this option is turned off, make sure you have a manual breakpoint set by Run > Toggle breakpoint.If you have the option turned on and still it’s not breaking, then there’s something wrong with the paths you have configured in your PHP server configuration. They need to match exactly with your setup or none of your breakpoints will work.
   
   
3. My webserver is not on localhost, or I would like to debug my staging configuration hosted elsewhere. How do I do that?1) In the PHP.ini configuration, put the IP address of your client machine (your machine with Eclipse) instead of 127.0.0.1.2) In your Eclipse PHP server configuration, configure the correct base URL and document roots.

   3) Make sure your firewall is not blocking the communication. XDebug uses port 9000 by default so you might want to add exceptions to your firewall if necessary.

Happy debugging!

Tags: eclipse, ganymede, PHP, xdebug

This entry was posted on Sunday, April 5th, 2009 at 1:56 am and is filed under Tutorials. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.