README

Chunky for Laravel

Chunk-based file upload package for Laravel with event-driven architecture, resume support, and framework-agnostic frontend clients for Vue 3, React, Alpine.js, and Livewire. Upload large files reliably over unstable connections.

Quick example
Requirements
5-minute quickstart
Production deployment checklist
Installation — Backend · Frontend · Livewire
Frontend packages
Usage
Batch upload (multiple files)
Authentication & authorization
Context setup
Listening to events
Broadcasting (Laravel Echo)
Using the facade
Configuration → full reference in docs/configuration.md
Error handling

Additional documentation:

docs/configuration.md — full config reference + deployment recipes
UPGRADE.md — minor-release migration notes (the package is in 0.x)
SECURITY.md — supported versions and reporting policy
CHANGELOG.md — release history

Quick Example

// Backend: Listen for completed uploads
// EventServiceProvider
protected $listen = [
    \NETipar\Chunky\Events\UploadCompleted::class => [
        \App\Listeners\ProcessUploadedFile::class,
    ],
];

<!-- Frontend: Vue 3 upload with progress -->
<script setup>
import { useChunkUpload } from '@netipar/chunky-vue3';

const { upload, progress, isUploading, pause, resume } = useChunkUpload();

function onFileChange(event) {
    upload(event.target.files[0]);
}
</script>

<template>
    <input type="file" @change="onFileChange" />
    <progress v-if="isUploading" :value="progress" max="100" />
    <button v-if="isUploading" @click="pause">Pause</button>
</template>

Requirements

PHP 8.2+
Laravel 11, 12 or 13

5-Minute Quickstart

# 1. Install backend
composer require netipar/laravel-chunky
php artisan vendor:publish --tag=chunky-config
php artisan migrate

# 2. Install frontend (Vue 3 example)
npm install @netipar/chunky-vue3

<!-- 3. Drop in the composable -->
<script setup>
import { useChunkUpload } from '@netipar/chunky-vue3';

const { upload, progress, isUploading, isComplete, error } = useChunkUpload();

function onFileChange(event) {
    const file = event.target.files[0];
    if (file) upload(file);
}
</script>

<template>
    <input type="file" @change="onFileChange" :disabled="isUploading" />
    <progress v-if="isUploading" :value="progress" max="100" />
    <p v-if="isComplete">Done!</p>
    <p v-if="error">Error: {{ error }}</p>
</template>

# 4. Test it
php artisan serve
# Open the page, upload a 10MB file. The chunks land in
# storage/app/chunky/temp/{uploadId}/ during the transfer; once
# complete, the AssembleFileJob writes the final file to
# storage/app/chunky/uploads/{uploadId}/{fileName}.

Production Deployment Checklist

Auth middleware on chunky.routes.middleware (e.g. ['api', 'auth:sanctum'])
Queue worker running for AssembleFileJob (don't run on sync)
Cache driver that supports Cache::lock() if using chunky.lock_driver = 'cache' (Redis / Memcached / DB / DynamoDB; not array or file)
CHUNKY_BROADCASTING=true if real-time UI updates are needed (requires Echo + a WebSocket server)
chunky.staging_directory set to a path with enough free space if accepting uploads larger than /tmp (cloud-disk targets buffer the full file locally before upload)
chunky.metadata.max_keys and chunky.max_files_per_batch tuned for your DOS profile
chunky.metrics.* wired to Datadog / Prometheus / your observability stack
chunky:cleanup scheduled daily (auto-scheduled if auto_cleanup = true)
Custom Authorizer bound if the default ownership check (auth user_id == upload user_id) doesn't fit your access model
routes/channels.php auto-registered (default) or hand-written if you set chunky.broadcasting.register_channels = false

Installation

Backend

composer require netipar/laravel-chunky

Publish the config file:

php artisan vendor:publish --tag=chunky-config

Run the migrations (for database tracker):

php artisan migrate

Frontend

Install the package for your framework:

# Vue 3
npm install @netipar/chunky-vue3

# React
npm install @netipar/chunky-react

# Alpine.js (standalone, without Livewire)
npm install @netipar/chunky-alpine

# Core only (framework-agnostic)
npm install @netipar/chunky-core

The @netipar/chunky-core package is automatically installed as a dependency of all framework packages.

Livewire

No npm package needed. The Livewire component uses Alpine.js under the hood and is included in the Composer package. Just add the component to your Blade template:

<livewire:chunky-upload />

Frontend Packages

Package	Framework	Peer Dependencies
`@netipar/chunky-core`	None (vanilla JS/TS)	-
`@netipar/chunky-vue3`	Vue 3.4+	`vue`
`@netipar/chunky-react`	React 18+ / 19+	`react`
`@netipar/chunky-alpine`	Alpine.js 3+	-

Usage

How It Works

Frontend initiates an upload with file metadata
Backend returns an upload_id, chunk_size, and total_chunks
Frontend slices the file and uploads chunks in parallel with SHA-256 checksums
Backend stores each chunk, verifies integrity, tracks progress
When all chunks arrive, an AssembleFileJob merges them on the queue
Events fire at each step -- hook in your own listeners

CSRF Protection

The frontend client automatically reads the XSRF-TOKEN cookie (set by Laravel) and sends it as the X-XSRF-TOKEN header. No manual CSRF setup is needed in most Laravel applications.

If you need a custom token header, use setDefaults():

import { setDefaults } from '@netipar/chunky-core';

setDefaults({ headers: { 'X-CSRF-TOKEN': 'your-token' } });

Config Isolation

For multiple upload scopes on the same page:

import { ChunkUploader, createDefaults } from '@netipar/chunky-core';

const scope = createDefaults({ headers: { 'X-Custom': 'value' } });
const uploader = new ChunkUploader({ context: 'docs' }, scope);

API Endpoints

The package registers seven routes (configurable prefix/middleware):

Method	Endpoint	Purpose
`POST`	`/api/chunky/upload`	Initiate upload
`POST`	`/api/chunky/upload/{uploadId}/chunks`	Upload a chunk
`GET`	`/api/chunky/upload/{uploadId}`	Get upload status
`DELETE`	`/api/chunky/upload/{uploadId}`	Cancel upload
`POST`	`/api/chunky/batch`	Initiate batch
`POST`	`/api/chunky/batch/{batchId}/upload`	Add file to batch
`GET`	`/api/chunky/batch/{batchId}`	Get batch status

HTTP status codes

Code	When
`201 Created`	Upload or batch initiated
`200 OK`	Chunk accepted, status fetched
`204 No Content`	Cancel succeeded
`404 Not Found`	Upload/batch doesn't exist — or the caller isn't its owner (intentional, prevents probe attacks)
`409 Conflict`	Late chunk against a cancelled / completed / failed / assembling upload
`410 Gone`	Upload has expired
`422 Unprocessable Entity`	Validation error (missing field, invalid file_name, batch in terminal state, etc.)
`503 Service Unavailable`	Upload temporarily contended on the lock; client may safely retry (idempotent)

Vue 3

<script setup lang="ts">
import { useChunkUpload } from '@netipar/chunky-vue3';

const {
    progress, isUploading, isPaused, isComplete, error,
    uploadId, uploadedChunks, totalChunks, currentFile,
    upload, pause, resume, cancel, retry,
    onProgress, onChunkUploaded, onComplete, onError,
} = useChunkUpload({
    maxConcurrent: 3,
    autoRetry: true,
    maxRetries: 3,
    withCredentials: true,
});

function onFileChange(event: Event) {
    const input = event.target as HTMLInputElement;
    if (input.files?.[0]) {
        upload(input.files[0]);
    }
}
</script>

<template>
    <input type="file" @change="onFileChange" :disabled="isUploading" />
    <progress v-if="isUploading" :value="progress" max="100" />
</template>

React

import { useChunkUpload } from '@netipar/chunky-react';

function FileUpload() {
    const {
        progress, isUploading, isPaused, isComplete, error,
        upload, pause, resume, cancel, retry,
    } = useChunkUpload({ maxConcurrent: 3 });

    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const file = e.target.files?.[0];
        if (file) upload(file);
    };

    return (
        <div>
            <input type="file" onChange={handleChange} disabled={isUploading} />
            {isUploading && <progress value={progress} max={100} />}
            {isUploading && (
                <button onClick={isPaused ? resume : pause}>
                    {isPaused ? 'Resume' : 'Pause'}
                </button>
            )}
            {error && <p style={{ color: 'red' }}>{error}</p>}
        </div>
    );
}

Alpine.js

<script>
import { registerChunkUpload } from '@netipar/chunky-alpine';
import Alpine from 'alpinejs';

registerChunkUpload(Alpine);
Alpine.start();
</script>

<div x-data="chunkUpload({ maxConcurrent: 3 })">
    <input type="file" x-on:change="handleFileInput($event)" :disabled="isUploading" />

    <template x-if="isUploading">
        <div>
            <progress :value="progress" max="100"></progress>
            <span x-text="Math.round(progress) + '%'"></span>
            <button x-on:click="isPaused ? resume() : pause()" x-text="isPaused ? 'Resume' : 'Pause'"></button>
            <button x-on:click="cancel()">Cancel</button>
        </div>
    </template>

    <template x-if="error">
        <div>
            <span x-text="error"></span>
            <button x-on:click="retry()">Retry</button>
        </div>
    </template>
</div>

Livewire

{{-- Basic usage --}}
<livewire:chunky-upload />

{{-- With context for validation --}}
<livewire:chunky-upload context="profile_avatar" />

{{-- With custom slot content --}}
<livewire:chunky-upload>
    <div class="my-custom-upload-ui">
        <input type="file" x-on:change="handleFileInput($event)" />
        <div x-show="isUploading">
            <progress :value="progress" max="100"></progress>
        </div>
    </div>
</livewire:chunky-upload>

Listen for the upload completion in your Livewire parent component:

#[On('chunky-upload-completed')]
public function handleUpload(array $data): void
{
    // Default payload: $data['uploadId'], $data['fileName'], $data['fileSize']
    //
    // Set `chunky.broadcasting.expose_internal_paths = true` in
    // config/chunky.php to additionally receive $data['finalPath'] and
    // $data['disk']. By default they're stripped to avoid leaking
    // server-internal paths to the browser.
}

Core (Framework-agnostic)

import { ChunkUploader } from '@netipar/chunky-core';

const uploader = new ChunkUploader({
    maxConcurrent: 3,
    autoRetry: true,
    maxRetries: 3,
    context: 'documents',
});

uploader.on('progress', (event) => {
    console.log(`${event.percentage}%`);
});

uploader.on('complete', (result) => {
    console.log('Done:', result.uploadId);
});

uploader.on('error', (error) => {
    console.error('Failed:', error.message);
});

await uploader.upload(file, { folder: 'reports' });

// Controls
uploader.pause();
uploader.resume();
uploader.cancel();
uploader.retry();

// Cleanup when done
uploader.destroy();

Batch Upload (Multiple Files)

Upload multiple files as a batch and get a single event when all files are done.

Vue 3

<script setup lang="ts">
import { useBatchUpload } from '@netipar/chunky-vue3';

const {
    progress, isUploading, isComplete, completedFiles, totalFiles,
    failedFiles, currentFileName, error,
    upload, cancel, pause, resume,
    onFileComplete, onComplete, onFileError,
} = useBatchUpload({ maxConcurrentFiles: 2, context: 'documents' });

function onFilesChange(event: Event) {
    const input = event.target as HTMLInputElement;
    if (input.files?.length) {
        upload(Array.from(input.files));
    }
}
</script>

<template>
    <input type="file" multiple @change="onFilesChange" :disabled="isUploading" />
    <div v-if="isUploading">
        <progress :value="progress" max="100" />
        <span>{{ completedFiles }}/{{ totalFiles }} files</span>
        <span v-if="currentFileName">Uploading: {{ currentFileName }}</span>
    </div>
    <p v-if="isComplete">All files uploaded!</p>
</template>

React

import { useBatchUpload } from '@netipar/chunky-react';

function MultiFileUpload() {
    const {
        progress, isUploading, isComplete, completedFiles, totalFiles,
        upload, cancel,
    } = useBatchUpload({ maxConcurrentFiles: 2 });

    const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        const files = e.target.files;
        if (files?.length) upload(Array.from(files));
    };

    return (
        <div>
            <input type="file" multiple onChange={handleChange} disabled={isUploading} />
            {isUploading && <progress value={progress} max={100} />}
            {isUploading && <span>{completedFiles}/{totalFiles} files</span>}
            {isComplete && <p>All files uploaded!</p>}
        </div>
    );
}

Alpine.js

<div x-data="batchUpload({ maxConcurrentFiles: 2 })">
    <input type="file" multiple x-on:change="handleFileInput($event)" :disabled="isUploading" />

    <template x-if="isUploading">
        <div>
            <progress :value="progress" max="100"></progress>
            <span x-text="completedFiles + '/' + totalFiles + ' files'"></span>
        </div>
    </template>
</div>

Core (Framework-agnostic)

import { BatchUploader } from '@netipar/chunky-core';

const batch = new BatchUploader({ maxConcurrentFiles: 2, context: 'documents' });

batch.on('fileComplete', (result) => console.log('File done:', result.fileName));
batch.on('complete', (result) => console.log(`Batch done: ${result.completedFiles}/${result.totalFiles}`));

await batch.upload(files);
batch.destroy();

How Batch Works

Frontend calls POST /api/chunky/batch with total_files count
Backend creates a batch record and returns batch_id
For each file, frontend calls POST /api/chunky/batch/{batchId}/upload to initiate
Chunks are uploaded normally via POST /api/chunky/upload/{uploadId}/chunks
When each file's assembly completes, the batch counter increments atomically
When all files are done, BatchCompleted (or BatchPartiallyCompleted) event fires

Every upload creates a batch — even a single file becomes a batch of 1. This ensures consistent behavior: every upload gets a batchId and fires BatchCompleted. useBatchUpload is the single entry point for all uploads.

Failure policy: Lenient -- if a file fails, other files continue. The batch ends with PartiallyCompleted status.

Sequential Batches with `enqueue()`

upload() throws if a batch is already in progress on the same BatchUploader instance. For UIs that accept files faster than they can upload (multi-paste, drag-while-uploading), use enqueue() instead:

import { BatchUploader } from '@netipar/chunky-core';

const uploader = new BatchUploader({ maxConcurrentFiles: 2 });

// First call: behaves like upload()
await uploader.enqueue([file1]);

// While the first batch is still running, queue more:
const second = uploader.enqueue([file2, file3]);
const third = uploader.enqueue([file4]);

// Each enqueue() returns its own promise. The queued batches run
// strictly serially (one at a time), so you get a consistent
// progress signal across all of them.
await Promise.all([second, third]);

If you cancel() or destroy() the uploader before a queued batch starts, its promise rejects with a clear error message. The Vue 3 / React / Alpine wrappers all expose enqueue as a sibling of upload.

Authentication & Authorization

Authentication

By default, upload endpoints use only the api middleware. To protect them with authentication, update routes.middleware in config/chunky.php:

'routes' => [
    'prefix' => 'api/chunky',
    'middleware' => ['api', 'auth:sanctum'],
],

This applies to all routes (initiate, upload chunk, cancel, status, batch). No custom request or controller override is needed.

Authorization (per-upload, per-batch)

When auth is active, the package automatically enforces ownership: an authenticated caller can only access uploads / batches they created (the user_id captured at initiation time). Non-owners see a 404 (not 403) so upload IDs can't be probed.

The check is delegated to a swappable Authorizer interface:

namespace NETipar\Chunky\Authorization;

interface Authorizer
{
    public function canAccessUpload(?Authenticatable $user, UploadMetadata $upload): bool;
    public function canAccessBatch(?Authenticatable $user, BatchMetadata $batch): bool;
}

The default DefaultAuthorizer does plain ownership: auth()->id() === upload->userId, with anonymous uploads (no user_id) accessible to everyone (backward compat).

Custom Authorizer (admin overrides, team access, …)

Bind your own implementation in AppServiceProvider::register():

use NETipar\Chunky\Authorization\Authorizer;
use NETipar\Chunky\Authorization\DefaultAuthorizer;

$this->app->singleton(Authorizer::class, function ($app) {
    return new class extends DefaultAuthorizer
    {
        public function canAccessUpload(?Authenticatable $user, UploadMetadata $upload): bool
        {
            // Admins access everything
            if ($user?->is_admin) {
                return true;
            }

            // Teammates share access
            if ($upload->userId !== null) {
                $owner = User::find($upload->userId);
                if ($owner && $user?->team_id === $owner->team_id) {
                    return true;
                }
            }

            return parent::canAccessUpload($user, $upload);
        }
    };
});

The same Authorizer is used by the broadcast channel auth callbacks (routes/channels.php, auto-registered when broadcasting.enabled = true) — HTTP and WebSocket access stay in sync.

`user_id` is portable

The chunked_uploads.user_id and chunky_batches.user_id columns are string type since v0.14, so any user-id shape works out of the box: auto-increment integers, UUIDs, ULIDs, or arbitrary strings. The package never does arithmetic on user_id, only string equality comparisons.

Quick Context Setup

For the most common case -- validate and move the file to a directory:

use NETipar\Chunky\Facades\Chunky;

Chunky::simple('documents', 'uploads/documents', [
    'max_size' => 50 * 1024 * 1024, // 50MB
    'mimes' => ['application/pdf', 'image/jpeg', 'image/png'],
]);

This registers a context that validates the file and moves it from the temp directory to uploads/documents/{fileName} after assembly. No event listener needed.

Context-based Validation & Save Callbacks

Contexts define per-upload validation rules and save handlers. You can use class-based contexts (recommended) or inline closures.

Class-based Contexts (Recommended)

Create a context class:

namespace App\Chunky;

use NETipar\Chunky\ChunkyContext;
use NETipar\Chunky\Data\UploadMetadata;

class ProfileAvatarContext extends ChunkyContext
{
    public function name(): string
    {
        return 'profile_avatar';
    }

    public function rules(): array
    {
        return [
            'file_size' => ['max:5242880'], // 5MB
            'mime_type' => ['in:image/jpeg,image/png,image/webp'],
        ];
    }

    public function save(UploadMetadata $metadata): void
    {
        auth()->user()
            ->addMediaFromDisk($metadata->finalPath, $metadata->disk)
            ->toMediaCollection('avatar');
    }
}

'contexts' => [
    App\Chunky\ProfileAvatarContext::class,
    App\Chunky\DocumentContext::class,
],

Or register manually in your AppServiceProvider:

use NETipar\Chunky\Facades\Chunky;

public function boot(): void
{
    Chunky::register(ProfileAvatarContext::class);
}

Inline Closures

For simple cases, you can register contexts inline:

use NETipar\Chunky\Facades\Chunky;

public function boot(): void
{
    Chunky::context(
        'documents',
        rules: fn () => [
            'file_size' => ['max:104857600'], // 100MB
            'mime_type' => ['in:application/pdf,application/zip'],
        ],
    );
}

Using Contexts from Frontend

// Vue 3
const { upload } = useChunkUpload({ context: 'profile_avatar' });

// React
const { upload } = useChunkUpload({ context: 'profile_avatar' });

// Alpine.js
// <div x-data="chunkUpload({ context: 'profile_avatar' })">

Listening to Events

use NETipar\Chunky\Events\UploadCompleted;
use NETipar\Chunky\Events\ChunkUploaded;
use NETipar\Chunky\Events\FileAssembled;

protected $listen = [
    UploadCompleted::class => [
        \App\Listeners\ProcessUploadedFile::class,
        \App\Listeners\NotifyUserAboutUpload::class,
    ],
    ChunkUploaded::class => [
        \App\Listeners\TrackUploadProgress::class,
    ],
];

Example listener:

namespace App\Listeners;

use NETipar\Chunky\Events\UploadCompleted;
use Illuminate\Support\Facades\Storage;

class ProcessUploadedFile
{
    public function handle(UploadCompleted $event): void
    {
        // Full UploadMetadata DTO available via $event->upload
        $upload = $event->upload;

        Storage::disk($upload->disk)->move(
            $upload->finalPath,
            "documents/{$upload->uploadId}.zip",
        );

        // Shorthand properties also available for convenience:
        // $event->uploadId, $event->finalPath, $event->disk, $event->metadata
    }
}

Available Events

Event	Payload	When	Broadcasts?
`UploadInitiated`	uploadId, fileName, fileSize, totalChunks	Upload initialized	—
`ChunkUploaded`	uploadId, chunkIndex, totalChunks, progress%	After each successful chunk	—
`ChunkUploadFailed`	uploadId, chunkIndex, exception	On chunk error	—
`FileAssembled`	uploadId, finalPath, disk, fileName, fileSize	After file assembly	—
`UploadCompleted`	upload (UploadMetadata)	Full upload complete	✅
`UploadFailed`	upload (UploadMetadata), reason	Save callback failed or assembly job exhausted retries	✅
`BatchInitiated`	batchId, totalFiles	Batch created	—
`BatchCompleted`	batchId, totalFiles	All batch files completed	✅
`BatchPartiallyCompleted`	batchId, completedFiles, failedFiles, totalFiles	Batch done with failures	✅

Broadcasting (Laravel Echo)

Get real-time notifications when uploads or batches complete. Broadcasting is disabled by default -- enable it in your .env:

CHUNKY_BROADCASTING=true

Four events are broadcastable: UploadCompleted, UploadFailed, BatchCompleted, and BatchPartiallyCompleted. They use private channels — when chunky.broadcasting.register_channels = true (default), the package auto-registers Broadcast::channel() callbacks that delegate to the bound Authorizer, so the same ownership rules apply on HTTP and WebSocket.

If you set register_channels = false, register them manually in your routes/channels.php:

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('chunky.uploads.{uploadId}', function ($user, $uploadId) {
    // Verify the user owns this upload
    return true;
});

Broadcast::channel('chunky.batches.{batchId}', function ($user, $batchId) {
    return true;
});

Vue 3

<script setup>
import { useChunkUpload, useUploadEcho } from '@netipar/chunky-vue3';

const echo = inject('echo');
const { upload, uploadId } = useChunkUpload();

useUploadEcho(echo, uploadId, (data) => {
    console.log('Upload ready:', data.fileName);
});
</script>

React

import { useChunkUpload, useUploadEcho } from '@netipar/chunky-react';

function FileUpload({ echo }) {
    const { upload, uploadId } = useChunkUpload();

    useUploadEcho(echo, uploadId, (data) => {
        console.log('Upload ready:', data.fileName);
    });

    // ...
}

Batch Echo

// Vue 3
import { useBatchUpload, useBatchEcho } from '@netipar/chunky-vue3';

const { upload, batchId } = useBatchUpload();

useBatchEcho(echo, batchId, {
    onComplete: (data) => console.log(`All ${data.totalFiles} files ready`),
    onPartiallyCompleted: (data) => console.log(`${data.failedFiles} files failed`),
});

Core (Framework-agnostic)

import { listenForUploadComplete, listenForBatchComplete } from '@netipar/chunky-core';

const unsubscribe = listenForUploadComplete(echo, uploadId, (data) => {
    console.log('Ready:', data.fileName);
});

// Cleanup when done
unsubscribe();

User Channel

Instead of subscribing per-upload or per-batch, listen on the user channel to receive all upload events — even after page reload:

// routes/channels.php
Broadcast::channel('chunky.user.{userId}', function ($user, $userId) {
    return (int) $user->id === (int) $userId;
});

<!-- Vue 3 -->
<script setup>
import { useUserEcho } from '@netipar/chunky-vue3';

const echo = inject('echo');
const userId = ref(auth.user.id);

useUserEcho(echo, userId, {
    onUploadComplete: (data) => console.log('File ready:', data.fileName),
    onBatchComplete: (data) => console.log(`All ${data.totalFiles} files done`),
    onBatchPartiallyCompleted: (data) => console.log(`${data.failedFiles} failed`),
});
</script>

// React
import { useUserEcho } from '@netipar/chunky-react';

useUserEcho(echo, auth.user.id, {
    onUploadComplete: (data) => console.log('File ready:', data.fileName),
});

The user channel requires authenticated routes (auth:sanctum middleware) and user_id is automatically captured from auth()->id() during upload initiation.

Using the Facade

use NETipar\Chunky\Facades\Chunky;

// Register contexts
Chunky::register(ProfileAvatarContext::class);
Chunky::context('documents', rules: fn () => [...], save: fn ($metadata) => ...);

// Programmatic initiation (returns InitiateResult DTO)
$result = Chunky::initiate('large-file.zip', 524288000, 'application/zip');
// $result->uploadId, $result->chunkSize, $result->totalChunks

// Query upload status (returns UploadMetadata DTO)
$status = Chunky::status($uploadId);
// $status->progress(), $status->fileName, $status->status, etc.

// Batch upload (returns BatchMetadata DTO)
$batch = Chunky::initiateBatch(totalFiles: 5, context: 'documents');
// $batch->batchId, $batch->totalFiles, $batch->status

// Add file to batch (returns InitiateResult DTO with batchId)
$file = Chunky::initiateInBatch($batch->batchId, 'photo.jpg', 5242880);
// $file->uploadId, $file->batchId

// Query batch status (returns BatchMetadata DTO)
$batch = Chunky::getBatchStatus($batchId);
// $batch->completedFiles, $batch->failedFiles, $batch->isFinished()

Configuration

The full configuration reference lives in docs/configuration.md — every key, default, and the common deployment recipes (large videos, S3, authenticated routes, per-chunk progress broadcast). The TL;DR .env:

CHUNKY_TRACKER=database          # database | filesystem
CHUNKY_DISK=local                # any Laravel filesystem disk
CHUNKY_CHUNK_SIZE=1048576        # 1MB
CHUNKY_BROADCASTING=false        # opt-in WebSocket broadcasting
CHUNKY_LOCK_DRIVER=flock         # flock | cache (cache for cloud disks)
CHUNKY_STAGING_DIRECTORY=        # null = sys_get_temp_dir()
CHUNKY_CACHE_PREFIX=chunky:v1:   # versioned cache-key prefix

Publish the config to customise:

php artisan vendor:publish --tag=chunky-config

The config is grouped into 10 sections (since v0.18): storage, chunks, lifecycle, limits, metadata, locking, idempotency, cache, authorization, broadcasting. Older flat keys were renamed — see UPGRADE.md for the full migration table.

Tracking Drivers

Database (default)

Uses the chunked_uploads table. Best for production -- queryable, reliable, supports status tracking.

CHUNKY_TRACKER=database

Filesystem

Uses JSON metadata files on disk. Zero database dependency -- useful for simple setups.

CHUNKY_TRACKER=filesystem

Error Handling

use NETipar\Chunky\Exceptions\ChunkyException;
use NETipar\Chunky\Exceptions\ChunkIntegrityException;
use NETipar\Chunky\Exceptions\UploadExpiredException;

try {
    $manager->uploadChunk($uploadId, $chunkIndex, $file);
} catch (ChunkIntegrityException $e) {
    // SHA-256 checksum mismatch
} catch (UploadExpiredException $e) {
    // Upload has expired (past 24h default)
} catch (ChunkyException $e) {
    // Base exception (catches all above)
}

Examples

Testing

composer test

Credits

NETipar

License

The MIT License (MIT). Please see License File for more information.

netipar / laravel-chunky

Maintainers

Package info

Statistics

Security

README

Chunky for Laravel

Table of contents

Quick Example

Requirements

5-Minute Quickstart

Production Deployment Checklist

Installation

Backend

Frontend

Livewire

Frontend Packages

Usage

How It Works

CSRF Protection

Config Isolation

API Endpoints

HTTP status codes

Vue 3

React

Alpine.js

Livewire

Core (Framework-agnostic)

Batch Upload (Multiple Files)

Vue 3

React

Alpine.js

Core (Framework-agnostic)

How Batch Works

Sequential Batches with enqueue()

Authentication & Authorization

Authentication

Authorization (per-upload, per-batch)

Custom Authorizer (admin overrides, team access, …)

user_id is portable

Quick Context Setup

Context-based Validation & Save Callbacks

Class-based Contexts (Recommended)

Inline Closures

Using Contexts from Frontend

Listening to Events

Available Events

Broadcasting (Laravel Echo)

Vue 3

React

Batch Echo

Core (Framework-agnostic)

User Channel

Using the Facade

Configuration

Tracking Drivers

Database (default)

Filesystem

Error Handling

Examples

Testing

Credits

License

Sequential Batches with `enqueue()`

`user_id` is portable