Azure Storage Blob Laravel Package

Getting Started

This package (microsoft/azure-storage-blob) is deprecated and will be retired on 17 March 2024. Before starting, strongly consider migrating to the modern azure/azure-storage-blob package (part of the Azure SDK for PHP), which is actively maintained and supports current Azure Storage features.

If you must use this legacy package (e.g., legacy app maintenance), begin with:

1. Install via Composer:

   composer require microsoft/azure-storage-blob
   

2. Instantiate a client with a valid connection string or SAS token:

   require 'vendor/autoload.php';
   use MicrosoftAzure\Storage\Blob\BlobRestProxy;
   
   $connectionString = 'DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...';
   $blobClient = BlobRestProxy::createBlobService($connectionString);
   

3. Perform a basic operation — list containers:

   $containers = $blobClient->listContainers();
   foreach ($containers->getContainers() as $container) {
       echo $container->getName() . PHP_EOL;
   }
   

First reference: samples/ (despite repo deprecation, sample patterns remain instructive for this package).

Implementation Patterns

Core Workflows

• Authentication & Client Setup
  Use connection strings for dev/testing; prefer SAS or OAuth (via createBlobServiceWithTokenCredential) in production. OAuth support was added in v1.4.0.

• Blob Upload/Download Streams
  Avoid loading large files into memory:

  // Upload from stream
  $handle = fopen('largefile.zip', 'r');
  $blobClient->createBlockBlob($containerName, 'largefile.zip', $handle);
  
  // Download to stream
  $result = $blobClient->getBlob($containerName, 'largefile.zip');
  $stream = fopen('php://output', 'r+');
  $result->getContentStream()->passthru($stream);
  

• Batch Operations via Middlewares
  Leverage middleware for retries, logging, or telemetry:

  $logMiddleware = function (callable $handler) {
      return function ($request, $options) use ($handler) {
          // log $request
          return $handler($request, $options);
      };
  };
  
  $client = BlobRestProxy::createBlobService($connStr, [
      'middlewares' => [$logMiddleware]
  ]);
  

• SAS Token Generation
  Generate readable/writable SAS URLs for client-side direct access:

  use MicrosoftAzure\Storage\Blob\Models\BlobSharedAccessSignatureHelper;
  
  $sasHelper = new BlobSharedAccessSignatureHelper($connStr);
  $sasUrl = $sasHelper->generateBlobServiceSharedAccessSignatureToken(
      $containerName,
      'report.pdf',
      'r', // permissions
      (new \DateTime())->modify('+1 hour')
  );
  

Integration Tips

• Laravel-like Services: Wrap BlobRestProxy in a singleton service/provider with lazy client initialization.
• Testing: Inject BlobRestProxy via dependency injection; mock it or use MockHandler (Guzzle) for unit tests.
• ** Guzzle 6/7 Compatibility**: v1.5.2+ supports both; ensure your project’s Guzzle version matches.

Gotchas and Tips

• 🚨 Deprecation & Retirement Deadline
  This package is officially retired. After March 2024, it will no longer receive updates, security fixes, or support. Start migration planning now using the migration guide.

• Certificate Verification Issues
  On Windows or misconfigured systems, you’ll hit Unable to get local issuer certificate. Fix via php.ini:

  curl.cainfo = "/path/to/cacert.pem"
  

  Or inject option on client creation:

  $options = ['http' => ['verify' => '/path/to/cacert.pem']];
  $client = BlobRestProxy::createBlobService($connStr, $options);
  

• 64-bit & Large Files
  Blobs >2GB or 64-bit integer operations require:

  • PHP 7+ 64-bit build (php -r "echo PHP_INT_SIZE;" → 8)
  • php_fileinfo.dll, php_mbstring.dll, php_openssl.dll enabled.

• Case-Sensitive Query Parameters
  Prior to v1.5.1, query param keys were uppercased inconsistently. Upgrade to avoid encoding bugs with special characters in SAS tokens.

• Blob Names with “0”
  Older versions failed to upload blobs named '0'. Fixed in v1.3.0. Ensure you’re on ≥v1.3.0 if using numeric blob names.

• Proxy & Middleware Conflicts
  Global middleware (set in client options) run after request-level middleware. Set request-specific middlewares in call options, not in $_options, to avoid ordering surprises.

• Documentation Is Legacy
  API docs at https://azure.github.io/azure-storage-php reflect this outdated package. For modern equivalents, see Azure Storage Blob SDK for PHP docs.