Storage Blob Flysystem Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require azure-oss/storage-blob-flysystem-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Azure\Storage\Blob\FlysystemBundle\AzureStorageBlobFlysystemBundle::class => ['all' => true],
   ];
   

2. Configuration Define Azure Blob Storage credentials in .env:

   AZURE_STORAGE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
   AZURE_STORAGE_CONTAINER="my-container"
   

3. First Use Case Inject the adapter in a service:

   use Azure\Storage\Blob\FlysystemBundle\AzureStorageBlobFlysystemAdapter;
   
   class MyService {
       public function __construct(
           private AzureStorageBlobFlysystemAdapter $adapter
       ) {}
   
       public function uploadFile(string $path, string $content) {
           $this->adapter->write($path, $content);
       }
   }
   

Implementation Patterns

Common Workflows

1. File Operations

   // Upload
   $adapter->write('folder/file.txt', 'content');
   
   // Download
   $content = $adapter->read('folder/file.txt');
   
   // Delete
   $adapter->delete('folder/file.txt');
   

2. Directory Handling

   // List files
   $files = $adapter->listContents('folder/', false);
   
   // Create directory (implicit via write)
   $adapter->write('folder/subfolder/file.txt', 'content');
   

3. Metadata & Visibility

   // Set metadata
   $adapter->setMetadata('file.txt', ['custom' => 'value']);
   
   // Set visibility (private/public)
   $adapter->setVisibility('file.txt', 'public');
   

Integration Tips

• Symfony Filesystem Use with league/flysystem-bundle for seamless integration:

  # config/packages/league_flysystem.yaml
  flysystem:
      storages:
          azure:
              adapter: azure_storage_blob
  

• Event Dispatching Listen to league.flysystem.* events for post-upload actions:

  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  use League\Flysystem\Event\FileUploaded;
  
  class UploadSubscriber implements EventSubscriberInterface {
      public static function getSubscribedEvents() {
          return [FileUploaded::class => 'onUpload'];
      }
  
      public function onUpload(FileUploaded $event) {
          // Process uploaded file
      }
  }
  

Gotchas and Tips

Pitfalls

1. Connection String Security

   • Never hardcode AZURE_STORAGE_CONNECTION_STRING in source. Use .env or Symfony’s ParameterBag.
   • Restrict permissions via Azure RBAC (e.g., Storage Blob Data Contributor).

2. Path Handling

   • Azure Blob Storage is case-sensitive. Ensure paths match exactly (e.g., folder/File.txt ≠ folder/file.txt).
   • Trailing slashes in paths may cause issues. Normalize with:

     $path = rtrim($path, '/');
     

3. Large File Uploads

   • Default chunk size (4MB) may fail for large files. Configure in config/packages/azure_storage_blob_flysystem.yaml:

     azure_storage_blob:
         options:
             chunk_size: 16777216 # 16MB
     

Debugging

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

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

  Then enable the channel in config/packages/azure_storage_blob_flysystem.yaml:

  azure_storage_blob:
      options:
          logger: true
  

• Common Errors

  Error	Solution
  InvalidConnectionString	Verify .env and connection string format.
  ContainerNotFound	Ensure the container exists in Azure Portal or create it programmatically.
  AccessDenied	Check Azure Storage account keys or SAS tokens.

Extension Points

1. Custom Metadata Extend the adapter to add custom metadata handlers:

   $adapter->extend('setCustomMetadata', function ($path, array $metadata) {
       $this->client->getBlobProperties($this->container, $path);
       // Modify metadata via Azure SDK
   });
   

2. Event-Driven Workflows Use Symfony’s event system to trigger actions on file operations:

   // config/packages/framework.yaml
   framework:
       event_dispatcher:
           listeners:
               'League\Flysystem\Event\FileUploaded': [App\Listener\AzureUploadListener]
   

3. Fallback Storage Implement a fallback adapter for offline scenarios:

   use League\Flysystem\Filesystem;
   use League\Flysystem\Storage\StorageInterface;
   
   class FallbackAdapter implements StorageInterface {
       public function write($path, $contents, Config $config) {
           // Fallback logic (e.g., local filesystem)
       }
       // ... other methods
   }