Storage Blob Laravel Package

Product Decisions This Supports

• Build vs. buy for object storage integration. The package covers the full Azure Blob REST surface — containers, blobs, block uploads, leases, snapshots, versions, soft-delete restore, index tags, and SAS signing. That is months of plumbing you do not have to write, test, or maintain against an evolving Azure API.
• Cloud/provider strategy. It sits under a Laravel/Flysystem driver (azure-oss/storage-blob-laravel / -flysystem), so choosing Azure becomes a configuration decision rather than an application rewrite. This supports a "storage-agnostic app, Azure-primary infrastructure" position.
• Roadmap unlocks. Enables concrete features that were previously blocked or expensive: user-generated media and avatars, document/contract repositories, report and export delivery, call-recording or asset archiving, signed-URL delivery of private files, and lifecycle-based tiering for cost control.
• Security and compliance posture.
  • Passwordless auth via Microsoft Entra ID (azure-oss/identity) versus long-lived shared keys — a real security decision, not just a technical one.
  • Time-limited SAS tokens let browsers fetch assets directly from Azure instead of through your app servers (removes an egress/proxy hop and a class of auth bugs).
  • Soft-delete, snapshots, and versions give you a defensible answer to "can we recover an accidentally deleted customer file?" and to retention requirements.
• Concurrency and data-integrity decisions. ETag, date, and lease conditions are first-class, so you can decide on optimistic locking, single-writer coordination, or distributed leases for background jobs — instead of hand-rolling advisory locks in Redis/DB.
• Cost modeling. Large-upload block sizing, lifecycle tiering, and SAS-direct delivery are all levers this package exposes; pricing conversations can be grounded in actual upload/download patterns rather than guesses.
• Integration surface choice. Standard CRUD should go through the Laravel filesystem driver; the raw SDK is justified only where you need leases, tags, snapshots, versions, or async server-side copy. That is a scoping decision worth making once, centrally, rather than per team.
• Vendor-risk decision. Small adoption (single-digit GitHub stars, zero dependents), community-maintained, and explicitly not affiliated with or endorsed by Microsoft. That is a governance input: are you comfortable being an early adopter, or does this workload require a commercially supported SDK?

When to Consider This Package

Adopt when:

• The application is Laravel/PHP and Azure Blob Storage is already, or is about to become, the system of record for files.
• You need more than put/get: leases, snapshots, blob versions, undelete, index-tag queries, async copy, or programmatic SAS generation. This is where the package earns its place over a thin filesystem driver.
• You want passwordless authentication via Entra ID / managed identity rather than shipping storage account keys into app config.
• You need local development parity — Azurite support means engineers can run the full storage path on a laptop.
• You are migrating from microsoft/azure-storage-blob and want a documented upgrade path (a migration guide exists).
• You are on Guzzle 7 or 8 (2.3.0 added 8 support), so it will not pin your HTTP stack.

Look elsewhere when:

• You only need Storage::put() / Storage::get() semantics. Use the Flysystem/Laravel driver instead — this SDK is lower-level and you would be writing glue for no benefit.
• Procurement requires a vendor-supported SDK with an SLA. This project states plainly that it is independent and unsupported by Microsoft; do not pitch it as an official SDK.
• The workload is not Azure-primary, or the team is standardized on S3/GCS tooling.
• You need extreme scale guarantees or a large community to lean on for edge cases. With ~2 stars and no dependents, you are effectively an early adopter: expect to read source, file issues, and possibly contribute patches.
• You need Queues, Tables, or File Share — those are separate sibling packages, not included here.

Adoption gate before committing: pin a version, run the integration suite against Azurite and a real storage account, and confirm the release cadence and changelog provenance. Also review the published release history carefully — one listed release date appears anomalous, so treat version metadata as something to verify rather than assume.

How to Pitch It (Stakeholders)

To executives — one paragraph: We can add Azure Blob Storage as our file backbone without building or maintaining an Azure integration ourselves. This is a free (MIT) PHP SDK that mirrors Azure's storage model — containers, files, versions, snapshots, recovery, temporary shareable links, and identity-based access — and plugs into Laravel's existing file APIs. It replaces an unknown number of engineering weeks of custom REST, retry, and signing code with a dependency, and it gives us direct-from-Azure asset delivery, which reduces load and bandwidth on our own servers. The trade-off is that it is a small, community-run project rather than a Microsoft-supported product, so I recommend a timeboxed pilot behind our own storage interface before standardizing.

To engineering — the substance:

• Scope: containers, blobs (string/stream upload with tunable block size), streaming download, sync and async copy, prefix and hierarchical listing with paging, metadata and HTTP headers, leases (acquire/renew/change/release/break), snapshots, versions, soft-delete restore for both blobs and containers, blob index tags and tag queries, and SAS generation at blob, container, and account scope.
• Auth: connection strings, shared key, SAS, and Entra ID tokens. Prefer Entra ID; treat connection strings as a local-dev-only escape hatch.
• Correctness features you would otherwise hand-roll: conditional requests via ETag/date/lease ID across uploads, downloads, deletes, copies, tags, and lease operations — this is the concurrency story.
• Integration path: use azure-oss/storage-blob-laravel as the Flysystem driver for ordinary reads/writes; drop to this SDK only for leases, tags, snapshots, versions, and SAS.
• Operability: Azurite for local dev and CI; Guzzle 7 and 8 both supported (2.3.0); async operations carry resolved promise types for static analysis. Changelog shows active, specific maintenance — SAS builder state-leak fix, typed SAS validation errors, lease break header correctness for Guzzle 8.
• Known friction: connection-string handling in .env, default 4MB upload block size needing tuning for large media, and CORS configuration in Azure for browser-side access. All are documented and low-effort, but budget for them.

Risk framing and mitigation (say this out loud):

• Very low adoption, no dependents, explicitly unendorsed by Microsoft → do not put it on a critical path without a seam.
• Put a thin internal storage interface in front of it so the SDK is swappable for the official SDK or an alternative driver.
• Pin the version, add an Azurite-backed integration test in CI, and assign one engineer as the point of contact for upstream issues.
• Reassess at the pilot's end on: integration effort actually saved, incident count, and whether upstream responded to anything we filed.

The ask: approve a two-week, single-service pilot behind our storage abstraction, with the decision to standardize deferred until we have measured it.