leafs/fs
leafs/fs is a lightweight filesystem package for Laravel that simplifies working with local and cloud disks. It offers clean helpers for reading, writing, uploading, and managing files while integrating with Laravel's Storage system, making common file operations more expressive and consistent acros...
Architecture fit
leafs/fs is a first-party module of the LeafPHP micro-framework, not a framework-agnostic filesystem library. Its value proposition is a terse, Express-style API surface for reading, writing, and enumerating files inside a Leaf application. In a Laravel codebase this is architecturally redundant: Laravel ships Illuminate\Filesystem\Filesystem for local operations and the Storage facade on top of league/flysystem for disk abstraction, both of which are more mature, better documented, and covered by the framework's own test and security processes. Introducing leafs/fs would create a second, parallel filesystem abstraction with different semantics and error behavior living beside the existing one.
Integration feasibility
Composer-installable and PSR-4 autoloaded, so it will technically install. The realistic blockers are ecosystem coupling (leafs/fs is designed to be consumed alongside Leaf's core/support packages and its global helper conventions) and the absence of any adapter interface that would let it sit on top of Laravel's disk configuration. There is no dependency on league/flysystem, so S3/GCS/FTP backends are not available out of the box — meaning any adoption immediately fragments our storage story. Net: feasible to install, not feasible to justify.
Technical risk
Materially high for anything on a production path. The signals are unambiguous: 3 stars, 0 dependents, a single-maintainer project, and a release history that suggests low external scrutiny. Filesystem code is a security-sensitive surface (path traversal, symlink following, TOCTOU on permission checks, MIME/extension validation) and a package at this adoption level has had effectively no third-party review or CVE exposure. Bus factor is 1. Semver stability is not demonstrated by downstream usage. This is the profile of a package we would inherit risk from without gaining capability.
Key questions
leafs/core or other Leaf internals, and if so, does that pull the framework into our dependency graph?write/copy/move return booleans, throw, or fail silently?fopen?Stack fit
Poor. Our stack is Laravel + Flysystem + Storage disks, with configuration-driven driver selection (local, S3, etc.). leafs/fs is a Leaf-native convenience layer with no disk abstraction. Adopting it means either (a) using it only for local-disk operations and maintaining two mental models for file I/O, or (b) replacing Storage wholesale, which is a large, value-destroying refactor.
Migration path
There is no inbound migration path worth pursuing. The only scenario where this package appears is an acquisition or legacy handover of an existing LeafPHP service. In that case the sequence is: keep leafs/fs in place inside the Leaf service, do not import it into Laravel; introduce a thin internal FileStore interface at the boundaries where the Leaf service and Laravel service share storage (preferably object storage, not shared local disk); then replace leafs/fs calls inside the Leaf service with direct league/flysystem usage behind that interface; finally retire the Leaf service or port it onto Laravel Storage.
Compatibility
Low-risk from a language standpoint (PSR-4, PHP 8-era) but high-risk from a convention standpoint: global helpers, Leaf-specific error handling, and no PSR-7/PSR-17 streams integration mean it will not compose cleanly with the rest of our I/O layer.
Sequencing
If we must touch it at all, sequence it as: (1) inventory any existing usage and confirm it is confined to a single service; (2) wrap every call site behind our own interface so the dependency is one swap away; (3) stand up the Flysystem-backed implementation in parallel; (4) migrate call sites disk-by-disk with dual-write verification on anything stateful; (5) remove the dependency. Do not begin any new work on top of it.
Maintenance
We would own it. There is no vendor, no commercial support, and no community large enough to surface regressions. Every PHP minor upgrade, every filesystem-behavior change, and every security review becomes our problem against a codebase we did not write and did not design. That is a permanent tax for a capability we already have.
Support
No SLA, no issue-triage track record, no security disclosure process. Incident response would rely entirely on internal reading of the source. For a package that touches disk, that is the wrong risk posture.
Scaling
Local-disk-only semantics do not survive horizontal scaling. Multiple app instances writing to container-local storage produce split-brain state; there is no locking, no conditional write, no multipart upload, no retry/backoff. Moving to object storage would require replacing the package anyway, so any scale-out event forces the migration we should have done up front.
Failure modes
The concerning ones are silent: partial writes with no atomic rename, boolean returns that swallow errors, missing or weak path-traversal defenses, unhandled permission-denied conditions surfacing as generic exceptions, and non-atomic move/copy across filesystems. None of these are observable without instrumentation we would have to add ourselves, and the package offers no hooks to add it.
Ramp-up
The API is small enough that an engineer can be productive in under an hour — that is its one genuine strength and the reason it exists in the Leaf ecosystem. The hidden cost is that the API's simplicity hides edge-case behavior: developers will assume Storage-like semantics and be wrong. Onboarding documentation would have to be written in-house.
Recommendation
Score of 15.7/100 with 3 stars and 0 dependents is consistent with "do not adopt." Reject for Laravel services; use Storage/Flysystem. If a Leaf service is inherited, contain and retire the dependency rather than expanding it.
How can I help you explore Laravel packages today?