Filament Upload Laravel Package

Technical Evaluation

Architecture fit Unchanged in substance: this is a presentation-layer Filament form field wrapping file upload with an inline PDF preview — no services, queues, migrations, or persistence model. What v2.1.0 changes is where the presentation lives. On Filament v5.7+ the component no longer relies on the published filament-forms::components.file-upload Blade view and instead renders through Filament's embedded-view pipeline (HasEmbeddedView / toEmbeddedHtml()). Net effect: the plugin's architectural surface moves closer to the host framework's internal rendering contract rather than further away. That is arguably a slightly higher coupling risk than a standalone Blade view, because it now depends on a first-party rendering API that is itself new. Blast radius remains low; leverage remains low. The build-vs-adopt benchmark is still well under one developer-day of native Filament work, so adoption must be justified by polish and convenience.

Integration feasibility Mechanically unchanged: composer require, register the plugin on the target panel in the PanelProvider, swap the existing FileUpload::make(...) for the package's field. The supported-version claim has widened materially — v2.1.0 explicitly states compatibility with Filament v3, v4, and v5.7+. Preconditions to verify before committing:

• Confirm which Filament line we actually run and whether v2.1.0 is even in scope. If we are on v3, this release is a maintenance signal rather than a functional change.
• Verify how the fallback is guarded. The release note says it "falls back to toEmbeddedHtml() when the Blade view is absent" — confirm the guard is existence-based (View::exists / method_exists) and not a version constant, otherwise an older Filament line lacking that API could be pushed down the embedded path and break.
• PHP 8.1+, Livewire 3, and a filesystem disk with correct visibility for private attachments.
• A browser-side PDF rendering path (native <iframe>/<object> or bundled PDF.js) that survives the host app's CSP. Note that on 5.7+ the markup arrives via toEmbeddedHtml(), so the CSP review must cover the rendered output, not just the Blade source.

Technical risk (ranked)

1. License is NOASSERTION — unchanged and still the hard gate. V2.1.0 introduces no LICENSE file and no licensing statement in the release notes. Absent an explicit grant, default copyright applies. Nothing about this release improves our right to use, modify, or redistribute the code.
2. Framework coupling — now realized, not hypothetical. Filament removed a first-party Blade view in a minor release (5.7), which hard-broke the plugin with View [components.file-upload] not found. The maintainer fixed it, but the lesson is that pinning the plugin alone is insufficient: a host-framework minor bump can break this field. Budget for this at every Filament minor, not just majors.
3. Bus factor 1, marginally improved. 45 stars, 0 dependents, single maintainer — but PR #11 from a second contributor (@zvizvi) was accepted and shipped, which is real evidence of responsiveness and external interest. Treat as "actively maintained, still single-owner," not as de-risked.
4. Semver misalignment. The plugin's 2.x line spans Filament v3/v4/v5.7+, so plugin version numbers carry no information about host-framework compatibility. 2.0.0 → 2.1.0 is a minor bump for what is functionally a patch-level compatibility fix. Any dependency policy that infers compatibility from version numbers will mislead us here.
5. Rendering surface. Still iframe/object/PDF.js, touching CSP (frame-src, object-src, blob:), asset publishing paths, and security review of rendering untrusted documents client-side. v2.1.0 does not reduce this surface.
6. Metadata hygiene. The new tag confirms the repository is live, partially mitigating the prior "abandoned / anomalous last-release date" concern. Still verify actual tags, Packagist versions, and release dates before trusting automated score inputs — the version numbers cited here (Filament v5.7) run ahead of what we operate.

Key questions to put to the maintainer / repo

• What are the exact composer.json constraints for filament/filament, illuminate/*, livewire/livewire, and PHP, and did v2.1.0 widen or narrow them?
• How is the toEmbeddedHtml() fallback guarded? Existence check or version check? Is there a test proving v3/v4 still take the Blade path?
• Is there a CI matrix across Filament v3 / v4 / v5.x? Without one, the v5.7 break will recur in the next minor.
• Is there a LICENSE file, and will the maintainer confirm MIT/Apache-2.0 in writing? (Still unanswered by this release.)
• Is the preview native-browser or PDF.js? If PDF.js, is the worker published and does it respect a non-root asset URL?
• How are private-disk files served — signed/temporary URLs or public disk?
• Any config file published? Any migration? Issue/PR response history over the last 12 months.

Integration Approach

Stack fit Unchanged: viable only if Filament is already the admin UI. In a plain Laravel/Inertia, Nova, or custom-admin codebase this package has no insertion point and should be rejected outright.

Migration path Additive and reversible. v2.1.0 is a drop-in from v2.0.0 — no migrations, no published config changes called out, no deprecated API in the release note. Treat rollback as a one-line revert plus composer remove. Register the plugin only on the panels that need it and keep the current FileUpload definition in version control as the standing fallback. If the plugin imposes its own directory/disk convention, reconcile it with existing storage policy first rather than letting two conventions coexist.

Compatibility Two pins now, not one:

• Pin the exact plugin version ("asmit/filament-upload": "2.1.0"), not a caret range.
• Pin the Filament minor alongside it. The v5.7 break proves that a caret range on the host framework is the actual failure vector — composer why-not should be run against the locked minor, and Filament minor upgrades should be treated as a scheduled, tested change rather than routine.

Do not assume plugin 2.x implies any particular Filament version; read the release notes for each tag. Test on the app's exact Filament minor, not "latest."

Sequencing 0. License/metadata gate. Read the whole source (1–2 hours) and get license clarity in writing. V2.1.0 did not resolve this — do not spend engineering time before it clears.

1. Guard verification. Read the fallback branch and confirm v3/v4 behaviour is provably unaffected. Cheap, and it is the specific new risk this release introduces.
2. Spike in a throwaway panel: upload a 10 KB, 10 MB, and 100 MB PDF; test against a private disk; test behind the production CSP; test on our Filament minor.
3. Fork-and-pin decision. If the license clears, vendor a pinned fork under our org to neutralize abandonment and to let us patch future view-removal breaks ourselves. If it does not clear, stop here.
4. Pilot in a single internal admin form with a named owner.
5. Rollout or replace — with the ~1-day native FileUpload + custom preview view as the standing fallback.

Operational Impact

Maintenance We own it in practice, and v2.1.0 raises the run-rate. Budget 1–2 dev-days per quarter for dependency bumps plus a short verification pass at every Filament minor (the 5.7 view removal is the template: a host-framework minor turned into a hard runtime failure on a plugin with no CI matrix). Keep 2–5 days budgeted at each Filament major. Register it in the third-party/SBOM inventory with a named owner and a review date.

Support Community-only: GitHub issues, no SLA, no security contact. The positive delta: an external contributor's PR was reviewed and shipped, so response latency is evidently reasonable. With zero dependents there is still no forum corpus, so our team remains the de facto authority. Define an internal escalation path before the pilot.

Scaling Unchanged. Preview cost is client-side and scales with file size and user hardware, not our infrastructure. Large PDFs will hit PHP upload_max_filesize/post_max_size, Livewire temporary-upload rules, and browser memory. Mitigations: hard size cap, lazy-render the preview on click rather than on form load, consider server-side first-page thumbnails, and move attachments to object storage with signed URLs for private data.

Failure modes

• View [components.file-upload] not found after a Filament minor bump → the exact failure v2.1.0 fixes; expect future variants. Mitigate by pinning the Filament minor, reading plugin release notes before every host upgrade, and holding a fork.
• Embedded-view fallback misfires on v3/v4 → verify the guard before rollout; keep the revert-to-native field ready.
• Preview blank after a Filament upgrade → pinned fork, upgrade on our schedule.
• CSP blocks the embed → add frame-src/object-src 'self' blob: deliberately, don't loosen the policy wholesale.
• PDF.js worker 404 in non-root deployments → publish assets and set the asset URL explicitly.
• Upload timeouts / OOM on large files → size cap plus direct-to-S3 or chunked upload.
• Package abandoned → fork retained; revert to native field.
• Data exposure → confirm temp uploads are cleaned and the disk is private; PDFs frequently contain PII.

Ramp-up A few hours for a Filament-fluent developer; effectively zero end-user training, since this is a form field. The disproportionate cost remains process — legal license clearance plus a client-side rendering security review — for the value of one field. Recommendation: v2.1.0 is a genuine maintenance positive (the repo is alive, responsive, and now spans v3–v5.7), but it does not move the two decisive variables: the license is still unasserted, and framework coupling has been demonstrated rather than theorized. Adopt only if the license resolves to a permissive OSI license and Filament is already the platform and we accept a per-Filament-minor verification obligation; otherwise spend the day building the native equivalent and keep the dependency count flat.