Introduction

This is the eighth article of a series of blog post called the WIMPinator Chronicles that describe how to setup a PHP development environment for Windows 7 and IIS 7.5.

So far we covered how to install a Wordpress blog and all its dependencies using the WPI (Web Platform Installer). Then we installed additional features and extensions to the PHP deployment on Windows for IIS. I explained how to get PEAR setup and how to download and deploy the PHPUnit unit testing framework using PEAR. In the next two posts I described how to install Eclipse PDT and make it work with Subversion source control using Subclipse. I explained how to create an IIS 7.5 Fast CGI web site from scratch and in the most recent tutorial I covered how to use ANT build tasks to deploy your PHP project from Eclipse to your IIS test server using custom build steps.

Now I am getting to the really cool stuff: Debugging PHP code while running on IIS 7.5. First I explain how to use XDebug and next time I will go into the details about how to run the Zend Debugger.

The Series

1. Getting a Wordpress blog installed in a jiffy on Windows 7 using the Web Platform Installer
2. Adding additional features to PHP
3. Installing PEAR and PHPUnit
4. Installing Eclipse PDT
5. Configuring Eclipse PDT to work with Subversion source control
6. Creating a new IIS 7.5 fast CGI web site
7. Configuring Eclipse to work with Ant build tasks
8. Setting up XDebug with Eclipse and IIS 7.5
9. Setting up the Zend Debugger with Eclipse and IIS 7.5
10. Configuring Ruby and Watir
11. Moving a Wordpress blog from GoDaddy shared hosting to my local debugging system.
12. NEW: Setting up the CodeIgnitor MVC framework with PDT and IIS 7.5
13. NEW: Configuring IIS 7.5 Rewrite rules to exclude index.php from the URL
14. NEW: Configuring SSL on IIS 7.5
15. NEW: Writing unit tests with PHP Unit
16. NEW: Writing web UI tests with Watir

References

I copied the following paragraph from the XDebug web site. It describes the functionality of the XDebug extension.

The Xdebug extension helps you debugging your script by providing a lot of valuable debug information. The debug information that Xdebug can provide includes the following:

• stack traces and function traces in error messages with:
  • full parameter display for user defined functions
  • function name, file name and line indications
  • support for member functions
• memory allocation
• protection for infinite recursions

Xdebug also provides:

• profiling information for PHP scripts
• code coverage analysis
• capabilities to debug your scripts interactively with a debug client

The last bullet point is the topic of this article: Using XDebug and Eclipse PDT to interactively debug PHP code.

Note: Eclipse PDT ships with the Zend Debugger, which I will cover in a blog post right after this one.

Here is a great article that has a lot of details about running XDebug with Eclipse PDT. For more details see the XDebug documentation: http://www.xdebug.org/docs/

Downloading and deploying the XDebug extension DLL

If you are a Windows user, you can download a compiled DLL from xdebug.org. Here are the links:

http://www.xdebug.org/download.php

http://www.xdebug.org/files/php_xdebug-2.0.5-5.2-nts.dll for php_xdebug-2.0.5-5.2-nts.dll (Current release)

http://www.xdebug.org/files/php_xdebug-2.1.0RC1-5.2-vc6-nts.dll for php_xdebug-2.1.0RC1-vc6-nts.dll (RC1 of next release)

Select the DLL that matches your PHP version. Remember on Windows 7 and IIS 7.5 you would pick the nts (Non-thread-safe) version and also the vc6 flavor.

Figure 1: XDebug dll download links for Windows binaries

You can find out what PHP version you are using either by looking at the file properties of the php.exe file or by running php –info from a command prompt. You must use the non-debug version of PHP with xdebug. If you have downloaded PHP from php.net, debugging should not be enabled. When in doubt, check the Debug Build entry in the phpinfo() output.

Figure 2: PHP Version from file properties

Figure 3: Downloading the correct XDebug extension DLL

I recommend putting the downloaded DLL into PHP's extension directory called ext, which should be a subdirectory of your PHP directory. You can put the DLL into any directory, provided that you state the full path to the DLL in php.ini.

 

Figure 4: Copying the XDebug extension DLL into the PHP extension folder

Activating the xdebug extension

To activate xdebug, you must add the following entries to the php.ini file:

zend_extension="C:/Program Files (x86)/PHP/extphp_xdebug-2.1.0beta2-5.2-vc6-nts.dll"

xdebug.remote_enable=On
xdebug.remote_host="localhost"
xdebug.remote_port=9000
xdebug.remote_handler="dbgp"

Figure 5: I added the following settings to the php.ini file

Important: On Windows for IIS you need the nts (non-thread-safe php runtime and extension files). In our case we use the XDebug DLLs that end with nts. In addition we need to be careful and not use the default extension keyword zend_extension_ts. This can only be used for the thread-safe version of the debug libraries. Instead use the zend_extension keyword that doesn’t have the _ts at the end. Here is the snippet that I added to the end of my php.ini file.

XDebug has many features and configuration options. I am only using the basic setup.

For a complete list of the configuration options see this link: http://www.xdebug.org/docs/all_settings 

After modifying the php.ini file, run the IISReset command as administrator to reload the php runtime with the new settings. Verify the extension DLL is loaded. Open a command prompt as Administrator and run php –m.

Figure 6: Verify that the XDebug extension is loaded correctly by running php -m

Figure 7: XDebug is listed in the Zend Modules section. The extension is loaded successfully

Configuring Eclipse PDT with XDebug

If you aren’t using Eclipse PDT or any other IDE you must pass the parameter called XDEBUG_SESSION_START to the script by GET, POST, or cookie to actually start a debugging session. The value of this parameter is the debug session name, which should be unique at a given point in time. This way XDebug can distinguish different debug sessions running concurrently. To end a debug session, you need to pass XDEBUG_SESSION_STOP  to the script. Firefox has an Add-On that does just that: https://addons.mozilla.org/en-US/firefox/addon/58688.

With Eclipse PDT the IDE takes care of passing the appropriate parameters to the browser. PDT also sends the IDE key to the XDebug extension automatically.

Here is how you configure PDT to work with the XDebug extension:

Go to Window Preferences in Eclipse.

Figure 8: Window->Preferences

Go to General Web Browser.

Figure 9: General->Web Browser

Click the Use external Web browser radio button.

Figure 10: Select Use external Web browser

Then navigate in the Preferences dialog to the PHP->Debug.

Figure 11: Now go to PHP->Debug in the Preferences dialog

In the Default Settings group change the the PHP Debugger from Zend Debugger to the XDebug.

Figure 12: Change the default PHP debugger from the Zend Debugger to XDebug

Then go to the Run->Debug Configurations… menu

Figure 13: Invoke the Run->Debug Configurations… menu

This opens the Debug Configurations dialog.

 

Figure 14: The Debug Configurations dialog

Double click on PHP Web page icon of the source file type list on the left.

 

Figure 15: Double click on the PHP Web Page entry

Create a new Debug Configuration. Give it a name. I called the configuration “hello1 debug configuration” in my example. Next configure XDebug as the Server Debugger. Specify the file that you want to be opened in the browser when the debugger starts. In my case it is called /CIM225/hello1.php.

The URL text field is deactivated by default, because the Auto Generate checkbox is activated. Uncheck Auto Generate and enter the correct URL in the URL text field, if you need more control over the exact URL that gets loaded into the browser. If the script requires any GET parameters, you can append them to the URL using the URL entry.

 

Figure 16: Specify the debug configuration associated with a specific file

Change to the Advanced tab and make sure that Open in Browser is checked in the Session Settings and also verify that the radio button Debug All Pages is selected.

Figure 17: Verify the Session Settings in the Advanced Debug Configuration settings

The following screenshot shows the Common Debug Configurations tab for completeness sake. No changes need to be made here.

Figure 18: Common Debug Configuration options

Test the interactive debugging with XDebug

Now you can close the configuration window and start a debugging session. To start a debug session switch to the PHP Debug Perspective. Click on the >> double arrow on the top right or go to Window->Open Perspective and select the PHP Debug perspective.

Figure 19: Switch to the PHP Debug perspective

Then add a break point to the hello1.php script. This is the one that I was referring to in the Debug Configurations above. Go to the line of source code that the debugger should start with and select the Toggle Breakpoints right-mouse-click menu.

Figure 20: Toggle Breakpoints

Figure 21: Breakpoint at line 11

Then press the F11 button to start the debugging. You can also use the Run->Debug menu option.

Figure 22: Start the debugging session in PDT

Acknowledge the following dialog and check remember my decision to not get annoyed by this question again in the future.

Figure 23: Say yes to Remember my decision

In the Debug Perspective you can step through lines of code, hover over variables to get their current values or see a complete list of variables and their values in the Variables pane on the right.

Figure 24: Interactive PDT debugging in action

Ausblick

Note: If you configured an Ant task to deploy your web site and then open your browser automatically as part of the deployment/testing build script then you need to disable the browser launch command in Ant since this will interfere with the debugger.

Note: Also in my setup there was no special firewall configuration needed. For example I didn’t need to add port 9000 to the firewall exclusion list.

Note: The following URL shows an example of a XDebug debugging session started from Eclipse. Notice the parameters that specify the XDebug session and the IDE key?

http://localhost//CIM225/hello1.php?XDEBUG_SESSION_STOP_NO_EXEC=ECLIPSE_DBGP&KEY=12660211628651

The next blog post of the series will explain how to use the default Zend debugger instead of XDebug.

Stay tuned!