Accessing Windows Azure Blob Storage from PHP
June 7, 2012 update: The Microsoft Windows Azure team has released a new Windows Azure SDK for PHP. This release is part of an effort to keep PHP client libraries up to date with new Windows Azure features and to make PHP a first-class citizen in Windows Azure. The latest client libraries are on GitHub: https://github.com/WindowsAzure/azure-sdk-for-php. While the SDK hosted on CodePlex will continue to work for the foreseeable future, it is strongly recommended that new PHP/Windows Azure application use the SDK hosted on GitHub.
The work done by Maarten Balliauw and other contributors in building the SDK hosted on CodePlex was critical in unifying the PHP developer experience for Windows Azure. The Windows Azure team is grateful to these contributors for their pioneering work and looks forward to their continued support (and yours!) in adding to the new SDK on GitHub.
Thanks,
The Windows Azure Team
A couple of weeks ago I wrote a post that covered the basics for accessing Windows Azure Table storage from PHP. In this post I will do something similar for accessing Windows Azure Blob Storage from PHP. This won’t be a deep-dive into Windows Azure Blob Storage, but it will be a “how to get started with the Microsoft_WindowsAzure_Storage_Blob class (which is part of the Windows Azure SDK for PHP)”-type post.
What is Windows Azure Blob Storage?
Windows Azure Blob Storage is a data store for text and binary data. Access to Blob Storage is done via REST/HTTP. (When you create a Windows Azure storage account (see below), you get three services: blob storage, table storage, and a queue service.) Blob storage is logically divided into containers, blobs and blob metadata. You may create any number of containers which can each contain any number of blobs, and each blob can have metadata associated with it (as key-value pairs). Access control is set at the container level as either public or private. All blobs within a public container are accessible to anyone while blobs within a private container are accessible only to people who have the storage account’s primary access key. The following diagram shows the basic structure of Windows Azure Blob Storage:
For a more detailed look at Windows Azure Blob Storage, see Blob Service Concepts and Blob Service API.
How do I create a storage account?
The steps for creating a storage account are the same whether you want to use the blob, table, or queue stores available in Windows Azure. Follow the steps in this post (under How do I create a storage account? ) to create a storage account.
How do I access Windows Azure Blob Storage from PHP?
As in my post about using Windows Azure Table Storage via PHP, I’ll use the Windows Azure SDK for PHP to interact with Windows Azure Blob Storage. If you haven’t already, start by downloading the SDK, unzipping the package, adding the unzipped folder to your PHP libraries, and adding the library directory to your include_path in your php.ini file. (I put the folder in my PHPLibraries directory and updated my include_path to include C:\PHPLibraries\PHPAzure-1.0.1\library.) You can get a good idea of how to use the API in the documentation here, but the code I’ll show here provides a bit more detail and is in the context of a very simple web page (code files attached).
The web page I’ve created will allow you to create/delete containers, set container ACLs, store/download/display blobs (I’ve written the scripts with the assumption that the blobs I’ll be storing are pictures). Keep in mind that this web page is meant as a proof-of-concept only. If you put the attached files in your root directory (and modify them to include your storage account name and primary access key), you should have a very simple application that demonstrates the basics of using the Windows Azure Blob Storage from PHP. I don’t demonstrate usage of all methods on the Microsoft_WindowsAzure_Storage_Blob class. See the documentation that is included with the Windows Azure SDK for PHP for more information about the class.
All of the code below assumes that you have referenced the Blob.php file and that you have instantiated a new Microsoft_WindowsAzure_Storage_Blob object:
require 'Microsoft\WindowsAzure\Storage\Blob.php';
$storageClient = new Microsoft_WindowsAzure_Storage_Blob('blob.core.windows.net',
'Your_Storage_Account_Name',
'Your_Primary_Access_Key');
Note: I modified line 1363 in the Blob.php file. The Blob.php file uses the ereg function, which is deprecated in PHP 5.3. I replaced it with the supported preg_match function.
Creating a Container and Setting the ACL
The first steps in creating a container for blobs are to make sure you have a valid container name (see Naming Containers, Blobs, and Metadata for more information) and that the container doesn’t already exist, which are easy to do with the isValidContainerName and containerExists methods. Then, the createContainer and setContainerAcl methods make it easy to create a container and set the ACL (note that when a container is created it is private by default).
if($storageClient->isValidContainerName($_POST['newcontainer']))
{
if(!$storageClient->containerExists($_POST['newcontainer']))
{
$result = $storageClient->createContainer($_POST['newcontainer']);
echo "<h2>Container created.</h2>";
if($_POST['acl'] == "public") //default is PRIVATE
{
$storageClient->setContainerAcl($_POST['newcontainer'],
Microsoft_WindowsAzure_Storage_Blob::ACL_PUBLIC);
}
}
else
{
echo "<h2>That container already exists.</h2>";
}
}
else
{
echo "<h2>That is not a valid container name.</h2>";
}
Deleting a Container
Deleting a container is straightforward with the deleteContainer method:
$storageClient->deleteContainer($_POST['containerlist']);
Listing Containers
Listing containers is also easy:
$containers = $storageClient->listContainers();
// some HTML
foreach($containers as $container)
{
print('<option value="'.$container->name.'">'.$container->name.'</option>');
}
Uploading a Blob
To upload a blob you must specify the container, the blob name, and the local file to be uploaded to the putBlob method:
$storageClient->putBlob($_POST['containerlist'], $_FILES['blobfile']['name'], $_FILES['blobfile']['tmp_name']);
Downloading a Blob
Downloading a blob is similar to uploading a blob. You must pass the container name, blob name, and the location to which you want the blob stored to the getBlob method:
$storageClient->getBlob($_POST['containerlist'],
$_POST['bloblist'],
'C:\Users\Public\Documents\\'.$_POST['bloblist']);
One thing that gave me trouble here was finding a folder to which I could write the blob (I ran into permissions problems). I’ve hard coded the C:\Users\Public\Documents\ folder as the location here because it generally has relaxed permissions for writing files. If you want to use a different folder, make sure that you have write permissions to it.
Streaming a Blob
To stream a blob, you need to register the $storageClient object as a PHP file stream wrapper with the registerStreamWrapper method. From there, you can open the stream by accessing a URL of this format: azure://containerName/blobName:
$blobUrl = 'azure://'.$_GET['container'].'/'.$_GET['blobname'];
$storageClient->registerStreamWrapper();
$fileHandle = fopen($blobUrl, 'r');
fpassthru($fileHandle);
Deleting a Blob
Deleting a blob is what you would expect:
$storageClient->deleteBlob($_POST['container'], $_POST['bloblist']);
Listing Blobs
Listing blobs is easy with the listBlobs method:
$blobs = $storageClient->listBlobs($containers[0]->name);
// some HTML
foreach($blobs as $blob)
{
print("<option value='".$blob->name."'>".$blob->name."</option>");
}
One more thing to note: When you have put a blob in a public container, it can be accessed by anyone with a URL like this: https://Your_Storage_Account_Name.blob.core.windows.net/container_name/blob_name. If you create a public container with the name $root (that's not a PHP variable), any blob in that container can be accessed with a URL like this: https://Your_Storage_Account_Name.blob.core.windows.net/blob_name.
That’s the basics. If you put the attached files in your root directory (and modify them to include your storage account name and primary access key), you should have a very simple application that will demonstrate the basics of using the Windows Azure Blob Storage. Play with it and let me know what you think.
Thanks.
-Brian