Windows Azure Command Line Tools for PHP and web.config Files
Last week, Ben Waine blogged about a problem he ran into when using the Windows Azure Command Line Tools for PHP to deploy a Zend Framework application to Windows Azure. As I investigated the problem further, I was able to generalize it and offer a work around, which is what I’ll explain in this post. (My work around is essentially the same as Ben’s, but my hope is that explaining it in the context of the generalized problem you will be able to avoid headaches when deploying any application to Azure, not just Zend Framework applications.)
The gist of the problem is this: In order for a PHP application to run in Windows Azure, the application must have a web.config file with certain elements (in particular, the <handlers> element must correctly specify PHP as a handler). If the necessary elements are not present in an application’s web.config file (or if there isn’t a web.config file), the Windows Azure Command Line Tools for PHP will add the necessary elements (or create a file and add the elements) for deployment to Azure. However, the tool doesn’t copy all the other elements (for example, a <rewrite> element) in the web.config to the file used for deployment to Azure. But, if the necessary elements are in the application’s web.config file, then the tool correctly copies all content to the web.config file used for deployment. So, the trick is to get the required elements into the web.config before running the command line tool. (If that is clear as mud, don’t worry. The Interoperability Team, who develop the tool, are aware of this and intend to fix it.)
To make that more concrete, I’ll walk you through the steps I went through to move a locally running Zend Framework application to the Windows Azure platform (because Zend applications require a rewrite rule). I’ll start with the Zend Framework tutorial application that I described how to build in this post: Using the Zend Framework and the PDO_SQLSRV Driver.
Note: Although my example is based on a Zend Framework application, if you keep the generalized problem (above) in mind, you should be able to leverage this example more broadly.
1. Migrate the database to SQL Azure. This only takes a couple of minutes with the SQL Azure Migration Wizard - follow the steps in the Creating a SQL Azure Server and Creating a SQL Azure Database sections of this post.
2. Update the application.ini file. By updating the following settings in the application.ini file, your locally running application will now be running with a SQL Azure back end:
resources.db.params.host = "ServerID.database.windows.net"
resources.db.params.username = UserName@ServerID
resources.db.params.password = Your_Password
resources.db.params.dbname = DB_Name
3. Use the Windows Azure Command Line Tools for PHP to create a web.config file. At this point, your application does not have a web.config file in its main directory. We’ll need one for deploying to Azure, but the command line tools don’t handle existing web.config files well. (As I mentioned earlier, the dev team is aware of this and intends to fix it.) So, the first step to getting the right web.config file is to let the tools generate one. To do this, run the following command from the the WindowsCommandLineTools4PHP directory (without the line breaks):
php package.php --project=ZF-MyAlbums
--source="C:\inetpub\wwwroot\zf-tutorial"
--defaultDoc="public/index.php"
--phpRuntime="Path\to\PHP\installation"
--target="Path\to\drop\directory"
This will generate a web.config file (in the ZF-MyAlbums_WebRole folder of you drop directory) that contains all the elements necessary for running a PHP application in Azure. The one thing that it is missing is the rewrite rules we need for the application.
Note: If you are not familiar with the Windows Azure Command Line Tools for PHP, this post will be helpful: Deploying Your First PHP Application with the Windows Azure Command Line Tools for PHP.
4. Update and copy the generated web.config to the application’s main directory. Add the following element to the <system.webserver> element in the generated web.config file and save the file in your application’s main directory:
<rewrite>
<rules>
<rule name="Imported Rule 1" stopProcessing="true">
<match url="^(.*)$" />
<conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile"
negate="true"
pattern=""
ignoreCase="false" />
</conditions>
<action type="Rewrite" url="public/index.php" appendQueryString="true" />
</rule>
</rules>
</rewrite>
5. Re-run the command line tool to test the application in the Compute Emulator. The following command will generate a new package and start the application in the locally running Compute Emulator (a.k.a. the Development Fabric):
php package.php --project=ZF-MyAlbums
--source="C:\inetpub\wwwroot\zf-tutorial"
--defaultDoc="public/index.php"
--phpRuntime="Path\to\PHP\installation"
--target="Path\to\drop\directory"
--cleanRebuild
--runDevFabric
6. Upload package and configuration file to Windows Azure. More on how to do this in this post.
That’s it. (Happy St. Patrick's Day.)
Thanks.
-Brian