Note:This article pertains to the CodePlex SDK initially released late 2009. The Windows Azure team has since then released a newer version of the Azure SDK for PHP on Github. Please refer to the Windows Azure PHP Developer Center for documentation on this more recent version of the SDK.
Please stay tuned and come back here regularly as we are working on refreshing the tutorials to deliver up to date and useful content for our PHP developers.
- Getting the Windows Azure Pre-Requisites
- Setup the Windows Azure SDK for PHP
The Windows Azure SDK for PHP includes a powerful scaffolding feature that allows users to quickly setup a pre-packaged and configured website ready for Windows Azure. In this tutorial you will learn the concepts of scaffolding and how to build and use scaffolds.
This tutorial uses the HelloAzure and HelloAzureScaffold samples from the Windows Azure Sample Kit 4 PHP
Place a copy of the files in C:\temp for the remainder of this tutorial.
The idea of scaffolding has been around the programming community for a long time. A scaffold is a skeleton application that can be used to quickly create a pre-built application needing little or no programming to be useful. The Windows Azure SDK for PHP includes a scaffolding feature that is quick and easy to use.
A typical scaffolding example can be used for an ecommerce site. Using the ecommerce scaffold you can quickly build a project that contains all the code needed to create an ecommerce site. With that base in place you can then concentrate on customizing the theme and plugins rather than designing, developing, and testing the entire thing yourself.
Building a scaffold
Building a scaffold is a relatively simple process that involves editing one file that controls the scaffolding logic and placing the application files in a resource directory.
For this portion we are going to use the application contained in the HelloAzure sample. We will be creating the scaffold in C:\temp\HelloAzureScaffold
Annotations in scaffolds
It is important to note that the scaffolding features of the Windows Azure SDK for PHP use annotations inside the PHPDoc comments to describe the scaffold and available command line parameters. The easiest way to create a new scaffold is to use the DefaultScaffold that ships with the Windows Azure SDK for PHP, but in order for it to function properly you will need to remember to update the annotations.
Using DefaultScaffolder to quickly create a new scaffold
The Windows Azure SDK for PHP ships with a default scaffold called DefaultScaffold. This scaffold sets up a very basic PHP project for Windows Azure. When you create a project using the DefaultScaffold the DefaultScaffold.phar file located at C:\Program Files\Windows Azure SDK for PHP\trunk\scaffolders will be used, however the entire source code for the DefaultScaffolder is available in the library. That code will be used to get a new scaffold created quickly.
Tip: If you often find yourself creating new scaffolds it is also possible to build a scaffold creation scaffold!
Setup the new scaffolder
- Copy the DefaultScaffolder folder from C:\Program Files\Windows Azure SDK for PHP\trunk\library\Microsoft\WindowsAzure\CommandLine\Scaffolders to C:\temp
- Rename C:\temp\DefaultScaffolder to C:\temp\HelloAzureScaffold
- Now you need to edit the C:\temp\HelloAzureScaffold\index.php file to reflect the name of the new scaffold
- Open C:\temp\HelloAzureScaffold\index.php for editing
- Find @command-handler DefaultScaffolder in the second comment block and change DefaultScaffolder to HelloAzureScaffold
- Change the class name from DefaultScaffolder to HelloAzureScaffold
- Save the file
Adding command line parameters
Scaffolds can take advantage of parameters passed in via the command line and be used to perform virtually any action. Adding a parameters is as simple as creating a new @command-parameter-for tag in the runCommand() comment block and adding the parameter to the method list.
In this example you are going to use a parameter to set the Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString in the ServiceConfiguration.cscfg file.
Add an additional @command-parameter-for at the end of the runCommand() comment block. The new tag should look like the following:
@command-parameter-for $diagnosticsConnection String ="UseDevelopmentStorage=true" Argv| ConfigFile|Env --DiagnosticsConnectionString|-d Optional. The diagnostics connection string. This defaults to development storage.
Note: There should be no line breaks in this tag
A breakdown of each portion of this tag is as follows
- $diagnosticsConnectionString is the name of the variable the parameter value will go into
- ="UseDevelopmentStorage=true". If this parameter is optional the value inside of the quotation marks will be used as the default parameter value when it is not specified on the command line
- Argv| ConfigFile|Env
- These are the locations from which the parameter may be accepted. They currently include
- Argv - passed as a command line parameter
- ConfigFile - will be found in the supplied configuration file
- Env - will be found as an environment variable
- This specifies the name of the parameter that can be used on the command line. In this case using either -DiagnosticsConnectionString or -d will work.
- It is good practice to provide a longer descriptive parameter name as well as a short name
- Determines whether the parameter should be required or now. Possible values are Required. and Optional. (Be sure to include the period)
- If a required parameter is not passed in the scaffold will halt and display the message in the remaining portion of the tag
- Anything past Optional.
- If a user simply types in the name of the scaffold the text after Optional. will be displayed as help along with a list of all the available parameters.
- If a required parameter is not specified this string will be displayed when the scaffolder halts execution.
The number and uses of parameters is virtually unlimited. Parameters such as the one listed above are used to set values in the ServiceConfiguration.cscfg file, however parameters are not limited to just setting text. The code inside your scaffolder can read a parameter and perform any action, such as downloading additional content for inclusion in the project for example.
Add the application
The easiest part of building a new scaffold is adding the application. Simply pick up a copy of the application source code and drop it into the resources folder and it will be included in the project files when the scaffold is used later.
This example is using the HelloAzure sample application inside of the scaffold as the pre-built application. You can add the files now.
Copy the files from C:\temp\HelloAzure\WebRole into C:\temp\HelloAzureScaffold\resources\PhpOnAzure.Web
That is it. Your new scaffold is now complete. The only remaining this to do is turn it into a PHP archive file and create new projects with it.
Create the HelloAzureScaffold PHP archive
The scaffolder tools uses the PHP archive type to create a single package in a .phar file of your entire project. The generated .phar file does not require any other files with it to function properly and can immediately be distributed to other systems.
Creating a scaffold PHP archive file is a simple as calling the command line scaffolding tool and giving it the location of the scaffold source code. Issue the following code to create the HelloAzureScaffold.phar scaffold file:
scaffolder build -in="C:\temp\HelloAzureScaffold" -out="C:\temp\HelloAzureScaffold.phar"
To see all the possible options available to the scaffolder tool type scaffolder with no parameters into the command line.
Using a scaffold
Generating a project from a scaffold only requires running one command. All of the project files contained within the PHP archive will be extracted and available for immediate use for further development or deployment.
To create a new project using the scaffold you created in the Building a scaffold section of this tutorial you simply need to issue the following command:
scaffolder run -s="C:\temp\HelloAzureScaffold.phar" -out="C:\temp\HelloAzure"
When you view C:\temp\HelloAzureProject\PhpOnAzure.Web you will notice that the contents are identical to C:\temp\HelloAzureScaffold\resources\PhpOnAzure.Web.
At this point you may freely alter application files in C:\temp\HelloAzure