Partager via

How to Enable XDebug in Windows Azure Web Sites

  • Article

This past weekend, the Windows Azure Web Sites team released several great improvements. For an overview of everything that was released, I suggest reading Scott Guthrie’s blog post on the subject: Announcing: Great Improvements in Windows Azure Web Sites. A couple of the consequences of these improvements are that you can now run a custom PHP runtime in Windows Azure Web Sites (see Cory Fowler’s post for more information: Enabling PHP 5.4 in Windows Azure Web Sites) and you can enable custom extensions (see my post from earlier this week for more information: Using Custom Extensions in Windows Azure Web Sites). In this post, I’ll cover how to run XDebug (including the profiler) in Windows Azure Web Sites.

Enabling XDebug in Windows Azure Web Sites is as simple as enabling an extension. However, enabling an extension for the built-in PHP runtime is slightly different than doing so for a custom PHP runtime. I’ll cover both scenarios here. In both cases, I’ll assume you have already created a website. If you haven’t, you can learn how by following this tutorial: Create a PHP-MySQL Windows Azure web site and deploy using Git. Or, for more brief instructions (that do not include setting up a database), follow the How to: Create a Website Using the Management Portal section in this tutorial: How to Create and Deploy a Website.

Enabling XDebug for the built-in PHP runtime

To make the XDebug extension (or any extension, for that matter) available to the built-in PHP runtime (currently PHP 5.3.13), you basically need to push the extension binary file to your site and add an application setting (via the Management Portal) that contains the path to the binary file. There are, however, a couple of small hurdles to overcome to enable the XDebug profiler. Here are the specific steps:

1. Download the XDebug DLL file for PHP 5.3: php_xdebug-2.2.1-5.3-vc9-nts.dll

2. Add a new folder to your application’s root directory locally and add the php_xdebug-2.2.1-5.3-vc9-nts.dll file to it. I suggest adding a folder called bin so that visitors of your site can’t browse its contents.

3. Create a new folder in the bin directory called xdebug_profiles. This is the folder to which profiling results will be written. (Note: If you are using Git to publish files, you will need to add some sort of file to this directory since Git won’t push empty directories.)

4. Add a file called .user.ini file to your root directory with the following contents.

 zend_extension = ".\bin\php_xdebug-2.2.1-5.3-vc9-nts.dll"
 xdebug.profiler_enable=1
 xdebug.profiler_output_dir="D:\home\site\wwwroot\bin\xdebug_profiles"

 

5. Push this new content to your site (via Git, FTP, or WebMatrix).

6. Navigate to your site’s dashboard in the Windows Azure Portal, and click on CONFIGURE.

image

7. Find the app settings section, and create a new key/value pair. Set the key to PHP_EXTENSIONS, and set the value to the location (relative to your application root) of your PHP extensions. In my case, it looks like this:

image

8. Click on the checkmark (shown above) and click SAVE at the bottom of the page.

image

That’s it. XDebug should now be running, and profile results should be written to the /bin/xdebug_profiles folder. One drawback I see right now is that the only way to get the contents of the /bin/xdebug_profiles folder is to use FTP. I plan to investigate better ways to do this in the future.

To disable XDebug (and/or the profiler), simply modify the .user.ini file accordingly.

Enabling XDebug for a custom PHP runtime

Since extensions are enabled via your php.ini file when using a custom PHP runtime, enabling XDebug is done in much the same way as you would do it in your development environment. Here, I’ll push my local PHP runtime to Windows Azure Web Sites together with my local php.ini file and with XDebug enabled.

1. Add a new folder to your application’s root directory locally and add your entire PHP runtime directory to it. I suggest adding a folder called bin so that visitors of your site can’t browse its contents.

Note: You will need to set fastcgi.logging=0 in your php.ini file. If you don’t disable FastCGI logging, IIS will return HTTP 500 errors when PHP scripts are executed.

2. Download the version on the XDebug DLL file that corresponds to your PHP runtime version (always choose a vc9-nts flavor): https://xdebug.org/files/. Add this to your extension directory.

3. Create a new folder in the bin directory called xdebug_profiles. This is the folder to which profiling results will be written.

Note: If you are using Git to publish files, you will need to add some sort of file to this directory since Git won’t push empty directories.

4. Add this to your php.ini file, making the sure the name of the DLL file is correct for your PHP version. As you can see, I’m using PHP 5.4:

 zend_extension = ".\ext\php_xdebug-2.2.1-5.4-vc9-nts.dll"
 xdebug.profiler_enable=1
 xdebug.profiler_output_dir="D:\home\site\wwwroot\bin\xdebug_profiles"

 

Note: With the exception of the value of the xdebug.profiler_output_directory, all paths in your php.ini file should be relative. For example, instead of having extension_dir = “C:\Program Files\PHP\ext”, you should have extension_dir=”.\ext”.

5. Push this new content to your site (via Git, FTP, or WebMatrix).

6. Navigate to your site’s dashboard in the Windows Azure Portal, and click on CONFIGURE.

image

7. Find the handler mapping section and add the information shown in the table below (assuming your PHP runtime is in a folder called php54). Note that you will need to click the small checkmark at the right of each entry to create a new entry.

Extension

Script Processor Path

Additional Arguments

*.php

D:\home\site\wwwroot\bin\php54\php-cgi.exe

  

8. Click SAVE at the bottom of the page.

image

Again, that’s it. XDebug should now be running, and profile results should be written to the /bin/xdebug_profiles folder. And, as I noted above, one drawback I see right now is that the only way to get the contents of the /bin/xdebug_profiles folder is to use FTP.

To disable XDebug (and/or the profiler) in this case, simply modify the php.ini file accordingly.

If you play with this new functionality in Windows Azure Web Sites, let us know what you think in the comments.

Thanks.

-Brian

Comments

  • Anonymous
    September 21, 2012
    Good Article.

  • Anonymous
    December 23, 2013
    A quick update. The above method to enable a Zend extension is not very reliable. It didn't work with Ion Cube for example. A better method is to add an app setting called PHP_ZENDEXTENSIONS and set its value to the path of the dll under bin. No need for the .user.ini then

  • Anonymous
    January 05, 2014
    Thanks for the information Ahmed!