Windowsazure Laravel Package

Getting Started

Minimal Setup for Daily Use

1. Installation:

   composer require microsoft/windowsazure
   

   Add to composer.json:

   "require": {
       "microsoft/windowsazure": "^0.5"
   }
   

2. Autoload & Connection:

   require_once __DIR__ . '/vendor/autoload.php';
   use WindowsAzure\Common\ServicesBuilder;
   use WindowsAzure\Common\ServiceException;
   

3. First Use Case (Blob Storage):

   $connectionString = 'DefaultEndpointsProtocol=https;AccountName=YOUR_ACCOUNT;AccountKey=YOUR_KEY';
   $blobService = ServicesBuilder::getInstance()->createBlobService($connectionString);
   
   // Upload a file
   $file = fopen('local-file.txt', 'r');
   $blobService->createBlockBlob('container-name', 'blob-name', $file);
   fclose($file);
   

Implementation Patterns

Core Workflows

1. Service Initialization:

   $connectionString = env('AZURE_STORAGE_CONNECTION_STRING');
   $services = ServicesBuilder::getInstance();
   $blobService = $services->createBlobService($connectionString);
   $tableService = $services->createTableService($connectionString);
   $queueService = $services->createQueueService($connectionString);
   

2. CRUD Operations (Blob Example):

   // Create container (idempotent)
   $blobService->createContainer('my-container');
   
   // Upload blob (stream or string)
   $blobService->createBlockBlob('my-container', 'blob.txt', fopen('local.txt', 'r'));
   
   // List blobs
   $blobs = $blobService->listBlobs('my-container');
   foreach ($blobs->getBlobs() as $blob) {
       echo $blob->getName();
   }
   
   // Delete blob
   $blobService->deleteBlob('my-container', 'blob.txt');
   

3. Table Operations:

   // Insert entity
   $entity = new \MicrosoftAzure\Storage\Table\Models\Entity();
   $entity->setPartitionKey('partition1');
   $entity->setRowKey('row1');
   $entity->addProperty('name', \MicrosoftAzure\Storage\Table\Models\EdmType::STRING, 'Test');
   $tableService->insertEntity('table-name', $entity);
   
   // Query entities
   $filter = "PartitionKey eq 'partition1'";
   $result = $tableService->queryEntities('table-name', $filter);
   foreach ($result->getEntities() as $entity) {
       echo $entity->getProperty('name');
   }
   

4. Queue Operations:

   // Create queue
   $queueService->createQueue('my-queue');
   
   // Send message
   $queueService->createMessage('my-queue', 'Hello Azure!');
   
   // Get messages
   $messages = $queueService->getMessages('my-queue');
   foreach ($messages as $message) {
       echo $message->getMessage();
       $queueService->deleteMessage('my-queue', $message->getId(), $message->getPopReceipt());
   }
   

5. Error Handling:

   try {
       $blobService->createBlockBlob('container', 'blob.txt', fopen('file.txt', 'r'));
   } catch (ServiceException $e) {
       log::error("Azure Error: {$e->getCode()}: {$e->getMessage()}");
       // Handle specific HTTP codes (e.g., 404 for missing container)
       if ($e->getCode() === 404) {
           $blobService->createContainer('container');
       }
   }
   

Integration Tips

1. Environment Variables: Store connection strings in .env:

   AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
   AZURE_SERVICE_BUS_CONNECTION_STRING=Endpoint=sb://...;SharedSecretIssuer=...;SharedSecretValue=...
   

2. Dependency Injection: Bind services in Laravel’s AppServiceProvider:

   public function register()
   {
       $this->app->singleton('azure.blob', function ($app) {
           return ServicesBuilder::getInstance()->createBlobService(env('AZURE_STORAGE_CONNECTION_STRING'));
       });
   }
   

3. Batch Operations: Use TableBatch for bulk inserts/updates:

   $batch = new \MicrosoftAzure\Storage\Table\Models\TableBatch();
   $batch->insertEntity($entity1);
   $batch->insertEntity($entity2);
   $tableService->submitBatch('table-name', $batch);
   

4. Async Processing: Offload queue processing to a Laravel queue worker:

   Queue::push(new ProcessAzureQueueJob('my-queue'));
   

5. Logging: Wrap SDK calls in logging middleware:

   $start = microtime(true);
   $blobService->createBlockBlob(...);
   Log::debug("Blob upload took: " . (microtime(true) - $start) . "s");
   

Gotchas and Tips

Pitfalls

1. Connection Strings:

   • Emulator vs. Live: Use UseDevelopmentStorage=true for local testing.
   • Service Bus: Ensure SharedSecretIssuer and SharedSecretValue are correct (not AccountKey).

2. Entity Limits:

   • Table entities must have PartitionKey and RowKey.
   • Blob names are case-sensitive and limited to 1024 chars.

3. Error Codes:

   • 404: Resource not found (e.g., container/blob missing).
   • 409: Conflict (e.g., duplicate entity).
   • 500: Server error (retry with exponential backoff).

4. Timeouts:

   • Default timeout is 30s. Increase for large operations:

     $blobService->setTimeout(60); // 60 seconds
     

5. Deprecation:

   • Media Services: Requires Azure AD token authentication (complex setup).
   • Service Management: Uses outdated API (2011-10-01). Avoid unless legacy support is needed.

Debugging Tips

1. Enable Debugging:

   ServicesBuilder::getInstance()->withLogger(new \Monolog\Logger('azure'), \Monolog\Logger::DEBUG);
   

2. Check HTTP Headers: Use Guzzle middleware to inspect requests:

   $client = new \GuzzleHttp\Client(['debug' => true]);
   

3. Common Fixes:

   • Permission Denied (403): Verify AccountKey or SAS token.
   • Slow Performance: Use setTimeout() or optimize batch sizes.
   • Entity Not Found: Ensure PartitionKey/RowKey match exactly.

Extension Points

1. Custom Metadata: Add metadata to blobs/containers/queues:

   $options = new \WindowsAzure\Blob\Models\CreateContainerOptions();
   $options->addMetaData('custom-key', 'custom-value');
   $blobService->createContainer('container', $options);
   

2. SAS Tokens: Generate shared access signatures for delegated access:

   $sasToken = $blobService->generateSharedAccessSignature(
       'container',
       'blob.txt',
       'r', // read permission
       new \DateTime('+1 hour')
   );
   

3. Event Subscriptions: Use Azure Storage Events (via Event Grid) for async notifications:

   // Requires additional setup with Azure Event Grid
   $eventGridTopic->sendEvent(new BlobCreatedEvent($blob));
   

4. Retry Logic: Implement exponential backoff for transient failures:

   $retryPolicy = new \WindowsAzure\Common\RetryPolicy\ExponentialBackoffPolicy();
   $blobService->setRetryPolicy($retryPolicy);
   

5. Local Testing: Use the Azure Storage Emulator (requires Docker or local install):

   docker run -p 10000:10000 mcr.microsoft.com/azure-storage/azurite
   

   Connection string: UseDevelopmentStorage=true.