Download the PHP package netipar/laravel-chunky without Composer
On this page you can find all versions of the php package netipar/laravel-chunky. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download netipar/laravel-chunky
More information about netipar/laravel-chunky
Files in netipar/laravel-chunky
Package laravel-chunky
Short Description Chunk-based file upload package for Laravel with event-driven architecture, resume support, batch upload, and framework-agnostic frontend clients for Vue 3, React, Alpine.js, and Livewire.
License MIT
Homepage https://github.com/NETipar/laravel-chunky
Informations about the package laravel-chunky
Chunky for Laravel
Resumable, chunk-based file uploads for Laravel — upload large files reliably over flaky connections. A small, typed backend built on ports & adapters, and a framework-agnostic frontend engine with first-class wrappers for Vue 3, React, Alpine.js, and Livewire.
Works out of the box with no queue worker and no broadcasting — the direct upload response already carries the result. Turn those on later for scale.
v1.0 is a ground-up rewrite. Coming from
0.x? See UPGRADE.md.
Contents
- Why Chunky
- Requirements
- 5-minute quickstart
- How it works
- Upload profiles
- Frontend
- Assembly modes (sync / queue / auto)
- Direct-to-S3 uploads
- Batch uploads
- Authorization
- Events & broadcasting
- Errors
- Console commands
- Configuration
Why Chunky
- Resumable. Chunks are tracked server-side; a reload resumes the same upload via a file fingerprint instead of re-sending bytes.
- Navigation-proof. On the frontend, uploads are owned by a module-level manager — switching pages (SPA) doesn't cancel them.
- Complete without infra. In the default
automode small files assemble in-request and the final response contains the file + your payload. No Echo, no worker required. - One state machine, two drivers. Database or filesystem tracking sit behind the same contract, verified by the same test suite — no driver drift.
- Typed end to end. PHPStan level max on the backend, strict TypeScript on the frontend.
Requirements
- PHP 8.3+, Laravel 12 or 13
- A queue worker only if you use
assembly.mode = queue(orautofor files above the threshold) - Broadcasting (Echo/Reverb) is entirely optional
5-minute quickstart
1. Install the backend.
2. Register an upload profile — where files go and what to do when they finish. In a service provider:
For real logic (e.g. creating a Media record), generate a class:
Register it in config/chunky.php:
3. Upload from the frontend.
That's it — no worker, no broadcasting. Files up to 256 MB assemble in the request and the result comes straight back.
How it works
- Initiate returns an
upload_id,chunk_size, andtotal_chunks. If a matching fingerprint is found, it resumes an existing upload instead. - The client uploads chunks concurrently, retrying transient failures.
- On the final chunk the server assembles the file (streaming, never loading it all into memory), runs your profile's
completed()hook, and — in sync mode — returns the result inline.
The full wire protocol is documented in docs/openapi.yaml.
Upload profiles
A profile is the single place that decides validation, destination, authorization, and the post-assembly hook. Two ways to define one:
Chunky::simple($name, $directory, $options)— a fixed directory + optionalmax_size/mimes.- A class extending
UploadProfile— overriderules(),disk(),directory(),authorize(),fileName(),completed(),maxFileSize().
The batch member endpoint validates against the batch's profile, so a client can't smuggle in a more permissive one.
Frontend
All wrappers are thin adapters over @netipar/chunky-core. The golden rule: a component unmounting only unsubscribes — it never cancels the upload. The upload lives in the manager and survives navigation.
Core (any framework)
uploader.getState() returns an immutable snapshot: { status, progress, uploadedChunks, totalChunks, bytesPerSecond, etaSeconds, file, result, error }.
For image uploads, uploader.previewUrl() lazily creates a cached object URL you can drop into an <img> (null for non-image files); the manager revokes it when the upload is evicted via manager.remove(). Need a real downscaled thumbnail instead? await createThumbnail(file, { maxDimension: 256 }) returns a Blob (WebP by default), dependency-free.
Want end-to-end verification? manager.upload(file, { profile: 'avatar', fileChecksum: true }) hashes the whole file (SHA-256, dependency-free) in parallel with the upload and the server verifies the assembled result against it.
Vue 3 — @netipar/chunky-vue3
useUploads() gives a reactive list of all active uploads (for a global tray); UploadTray and ChunkDropzone are headless components you can style.
React — @netipar/chunky-react
Alpine.js — @netipar/chunky-alpine
Livewire
composer require livewire/livewire, register the Alpine component as above, then drop in the widget:
Assembly modes
config('chunky.assembly.mode') — auto (default), sync, or queue.
| Mode | Final chunk response | Needs a worker? |
|---|---|---|
sync |
{"status":"completed", "file":…, "payload":…} |
No |
queue |
{"status":"assembling"} — client polls status |
Yes |
auto |
sync under assembly.sync_threshold (256 MB), else queue |
Only for large files |
The frontend await uploader.upload() resolves with the final result in all modes — it polls automatically when assembly is queued.
Direct-to-S3 uploads
For the biggest scale win, a profile can opt into the direct_s3 transport — chunks go straight to S3 as multipart parts via presigned URLs, and Laravel only orchestrates (initiate, URL issuing, complete, abort). PHP never touches the bytes and there is no merge step: assembly is the S3 CompleteMultipartUpload.
Set chunky.transports.direct_s3.disk to your s3 disk, require aws/aws-sdk-php, and add ExposeHeaders: ETag to the bucket CORS (docs/en/protocol.md.
Batch uploads
Cancelling a batch cancels every non-terminal member on any tracker driver.
Authorization
Uploads are owned by the authenticating user. Non-owners are answered with 404 on status/cancel (so upload ids can't be enumerated) and 403 on chunk POST. Anonymous uploads stay open for backward compatibility. Swap the Authorizer in config/chunky.php to customize.
Events & broadcasting
Eleven events fire through the lifecycle (UploadInitiated, ChunkUploaded, UploadCompleted, BatchCompleted, …). Listen to them like any Laravel event.
Broadcasting is off by default (broadcasting.enabled). When enabled, payloads are sanitized (disk, final_path, user_id never leave the server) and versioned ({"v":1,…}). High-frequency events (ChunkUploaded, …) are excluded by default so turning it on only pushes the useful completion events.
Errors
Every non-2xx response is a machine-readable envelope:
The frontend surfaces this as a typed ChunkyError with a stable .code (validation_failed, unauthorized, upload_not_found, invalid_state, checksum_mismatch, lock_timeout, …). Retry decisions use the code, never the message. Full table in docs/en/protocol.md.
Console commands
| Command | What it does |
|---|---|
chunky:install |
Publish config + migrations |
chunky:doctor |
Live health checks: disks, queue worker probe (--wait=5), broadcast driver, locking, tracker — exits non-zero on errors (CI/deploy gate) |
chunky:cleanup |
Remove expired, unfinished uploads and their chunks (schedule it) |
make:chunky-profile |
Generate an UploadProfile class |
Configuration
config/chunky.php is validated at boot into a typed ChunkyConfig — a bad value fails fast with the offending key. Full reference and deployment recipes in magyarul).
- UPGRADE.md — migrating from
0.x - CHANGELOG.md — release history
- SECURITY.md — supported versions and reporting
- CONTRIBUTING.md — development setup
Licensed under the MIT license.
All versions of laravel-chunky with dependencies
illuminate/bus Version ^12.0||^13.0
illuminate/database Version ^12.0||^13.0
illuminate/filesystem Version ^12.0||^13.0
illuminate/http Version ^12.0||^13.0
illuminate/queue Version ^12.0||^13.0
illuminate/routing Version ^12.0||^13.0
illuminate/support Version ^12.0||^13.0