Chunked Uploads

Chunked uploads provide an alternative upload mode for the standalone file manager and SanchayaPicker. When enabled, the chunked uploader is shown instead of the standard Livewire uploader. The existing disk selector remains available when multiple disks are configured. The browser sends the file in smaller requests, which are assembled before the final file is published to the selected disk.

Enable chunked uploads

Chunked uploads are disabled by default. Enable them in config/filament-sanchaya.php:

php

'file' => [
    'chunked' => true,
    'max_chunked_file_size' => 102400, // KB per file
    'chunk_size' => 1024, // KB per request
],

The default limit is 100 MB per file and the default chunk size is 1 MB. A multipart request is larger than the chunk itself, so both the PHP and web-server request-body limits must leave room above chunk_size. A 2 MB request-body limit can reject a 2 MB chunk because of this overhead.

Enable it for a picker

Use the field methods to enable or override the large-file mode for a particular picker:

php

SanchayaPicker::make('gallery')
    ->chunked()
    ->chunkedUploadMaxFileSize(204800); // 200 MB, in KB

Use ->chunked(false) to use the standard Livewire uploader for an individual picker when chunked uploads are enabled globally. The two upload controls are mutually exclusive. In a multiple-file picker, selected files upload sequentially: each file is assembled and saved before the next begins. The dialog stays open until the final file succeeds. If a file fails, processing stops, the error is shown, and files that have not yet uploaded remain selected so you can retry.

Staging and deployment

Chunks are staged in the application's local storage/app/sanchaya-chunks directory. Once all chunks arrive, Sanchaya assembles the file, streams it to the selected disk, and creates the file record. Incomplete uploads older than one day are cleaned up when a new upload starts.

From v1.1.1, chunked uploads also work inside folders created at the standalone manager root, whose paths are relative to the disk root. Directory-scoped pickers still enforce their configured namespace, and the selected disk must match the destination folder's disk.

Multi-server deployments need shared staging storage or request affinity for the duration of an upload. The staging directory must be writable by the application process.

Custom chunk route

Sanchaya registers its default endpoint using the fixed package route name sanchaya.upload-chunk. Its URI, middleware, signed URL requirement, and expiration are configurable:

php

'chunk_upload' => [
    'register_route' => true,
    'uri' => 'sanchaya/upload-chunk',
    'require_signed_url' => true,
    'signed_url_expiration' => 120, // minutes
    'middleware' => ['web', 'throttle:600,1'],
],

To use an application-owned controller, disable the package route and define an application route with the configured name. The route_name setting is only used in this mode:

php

'chunk_upload' => [
    'register_route' => false,
    'route_name' => 'media.chunks',
    'require_signed_url' => true,
],

php

Route::middleware(['web', 'signed', 'throttle:600,1'])
    ->post('media/chunks', [MediaChunkController::class, 'store'])
    ->name('media.chunks');

The custom controller receives the Laravel Request. Each successful request must return JSON containing the new assembled byte offset:

json

{"offset": 2097152}

Keep signed URL validation, authentication, authorization, CSRF protection, and throttling enabled unless the application intentionally provides equivalent protections.

Customize finalization

Chunk collection and final publishing are separate operations. Sanchaya collects and validates chunks first, then resolves the configured finalizer to publish the completed temporary file to the selected disk and create the database record.

php

'file' => [
    'finalizer' => \App\Actions\FinalizeMediaUploadAction::class,
],

Custom finalizers should implement DP0\Sanchaya\Contracts\ChunkUploadFinalizer. The execute() method receives the completed upload metadata, disk, optional parent folder ID, optional picker directory, accepted MIME patterns, and maximum file size. It must return the created SanchayaFile.

The default implementation is DP0\Sanchaya\Actions\FinalizeChunkedUploadAction. It performs size, quota, MIME, destination-scope, storage, checksum, and database-record validation.

Standard upload safeguard

Chunked uploads provide their own Cancel action, which aborts the active chunk request and removes its staged data; previously completed files remain saved. When chunked uploads are disabled, standard Livewire uploads keep the Upload action disabled while the browser is still transferring files. The action becomes available after the transfer reaches 100%.

Chunked Uploads ​