Flysystem Laravel Package

Product Decisions This Supports

• Build vs. buy for storage abstraction. Answers “do we hand-roll a storage layer?” — no. This package is a thin, config-driven bridge (Manager + facade over League\Flysystem\Filesystem), so the decision is really “adopt a pre-built manager pattern” vs. “use Laravel's native Storage facade.”
• Multi-provider file strategy. Choosing whether the product supports one storage backend (local/S3) or many (S3, Azure, Dropbox, Google Cloud, SFTP, WebDAV, GridFS, Zip) with per-connection config — this package makes that a config file, not a codebase rewrite.
• Per-tenant / per-environment storage routing. Flysystem::connection('foo') plus setDefaultConnection() at runtime supports decisions like “enterprise tenants bring their own bucket,” “EU data stays in EU,” or “dev uses local, prod uses S3.”
• Upload, media, and export feature scope. Concrete roadmap items it unblocks: user file uploads and attachments, generated report/CSV/PDF exports written to a disk, database/asset backups, static asset offload to a CDN origin, log/archive shipping.
• Adapter caching as a product decision. The cache config (illuminate or adapter drivers) lets you ship a cheaper read path for hot files without a new service — a cost/latency trade-off, not just a technical one.
• Platform upgrade sequencing. The Laravel/PHP compatibility matrix directly informs roadmap planning: v8.0 = PHP 7.4–8.1, Laravel 8 only. Adopting it constrains your upgrade window, so it belongs in deprecation/technical-debt planning, not just a sprint ticket.
• Vendor risk assessment. Single maintainer, 0 dependents, Tidelift-backed commercial support option — input to a dependency-approval decision and to whether you need an internal fork/maintenance budget.

When to Consider This Package

Consider it when all or most of these hold:

• You are on Laravel 8 with PHP 7.4–8.1 and are not upgrading soon.
• You genuinely need three or more heterogeneous adapters (e.g., S3 + Dropbox + SFTP) rather than one, and you want them behind a single manager interface instead of scattered client code.
• You need runtime connection switching — per-tenant disks, regional residency, or user-configured destinations — which is awkward with plain Storage::disk() bound at call sites.
• You want a facade + DI manager (FlysystemManager) that behaves like a filesystem, so feature teams can inject one interface and stop caring which provider is behind it.
• You value config-over-code onboarding: php artisan vendor:publish, edit config/flysystem.php, ship.

Look elsewhere when:

• Greenfield or Laravel 9+. Laravel's first-party Storage / config/filesystems.php covers local, S3, FTP, and SFTP with framework maintenance and docs. This package adds a layer you'd be paying to maintain.
• You only need one backend. If it's S3 or local, native Storage is strictly less risk.
• You need modern Flysystem. Every adapter here pins Flysystem ^1.0 (league/flysystem-aws-s3-v3, -sftp, -webdav, etc.), while Flysystem v2/v3 is current and the v1 adapter packages are deprecated. This is a deliberate version lock, not a detail.
• You need social proof or a support contract SLA. 0 dependents and a single maintainer mean you are effectively the QA department. Tidelift exists but is a paid subscription, not a guarantee.
• You want the Zip adapter, GridFS, or Azure specifically. These depend on small, less-maintained third-party adapters (plus alcaeus/mongo-php-adapter for GridFS) — budget for breakage.

How to Pitch It (Stakeholders)

For executives: This is a small, free, MIT-licensed Laravel package that turns file storage into a configuration choice instead of an engineering project. It lets one codebase write to local disk, S3, Azure, Dropbox, Google Cloud, SFTP, or WebDAV, and lets us route different customers to different storage without new development. That is genuinely useful for enterprise “bring your own bucket” asks and for data-residency commitments. The counterweight is risk: it's a one-maintainer wrapper around an older major version of Flysystem, it supports only Laravel 8 / PHP ≤ 8.1, and Laravel's own built-in file storage already does most of this. Recommendation: do not standardize on it; evaluate it only for a legacy Laravel 8 service that needs many adapters at once, and treat it as a time-boxed dependency with a named owner and an exit plan to native Storage.

For engineering: It's a Laravel Manager-based bridge — FlysystemManager bound as 'flysystem', Facades\Flysystem proxying to the default connection, connection('name') for the rest, setDefaultConnection() at runtime, publishable config/flysystem.php with default, connections, and cache sections. Adapters are opt-in Composer packages, so the footprint is only what you use. Two things to go in with eyes open: (1) all adapters are Flysystem v1-era (^1.0), so you're on a deprecated major with no in-place migration to v3; (2) the abstraction is thin — everything still resolves to League\Flysystem\Filesystem — so there's little it does that a custom filesystems.php disk driver couldn't. If we adopt it, wrap it behind our own StorageService interface so the bridge is swappable in one file, and add a CI check that fails on Laravel/PHP version drift.