Flysystem Failover Bundle Laravel Package

Technical Evaluation

Package: webalternatif/flysystem-failover-bundle — v0.8.0 (Oct 3, 2026)

Evidence base: The release provides only a changelog link; no diff, no migration notes, no semver signal beyond the version bump. Assessment below is scoped accordingly and should be treated as provisional until the changelog and tag diff are reviewed.

Architecture fit. This is a Symfony bundle, not a Laravel package. That distinction matters more than usual here: bundles ship a Bundle class, a DI Extension, and YAML service wiring, none of which Laravel consumes. The reusable asset is the underlying Flysystem failover adapter logic, not the bundle surface. Our fit is therefore "library-level reuse, framework-level bypass" — we would depend on the package for its adapter and re-register it through Laravel's filesystem driver layer. Any assessment that assumes composer require + auto-discovery is wrong and should be corrected at the outset.

Conceptually, the capability is well-aligned with a real gap: Laravel's Storage disk abstraction has no first-class failover or redundancy semantics. A write-through/fallback adapter is a plausible building block for multi-region or primary+secondary object storage patterns. The architectural question is whether we want failover (transparent substitution, invisible to the caller) or replication/verification (explicit, observable, reconcilable). These are different products; failover is the cheaper one to build and the more expensive one to operate.

Integration feasibility. Moderate. Two viable paths: (a) Storage::extend() to register a custom driver that composes the failover adapter, keeping the Laravel ergonomics (Storage::disk('redundant')->put(...)); or (b) use the Flysystem adapter directly at the League level and bypass Storage for the affected code paths. Path (a) is preferable for developer experience but requires us to own an adapter shim that has no upstream maintainer — a permanent maintenance tax. Path (b) fragments our storage access patterns.

Blocking unknowns: whether the adapter targets Flysystem v3 (Laravel 10/11/12 ship v3) or still supports v1/v2; whether it pulls in symfony/http-kernel or other framework packages as hard dependencies, which would be a non-starter for a Laravel-only service.

Technical risk. Several, in descending order of severity:

1. Silent failure masking. Failover that is invisible to the caller turns a hard, alertable failure into a soft, silent one. If we cannot distinguish "wrote to primary" from "wrote to secondary," we lose the ability to reason about durability. This is the single largest risk and must be resolved before any production use.
2. Divergence and reconciliation. If writes fail over, the primary is now stale. What restores it? If the package does not provide backfill/reconciliation, we are responsible for inventing it — and that is the expensive part of the system, not the adapter.
3. Read-path semantics undefined. Does failover apply to reads? If a read fails over to a secondary holding an older object, we serve stale data silently. Inconsistent read semantics are worse than no redundancy, because they are undetectable in testing.
4. Pre-1.0 instability. At 0.8.x, minor bumps may break APIs. A failover layer sits directly under persistence — the highest blast-radius position in the stack. Adopting a 0.x dependency there is a deliberate trade of stability for capability.
5. Delete/rename/copy semantics. Multi-target deletes are notoriously ambiguous (best-effort vs. transactional). Partial deletes create orphans that surface as billing anomalies months later.

Key questions for the maintainer (or the changelog review):

• Which operations participate in failover: write, read, delete, copy, move, listContents, url/temporary URLs?
• What exception classes trigger failover, and is the trigger list configurable?
• Is failover state observable — events, PSR-3 logging, metrics, health endpoints?
• Are there post-failover reconciliation or rehydration utilities?
• Flysystem version support and hard dependency list.
• Does it support more than two targets, weighted selection, or circuit-breaking/backoff?
• What changed between 0.7.x and 0.8.0 — additions only, or contract changes?

Integration Approach

Stack fit. Laravel's filesystem layer is a thin facade over Flysystem v3 with a driver registry. That is a favorable seam: we can register the failover adapter as a custom driver without forking anything, and without adopting Symfony bundle machinery. Recommended shape:

• A small internal package (acme/laravel-filesystem-failover) that depends on webalternatif/flysystem-failover-bundle, exposes a failover driver via Storage::extend(), and centralizes configuration in config/filesystems.php.
• Pin the upstream version exactly (not ^0.8) and treat every bump as a reviewed change, not an automatic update.

Migration path. Do not migrate existing disks. Introduce the driver as a new disk alongside current ones, and route a single, low-criticality workload through it first.

Suggested sequencing:

1. Changelog and dependency audit (0.5–1 day). Diff 0.7→0.8, confirm Flysystem v3, confirm no Symfony runtime dependency leaks. Gate: no hard framework dependencies, no unresolved semantics questions from the list above.
2. Adapter shim + instrumentation (3–5 days). Build the Storage::extend() wrapper with mandatory structured logging on every failover event and a counter metric. Non-negotiable: a failover that produces no telemetry is not shippable.
3. Semantics characterization (2–3 days). Write integration tests against two real backends (e.g. S3 primary + S3 secondary in a different region) covering read-after-failover, partial deletes, temporary URL generation, and large multipart uploads. This is where the unknowns get converted into documented behavior.
4. Pilot (2–4 weeks). One non-critical workload — a log/export bucket or derived-artifact storage, not source-of-truth user data. Run with alerting on failover events.
5. Reconciliation tooling (contingent). If step 3 shows divergence is possible and upstream offers no backfill, budget 1–2 engineer-weeks before widening scope. This is the step most likely to be under-estimated.

Compatibility. Confirm the package resolves against our PHP version and Laravel major. Test against the lowest Laravel version we support, not just the newest — the driver registry API has been stable for a while but Storage::extend() call-site conventions have shifted.

Sequencing note. Steps 2 and 3 can partially overlap, but step 3 must complete before step 4. Deploying failover without having characterized its semantics is the specific failure mode this plan exists to prevent.

Operational Impact

Maintenance. We inherit two ongoing costs: (a) tracking a 0.x upstream that we cannot auto-upgrade, and (b) owning the Laravel shim, which has no upstream. Estimated steady-state: a few hours per quarter for version review, plus the shim's share of general platform maintenance. Acceptable given the shim is small; unacceptable if it grows, so keep it strictly to driver registration and configuration mapping.

Support. No commercial support, single-maintainer project, Symfony-oriented community. Internal expertise must be built deliberately — plan for one primary and one secondary engineer, with the failover runbook written by the pilot team while context is fresh. Expect Laravel-specific questions to go unanswered upstream; our shim is the support boundary.

Scaling. The adapter is I/O-bound and stateless, so horizontal scaling is not a concern. Two real costs: throughput — a failing primary adds timeout latency to every request until the failure is detected, so failover must be paired with a circuit breaker, or tail latency will spike service-wide; and storage — redundancy roughly doubles object storage and egress. For large buckets, quantify this before committing, since egress on cross-region replication is often the line item that kills the business case.

Failure modes to instrument and alert on:

Ramp-up. Realistic estimate: 1–1.5 engineer-weeks to reach confident pilot deployment, including audit and characterization; 3–4 weeks elapsed to a decision on wider rollout. The learning curve is not the adapter itself (small, readable) but the operational model — specifically, teaching the team that "the write succeeded" no longer implies "the write landed where you think it did." That conceptual shift is the real ramp-up cost and should drive onboarding material.

Recommendation. Worth a time-boxed pilot, not a broad adoption. The capability gap is real, the integration seam is clean, and the pilot cost is low. But the decision to widen scope should be gated on two findings from the pilot: (1) upstream provides, or we can cheaply build, reconciliation for post-failover divergence, and (2) failover is fully observable. If either fails, the correct outcome is to keep the pilot's instrumentation and build the redundancy explicitly rather than depend on a 0.x package at the persistence layer.