This project provides a set of PHP client libraries that make it easy to access Windows Azure tables, blobs, queues, service bus (queues and topics), service runtime and service management APIs. For documentation on how to host PHP applications on Windows Azure, please see the Windows Azure PHP Developer Center.
- Tables
- create and delete tables
- create, query, insert, update, merge, and delete entities
- batch operations
- REST API Version: 2011-08-18
- Blobs
- create, list, and delete containers, work with container metadata and permissions, list blobs in container
- create block and page blobs (from a stream or a string), work with blob blocks and pages, delete blobs
- work with blob properties, metadata, leases, snapshot a blob
- REST API Version: 2011-08-18
- Storage Queues
- create, list, and delete queues, and work with queue metadata and properties
- create, get, peek, update, delete messages
- REST API Version: 2011-08-18
- Service Bus
- Queues: create, list and delete queues; send, receive, unlock and delete messages
- Topics: create, list, and delete topics; create, list, and delete subscriptions; send, receive, unlock and delete messages; create, list, and delete rules
- Service Runtime
- discover addresses and ports for the endpoints of other role instances in your service
- get configuration settings and access local resources
- get role instance information for current role and other role instances
- query and set the status of the current role
- REST API Version: 2011-03-08
- Service Management
- create, update, delete, list, regenerate keys for storage accounts
- create, update, delete, list affinity groups
- REST API Version: 2011-10-01
To get the source code from GitHub, type
git clone https://github.com/WindowsAzure/azure-sdk-for-php.git
cd ./azure-sdk-for-php
Note
The PHP Client Libraries for Windows Azure have a dependency on the HTTP_Request2, Mail_mime, and Mail_mimeDecode PEAR packages. The recommended way to resolve these dependencies is to install them using the PEAR package manager.
Alternatively, you can download the client libraries and all dependencies using the PHP package manager PEAR:
-
Install the PEAR package:
pear install pear.windowsazure.com/WindowsAzure
There are four basic steps that have to be performed before you can make a call to any Windows Azure Storage API when using the libraries.
-
First, include the autoloader script:
require_once "WindowsAzure/WindowsAzure.php";
-
Include the namespaces you are going to use.
Before you can access any of the services you must set your authentication credentials up in an instance of the
Configuration
class:use WindowsAzure\Common\Configuration;
To access a service you need to include at least two namespaces - one for the factory instantiating REST wrapper objects, and another for the configuration settings object. For example, for tables you need:
use WindowsAzure\Table\TableService; use WindowsAzure\Table\TableSettings;
To process exceptions you need:
use WindowsAzure\Common\ServiceException;
-
Set your authentication credentials within the Configuration object. Use the settings object to determine the right key names:
$config = new Configuration(); $config->setProperty(TableSettings::ACCOUNT_NAME, '[YOUR_STORAGE_ACCOUNT_NAME]'); $config->setProperty(TableSettings::ACCOUNT_KEY, '[YOUR_STORAGE_ACCOUNT_KEY]'); $config->setProperty(TableSettings::URI, '[YOUR_STORAGE_ACCOUNT_NAME]' . '.table.core.windows.net');
-
Instantiate a "REST Proxy" - a wrapper around the available calls for the given service. For example, for Tables use the TableService factory passing in the Configuration object:
$tableRestProxy = TableService::create($config);
The following are examples of common operations performed with the Table serivce. For more please read How-to use the Table service.
To create a table call createTable:
try {
// Create table.
$tableRestProxy->createTable("mytable");
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
Error Codes and Messages for Tables
To add an entity to a table, create a new Entity object and pass it to TableRestProxy->insertEntity. Note that when you create an entity you must specify a PartitionKey
and RowKey
. These are the unique identifiers for an entity and are values that can be queried much faster than other entity properties. The system uses PartitionKey
to automatically distribute the table’s entities over many storage nodes.
use WindowsAzure\Table\Models\Entity;
use WindowsAzure\Table\Models\EdmType;
$entity = new Entity();
$entity->setPartitionKey("pk");
$entity->setRowKey("1");
$entity->addProperty("PropertyName", EdmType::STRING, "Sample");
try{
$tableRestProxy->insertEntity("mytable", $entity);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
To query for entities you can call queryEntities. The subset of entities you retrieve will be determined by the filter you use (for more information, see Querying Tables and Entities). You can also provide no filter at all.
$filter = "RowKey eq '2'";
try {
$result = $tableRestProxy->queryEntities("mytable", $filter);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
$entities = $result->getEntities();
foreach($entities as $entity){
echo $entity->getPartitionKey().":".$entity->getRowKey()."<br />";
}
To get started using the Blob service you must include the BlobService
and BlobSettings
namespaces and set the ACCOUNT_NAME
and ACCOUNT_KEY
configuration settings for your credentials. Then you instantiate the wrapper using the BlobService
factory.
The following are examples of common operations performed with the Blob serivce. For more please read How-to use the Blob service.
// OPTIONAL: Set public access policy and metadata.
// Create container options object.
$createContainerOptions = new CreateContainerOptions();
// Set public access policy. Possible values are
// PublicAccessType::CONTAINER_AND_BLOBS and PublicAccessType::BLOBS_ONLY.
// CONTAINER_AND_BLOBS: full public read access for container and blob data.
// BLOBS_ONLY: public read access for blobs. Container data not available.
// If this value is not specified, container data is private to the account owner.
$createContainerOptions->setPublicAccess(PublicAccessType::CONTAINER_AND_BLOBS);
// Set container metadata
$createContainerOptions->addMetaData("key1", "value1");
$createContainerOptions->addMetaData("key2", "value2");
try {
// Create container.
$blobRestProxy->createContainer("mycontainer", $createContainerOptions);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
Error Codes and Messages for Blobs
For more information about container ACLs, see Set Container ACL (REST API).
To upload a file as a blob, use the BlobRestProxy->createBlockBlob method. This operation will create the blob if it doesn’t exist, or overwrite it if it does. The code example below assumes that the container has already been created and uses fopen to open the file as a stream.
$content = fopen("myfile.txt", "r");
$blob_name = "myblob";
try {
//Upload blob
$blobRestProxy->createBlockBlob("mycontainer", $blob_name, $content);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
While the example above uploads a blob as a stream, a blob can also be uploaded as a string.
To list the blobs in a container, use the BlobRestProxy->listBlobs method with a foreach loop to loop through the result. The following code outputs the name and URI of each blob in a container.
try {
// List blobs.
$blob_list = $blobRestProxy->listBlobs("mycontainer");
$blobs = $blob_list->getBlobs();
foreach($blobs as $blob)
{
echo $blob->getName().": ".$blob->getUrl()."<br />";
}
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
To get started using the Queue service you must include the QueueService
and QueueSettings
namespaces and set the ACCOUNT_NAME
and ACCOUNT_KEY
configuration settings for your credentials. Then you instantiate the wrapper using the QueueService
factory.
The following are examples of common operations performed with the Queue serivce. For more please read How-to use the Queue service.
A QueueRestProxy object lets you create a queue with the createQueue method. When creating a queue, you can set options on the queue, but doing so is not required.
$createQueueOptions = new CreateQueueOptions();
$createQueueOptions->addMetaData("key1", "value1");
$createQueueOptions->addMetaData("key2", "value2");
try {
// Create queue.
$queueRestProxy->createQueue("myqueue", $createQueueOptions);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
Error Codes and Messages for Queues
To add a message to a queue, use QueueRestProxy->createMessage. The method takes the queue name, the message text, and message options (which are optional).
try {
// Create message.
$queueRestProxy->createMessage("myqueue", "Hello World!");
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
You can peek at a message (or messages) at the front of a queue without removing it from the queue by calling QueueRestProxy->peekMessages.
// OPTIONAL: Set peek message options.
$message_options = new PeekMessagesOptions();
$message_options->setNumberOfMessages(1); // Default value is 1.
try {
$peekMessagesResult = $queueRestProxy->peekMessages("myqueue", $message_options);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
$messages = $peekMessagesResult->getQueueMessages();
// View messages.
$messageCount = count($messages);
if($messageCount <= 0){
echo "There are no messages.<br />";
}
else{
foreach($messages as $message) {
echo "Peeked message:<br />";
echo "Message Id: ".$message->getMessageId()."<br />";
echo "Date: ".date_format($message->getInsertionDate(), 'Y-m-d')."<br />";
echo "Message text: ".$message->getMessageText()."<br /><br />";
}
}
Your code removes a message from a queue in two steps. First, you call QueueRestProxy->listMessages, which makes the message invisible to any other code reading from the queue. By default, this message will stay invisible for 30 seconds (if the message is not deleted in this time period, it will become visible on the queue again). To finish removing the message from the queue, you must call QueueRestProxy->deleteMessage.
// Get message.
$listMessagesResult = $queueRestProxy->listMessages("myqueue");
$messages = $listMessagesResult->getQueueMessages();
$message = $messages[0];
// Process message
// Get message Id and pop receipt.
$messageId = $message->getMessageId();
$popReceipt = $message->getPopReceipt();
try {
// Delete message.
$queueRestProxy->deleteMessage("myqueue", $messageId, $popReceipt);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
There are four basic steps that have to be performed before you can make a call to any Windows Azure Storage API when using the libraries.
-
First, include the autoloader script:
require_once "WindowsAzure/WindowsAzure.php";
-
Include the namespaces you are going to use.
use WindowsAzure\Table\ServiceBusService; use WindowsAzure\Common\ServiceException;
-
Set your authentication credentials within the Configuration object. Use the settings object to determine the right key names:
$config = new Configuration(); ServiceBusSettings::configureWithWrapAuthentication( $config, $namespace, $issuer, $key);
-
Instantiate a "REST Proxy" - a wrapper around the available calls:
$serviceBusRestProxy->createQueue($queueInfo);
The following are examples of common operations performed with Service Bus Queues service. For more please read How-to use Service Bus Queues.
try {
$queueInfo = new QueueInfo("myqueue");
// Create queue.
$serviceBusRestProxy->createQueue($queueInfo);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
To send a message to a Service Bus queue, your application will call the ServiceBusRestProxy->sendQueueMessage method. Messages sent to (and received from ) Service Bus queues are instances of the BrokeredMessage class.
try {
// Create message.
$message = new BrokeredMessage();
$message->setBody("my message");
// Send message.
$serviceBusRestProxy->sendQueueMessage("myqueue", $message);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
The primary way to receive messages from a queue is to use a ServiceBusRestProxy->receiveQueueMessage method. Messages can be received in two different modes: ReceiveAndDelete (mark message as consumed on read) and PeekLock (locks message for a period of time, but does not delete).
The example below demonstrates how a message can be received and processed using PeekLock mode (not the default mode).
try {
// Set the receive mode to PeekLock (default is ReceiveAndDelete).
$options = new ReceiveMessageOptions();
$options->setPeekLock(true);
// Receive message.
$message = $serviceBusRestProxy->receiveQueueMessage("myqueue", $options);
echo "Body: ".$message->getBody()."<br />";
echo "MessageID: ".$message->getMessageId()."<br />";
// *** Process message here ***
// Delete message.
$serviceBusRestProxy->deleteMessage($message);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
try {
// Create topic.
$topicInfo = new TopicInfo("mytopic");
$serviceBusRestProxy->createTopic($topicInfo);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
try {
// Create subscription.
$subscriptionInfo = new SubscriptionInfo("mysubscription");
$serviceBusRestProxy->createSubscription("mytopic", $subscriptionInfo);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
Messages sent to Service Bus topics are instances of the BrokeredMessage class.
try {
// Create message.
$message = new BrokeredMessage();
$message->setBody("my message");
// Send message.
$serviceBusRestProxy->sendTopicMessage("mytopic", $message);
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
The primary way to receive messages from a subscription is to use a ServiceBusRestProxy->receiveSubscriptionMessage method. Received messages can work in two different modes: ReceiveAndDelete (the default) and PeekLock similarly to Service Bus Queues.
The example below demonstrates how a message can be received and processed using ReceiveAndDelete mode (the default mode).
try {
// Set receive mode to PeekLock (default is ReceiveAndDelete)
$options = new ReceiveMessageOptions();
$options->setReceiveAndDelete();
// Get message.
$message = $serviceBusRestProxy->receiveSubscriptionMessage("mytopic",
"mysubscription",
$options);
echo "Body: ".$message->getBody()."<br />";
echo "MessageID: ".$message->getMessageId()."<br />";
} catch(ServiceException $e){
$code = $e->getCode();
$error_message = $e->getMessage();
echo $code.": ".$error_message."<br />";
}
For more examples please see the Windows Azure PHP Developer Center
Be sure to check out the Windows Azure Developer Forums on Stack Overflow if you have trouble with the provided code.
If you would like to become an active contributor to this project please follow the instructions provided in Windows Azure Projects Contribution Guidelines.
To setup your development environment, follow the instructions in this wiki page.
If you encounter any bugs with the library please file an issue in the Issues section of the project.