Flysystem Azure Blob Storage Laravel Package

Getting Started

1. Install via Composer: Run composer require league/flysystem-azure-blob-storage — this pulls in Flysystem v3+ and Microsoft’s microsoft/azure-storage-blob SDK (v1.1+).
2. Prerequisites: Ensure you have an Azure Storage Account (v2 GP) and valid credentials (connection string, account name + key, or SAS token).
3. Initial setup: Instantiate the adapter and filesystem in a single file or artisan command to verify connectivity:

   $client = BlobRestProxy::createBlobService(env('AZURE_STORAGE_CONNECTION_STRING'));
   $adapter = new AzureBlobStorageAdapter($client, 'my-container');
   $filesystem = new Filesystem($adapter);
   // Test: Create container first if missing
   $client->createContainer('my-container');
   $filesystem->write('test.txt', 'Hello Azure');
   

4. Verify permissions: Ensure the account used has Storage Blob Data Contributor or equivalent RBAC on the container — connection strings with keys work out-of-the-box, but managed identity/SAS require extra setup (see Gotchas).

Implementation Patterns

• Laravel integration: Extend the Storage facade with a custom driver:

  // app/Providers/AppServiceProvider.php
  public function boot()
  {
      Storage::extend('azure', function ($app, $config) {
          $client = BlobRestProxy::createBlobService($config['connection_string']);
          return new Filesystem(new AzureBlobStorageAdapter($client, $config['container']));
      });
  }
  

  Then use Storage::disk('azure')->put('file.txt', $content) seamlessly.
• Environment-driven config: Store sensitive values in .env and reference in config/filesystems.php:

  'azure' => [
      'driver' => 'azure',
      'connection_string' => env('AZURE_STORAGE_CONNECTION_STRING'),
      'container' => env('AZURE_CONTAINER', 'default'),
      'visibility' => env('AZURE_VISIBILITY', 'private'), // Maps to container ACL
  ]
  

• Cost/performance tuning: For media assets, check blob tier via $filesystem->getVisibility($path)['visibility'] and migrate using ->setVisibility($path, 'public-read') (maps to Container ACL) or Azure SDK tier operations ($client->setBlobTier(...)).
• SAS token handling: Generate time-limited access URLs with generateBlobSasUri():

  $sas = BlobSharedAccessSignatureHelper::generateBlobSasUri(
      $client, 'my-container', 'file.jpg', 
      SharedAccessBlobPolicy::PERMISSION_READ, 
      now()->addDay()
  );
  

Gotchas and Tips

• Container naming rules: Names must be 3–63 chars, lowercase, alphanumeric + hyphens only — no consecutive hyphens, no leading/trailing hyphens. Validate before usage (preg_match('/^[a-z0-9][a-z0-9-]*[a-z0-9]$/', $name)).
• Visibility ≠ S3: Azure has no bucket-level ACLs like S3. Visibility::PUBLIC requires the container ACL to be Container (not Blob or Private) — configure via $client->setContainerAcl($name, 'container').
• Path encoding: Avoid ?, #, % in filenames. Azure URL-encodes paths automatically, but inconsistent encoding can cause 404 Not Found errors — normalize filenames before operations.
• Client lifecycle: Never instantiate BlobRestProxy per operation in loops/facades — bind it as a singleton in Laravel’s service container ($this->app->singleton(BlobRestProxy::class, ...)).
• Error normalization: Wrap Flysystem calls in try/catch blocks for ServiceException (e.g., container missing) or OperationTimedOutException — Azure SDKs lack consistent retry logic. Consider adding a retry middleware:

  $filesystem = new Filesystem(
      new RetryMiddleware($adapter, 3, 200)
  );
  

• SDK version warning: This adapter depends on the deprecated microsoft/azure-storage-blob (REST-based). The newer azure/azure-storage-blob (guzzle-based) is incompatible — avoid upgrading it unless you patch the adapter manually.