Nova Filemanager Laravel Package

Technical Evaluation

Architecture fit. This is a Nova tool — an admin-panel UI bolted onto Laravel's existing Storage facade — not a service, not a domain component, not a data layer. That is the most important architectural fact for a TPM: it introduces no coupling to application models and no durable contract to the rest of the system. Blast radius is confined to the Nova dashboard and whichever disk you point it at. It fits cleanly when (a) the product already runs Nova, (b) the need is internal operator/editor convenience (upload, browse, rename, move, delete, preview), and (c) media lives on a dedicated filesystem disk. It does not fit anything that resembles a digital asset management system, a customer-facing file portal, a multi-tenant document store, or a regulated/audit-trailed content workflow. Treat this as a build-vs-buy decision on a non-differentiating capability, not a platform bet.

Integration feasibility. Mechanically trivial: composer require, publish the tool provider config, php artisan storage:link, register the tool class in NovaServiceProvider::tools(). The entire day-to-day configuration surface is one file — config/nova-filemanager.php (disk, root/folder path, permission flags) — which is a strong signal for maintainability: a single reviewable artifact governs behavior. The extension points are also few and legible: subclass Filemanager for per-domain roots and canSee() display gating, publish views if the toolbar must change, add middleware to the nova group for IP allow-listing. Feasibility is therefore high conditional on one gate, below.

Technical risk. Ranked, and each is a decision the TPM owns rather than an engineering detail:

1. Abandonment / vendor risk (highest). Last tagged release is 2.8.3, 2020-08-21 — a single bugfix for a missing cover image. 218 stars, zero public dependents. Observable production adoption is unproven and no release cadence should be inferred. Budget a named internal owner and treat fork candidacy as the default posture, not the contingency.
2. Nova 4/5 asset pipeline incompatibility. The 2020 release targets the Nova 2/3 Mix-manifest pipeline; Nova 4/5 uses Nova::script/Vite. The classic failure is a tool that registers but renders a blank panel. Fixable by publishing assets manually or forking and rebuilding the frontend — budget roughly a day if you are on Nova 4+.
3. Security surface. The extension allow-list is effectively your only upload guard, and canSee() hides UI; it does not enforce. A .php file uploaded into a web-served directory is a remote shell. Mitigation is architectural, not package-level: dedicated disk rooted at the target folder (path traversal prevented by the filesystem driver, not by the package), non-executable/out-of-document-root storage, canSee() for UX plus a real policy/gate for truth, and server-side validation.
4. Destructive operations. Delete is permanent and immediate — no trash, no versioning, no undo. Any reference stored as a raw path silently breaks when a file is renamed.
5. Multi-tenant leakage by default. Per-user/per-tenant scoping is not built in. Without a subclass that scopes the root per tenant, every tenant sees every file on the disk.
6. Non-local driver semantics unverified. Uploads and listings generally work via the filesystem abstraction, but signed-URL generation for private buckets and rename() on S3 (no POSIX rename) must be tested, not assumed.
7. Ephemeral filesystems. On Forge/Vapor-style containers the default local root vanishes on redeploy — and takes the media with it.

Key questions (close these before any commitment):

• Which Nova version are we on today, and is a 4/5 upgrade on the roadmap within the life of this feature? This single answer determines whether the rest of this evaluation applies.
• Which Laravel/PHP versions must be supported, and can we pin Nova/Laravel/PHP and the package at 2.8.3 exactly?
• Local disk only, or S3-compatible/SFTP? Who verifies signed URLs and rename semantics?
• Who is the named owner of this dependency, and what is the annual maintenance budget (hours, not dollars)?
• Is a nightly backup of the media disk an acceptable substitute for a trash can and versioning?
• Which roles get delete? Is deletion routed through our own reference-checking flow or left to the tool?
• Is multi-tenancy in scope now or plausibly within 12 months? If plausibly, scope the root by tenant before the first customer onboards.
• What is the honest build-vs-buy delta — days saved versus ongoing fork ownership — and is the alternative simply a small custom Nova tool?

Integration Approach

Stack fit. Strong for Nova 2/3-era stacks (Laravel 6–8, PHP 7.x). Unproven and requiring a spike for PHP 8.x / Laravel 9+ / Nova 4–5. Publish an explicit support matrix — Nova version, Laravel version, PHP version, disk drivers — and record it as the accepted baseline. Anything outside the matrix is a spike, not a plan.

Migration path. Two viable paths, and the TPM should choose one deliberately:

• Pin-and-wrap (default). Adopt at exactly 2.8.3 (no caret range), point at a dedicated disk, wrap every referenced file in a Media model (disk, path, mime, size, uploaded_by) with a Nova resource. The model is the strategic hedge: URLs resolve through Storage::disk($media->disk)->url($media->path), so replacing the manager later is a UI swap, not a data migration. Never patch vendor/.
• Fork-on-need. If Nova 4/5 assets or per-tenant scoping require changes, fork into your own namespace so the diff is visible in review and survives composer install. This converts a vendor dependency into an internal one — a real cost that must be accepted explicitly, not discovered later.

Compatibility. Verify by execution, not by composer.json reading: install in a scratch application, register the tool, and confirm the three signals — the tool renders, uploads land on disk, thumbnails resolve. Hit the nova-vendor/filemanager/... endpoints directly with curl and a session cookie to separate frontend failures (asset pipeline) from backend failures (permissions, disk config, routes). Confirm route names with php artisan route:list | grep filemanager — the path has moved between releases. Enforce lowercase-on-upload if case-sensitive-vs-not collisions across macOS and Linux matter to the content team.

Sequencing. Phase the rollout so each step has an exit criterion and a reversal:

1. Spike (time-boxed, 1 day, scratch app). Exit: three signals green on the target Nova version, or the decision is "fork" or "don't adopt."
2. Foundation. Dedicated disk (e.g. storage/app/public/media), disk root outside executable paths, storage:link, www-data write ownership, config:clear. Exit: upload survives a deploy.
3. Governance. Tool registration, canSee() per role, policy/gate enforcement, extension allow-list, upload-limit triad documented (PHP upload_max_filesize/post_max_size, Nginx client_max_body_size, WAF). Exit: security review sign-off.
4. Durability — day one, not later. Nightly media-disk backup, scheduled prune of an incoming/ temp folder, Media model + resource, delete routed through reference checking or disabled for editor roles.
5. Expansion (optional, demand-driven). Additional tool instances per content domain with their own roots; RTE iframe picker wired at the filemanager route; per-tenant root scoping if multi-tenancy applies.

Operational Impact

Maintenance. No active vendor. The realistic model is internal ownership: a named maintainer, a pinned version, quarterly dependency review, and a standing assumption that Nova upgrades are migration events requiring asset work. Forking is the escalation path and should be sized before it is needed, not after. Documentation is thin — this evaluation plus the spike findings should become the internal runbook.

Support. MIT license, no SLA, no vendor escalation. Community issues only. Anything the team needs answered must be answerable by reading src/Filemanager.php, config/nova-filemanager.php, and the package routes/. Accept this explicitly at the product level: this is not a supported component.

Scaling. Adequate for its actual niche — a handful of internal editors, low concurrency, human-paced uploads. It does not scale as infrastructure: local disk breaks on multi-server and ephemeral containers; large flat folder listings on S3 degrade; there is no CDN or thumbnail-generation strategy beyond what the disk config provides; there is no virus scanning, retention policy, or audit trail. If any of those appear in requirements, the correct answer is to re-scope, not to harden this package.

Failure modes — each with a detection path and an owner, because these recur:

• Blank panel, tool registered → Nova 4/5 asset pipeline. Detect: frontend-only failure, endpoints respond to curl. Mitigate: publish assets / Nova::script / fork rebuild.
• Uploads succeed, images 404 → missing storage:link. Check first, always.
• Opaque 500s after deploy → filesystem ownership; chown -R www-data:www-data the disk root.
• Generic 500/419 on large files → one of the three upload limits, not a package bug. Never surfaced as friendly validation — pre-empt with documented limits.
• Config change silently ignored → config cache; php artisan config:clear.
• Broken references after rename/delete → no referential integrity. Mitigate: Media model + reference check before delete + nightly backup.
• Tenant sees another tenant's files → unscoped root. Prevent before first customer.
• .php upload executed → web-executable disk. Prevent by construction.
• Media disappears on redeploy → ephemeral local filesystem; use persistent volume or object storage.
• Rename fails on S3 → POSIX assumption; verify in the spike.

Ramp-up. Roughly 1 day spike, 1–2 days integration and disk setup, ~1 day hardening and security review, ~1 day editor/RTE wiring — plus a day budgeted for Nova 4+ asset work if applicable, and a small recurring maintenance allowance thereafter. Engineer onboarding is cheap: three files and one config file cover the whole surface. The genuine ramp-up cost is not learning the package; it is accepting the ownership burden that comes with a 2020-era, zero-dependent dependency and writing it down before the first upload lands.