Fluppy Laravel Package

Getting Started

• Requirements: PHP 8.2+, Filament 4 or 5. Install with composer require saade/fluppy:"^1.0".

• This is not a zero-config install. Fluppy ships CSS that must be compiled through your own Filament panel theme. If you don't already have a custom theme (php artisan make:filament-theme), create one, then add to resources/css/filament/{panel}/theme.css:

  @import '../../../../vendor/saade/fluppy/resources/css/fluppy.css';
  @source '../../../../vendor/saade/fluppy/resources/views/**/*.blade.php';
  

  and rebuild assets (npm run build / vite build). Skipping this is the most common "it looks broken" first-hour problem.

• First use case: swap FileUpload::make('attachments') for FluppyField::make('attachments') and keep the rest of your chain (->disk(), ->directory(), ->multiple(), validation rules). Test with a small file first, then one larger than upload_max_filesize to confirm chunking actually kicks in.

• Before letting anyone upload big files, run php artisan fluppy:doctor in staging. It audits the full path a large upload travels: Livewire, PHP ini, web server config, and bucket CORS. Re-run it after any infra change.

• For S3, set Livewire's temporary upload disk to S3 so large files become multipart uploads straight to the bucket, and configure bucket CORS accordingly.

• Read the README's per-source setup section before enabling anything beyond the local disk — every third-party source (Drive, Dropbox, Zoom, etc.) needs your own OAuth credentials.

Implementation Patterns

• Drop-in replacement in existing resources. Keep using what you already know from FileUpload: image(), acceptedFileTypes(), maxSize(), imageEditor(), reorderable(), openable(), downloadable(), custom disk()/directory(). Fluppy layers chunked uploads and extra sources on top rather than replacing the API.
• Inside complex layouts. It works in modals, slide-overs, repeaters, builders, relation managers and table action forms, but state paths get involved. For multiple() inside a repeater, test each row independently and cap files with maxFiles() so one row can't saturate connections.
• Media library. Use SpatieMediaLibraryFluppyField (a separate class) instead of the base field in Spatie Media Library resources; keep your collectionName() and conversions. Conversions run after the upload finishes, so move heavy image/video conversions to a queue rather than sync.
• Keep Uppy's own UI for progress. Don't wrap the field in wire:poll or try to drive your own progress bar from a wire:model property — upload state lives in Uppy, not in a normal Livewire attribute.
• Resume on reload. "Reselect the same file and continue" keys off the file's identity (name/size/type). Don't transform or rename files client-side before reselecting, or you lose the resume.
• Direct-to-S3 as the default for large media. Use it whenever maxSize is in the hundreds of MB or uploads are frequent; keep a local temp disk for local development so you don't need a bucket to work offline.
• Ops hygiene. Schedule php artisan fluppy:prune daily (in routes/console.php on Laravel 11+) to remove unfinished-upload leftovers and aborted multipart parts.
• Custom sources are a Pro feature. Writing sources as a class plus Blade view lives in Fluppy Pro; treat that as a paid-upgrade decision, not a free extension point.

Gotchas and Tips

• The Tailwind @source line is Tailwind 4 syntax. If your Filament theme is still on a Tailwind 3 pipeline, confirm the README's instructions apply — otherwise vendor Blade classes are silently not scanned and the field renders unstyled.
• Filament 4/5 only. Any panel still on Filament 3 blocks installation; use composer what-not saade/fluppy (or composer why-not) to see the conflicting package when the constraint fails.
• Many limits in the chain. upload_max_filesize, post_max_size, max_execution_time, max_input_time, nginx client_max_body_size, proxy read timeouts, plus any CDN/WAF body-size cap. fluppy:doctor is the intended debugger here — start there rather than chasing a bare 413.
• S3 CORS is a classic silent failure. Allow PUT/POST from your app origin with the right exposed headers; a bad rule looks identical to "upload just doesn't happen". Add bucket lifecycle rules for aborted multipart uploads as a backstop to fluppy:prune.
• Chunk size is a tradeoff. Smaller chunks survive flaky mobile networks but multiply requests and server overhead. Keep chunk size comfortably below post_max_size and client_max_body_size.
• Validation applies to the assembled file, not per chunk. Bytes may be uploaded before a file is rejected, so set maxSize() and acceptedFileTypes() up front to avoid wasted bandwidth, and don't skip fluppy:prune.
• Each external source needs its own OAuth app. Redirect URIs, scopes, and provider review requirements all apply; over-narrow scopes fail at the picker with unhelpful errors. Budget setup time per provider, not for "the sources feature".
• No Companion server means your app does the work. Provider callbacks and remote-file downloads run through your Laravel app — queue anything slow and watch memory when streaming remote files into a disk.
• Easy swap mistake: in Spatie Media Library resources, replacing FileUpload with FluppyField still leaves you on the base field. Use SpatieMediaLibraryFluppyField.
• Pro is a separate paid package (AI image generation/editing, stock photos, icons, GIFs, signatures, QR codes, maps, templates, TTS, custom source classes). Don't plan around those features on the MIT package; record the licence decision and pin "^1.0" since this is a first release.
• Roll out behind a feature flag or to one panel first, and re-test table actions, modals and repeaters on your exact Filament version before making it the default upload field.