Flysystem Failover Bundle Laravel Package

Product Decisions This Supports

Baseline: v0.8.0 (pre-1.0). This is the initial assessment for webalternatif/flysystem-failover-bundle, a Symfony bundle that wires League Flysystem's failover adapter (FailoverFilesystemAdapter) into configuration, so a primary filesystem transparently hands off to one or more fallbacks when an operation fails.

• Storage resilience / DR roadmap. Decides whether redundancy lives in the application (this package) or in the storage vendor (S3 Cross-Region Replication, GCS dual-region, etc.). Application-level failover covers vendor outages and credential/endpoint failures that native replication does not.
• Build vs. buy. The alternative is bespoke try/catch-and-retry code around every write/read call. This package replaces that with declarative config — a clear buy for teams already on Flysystem.
• Multi-vendor portability and migration. Primary S3 with fallback to GCS or local disk supports dual-write during a storage migration, plus exit leverage in vendor negotiations.
• Feature use cases to scope against: user uploads and media pipelines, generated PDFs/invoices/exports, report and audit archives, and any write path where a silent loss is a customer-visible or compliance event.
• Explicit non-goal it forces you to name: this is failover, not replication or consistency. It does not give RPO=0, does not reconcile divergent copies, and does not verify bytes. If the roadmap needs those, the decision is a different (often vendor-native or queue-based) architecture.

When to Consider This Package

Consider it when:

• The application is Symfony and already uses Flysystem v3 for one or more storage backends. Note the Laravel angle: there is no Laravel service provider here — a Laravel team would consume the underlying league/flysystem failover adapter directly, so this bundle's value is config integration, not capability.
• You want failover behaviour expressed in config/packages/*.yaml rather than scattered through domain code.
• Your failure mode is whole-backend unavailability (5xx, timeouts, bad credentials, region outage) rather than per-object corruption.
• You can pin the dependency and wrap it behind an internal storage interface, given pre-1.0 API churn.

Look elsewhere when:

• You need strong consistency, atomic multi-write, or automatic reconciliation of objects that landed on different backends.
• You need asynchronous/queued replication, checksum verification, or point-in-time recovery.
• Your durability requirement is RPO≈0 — that is a storage-native or managed-service decision, not an application adapter.
• You are Laravel-first and want first-class framework integration, or you need per-object tiering/lifecycle policy rather than failure handling.
• You cannot absorb pre-1.0 breaking changes: v0.8.x is a signal that the public configuration surface is still settling. Action: the v0.8.0 release notes supplied here are only a link to CHANGELOG.md; confirm the actual diff before committing — specifically whether config keys, the failover adapter name, or minimum Flysystem/PHP versions changed.

How to Pitch It (Stakeholders)

For executives: A small, config-only dependency that keeps uploads and generated documents working when a cloud storage provider has an outage or a credential expires. It is cheap insurance against a class of incident that is otherwise invisible until it happens in production. Risk is contained: it is a thin layer over a widely used open-source filesystem library, costs nothing to license, and is isolated behind our storage interface so it can be removed.

For engineering: The bundle is a Symfony configuration wrapper around Flysystem's built-in failover adapter — it does not add new I/O semantics. Adoption means declaring primary and fallback adapters in config and pointing our storage service at the failover name, deleting whatever hand-rolled retry logic we maintain today. Two caveats to plan around: the project is pre-1.0 (v0.8.0), so pin the version and expose storage only through our own interface; and failover is per-operation best-effort, not replication — no reconciliation, no consistency guarantees, so we should not sell it internally as a backup or DR solution. Effort is roughly a day of integration plus test coverage for the degraded-path behaviour.