Storage Blob Symfony Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require azure-oss/storage-blob-symfony
   

   Ensure league/flysystem-bundle is also installed (required dependency).

2. Configure Flysystem Add Azure Blob Storage configuration to config/packages/flysystem.yaml:

   flysystem:
       storages:
           azure_blob:
               adapter: azure_oss
               options:
                   service: 'azure://<connection>'
                   bucket: 'your-container-name'
                   endpoint: 'https://<account>.blob.core.windows.net'
                   credentials:
                       key: '%env(AZURE_STORAGE_KEY)%'
                       secret: '%env(AZURE_STORAGE_SECRET)%'
   

3. First Use Case: Upload a File Inject the Flysystem service and use it like any other Flysystem adapter:

   use League\Flysystem\FilesystemInterface;
   
   public function uploadFile(FilesystemInterface $storage)
   {
       $storage->write('path/to/file.txt', 'file contents');
   }
   

Implementation Patterns

Common Workflows

1. Service Configuration Reuse the same connection across multiple storages by defining a service key in flysystem.yaml:

   flysystem:
       storages:
           primary_blob:
               adapter: azure_oss
               service: 'azure://default'
           backup_blob:
               adapter: azure_oss
               service: 'azure://default'
   

2. Environment-Specific Config Use Symfony’s %env% for dynamic values (e.g., endpoint, credentials):

   options:
       endpoint: '%env(AZURE_BLOB_ENDPOINT)%'
   

3. Integration with Laravel If using Laravel, alias the Symfony service in config/app.php:

   'filesystems' => [
       'disks' => [
           'azure' => [
               'driver' => 'flysystem',
               'adapter' => 'azure_oss',
               'options' => [
                   'service' => 'azure://default',
                   'bucket' => env('AZURE_CONTAINER'),
               ],
           ],
       ],
   ],
   

4. Streaming Large Files Leverage Flysystem’s streaming capabilities for large uploads/downloads:

   $storage->writeStream('large-file.zip', fopen('local/path.zip', 'r'));
   

5. Metadata Handling Set custom metadata during upload:

   $storage->write(
       'file.txt',
       'contents',
       [
           'custom-meta' => 'value',
           'content-type' => 'text/plain',
       ]
   );
   

Gotchas and Tips

Pitfalls

1. Connection String Format The service key expects a URI-like string (e.g., azure://default). Ensure it matches the configured connection in azure-oss/storage-blob-flysystem.

2. Credentials Handling Avoid hardcoding secrets. Use Symfony’s %env% or Laravel’s .env:

   credentials:
       key: '%env(AZURE_STORAGE_KEY)%'
       secret: '%env(AZURE_STORAGE_SECRET)%'
   

3. Endpoint Overrides If using Azure’s public endpoint (core.windows.net), omit the endpoint key. For private endpoints, specify the full URL.

4. CORS and Public Access Ensure the Azure Storage container has the correct CORS rules or public access level (blob or container). Private containers require signed URLs for direct access.

5. Flysystem Bundle Version Ensure compatibility with league/flysystem-bundle (v2.x+). Check the package’s composer.json for constraints.

Debugging

• Connection Errors: Verify endpoint, credentials, and bucket (container) names. Use Azure Storage Explorer to validate container existence.
• Permission Issues: Ensure the storage account key has Storage Blob Data Contributor or equivalent permissions.
• Logging: Enable Symfony’s monolog to debug Flysystem operations:

  monolog:
      handlers:
          main:
              level: debug
  

Extension Points

1. Custom Adapters Extend the underlying azure-oss/storage-blob-flysystem adapter for custom logic (e.g., pre/post-upload hooks).

2. Event Listeners Use Symfony’s event system to intercept file operations:

   // src/EventListener/AzureBlobListener.php
   public function onFileUploaded(FilesystemEvent $event) {
       if ($event->getStorage()->getAdapter() instanceof AzureOssAdapter) {
           // Custom logic
       }
   }
   

3. Flysystem Plugins Integrate plugins like league/flysystem-aws-s3-v4 for shared functionality (e.g., caching, checksums).

4. Testing Mock the FilesystemInterface in tests:

   $storage = $this->createMock(FilesystemInterface::class);
   $storage->method('write')->willReturn(true);