Using PEAR with Windows Azure Websites and PHP

UPDATE 7-26-2012: The tutorial linked to below has since been updated to use Composer. You should use Composer but if for some reason you want to use your own PEAR directory, you can continue with the below.

If you’ve started to play around with Windows Azure Websites and PHP and you want to use PEAR, you may have run into problems.  As of now, PEAR extensions aren’t officially supported on Windows Azure Websites. 

If you go through this tutorial on the Windows Azure website, it actually instructs you to use PEAR and to push your site up to Windows Azure Websites at the end.  If you follow all of the steps, the site will work flawlessly on your own computer but will return 500 errors when you try to run it on Windows Azure.  It’s not exactly easy to figure out the specific reason for this as there isn’t any error information outputted to the browser.  In order to get any more information out of your site, you’ll need to create a .user.ini file and set display_errors = On as described here.  The .user.ini file allows you to override some options from the php.ini file.  In this case you’re telling IIS to display error information.  If you do that, and then run your site, you’ll see the following error:

My ToDo List (powered by PHP and Azure Tables)
Not working? Warning: require_once(HTTP/Request2.php): failed to open stream: No such file or directory in C:\DWASFiles\Sites\phpsassample\VirtualDirectory0\site\wwwroot\WindowsAzure\Common\
Internal\Http\HttpClient.php on line 33 Fatal error: require_once(): Failed opening required 'HTTP/Request2.php' (include_path='.;C:\php\pear') in C:\DWASFiles\Sites\phpsassample\VirtualDirectory0\site\wwwroot\WindowsAzure\Common\Internal\Http\HttpClient.php on line 33

This is because, as I said before, PEAR extensions aren’t supported.  Thankfully, there is a way around this.  It includes copying the PEAR directory into the root directory of your web application and then pushing it up with your website.  So, on OSX, my PEAR directory is located at /Users/chrisner/pear.  I copied that whole directory into my website’s root folder.  Now, let’s say you’re accessing PEAR or Windows Azure libraries from different sub-folders.  Unfortunately, the "require_once” call isn’t smart enough to search your whole site directory for a file and the php.ini isn’t set up to include your directory either.  Thankfully, the .user.ini file can rescue us again.  In addition to the display_errors line, we can add a include_path which will override what is in the php.ini:

display_errors = On     <br />include_path=".;C:\DWASFiles\Sites\phpsassample\VirtualDirectory0\site\wwwroot\Pear";

As you can see from the errors outputted above, my website is located in C:\DWASFiles\Sites\phpsassample\VirtualDirectory0\site\wwwroot\.  This means that the PEAR folder I push to the server will be located in that directory.  So, if you set the include_path to be that PEAR directory, whenever any PHP file tries to include a PEAR PHP file, it will find it there.  Now this leaves one obvious issue that you will have to deal with:  updates.  Since you’re pushing the PEAR directory to the site on your own, you’d need to handle updating any of those files manually.  On the flip side, you can use Composer which is supported.