Fluppy Laravel Package

Technical Evaluation

Architecture fit. Fluppy is a drop-in replacement for Filament's FileUpload that swaps the front-end for an Uppy dashboard. Because it extends FileUpload rather than reimplementing it, the existing validation rules, disk configuration, directory conventions, and field modifiers (imageEditor(), reorderable(), openable(), downloadable()) are inherited rather than re-derived. That is the most important architectural fact: adoption is a one-word change at the field level, and it should be reversible with the same one-word change. It is a strong fit for teams already on Filament 4/5 whose upload requirements have outgrown a single-request POST. It is a poor fit for Filament 3 panels, teams without a custom theme, or anyone who needs the field to work in an environment where they cannot rebuild front-end assets.

Integration feasibility. Medium-low friction, with three concrete preconditions:

1. PHP 8.2+ and Filament 4 or 5. No Laravel version matrix is published, so that must be confirmed against our pinned framework before scheduling.
2. A custom panel theme. The package ships an uncompiled CSS file that must be @imported and @sourced into the theme, then rebuilt. Panels using only the default Filament theme need one created first, and our CI must run composer install before the asset build so the vendor path exists. This is a pipeline ordering requirement, not just a styling detail.
3. Server-side headroom for large uploads. Chunked uploads only help if the chunk size sits under upload_max_filesize/post_max_size, the web server's body limit, and any proxy/WAF body limits; S3 paths additionally require bucket CORS and multipart permissions. The fluppy:doctor command is designed to check exactly this chain, which materially reduces the discovery cost — but it needs to be run in every environment, not just the developer laptop.

Technical risk.

• Pre-1.x-stability risk is low, but ecosystem risk is not. v1.0.0 with an explicit ^1.0 constraint is reasonable. The larger risk is that Filament 5 is already in scope; a future Filament 6 will likely force a coordinated upgrade of both Filament and Fluppy.
• Bus factor. Single-author package. Core is MIT and forkable, which is the mitigating factor; Pro is not.
• Open-core boundary. Pro is where custom sources, AI image generation, and the ready-made connectors live. Any roadmap item that sounds like "we need a source Uppy doesn't ship" is a paid dependency, which turns a free package into a procurement item later. Worth deciding now whether that's acceptable.
• Third-party source connectors are not free. Drive, Dropbox, OneDrive, Box, Zoom, and Facebook normally require a Companion server; here the Laravel app performs that role, which almost certainly means per-provider OAuth client credentials, redirect URIs, and provider app-verification processes (Google's in particular). The release notes say "no Companion to run" — true — but the credential and consent-screen burden moves to us. Enabling all sources by default would be a mistake.
• Resume semantics. Resuming after a tab reload depends on Uppy's fingerprinting of the same file plus whatever session state the server retains. That is a strong UX claim that needs a real test on flaky networks before we promise it to users.

Key questions. Published Laravel version matrix and test coverage? Does chunk assembly for non-S3 disks assume a single app node or shared storage (i.e. does it survive a load-balanced, autoscaled deployment)? Do the package's upload routes enforce Filament authorization, policies, and tenant scoping, or must we gate them ourselves? How large is the JS payload with all sources enabled, and are sources individually disableable? Does validation run on the assembled file rather than per chunk? What's the security posture on MIME sniffing and filename handling?

Integration Approach

Stack fit. Adopt on new or actively developed Filament panels first. Keep the default FileUpload for small, simple attachments — an Uppy dashboard is more UI than a 200 KB PDF needs — and use FluppyField where file size, resumability, or capture sources are the actual problem. The SpatieMediaLibraryFluppyField variant means teams on Spatie Media Library are not blocked.

Migration path. Field-level substitution is inherently incremental and per-field reversible, so there is no big-bang migration. The sequenced path:

1. Spike on a non-production panel: install, add the theme imports, rebuild assets, run fluppy:doctor in staging, and exercise a file larger than the current limit.
2. Validate the deployment topology: multi-node behaviour, S3 multipart against the real bucket policy, proxy and WAF limits, and the prune schedule.
3. Convert one field on one panel behind a feature flag or branch. Compare validation behaviour, storage paths, and generated filenames against the current field before widening.
4. Only then enable third-party sources, one at a time, each with its own OAuth app registration.

Compatibility. Pin ^1.0 and treat minor bumps as reviewable, not automatic. Confirm the Laravel matrix before pinning, and add a CI check that the panel theme build still resolves the vendor CSS path after composer update — that import is a silent breakage point if the vendor directory layout changes.

Sequencing. Theme work and CI pipeline changes first (they gate everything), then the staging doctor run, then a single field, then S3/multipart, then connectors, with Pro evaluated only when a concrete requirement lands on it.

Operational Impact

Maintenance. Low ongoing code maintenance — one field swap and a CSS import. The recurring cost is environmental: the CSS import must survive theme changes, and the prune command needs a scheduler entry. Assign explicit ownership of both; unowned, they rot quietly.

Support. Support flows to a single maintainer via GitHub issues, with no SLA on the MIT core. Pro's support terms are not described in the release notes and must be confirmed before relying on it for custom sources. For a team that needs a contractual support path, this package does not provide one; budget for internal capability to read and patch the source instead.

Scaling. Chunked and multipart uploads improve reliability and shift load off PHP request limits, but they add two new resource dimensions: temporary storage (local or bucket) and concurrent in-flight uploads. Unfinished uploads leave residue — that is what fluppy:prune exists for, and it should be scheduled from day one rather than after the first disk-space incident. S3 multipart uploads that are abandoned also accrue storage cost until aborted; verify whether prune covers bucket-side aborts or whether an S3 lifecycle rule is needed as a backstop.

Failure modes to plan for. Chunk assembly failing on multi-node deployments without shared storage; presigned URL expiry mid-upload on slow connections; OAuth token expiry and provider API changes; proxy or WAF body limits silently truncating chunks; orphaned temp files and multipart parts; the theme CSS import being dropped in a refactor; and Pro-gated requirements discovered mid-project. The doctor command covers the configuration-class failures; the resource-leak and vendor-gating failures need runbooks.

Ramp-up. For a Filament-fluent developer, hours — it is a one-word change and the inherited API means existing knowledge transfers. The real learning curve is Uppy itself: restrictions, metadata, custom sources (Pro), and the server endpoints the Laravel side exposes. Budget a day for whoever owns the first integration to read both the package README and Uppy's documentation, and treat that person as the internal reference for later fields.