Filament File Upload Chunked Laravel Package

Getting Started

Install the package and publish any assets/config it ships with:

composer require owainjones74/filament-file-upload-chunked
php artisan vendor:publish --tag="filament-file-upload-chunked-config"
php artisan filament:assets
php artisan optimize:clear

Look first at:

1. The package README for the exact component namespace and method names for your installed version.
2. config/filament-chunked-file-upload-chunked.php or the published config file, if present, for chunk size, temp paths, and disk defaults.
3. src/Forms/Components/ChunkedFileUpload.php in vendor/owainjones74/filament-file-upload-chunked to confirm which Filament FileUpload methods it supports.

The first practical use case is replacing a normal Filament FileUpload field for large PDFs, videos, or archives where PHP/Livewire limits otherwise cause failed uploads:

use OwainJones\FilamentChunkedFileUploads\Forms\Components\ChunkedFileUpload;

ChunkedFileUpload::make('attachment')
    ->disk('local')
    ->directory('attachments')
    ->acceptedFileTypes(['application/pdf', 'video/mp4'])
    ->maxSize(500 * 1024) // Filament maxSize is usually KB
    ->chunkSize(5 * 1024 * 1024); // confirm units in README; often bytes

Start by swapping one large-file field, verify the browser sends multiple chunk requests in the network tab, and confirm the assembled file lands on the expected disk/path. Keep normal FileUpload for small images and avatars.

Implementation Patterns

Use chunked uploads selectively. Keep Filament’s standard FileUpload for images, thumbnails, and small documents. Use ChunkedFileUpload only where file size is the problem; chunking adds request volume and temp-file cleanup concerns.

Configure disk and directory explicitly. Do not rely on global defaults for important uploads:

ChunkedFileUpload::make('contract')
    ->disk('private')
    ->directory(fn () => 'tenants/' . auth()->user()->tenant_id . '/contracts')
    ->visibility('private')
    ->acceptedFileTypes(['application/pdf'])
    ->maxSize(200 * 1024)
    ->chunkSize(5 * 1024 * 1024);

For tenant-aware apps, derive the directory from the authenticated user/tenant server-side. Do not accept a client-provided directory.

Pair client validation with server rules. Use acceptedFileTypes() and maxSize() for UI feedback, but keep model/policy validation and a final file check in your save action or job. MIME detection can differ between browser and server, especially for large media files.

Treat the upload as a staging step. Store the final path on your model, then dispatch post-processing to a queue:

->afterStateUpdated(function ($state) {
    // Avoid heavy work here; Livewire requests can time out.
})

For example, after saving the form, dispatch a job to generate thumbnails, virus-scan, or move the file to permanent storage. This keeps the Livewire upload request short.

Use chunk size as a tuning knob. A 5 MB chunk is a reasonable default. Very small chunks create hundreds of requests and slow uploads; very large chunks hit PHP/nginx limits and reduce retry granularity. Align chunk size with:

• upload_max_filesize
• post_max_size
• nginx client_max_body_size
• Livewire temporary upload settings
• any proxy or WAF request-size limits

Handle progress and retries in the UI. Chunked uploads are network-sensitive. Add helper text explaining that large files upload in parts, and test on slow connections. If the package exposes upload progress events, use them to disable submit while chunks are in flight.

Test with browser coverage. Livewire unit tests will not exercise the JavaScript chunking loop. Use Storage::fake() and a small fake file for form/component tests, then use a browser test or manual network-tab check to verify actual chunking, retries, and final assembly.

Gotchas and Tips

• Maintenance risk: The last release was November 2023, with 17 stars and zero dependents. Pin the package version and test against your Filament major version before relying on it. If you are on a newer Filament release, verify the component still renders and uploads; otherwise fork it or use native temporary uploads/S3 multipart uploads.
• Units matter: Filament’s maxSize() is typically in kilobytes, while chunk-size options in upload packages are often in bytes. Confirm both in the README before setting values.
• Assets and config cache: If the field renders as a plain input or JavaScript is missing, run php artisan filament:assets, clear config/cache, and confirm the package service provider is auto-discovered or registered.
• Temp-file cleanup: Chunked uploads often leave partial chunks behind on failure. Check the package config for a temp directory and add a scheduled cleanup command if the package does not provide one. Scope temp paths by user/session/UUID to avoid collisions during concurrent uploads.
• Proxy limits still apply: Chunking reduces per-request size, but nginx, load balancers, and WAFs can still reject requests. Check client_max_body_size, timeouts, and buffering settings. Long uploads can also outlive sessions; consider session lifetime and re-auth behavior.
• Orphaned files and authorization: Validate that the current user may upload to the target disk/directory. Never trust a client-supplied filename; prefer generated filenames or sanitize and preserve extensions carefully.
• S3 and private disks: If the package uploads chunks server-side, CORS is usually not required, but disk credentials and visibility settings are. If you later switch to direct-to-S3 multipart uploads, CORS, multipart cleanup, and presigned URL expiry become your responsibility.
• Multiple files: Verify ->multiple() support before using it for galleries or bulk imports. Chunked multiple uploads can create many concurrent requests and complicate progress UI.
• Debugging checklist: Use the browser network tab to confirm multiple chunk requests, check storage/logs/laravel.log for assembly errors, inspect the configured temp directory for leftover chunks, and verify the final path with Storage::disk(...)->exists(...).
• Extension points: If ChunkedFileUpload extends Filament’s FileUpload, standard callbacks such as saveUploadedFileUsing() may work, but confirm in the source before depending on them. For anything non-trivial, wrap the upload in your own form action/service class rather than fighting the component.