Files Module Laravel Package

Technical Evaluation

Architecture fit. anomaly/files-module is not a general-purpose Laravel asset library — it is a module in the PyroCMS addon ecosystem, built on top of anomaly/streams-platform. Its role is to provide file/folder entities ("streams"), a control-panel UI, a FileFieldType for attaching assets to other content types, a template plugin (FilesPlugin), and storage/transform handling layered over Flysystem and Intervention Image. This means the unit of adoption is not "add a package" but "adopt the Streams Platform's data model, addon registration, and admin scaffolding." If the target application is not already a PyroCMS/Streams application, the true integration surface is many multiples of this repository's own footprint.

Integration feasibility. Low for a conventional Laravel service. Feasibility rises to moderate only under two scenarios: (a) the organization is already committed to PyroCMS and needs the standard asset module, or (b) the team wants a reference implementation of file/folder/field-type design to fork rather than consume. For a vanilla Laravel app on a current version, direct consumption is not realistic — the module's contracts assume Streams' field types, view namespaces, asset publishing, and addon manifests.

Technical risk. High, concentrated in four areas:

• Abandonment / bus factor. 3 stars and 0 dependents indicates effectively no community surface. Upstream maintenance is single-vendor (Anomaly Labs) and tied to PyroCMS's release cadence, which historically lags current Laravel majors. Any Laravel upgrade becomes a coupled, unsupported migration.
• Framework version lock. The module's illuminate/* and anomaly/streams-platform constraints will pin the host application's Laravel version. Verify constraints before any spike; a mismatch is a hard stop.
• Security surface. File upload and on-the-fly image transformation are among the highest-risk code paths in any web app. Expect to independently audit MIME/extension validation, path traversal in folder operations, SVG/HTML upload XSS, authorization on the control-panel routes, and transform endpoint rate/cost exposure. Zero dependents means zero external security review.
• Scope illusion. The 0.895 score and "powerful asset management made easy" description understate the dependency tree; the module is the tip of the Streams Platform.

Key questions.

1. Are we already, or committed to becoming, a PyroCMS/Streams Platform application? If no, this is likely disqualified as a direct dependency.
2. What is the module's declared Laravel/Streams version range, and does it overlap our target framework version and support window?
3. What is upstream's commit/release cadence over the last 12 months, and is there a responsive maintainer for security issues?
4. Which capabilities do we actually need — storage abstraction, folder taxonomy, image derivatives, field-type reuse in a CMS UI — and how many of those are already satisfied by Spatie Media Library, Flysystem directly, or our admin framework (Filament/Nova)?
5. What is our cost of ownership if upstream stalls — is the module small enough to fork and maintain internally, and is that acceptable?

Integration Approach

Stack fit. Poor as a standalone dependency; acceptable only as part of a PyroCMS deployment. If the requirement is "asset management in a Laravel app," the better-fitting options are Spatie Laravel Media Library (file attachments to models), a thin Flysystem service class (raw storage), or the file-upload primitives of our admin layer (Filament FileUpload, Nova File). The Files module's genuine differentiators — folder tree, CP browsing UI, and a reusable FileFieldType for Streams-based content types — are only valuable if we are inside Streams.

Migration path. Two viable paths, chosen by scenario:

• Scenario A — already on PyroCMS: consume the module as intended via the addon manager, pin the version, and vendor-lock the Streams Platform. Treat upgrades as project work with a test gate, not routine dependency bumps.
• Scenario B — not on PyroCMS: do not integrate. Run a short spike that installs PyroCMS in a throwaway environment, exercises the Files module end-to-end (upload, folder move, field-type attach, image transform, storage-disk switch), and uses it as a design reference. Extract the data model (files, folders, pivot attachments, derivative cache keys) and reimplement against Medialibrary or a custom service. Budget the spike in days, not weeks, and timebox hard.

Compatibility. Confirm before anything else: PHP version, illuminate/* constraints, anomaly/streams-platform constraint, Flysystem major (v1 vs v3 is a breaking API difference in this lineage), and Intervention Image major (v2 vs v3 changed the API). Any one of these mismatching our baseline converts the evaluation into a fork-and-port decision with a materially different cost profile.

Sequencing.

1. Constraint audit — read composer.json and the Streams Platform constraint; produce a go/no-go on version compatibility.
2. Capability gap analysis — enumerate required asset features against Medialibrary/Flysystem/admin-native options. Most teams find the gap is small.
3. Timeboxed spike (Scenario B) or sandbox install (Scenario A), including a storage-disk swap and an S3/object-store test.
4. Security review of upload validation and transform endpoints, regardless of path.
5. Decision gate: adopt → fork → reimplement → reject. Default recommendation absent a PyroCMS mandate is reimplement or use Medialibrary.

Operational Impact

Maintenance. The dominant cost. Low adoption means we are, in practice, the maintainers. Assume we own patch response for Laravel upgrades, Intervention/Flysystem major bumps, and security fixes. This is acceptable only if the module is small and well-factored enough to fork cleanly (verify LOC and coupling to Streams internals), and if we formally accept that fork as a costed line item rather than an implicit one.

Support. No commercial SLA, no dependents to learn from, and a small issue tracker. Internal knowledge will be concentrated in whoever runs the spike — a single-person dependency on top of a single-vendor one. Mitigate by pairing the spike and documenting the fork/upgrade runbook from day one.

Scaling. Storage scales well if we stay on Flysystem with object storage plus a CDN; the module's abstraction here is a genuine strength. The scaling concern is image derivatives: on-demand transformation is CPU-bound and, if not aggressively cached at the edge, becomes the bottleneck under load. Verify derivative caching behavior and whether transforms are generated at upload time or request time. Also verify folder-tree queries do not degrade with deep nesting or high file counts, and that the CP listing is paginated.

Failure modes to plan for.

• Orphaned assets — files written to disk on a request that later fails or rolls back in the database. Requires a reconciliation job.
• Broken derivatives — stale cache keys after re-upload or a transform library major bump; users see missing thumbnails. Needs a regenerate command and a cache-key version.
• Disk/permission misconfiguration — silent failures on the configured storage disk, or public/private visibility mismatches leaking files.
• Upgrade breakage — a Streams Platform bump altering field-type or stream schema contracts, taking down content types that embed files.
• Security regression — permissive MIME handling or traversal in folder paths, surfacing only under audit.
• Upstream stall — no fix available for a framework incompatibility; the fork becomes urgent and unscheduled.

Ramp-up. Non-trivial and specific to Streams Platform: developers must absorb streams, assignments, field types, addon manifests, and control-panel/API namespacing before touching the Files module productively. Estimate one to two weeks of ramp for a mid-level Laravel developer, on top of the spike. If the team is not otherwise learning Streams, that ramp cost is pure overhead against a requirement that is usually satisfiable with a mainstream package.