Azure Distribution Bundle Laravel Package

Getting Started

Minimal Steps

1. Verify Active Fork: Since the original repo is unmaintained, check the active fork for compatibility and updates. Ensure your Symfony version (5.x/6.x) aligns with the fork’s support.
2. Installation:

   composer require brainsonic/azure-distribution-bundle
   

   Add the bundle to config/bundles.php:

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

3. Configure Azure SDK: Add Azure credentials to .env:

   AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=..."
   AZURE_WEBSITE_NAME="your-app-name"
   

4. First Use Case: Deploy a static file to Azure Blob Storage via a controller:

   use Brainsonic\AzureDistributionBundle\Service\AzureStorageService;
   
   class FileController extends AbstractController {
       public function uploadFile(AzureStorageService $azureStorage): Response {
           $azureStorage->uploadFile(
               'my-container',
               'path/to/file.txt',
               fopen('local-file.txt', 'r')
           );
           return new Response('File uploaded!');
       }
   }
   

Implementation Patterns

Core Workflows

1. Azure Blob Storage Integration:

   • Upload/Download Files: Use AzureStorageService for direct file operations:

     $azureStorage->uploadFile('container', 'blob-name', $fileStream);
     $blobContent = $azureStorage->downloadFile('container', 'blob-name');
     

   • List Containers/Blobs:

     $containers = $azureStorage->listContainers();
     $blobs = $azureStorage->listBlobs('container');
     

2. Azure Websites Deployment:

   • Kudu API Interaction: Use AzureWebsiteService to trigger deployments via Kudu (Azure’s deployment engine):

     $websiteService->deployViaKudu(
         'your-app-name',
         'path/to/deploy.zip',
         'https://your-app-name.scm.azurewebsites.net/api/zipdeploy'
     );
     

   • Composer-Based Deployments: For PHP-based deployments, extend the AzureComposerDeployer to customize post-deploy hooks (e.g., cache warming).

3. Environment Awareness:

   • Detect Azure Context: Use AzureEnvironmentDetector to check if the app is running on Azure:

     if ($detector->isOnAzure()) {
         // Azure-specific logic (e.g., blob fallback for assets)
     }
     

Integration Tips

• Symfony Cache Adapter: Configure Azure Blob Storage as a cache backend in config/packages/cache.yaml:

  framework:
      cache:
          app: azure_blob
          pools:
              azure_blob:
                  adapter: cache.adapter.azure_blob
                  provider: 'azure://DefaultEndpointsProtocol=https;AccountName=...'
  

• Event Listeners: Trigger actions on Azure-specific events (e.g., blob uploads):

  // config/services.yaml
  Brainsonic\AzureDistributionBundle\EventListener\AzureBlobUploadListener:
      tags:
          - { name: kernel.event_listener, event: azure.blob.uploaded, method: onBlobUploaded }
  

Gotchas and Tips

Pitfalls

1. Deprecated SDK:

   • The original bundle relied on the WindowsAzure SDK for PHP, which is deprecated. The fork may use Microsoft’s newer SDK (microsoft/azure-storage-blob-php). Verify compatibility:

     composer show microsoft/azure-storage-blob-php
     

   • Fix: Update dependencies or wrap legacy calls in a compatibility layer.

2. Kudu API Rate Limits:

   • Azure’s Kudu API has rate limits. Handle 429 Too Many Requests gracefully:

     try {
         $websiteService->deployViaKudu(...);
     } catch (AzureHttpException $e) {
         if ($e->getCode() === 429) {
             sleep(5); // Retry after delay
         }
     }
     

3. Connection String Security:

   • Hardcoding AZURE_STORAGE_CONNECTION_STRING in .env exposes secrets. Use Azure Key Vault or Symfony’s parameter encryption:

     # config/packages/security.yaml
     security:
         encryption_key: '%env(AZURE_ENCRYPTION_KEY)%'
     

4. Blob Leases:

   • Concurrent writes to the same blob can cause conflicts. Use leases for critical operations:

     $azureStorage->acquireLease('container', 'blob-name', 60); // 60-second lease
     

Debugging

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

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

  Then enable logging in your service:

  $azureStorage->setLogger($logger);
  

• Test Locally with Azure Storage Emulator: Use the Azure Storage Emulator for development:

  AZURE_STORAGE_CONNECTION_STRING="UseDevelopmentStorage=true"
  

Extension Points

1. Custom Blob Metadata: Extend AzureBlob to add custom metadata:

   class CustomAzureBlob extends \Brainsonic\AzureDistributionBundle\Model\AzureBlob {
       public function setCustomMetadata(array $metadata): void {
           $this->metadata['custom'] = $metadata;
       }
   }
   

2. Pre-Signed URLs: Generate time-limited URLs for blob access:

   $azureStorage->generateSasUrl('container', 'blob-name', '+1 hour');
   

3. Webhook Integration: Use Azure Event Grid to trigger Symfony events on blob changes. Example listener:

   class AzureEventGridListener {
       public function onEventGridMessage(array $event): void {
           $this->eventDispatcher->dispatch(
               new AzureBlobEvent($event['data']['blob']),
               AzureBlobEvent::UPLOADED
           );
       }
   }