New Connection Pattern in the PHP Client Libraries for Windows Azure

Today, the Windows Azure team released an update to the PHP Client Libraries for Windows Azure. You can always see what work has been done (and what is planned) by looking at the Github repository, but to summarize, the update includes several minor bug fixes and a change in the way connecting to a service is done. Note that this change is a breaking change.

What is the change?

Old Connection Pattern

Previously, connecting to a Windows Azure service (storage service or service bus service) was done by using a Configuration object. The following example shows the old pattern for creating a configuration object used to connect to a Blob service.

 use WindowsAzure\Common\Configuration;
 use WindowsAzure\Blob\BlobService;
 use WindowsAzure\Blob\BlobSettings;
  
 $config = new Configuration();
 $config->setProperty(BlobSettings::ACCOUNT_NAME, $storage_account_name);
 $config->setProperty(BlobSettings::ACCOUNT_KEY, $storgae_account_key);
 $config->setProperty(BlobSettings::URI, $storage_account_URI);
  
 $blobRestProxy = BlobService::create($config);

New Connection Pattern

The new connection pattern is simpler and involves using an ODBC-like connection string and the new ServiceBuilder factory class. The connection string format for the Blob, Table, and Queue services is this:

 DefaultEndpointsProtocol=[http | https];AccountName=<your storage account name>;AccountKey=<your storage account key>

For the Service Bus Queues and Service Bus Topics services, the connection string format is this:

 Endpoint=[yourEndpoint];SharedSecretIssuer=[yourWrapAuthenticationName];SharedSecretValue=[yourWrapPassword]

Note: Endpoint is usually has this format: https://[yourNamespace].servicebus.windows.net.

After you have created a connection string, you can create a rest proxy object as shown in the example below (which uses the Blob service, but the code of other services is similar).

 use WindowsAzure\Common\ServicesBuilder
  
 $conn_string = "DefaultEndpointsProtocol=http;AccountName=myaccountname;AccountKey=A4HlJzOy156Q6Y+ty6AAXqULxhUeQ+bVP8sjHTX1+wwKBjP+cBcyBrAmGGG6tEFgg8cKNciU/+xG7afG4JNiNw==";
  
 $blobRestProxy = ServicesBuilder::getInstance()->createBlobService($conn_string);

For more information (and examples) on using the storage or service bus services, see PHP Developer Center – How To Guides.

One important feature that is built into this change is the ability to store connection strings anywhere you want. By default, the SDK is configured to look for connection strings that are stored in an environment variable. The connection string is found by using the static getConnectionString method on the CloudConfigurationManager class.  For example, suppose you have stored your connection string in an environment variable called AZURE_STORAGE_CONN_STRING. Then you can create a rest proxy object like this (again, using the Blob service as an example):

 use WindowsAzure\Common\ServicesBuilder;
 use WindowsAzure\Common\CloudConfigurationManager;
  
 $conn_string = CloudConfigurationManager::getConnectionString('AZURE_STORAGE_CONN_STRING');
  
 $blobRestProxy = ServicesBuilder::getInstance()->createBlobService($conn_string);

You can configure the CloudConfigurationManager to look for connection strings in other places by using static CloudConfigurationManager::registerSource method. This requires passing an anonymous function to registerSource method that searches for the expected key. For example:

 CloudConfigurationManager::registerSource(
        'my_source',
        function ($key) use ($expectedKey, $expectedValue)
        {
            if ($key == $expectedKey) {
                return $expectedValue;
            }
        }
 );

You can remove sources by using the CloudConfigurationManager::unRegisterSource method.

Why the change?

The main reason for making this change is to allow for more flexibility when developing applications. The ability to store connection strings in environment variables (or other sources) adds flexibility by itself, but is also makes it easier to build secure applications by allowing you to easily store credentials outside your application code. And, by switching to a connection-string based approach, you can use explicit endpoints for the Blob, Table, and Queue services (details here: Configuring Connection Strings). For example, you could use a connection string like the following:

 BlobEndpoint=myBlobEndpoint;QueueEndpoint=myQueueEndpoint;TableEndpoint=myTableEndpoint;AccountName=myAccountName;AccountKey=myAccountKey

Additionally, you with this change in place, you can extend the ServicesBuilder class to build a custom builder class. For example, you could build MyServicesBuilder that overrides only the createBlobService method so that logging is enabled.

Finally, this change brings to the PHP SDK the same connection patterns that are used in the SDKs for other languages. This (hopefully) makes it easier build Azure applications while moving from language to language (which seems increasingly more common today).

What if I want to continue using the old pattern?

If you have code that uses the old connection pattern, then you will need to use the 0.1.0 or 0.2.0 versions of the PHP Client Libraries for Windows Azure. Starting with version 0.3.0 (today’s release), the libraries will support only the new connection pattern described above. You can specify which version you want to install when you install the libraries using Composer or PEAR. The steps below show you how to specify the 0.2.0 version when installing via Composer or PEAR.

Note: The instructions below show you how to get an older version of the client libraries. If you want the latest version (with the new connection pattern), replace 0.2.0 with 0.3.0.

Install via Composer

1. Install Git.

Note: On Windows, you will also need to add the Git executable to your PATH environment variable.

2. Create a file named composer.json in the root of your project and add the following code to it:

 { 

  "require": { 

  "microsoft/windowsazure": "0.2.0" 

  }, 

  "repositories": [ 

  { "type": "pear", "url": "https://pear.php.net" } 

  ] 

  }

3. Download composer.phar in your project root.

4. Open a command prompt and execute this in your project root

       php composer.phar install

Install as a PEAR package

To install the PHP Client Libraries for Windows Azure as a PEAR package, follow these steps:

1. Install PEAR.

2. Set-up the Windows Azure PEAR channel:

    pear channel-discover pear.windowsazure.com
   

3. Install the PEAR package:

    pear install pear.windowsazure.com/WindowsAzure-0.2.0
   

As always, please send us your feedback, either as comments below or on the Windows Azure SDK for PHP repository on Github.

Thanks.

-Brian