Flysystem Vfs Laravel Package

Technical Evaluation

Architecture fit. This package is a thin bridge: a single VfsAdapter class that maps Flysystem's adapter contract onto michael-donat/php-vfs, an in-memory filesystem exposed through the vfs:// stream wrapper. It was written against Flysystem 1.x's AdapterInterface. Modern Laravel (9/10/11) ships Flysystem 3.x, whose adapter contract was rewritten (FilesystemAdapter with write/writeStream/read/readStream/listContents/move/copy/fileExists/directoryExists/lastModified/mimeType/fileSize/visibility/setVisibility). The bridge does not implement that interface, so it is architecturally misaligned with any current Laravel stack. Its only legitimate fit is a legacy Laravel 5.x application still pinned to Flysystem 1.x.

Integration feasibility. Mechanically simple — composer require, then either register a custom disk driver via Storage::extend('vfs', ...) in a service provider or instantiate new Filesystem(new VfsAdapter(new Vfs)) directly. The blocker is dependency resolution: Composer will almost certainly refuse to co-install this alongside league/flysystem ^2|^3, and forcing it means downgrading the Flysystem that Laravel's own filesystem layer depends on. Realistic effort is therefore not "integration" but "fork and port" — roughly a small adapter rewrite plus test coverage, not a one-line install.

Technical risk. High and multi-sourced:

• Abandonment — last release 2016-07-10, no upstream maintainer activity, 0 dependents and 19 stars, i.e. effectively unexercised in the wild.
• Upstream dependency risk — php-vfs is similarly dormant and depends on PHP stream-wrapper internals, which are sensitive to PHP 8 type and behavior changes.
• Global state — stream wrappers register process-wide; a leaked wrapper or leftover vfs:// contents across tests produces hard-to-diagnose pollution.
• Surface incompleteness — visibility, MIME, and last-modified semantics on a virtual FS are approximate; behavior diverges from Laravel's local/s3 disks, creating "green in CI, broken in prod" surprise.
• Memory-bound — the virtual FS lives in process memory; it is not a persistence or large-file mechanism.

Key questions.

1. Is the actual requirement a virtual filesystem, or merely an in-memory, non-persistent filesystem? If the latter, league/flysystem-memory (maintained) or Laravel's Storage::fake() already satisfies it.
2. Which Laravel/PHP versions are in scope? Anything ≥ Laravel 9 rules this out without a fork.
3. What workload (file sizes, concurrency, persistence expectations) actually drives the VFS need?
4. Do we have an internal owner prepared to maintain a fork, and is that cost justified by the use case?
5. Is the target use case production traffic, or tests/CI/sandboxed plugin I/O only?

Integration Approach

Stack fit. Against Laravel 11 / Flysystem 3 there is no out-of-box fit. Recommended posture: do not register a vfs disk driver in any application we intend to keep. For test-time isolation use Storage::fake('disk') (Laravel's built-in FakeFilesystemAdapter) or the flysystem-memory adapter wired to a custom disk. For sandboxed or plugin I/O, prefer a namespaced directory on the local driver with an explicit cleanup step. Only if a true in-memory namespace is a hard requirement should this package's lineage be considered — and then via a fork, not the published artifact.

Migration path. If a legacy app genuinely depends on it:

1. Isolate behind an internal VirtualFilesystem contract (write/read/list/delete) so the adapter becomes an implementation detail.
2. Vendor the adapter into the codebase or a private package mirror so upstream abandonment cannot break CI.
3. Add a deprecation shim routing that contract to flysystem-memory or a temp-dir local disk, so swapping is a config change rather than a refactor.
4. Retire the dependency when the legacy Flysystem version is dropped.

Compatibility. Pin Composer constraints explicitly; do not rely on a floating ^1.0. Verify PHP-version compatibility of both the adapter and php-vfs on the target runtime (PHP 8.x is untested territory for this stack). Confirm the stream wrapper is registered and unregistered per test/process lifecycle. Validate whether visibility and metadata operations work or are silent no-ops, and document whichever is true.

Sequencing.

1. Prove the need — reproduce the use case with Storage::fake() or flysystem-memory first; most "we need a VFS" asks collapse at this step.
2. Spike — if the need survives, spike php-vfs directly (without Flysystem) to confirm PHP-version viability.
3. Port — write a ~150-line adapter against League\Flysystem\FilesystemAdapter rather than resurrecting the 2016 class.
4. Wrap — hide it behind the internal VirtualFilesystem contract and a service-provider registration.
5. Test — integration tests covering cross-test cleanup, memory bounds, and metadata divergence from the production disk.
6. Document — state plainly that VFS is ephemeral and never a production persistence layer.

Operational Impact

Maintenance. Effectively zero upstream maintenance; adopting this means we own it. Budget for a private fork, composer patches or a mirrored package, and periodic PHP-upgrade audits. The thin adapter class is cheap to port; the embedded php-vfs dependency is the recurring tax, since stream-wrapper behavior drifts across PHP releases. Treat any adoption as an internal library commitment, not a dependency.

Support. No upstream issue triage, no security-response process, and a negligible community knowledge base (19 stars, 0 dependents means few searchable answers). On-call engineers must understand both Flysystem adapter internals and PHP stream wrappers — a narrow skill set. The escalation path is entirely internal, so runbooks for wrapper registration, cleanup, and known metadata gaps must be written before adoption, not after the first incident.

Scaling. Scales with process RAM, not disk. Unsuitable for large files, high-throughput writes, or durable storage; it will OOM under volume. Semantics are single-process with no concurrency guarantees across workers — each PHP-FPM worker gets its own isolated VFS, which is correct for ephemeral CI workloads and wrong for anything requiring shared state. Appropriate ceiling: small-file, test, and sandboxed ephemeral workloads only.

Failure modes. Memory exhaustion on large or accumulating writes; stream-wrapper double-registration or leakage causing cross-test contamination and flaky suites; fatal errors from Flysystem API mismatch after any dependency bump; silent loss of visibility/MIME/last-modified semantics so code paths pass under VFS and fail on local/s3; and orphaned vfs:// contents holding memory after the logical test has ended. Each needs an explicit detection or cleanup step in the test harness.

Ramp-up. Low to learn, high to own safely. The usage surface is small enough that a mid-level engineer can wire it in an afternoon; the risk is concentrated in what they will not know — that the wrapper is process-global, that metadata is approximate, that the package is unmaintained. Plan for a short internal write-up plus a review checkpoint, and gate adoption on one engineer owning the wrapper lifecycle. If that owner does not exist, the honest TPM recommendation is to skip this package entirely and standardize on Storage::fake() / flysystem-memory, which delivers the same testing benefit with no ownership burden.