Last week during PHP[World], my team Azure Web App and I released experimental support for PHP7 RC7 on Azure Web App. This is a really exciting announcement as it allows developers to simply set up an environment to test a PHP 7 app. How simple you ask? Really simple as demonstrated by Jose Miguel Parrella in the following video.
Not simple enough? Try clicking this button below to setup a site in your subscription with PHP 7 pre-installed.
The functionality is provided by leveraging a Site Extension which hooks into the IIS pipeline using an applicationHost.xdt transform file. This means that there are a few things you need to be aware of including how to change the php.ini settings for the site which can be done in two different ways.
Changing the PHP.ini
The site extension works by downloading the PHP 7 RC7 runtime from the Windows side of PHP.net. This means that you need to track down the install folder to change the PHP.ini directly. This is slightly hidden away due to the Site Extension, but you can find the php.ini in the following directory:
There is another way of providing changes to the PHP.ini without modifying the main php.ini directly, this is to create a PHP_INI_SCAN_DIR App Setting and provide it a path in which you will drop new ini files. I consider this the preferred method of implementing ini changes as the changes can persist in the same Web App after the Site Extension is deleted (when PHP7 is available in a supported capacity on Web App). There are full instructions on how to make this work available on Azure.com under the article Changing PHP_INI_SYSTEM configuration settings.
In a previous post I outlined how to enable deployment time dependency management with Wep App by hooking the deployment with Kudu. In this post, I will explain how I iterated on the techniques used in that previous post, to enable Composer in Web App via a Site Extension which lowers the barrier to use Composer with Web App.
Cool, but what exactly is a Site Extension?
Site Extensions are a means of extending the Azure App Service platform. The best part about Site Extensions are that they can be created by anyone, it is as simple as creating a Website, WebJob or IIS Module, an applicationHost.xdt file (applicationHost.config Transform), and possibly some supporting files to help install or setup the Site Extension components. These components are then packaged with NuGet and uploaded to the Site Extension Gallery
More information is available on how to create a Site Extension is available in the Kudu Wiki.
Now, How do I use Composer in Web App?
To get started with Composer on Web App, you’ll need to install the Site Extension, luckily I wrote a post which explains how to enable a site extension. You’ll find Composer in the list of Site Extensions.
Creating a web site which uses Composer
Composer has a number of different ways that it can be leveraged, you can run it as a tool from the command line directly to have it build files or you can manually create a composer.json file. I’ll refer you to the documentation to figure out how you’d like to use it.
For my application, I crafted the composer.json file by hand using Packagist as a reference for my file dependencies. I wanted to create an application which lists files from a particular container in Azure Storage, this means I would require the Microsoft Azure SDK for PHP and it’s dependencies. Here is my composer.json file.
The composer.json file should be placed in the root of the repository. The Composer Site Extension has the COMPOSER_VENDOR_DIR set to d:\home\site\vendor which is out of the public wwwroot directory so that the dependencies cannot be addressable publicly.
Now that we have our dependencies taken care of simply build a PHP application which requires the autoloader which is created for us by composer, then write our code. Here is my index.php file which iterates over items in my storage container.
Now we’re ready to deploy the application and configure a few of the settings to make the application come to life. Click the button below to deploy the application into your Microsoft Azure Subscription:
This Deploy to Azure button could be configured to set these App Settings automatically on deployment, If you see a azuredeploy.json file in the repository you can disregard the following steps. As I have found the time to make the Azure Resource Manager template to hydrate these values.
Add the following App Settings to the App Settings list in the Portal:
container – This is the name of the container in your storage account that you’d like to list the values of. This is referenced in the code above by the call to getenv(‘container’) which reads this value from an environment variable
DEPLOYMENT_SOURCE – Typically, I would add a .deployment file to the respository to change the project config setting to web as this will change the deployment directory and only deploy the items in the web folder. Due to how the Composer site extension is hooking the deployment, the .deployment file doesn’t work so this setting is needed to let Kudu know that the contents of web should be copied to the wwwroot directory
Add the following Connection String to the Connection Strings list in the Portal:
BlobConnectionString – This should contain the connection string for your azure storage account. Set the type to Custom.
There is an assumption here that you actually have a few items in the storage account. If you don’t upload a few now then refresh the website.
That’s it! You have successfully deployed a PHP application which uses composer!
WordPress is the most popular CMS on the Web so there are obviously a great set of tools surrounding it to enable the wide variety of developers who build on the WordPress platform. One of such tools is WP CLI which is a command line interface for managing your WordPress site. In this post, I’m going to cover how to install the WP CLI site extension into your Azure Websites hosted WordPress install to enable command line access to your site.
Install WordPress on Azure
Install WP CLI Site Extension
Command line to WordPress
Install WordPress on Azure
This step is a little bit out of scope for this topic, if you’re savvy enough to know there is a command line tool for WordPress, I’d assume you’d know how it set it up. If for some reason you don’t know, I’m just going to leave these here:
To add a site extension, you need to login to the Azure Portal and go into your site.
If you scroll to the bottom of the site blade, you will find a part called Extensions which on that which will open the Site Extensions blade.
Scroll down the list until you find WordPress CLI, click on the item, then accept the license terms. Click OK and the site will begin to install the extension.
Command line to WordPress
Ok great, I have the Site Extension installed but how does that help me? I want to use the command line. There are two different command lines that I want to show off.
Kudu – Debug Console (Web Based)
When you create an Azure Website in the background a second site is created at http://<site-name>.scm.azurewebsites.net which exposes the Kudu Console (Kudu is the deployment engine for Azure Websites). You can access this site using either OAuth (which is enabled by default) or Basic Auth (http://<site-name>.scm.azurewebsites.net/basicauth). It’s cool that you have web based access to your website.
KuduExec (Terminal, PowerShell, Command Prompt)
Although it is really cool to be able to use the command line in a web browser, wouldn’t it be nice to be able to use your command line of choice? Well, the team thought so too, and enabled it using Node.js. KuduExec is a command line tool which gives you command line access to your Azure Website.
To install KuduExec, first you’ll need to install Node. Once you have node and npm installed run the following command.
npm install kuduexec –g
After kuduexec installs you can run it from the command line to login. To use KuduExec, type in kuduexec then the scm endpoint for your site (hint: http://<site-name>.scm.azurewebsites.net) then use your deployment credentials to login.
Then you have full access to your Azure Websites site.
Guzzle is a very simple abstraction over cURL which provides a great HTTP client for working with web services. This provides a great way of interacting with the Windows Azure Management API with PHP. In this example, I’m going to show how you can enable and disable an SSL Certificate in a Windows Azure Web Site using the Windows Azure Management API.
The majority of Windows Azure Web Site tasks can be automated using either the Windows Azure PowerShell cmdlets or the Windows Azure Cross Platform Command Line tools. This includes the ability to upload an SSL Certificate for your Web Site, however at this point there is no ability to bind the SSL Certificate to the Web Site itself. That’s where Guzzle and the Windows Azure Management API come into the picture.
You can do the following exercise from the Windows Azure Management Portal by following the instructions in the article Enable HTTPS for a Windows Azure web site. This entry is to demonstrate how you can achieve SSL Certificate binding as part of an automated environment script.
Automating SSL Certificate Upload to Azure Web Sites
Before we start interacting with the Management API let’s get the Windows Azure Web Site ready by adding the SSL Certificate to the Environment. This task is incredibly simple to accomplish using the Windows Azure Cross Platform tools.
azure site cert add [ssl-cert-path].pfx --key [cert-password] [web-site-name]
That’s it! The cert will now be added to the Windows Azure Web Site.
Create and Upload Export a Windows Azure Management Certificate
You could very well create and upload a management certificate of your own by creating one with OpenSSL and uploading it via the Windows Azure Management Portal (Settings > Management Certificates). However, there is a much easier way to achieve this without having to generate your own certificates, by using the Windows Azure Cross Platform Tools.
azure account cert export [--subscription]
The optional subscription parameter can be either the name of the subscription name or id from the azure account list command output.
Create a PHP Application with Guzzle to interact with the Windows Azure Management API
This is where things get fun! Let’s start by creating a composer file to acquire Guzzle.
Next we’ll want to take a look at the documentation for how to Enable or Disable SSL in Windows Azure Web Sites with the Management API. This gives us the information for the rest endpoint, http verb and xml/json payload to enable or disable the SSL Certificate.
Warning! At the time of writing SSL Certificates are only available for upload/binding if the Web Site is in Standard Mode. If the site isn’t in Standard Mode your requests will return with the status code HTTP 400 Bad Request.
Enable SSL JSON Playload
Disable SSL JSON Playload
PHP Source Code
To enable or disable SSL in a Web Site you will need to make a PUT request against the management API pass in your SubscriptionId, the webspace of the site, the site name and the Client Certificate. In Guzzle the request is constructed by the client, which you can pass an array of values into for replacement when you create the request by calling the PUT method.
This is how simple it is to make calls to the Windows Azure Management API from PHP using Guzzle. This blog post covers the usage of JSON for the request payload, however, there is a full example available as a Gist if you’d like to see how this can be done with XML.
Windows Azure Web Sites provides the ability to manage dependencies on deployment for .NET using NuGet, and Node.js using npm. This functionality is facilitated by an open source project called Kudu which is built and maintained by the Windows Azure Web Sites team [it can also be installed on Windows Server 2012].
If you’re a PHP Developer, you should know about Composer. Wouldn’t it be great if you could use Composer on Windows Azure Web Sites to fetch your dependencies during the deployment of your PHP Application? I thought so too!
Customizing a Windows Azure Web Sites Deployment for PHP
The Windows Azure Cross Platform Command Line tools expose an extended part of the Kudu functionality called KuduScript. KuduScript can be used to generate a set of files (.deployment, deploy.cmd) which hooks a Kudu deployment, enabling a custom script to be run at deployment time.
To generate a deployment hook with the Cross Platform Tools, run the following command:
azure site deploymentscript --php [-t bash]
This will generate a deployment hook for a PHP application, you could optionally pass in –t bash which would output the script in bash instead of the default batch.
Now that we have a customized deployment script, let’s add a few customizations; one to download composer to our Windows Azure Web Site, the second to run composer to fetch our dependencies specified in our Composer.json file. Add the following two lines above the Deployment section of the deploy.cmd.
:: Download Composer
echo Downloading Composer
IF NOT DEFINED COMPOSER_VENDOR_DIR (
echo Downloading Composer
curl -sS https://getcomposer.org/installer | php
IF !ERRORLEVEL! NEQ 0 goto error
php -d extension=php_intl.dll composer.phar install --prefer-dist --no-dev --optimize-autoloader
Debugging Deployment Issues
Now that you’ve added a process to your deployment that has an external dependency there will most likely come a time where you will need to diagnose issues with your custom deployment. Not to worry, Windows Azure Web Sites includes the output of the deployment script in the Windows Azure Management Portal. To view the deployment log:
Click into the details view of your Windows Azure Web Site
Click on the DEPLOYMENTS tab
Click on the top item in the Deployment History section
An arrow will appear to the right of the entry, Click the Arrow.
Click on the View Log link
Moving the Web Root in Windows Azure Web Sites
A common practice in PHP is to have the vendor directory which is created by running composer be a sibling of the web root directory. This provides a level of security as the vendor directory is not stored in a publicly accessible location avoiding public calls into third party code downloaded by composer.
This can be achieved in Windows Azure Web Sites by changing the Virtual Directory of the web root from within the Windows Azure Management Portal. Assuming my application serves it’s public content from a folder called web contained in the root of my source control, the following steps will move the web root to the web directory:
Click into the Details of your Windows Azure Web Site
Click on the CONFIGURE tab
Scroll to the bottom of the CONFIGURE screen until you find virtual applications and directories
Change the record for / from site\wwwroot\ to site\wwwroot\web
Click the Save button in the Command Bar
Production Web Site Guidance
In a production environment setting, having an external dependency as part of your deployment process can impede the ability to deploy your application. It is up to you to understand the non-functional requirements of your application which includes the acceptable deployment time. It may be required to ensure that the latest version of your code be available in production in a moments notice. In cases such as these it is important to keep a backup of your dependencies which could either be in your production branch of source control, or maintained independently of your project. It may be necessary to stage your deployment in a staging environment before pushing to a production server. In my next post, I’ll cover how you can deploy to a Windows Azure Web Sites staging slot and swap that staging deployment into production.
In upcoming weeks Windows Azure Web Sites will update the default PHP version from PHP 5.3 to PHP 5.4. PHP 5.3 will continue to be available as a non-default option. Customers who have not explicitly selected a PHP version for their site and wish the site to continue to run using PHP 5.3 can select this version at any time from the Windows Azure Management Portal, Windows Azure Cross Platform Command Line Tools, or Windows Azure PowerShell Cmdlets. The Windows Azure Web Sites team will also start onboarding PHP 5.5 as an option in the near future.
Explicitly Selecting a PHP version in Windows Azure Web Sites
If you wish to continue to run PHP 5.3 in your Windows Azure Web Site, follow one of the options below to explicitly set the PHP runtime of your site.
Selecting the PHP version from the Windows Azure Management Portal