Download the PHP package netipar/laravel-chunky without Composer

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.

Table of contents

• Quick example
• Requirements
• 5-minute quickstart
• Production deployment checklist
• Livewire
• Frontend packages
• Usage
• Batch upload (multiple files)
• Authentication & authorization
• Context setup
• Listening to events
• Broadcasting (Laravel Echo)
• Using the facade
• 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

Requirements

• PHP 8.2+
• Laravel 11, 12 or 13

5-Minute Quickstart

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

Publish the config file:

Run the migrations (for database tracker):

Frontend

Install the package for your framework:

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:

Frontend Packages

Usage

How It Works

1. Frontend initiates an upload with file metadata
2. Backend returns an upload_id, chunk_size, and total_chunks
3. Frontend slices the file and uploads chunks in parallel with SHA-256 checksums
4. Backend stores each chunk, verifies integrity, tracks progress
5. When all chunks arrive, an AssembleFileJob merges them on the queue
6. 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():

Config Isolation

For multiple upload scopes on the same page:

API Endpoints

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

HTTP status codes

Vue 3

React

Alpine.js

Livewire

Listen for the upload completion in your Livewire parent component:

Core (Framework-agnostic)

Batch Upload (Multiple Files)

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

Vue 3

React

Alpine.js

Core (Framework-agnostic)

How Batch Works

1. Frontend calls POST /api/chunky/batch with total_files count
2. Backend creates a batch record and returns batch_id
3. For each file, frontend calls POST /api/chunky/batch/{batchId}/upload to initiate
4. Chunks are uploaded normally via POST /api/chunky/upload/{uploadId}/chunks
5. When each file's assembly completes, the batch counter increments atomically
6. 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:

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:

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:

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():

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:

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:

Register via config (config/chunky.php):

Or register manually in your AppServiceProvider:

Inline Closures

For simple cases, you can register contexts inline:

Using Contexts from Frontend

Listening to Events

Register listeners in your EventServiceProvider:

Example listener:

Available Events

Broadcasting (Laravel Echo)

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

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:

Vue 3

React

Batch Echo

Core (Framework-agnostic)

User Channel

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

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

Using the Facade

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:

Publish the config to customise:

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.

Filesystem

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

Error Handling

Examples

• English examples
• Magyar peldak

Testing

Credits

• NETipar

License

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