Laravel Azure Blob Storage Laravel Package

Getting Started

• Require the package and confirm the transitive Flysystem adapter version: composer require <this-package> then composer show azure-oss/storage-blob-flysystem — 1.3.0 requires ^2.0, so a stale composer.lock pinned to 1.x is the first thing to check.
• Publish/register the disk in config/filesystems.php with 'driver' => 'azure', plus container name and credentials (connection string, account key, or SAS token) sourced from .env. Never inline keys; keep them in config and reference via env() only inside config files.
• First use case to smoke-test: upload a private blob and hand out a time-limited link.

  Storage::disk('azure')->putFileAs('invoices', $request->file('invoice'), "{$invoice->id}.pdf");
  $url = Storage::disk('azure')->temporaryUrl("invoices/{$invoice->id}.pdf", now()->addMinutes(15));
  

• Read the package README's config table first, then the azure-oss upgrade guide linked in the release notes — the package API is unchanged in 1.3.0, but the adapter underneath is not.
• Add a Storage::fake('azure') test for the upload path before wiring anything into production code.

Implementation Patterns

• Disk-per-container or disk-per-purpose. Define distinct disks (azure, azure-public, azure-archive) rather than passing container names at call sites; keeps credentials and visibility policy in one place and makes Storage::fake() swaps trivial.
• Prefer temporaryUrl() over public containers for anything user-generated. 1.3.0 fixes percent-encoding of the SAS expiry timestamp, so URLs now generate correctly for all expiry values; this is the supported path for private blobs.
• Stream large files with put()/writeStream() and Storage::disk('azure')->readStream() rather than get() into memory. Azure blobs can be multi-GB; the Flysystem adapter handles chunked uploads for you.
• Wrap storage calls in a small service or repository (e.g. DocumentStorage) that exposes store(), url(), delete(). This is your seam for swapping disks in tests and for the upcoming adapter upgrade.
• Queue anything slow. Uploads of large files or bulk copies belong in a job; the storage layer is I/O-bound and will otherwise eat request time.
• Normalise paths once. Build blob keys from a single helper (prefix + UUID + extension) so you never concatenate user input into a path; Azure treats / as a virtual directory but rejects/normalises some characters.
• Test with Storage::fake() for logic, and keep one integration test (marked or gated by env) that hits a real container, since SAS signing behaviour cannot be faked.
• CI hygiene: after bumping to 1.3.0 run composer update --with-dependencies and then composer why azure-oss/storage-blob-flysystem to confirm a single 2.x version is resolved.

Gotchas and Tips

• The breaking change is transitive, not in this package. azure-oss/storage-blob-flysystem ^2.0 depends on an azure-oss/storage* 2.x line that removed exception classes. If your app composer requires any azure-oss/storage* package directly, or your catch blocks reference its old exception classes, they will silently stop matching. Grep for Azure\\Storage\\ in app/ and tests/ before deploying.
• Catch the right layer. Prefer Flysystem's League\Flysystem\UnableToReadFile / UnableToWriteFile / FilesystemException interfaces over adapter-specific exceptions — they survive this kind of dependency bump and are what the Laravel Storage facade surfaces.
• Temporary URL assertions may break. Because SAS expiry timestamps are now percent-encoded, any test asserting an exact temporaryUrl() string, or any client/partner that pre-computes or regex-validates signed URLs, needs re-checking. Assert on host/container/path and se= presence instead of full-string equality.
• Clock skew kills SAS links. Azure allows only a few minutes of skew; if temporaryUrl() links fail immediately in local dev, check the container/app clock and keep expiry margins generous (≥5 minutes).
• temporaryUrl() requires a credential that can sign. A connection string or account key works; a read-only SAS token pasted into config generally cannot mint new SAS URLs — use a stored SAS with sufficient expiry, or a managed identity/account key.
• Visibility is container-level in Azure. 'visibility' => 'public' in the disk config will not make a private container public; don't rely on it as an access-control switch.
• Containers are not created for you. Provision them in IaC or a one-off artisan command; a typo in the container name surfaces as an opaque 404/ContainerNotFound at first write, not at boot.
• Debugging order: config('filesystems.disks.azure') → Storage::disk('azure')->allFiles() (a minimal list call isolates auth from write issues) → adapter version via composer show → Azure storage logs.
• Extension points to reach for before forking: a custom Flysystem adapter or a decorated disk registered in a service provider, and Storage::extend() for a driver that adds prefixing/retry logic. Keep such customisations thin — 1.3.0 shows the adapter layer is where churn happens.