Azure Distribution Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require brainsonic/azure-distribution-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Brainsonic\AzureDistributionBundle\AzureDistributionBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console brainsonic:azure:install
   

   Update config/packages/azure_distribution.yaml with your Azure credentials:

   azure_distribution:
       account_name: 'your-storage-account'
       account_key: 'your-storage-key'
       blob_service: 'https://your-account.blob.core.windows.net'
   

3. First Use Case: Blob Storage Upload a file to Azure Blob Storage:

   use Brainsonic\AzureDistributionBundle\Service\BlobService;
   
   class SomeController
   {
       public function uploadFile(BlobService $blobService)
       {
           $blobService->upload('container-name', 'file.txt', '/path/to/local/file.txt');
       }
   }
   

Implementation Patterns

Core Workflows

1. Blob Storage Operations

   • Upload/Download Files:

     $blobService->upload('container', 'remote-file.txt', '/local/path/file.txt');
     $blobService->download('container', 'remote-file.txt', '/local/path/');
     

   • List Containers/Blobs:

     $blobService->listContainers();
     $blobService->listBlobs('container-name');
     

2. Table Storage (NoSQL)

   • Entity Management:

     $tableService->insert('entity-name', ['PartitionKey' => 'key', 'RowKey' => 'row', 'data' => 'value']);
     $tableService->get('entity-name', 'key', 'row');
     

3. Queue Storage

   • Message Handling:

     $queueService->createQueue('queue-name');
     $queueService->sendMessage('queue-name', 'message-data');
     $queueService->getMessages('queue-name', 10);
     

Integration Tips

• Dependency Injection: Use services directly via constructor injection (e.g., BlobService, TableService).
• Event Listeners: Extend functionality by subscribing to azure.distribution.* events (e.g., post-upload hooks).
• Configuration Overrides: Override default config in config/packages/azure_distribution.yaml for environment-specific settings (e.g., staging vs. production).

Gotchas and Tips

Common Pitfalls

1. Authentication Errors

   • Ensure account_name and account_key are correct and have the right permissions (e.g., Storage Blob Data Contributor).
   • Validate keys via Azure Portal under Access Keys.

2. Container/Blob Existence

   • Containers must be created explicitly (Azure Blob Storage doesn’t auto-create them):

     $blobService->createContainer('container-name', 'public'); // 'public' for public access
     

   • Check existence before operations:

     if (!$blobService->containerExists('container-name')) { ... }
     

3. CORS Issues

   • If accessing blobs from a web app, configure CORS rules in Azure Portal or via SDK:

     $blobService->setCorsRules('container-name', [
         ['AllowedOrigins' => ['*'], 'AllowedMethods' => ['GET', 'PUT']],
     ]);
     

Debugging Tips

• Enable Logging: Add to config/packages/monolog.yaml:

  handlers:
      azure:
          type: stream
          path: "%kernel.logs_dir%/%azure_distribution%.log"
          level: debug
          channels: ["azure"]
  

• SDK Debugging: Use the underlying Azure SDK’s debug mode:

  $blobService->getClient()->getBlobRestProxy()->setDebug(true);
  

Extension Points

1. Custom Services Extend the base services (e.g., BlobService) by creating a decorator:

   use Brainsonic\AzureDistributionBundle\Service\BlobServiceInterface;
   
   class CustomBlobService implements BlobServiceInterface
   {
       private $decorated;
   
       public function __construct(BlobService $decorated) { $this->decorated = $decorated; }
   
       public function upload($container, $blob, $filePath)
       {
           // Pre/post-processing logic
           $this->decorated->upload($container, $blob, $filePath);
       }
   }
   

   Register the decorator in services.yaml:

   services:
       Brainsonic\AzureDistributionBundle\Service\BlobService: '@custom_blob_service'
       custom_blob_service:
           class: App\Service\CustomBlobService
           arguments: ['@azure_distribution.blob_service']
   

2. Event Subscribers Listen for events like azure.distribution.blob.uploaded:

   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   use Brainsonic\AzureDistributionBundle\Event\BlobEvent;
   
   class AzureEventSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents()
       {
           return [
               'azure.distribution.blob.uploaded' => 'onBlobUploaded',
           ];
       }
   
       public function onBlobUploaded(BlobEvent $event)
       {
           // Custom logic (e.g., log, notify)
       }
   }
   

3. Azure SDK Updates

   • Monitor the WindowsAzure PHP SDK for breaking changes.
   • Pin the SDK version in composer.json to avoid unexpected updates:

     "require": {
         "windowsazure/azure-sdk-for-php": "~0.5.0"
     }