- How do I install azure-oss/storage-blob-flysystem in a Laravel app?
- Install it with Composer by running composer require azure-oss/storage-blob-flysystem. For a ready-made Laravel driver you can instead require azure-oss/storage-blob-laravel, which wires the adapter into Laravel's filesystem manager. Then add an azure disk to config/filesystems.php with your container, endpoint and credentials, and use Storage::disk('azure').
- Does this package work with Laravel's Storage facade?
- Yes. The adapter implements League Flysystem's FilesystemAdapter contract, which is exactly what Laravel's Illuminate\Filesystem\FilesystemManager expects, so Storage::disk('azure')->put(), get(), exists() and delete() all work. You either register a custom driver in a service provider or use the azure-oss/storage-blob-laravel package that ships the driver preconfigured.
- Which PHP and Laravel versions are supported?
- The package targets modern PHP, generally PHP 8.1 and above, and works with any Laravel version that ships a Flysystem 3 compatible filesystem layer, which means Laravel 10 and later. Always check the composer.json constraints on Packagist before upgrading, since Flysystem major versions are not interchangeable. If you are on an older Laravel release pinned to Flysystem 1 or 2, you will need a different adapter.
- How do I authenticate to Azure Blob Storage with this adapter?
- You create a container client with azure-oss/storage-blob and pass it to the AzureBlobStorageAdapter. BlobServiceClient supports fromConnectionString(), shared key credentials and SAS tokens, so you can load the connection string or SAS token from your .env file. Keep secrets out of config/filesystems.php and read them through env() or Laravel's config caching.
- How do I stream large file uploads to Azure Blob Storage using Flysystem?
- Open the file handle with fopen() and pass it to $filesystem->writeStream('path/file.zip', $stream), then close the handle. The adapter forwards the stream to the underlying SDK, so you avoid loading the whole file into memory. Use readStream() for downloads when you want to pipe content straight to a response.
- Is azure-oss/storage-blob-flysystem officially supported by Microsoft?
- No. It is community-maintained by the Azure OSS for PHP group and is explicitly not affiliated with, endorsed by, or supported by Microsoft. It exists largely because Microsoft's own PHP blob SDK was abandoned. Treat it as a third-party dependency and pin versions in composer.json.
- How does it compare to league/flysystem-azure-blob-storage?
- This package is the actively maintained replacement for the older league/flysystem-azure-blob-storage adapter, which is effectively unmaintained. The project publishes a migration guide covering the namespace and client construction changes. In most cases you swap the adapter class and move from a connection-string-only setup to a BlobServiceClient plus container client.
- How do I list files recursively in an Azure container?
- Call $filesystem->listContents('docs', true) with the second argument set to true for recursive listing. Each returned item is a Flysystem StorageAttributes object, so you can call path(), isFile() or isDir() on it. For very large containers, paginate with the underlying azure-oss/storage-blob SDK instead of loading everything at once.
- How can I test Azure Blob Storage code without hitting the real Azure service?
- Laravel's Storage::fake() only fakes local disks, so it will not exercise this adapter. Use the Azurite storage emulator locally, or write integration tests that point the connection string at Azurite and run them in CI. For unit tests, mock the Flysystem Filesystem or the container client rather than the adapter itself.
- Does the adapter support metadata, content types, storage tiers and blob leases?
- The adapter covers the core Flysystem operations: write, read, stream upload, list, delete, copy, move and visibility. Advanced Azure features such as access tiers, leases and custom metadata are outside Flysystem's contract and must be done with the underlying azure-oss/storage-blob SDK directly. That is fine for most Laravel apps, but plan for direct SDK calls if you need tiering or lease-based locking.