Flysystem Azure File Storage Laravel Package

Getting Started

This package provides a Laravel filesystem disk driver built on Flysystem v3. Release 1.0.0 is the first Flysystem v3-compatible version, so treat it as a new major line rather than a drop-in replacement for any earlier v1/v2 integration.

Minimum steps:

1. Confirm your runtime matches Flysystem v3:
   • PHP 8.0+
   • Laravel 9+ (Laravel 9 is the first release that ships Flysystem v3 by default)
   • No other package pinned to league/flysystem:^1.0|^2.0
2. Install:

   composer require vendor/package
   

3. Publish any config if the package provides it:

   php artisan vendor:publish --tag=package-config
   

4. Register a disk in config/filesystems.php:

   'disks' => [
       'package' => [
           'driver' => 'package',
           // package-specific credentials/options
       ],
   ],
   

5. First use case — write, read, and confirm metadata:

   use Illuminate\Support\Facades\Storage;
   
   Storage::disk('package')->put('hello.txt', 'hello');
   Storage::disk('package')->get('hello.txt');
   Storage::disk('package')->fileExists('hello.txt');
   

Where to look first:

• README.md for the supported Laravel/Flysystem matrix.
• The package service provider for how the disk driver is registered (Storage::extend / FilesystemManager::extend).
• The adapter class implementing League\Flysystem\FilesystemAdapter.
• Issue #12 on the package repository — the release notes explicitly say the Flysystem v3 work is incomplete and further changes are tracked there.

Implementation Patterns

Register the disk via the service provider. Typical Laravel integration creates a Flysystem Filesystem around the package adapter and wraps it in Laravel’s FilesystemAdapter:

Storage::extend('package', function ($app, $config) {
    $adapter = new PackageAdapter($config);
    $filesystem = new \League\Flysystem\Filesystem($adapter, new \League\Flysystem\Config([
        'visibility' => $config['visibility'] ?? 'private',
        'directory_visibility' => $config['directory_visibility'] ?? 'private',
    ]));

    return new \Illuminate\Filesystem\FilesystemAdapter($filesystem, $adapter);
});

Use the Storage facade for day-to-day work. Prefer the Laravel API (put, get, exists, delete, url, temporaryUrl, files, allFiles) over calling Flysystem directly. It keeps application code portable across disks.

Use Flysystem directly when you need v3-specific metadata. Laravel’s FilesystemAdapter hides some Flysystem v3 behaviour. For listings and attributes, use the underlying filesystem:

$filesystem = Storage::disk('package')->getDriver();
foreach ($filesystem->listContents('', true) as $item) {
    $item->type();       // 'file' or 'dir'
    $item->path();
    $item->fileSize();   // ?int
    $item->mimeType();   // ?string
    $item->lastModified(); // int
}

Stream large files. Flysystem v3 treats streams as first-class:

$stream = Storage::disk('package')->readStream('large.zip');
Storage::disk('package')->writeStream('copy.zip', $stream);

Testing pattern. Storage::fake('package') swaps the disk for a local temporary disk, so it validates application logic but not the package adapter. Add at least one integration test that exercises the real driver against a test bucket/container/endpoint. Use Storage::fake() for fast request-level tests and a separate adapter test for listContents, visibility, and error paths.

Upgrade workflow for a Flysystem v2 → v3 move. Run the package’s own tests first, then your application’s storage tests, then a smoke test of the operations your app actually uses (upload, download, temporary URL, delete, listing). Pin the exact version in composer.json until issue #12 is closed:

"vendor/package": "1.0.0"

Feature detection is safer than version sniffing. If you support older and newer versions of the package, wrap calls that only exist in v3 (mimeType(), DirectoryListing, Visibility constants) behind method checks or adapter-level abstractions.

Gotchas and Tips

• This is explicitly an incomplete release. The notes state it is “not fully complete, but good enough for a release” with follow-up work in issue #12. Audit that issue before production use and avoid assuming parity with the previous major version.
• Flysystem v3 is a breaking upgrade. Expect changes including:
  • League\Flysystem\FilesystemInterface is gone; use League\Flysystem\Filesystem.
  • getAdapter() is no longer available on the Flysystem object.
  • listContents() returns a DirectoryListing of StorageAttributes (FileAttributes, DirectoryAttributes), not arrays.
  • getMimetype()/getSize()/getTimestamp() style calls became mimeType(), fileSize(), lastModified(), and metadata can be null.
  • Exception types changed to UnableToReadFile, UnableToWriteFile, UnableToDeleteFile, UnableToCreateDirectory, etc. Do not catch the old FileNotFoundException hierarchy.
  • Visibility is handled through League\Flysystem\Visibility constants and a Config object.
  • Adapters implement the FilesystemAdapter interface; method signatures and return types must match v3 exactly.
• Laravel/Flysystem mismatch is the most common failure. Laravel 8 uses Flysystem v2; Laravel 9+ uses v3. Mixing package versions across those Laravel versions will produce adapter interface errors or runtime Class not found failures.
• fileExists vs directoryExists. In v3 these are distinct; fileExists() should not be used as a proxy for “path exists”.
• Nullable metadata. mimeType(), fileSize(), lastModified(), and visibility can all be null or adapter-dependent. Code that assumes non-null metadata will break on adapters that cannot supply it cheaply.
• Path handling. Flysystem v3 normalises paths more strictly. Avoid leading slashes and .. segments in application code; test root-level versus nested paths.
• Storage::fake() can hide adapter bugs. It replaces the disk entirely. If your application depends on package-specific behaviour (ACLs, custom URLs, eventual consistency), write a real integration test.
• Temporary URLs are adapter-specific. If the package supplies temporaryUrl() support, verify it against your actual storage backend; a missing or incomplete implementation may only surface at runtime.
• Debugging. Log at the adapter boundary (method, path, result) rather than inside Laravel’s filesystem layer. Flysystem’s Config options such as disabling assertion checks can help isolate adapter failures, but do not disable them in production. Inspect the underlying Filesystem directly when FilesystemAdapter hides the failure.
• Extension points. Flysystem v3 plugins are added to the Filesystem instance via addPlugin(). If the package wraps the filesystem internally, confirm you can access it (or that the package exposes a way to register plugins); otherwise you may need to construct the adapter yourself.
• Pin and watch. Until issue #12 is resolved, pin 1.0.0, subscribe to the repository, and re-run storage integration tests on every patch release.