Laravel Chunky Laravel Package

Getting Started

1. Install: composer require jobtech/laravel-chunky. The package publishes a service provider that auto-registers inside Laravel 10/11.
2. Publish config: php artisan vendor:publish --tag=chunky-config — you'll want to review the default disk, temp/chunk storage path, and any TTL/cleanup settings before wiring it into endpoints.
3. Configure storage: point the package at a filesystem disk (local or S3) in config/chunky.php / filesystems.php. Chunks are written to the same disk as the final file, so pick something with enough space and writable permissions.
4. Read the source, not just the README: the repo is small (44 stars, 0 dependents, last release Feb 2024). Start with src/, config/, and any routes/ file to see the exact facade name, method signatures, and driver contract before you code against them.
5. First use case: large-file uploads where the browser splits a Blob with file.slice() and posts each slice to a POST /uploads/{id}/chunks style endpoint — typically videos, CSVs, or archives that exceed upload_max_filesize / post_max_size.

A minimal happy path: create an upload (returns an upload ID), loop client-side slices into chunk endpoints, then call a complete/merge action that concatenates chunks into the final file and returns its path.

Implementation Patterns

• Manager + drivers: chunky follows Laravel's Manager pattern. Use the default disk driver for most cases; register a custom driver via the manager's extend() only if you need non-standard storage behavior (e.g., an S3 multipart implementation).
• Controller-per-action: keep three thin endpoints — init, chunk, complete — and put business logic in a service. This makes it trivial to swap the package later if it goes stale.
• Client-driven IDs: generate the upload identifier client-side (UUIDv4) and send it on every chunk request. Server-side UUIDs make resume-after-refresh trivial; server-generated IDs usually don't.
• Authorization first: gate init, chunk, and complete behind the same policy. A leaked upload ID should not allow appending or finalizing someone else's file — check ownership on every chunk call, not just complete.
• Post-processing via queues: once complete runs, dispatch a job (ProcessUpload) for virus scanning, image resizing, thumbnail generation, or moving the merged file to permanent storage. Don't do heavy work inside the request that finalizes the upload.
• Multi-tenant disks: if tenants have separate S3 prefixes, resolve the disk per-request from the authenticated user and pass it explicitly into the manager rather than mutating global config.
• Resumable UX: expose a GET /uploads/{id} status endpoint that returns received chunk indices. Clients can then skip already-uploaded chunks on page reload.
• Cleanup as a scheduled command: schedule a nightly job that deletes chunk directories older than N hours with no complete call. Abandoned uploads are the #1 way this package silently fills your disk.
• Feature tests: use Storage::fake() and drive the full flow through HTTP tests. Assert the final file's bytes equal the concatenated chunks — hash comparison, not just assertExists.

Gotchas and Tips

• Server upload limits: chunk size must be smaller than upload_max_filesize and post_max_size. If you set the JS slice to 10 MB but PHP caps at 2 MB, every chunk 413s. Make chunk size a config value shared with the frontend.
• Naive concatenation doesn't scale to S3: many simple chunked-upload packages merge by streaming chunks back together on the app server. For very large files on S3 this wastes bandwidth and is slow; confirm whether the package supports S3 multipart or whether you must implement that driver yourself.
• Race conditions with parallel chunks: HTTP/2 lets browsers send chunks concurrently. If the package appends sequentially to a single temp file, you can corrupt the result. Either force sequential uploads client-side or verify the driver writes each chunk as a separate numbered file before merging.
• Path traversal & filename hygiene: upload IDs and chunk indices come from the client. Sanitize and validate them (Str::isUuid, integer indices) before using them in storage paths. Never interpolate the original filename into a path without basename() and a whitelist.
• Merge timeouts: finalizing a multi-GB upload can exceed PHP's max_execution_time or the load balancer's idle timeout. Either bump limits on that route or push merge into a queued job and return early with a pending status.
• Temp disk fills up quietly: point chunk storage at a dedicated disk/volume, not the same one as your OS or /tmp. A single abandoned 50 GB upload takes down the box, not just that user.
• Storage config drift: chunks and the final file must land on the same disk. If your .env changes FILESYSTEM_DISK between requests, complete will "succeed" but the file won't be where the client expects. Pin the disk explicitly per upload.
• Package freshness: last release Feb 2024, zero dependents, low score — treat it as a utility, not a platform. Pin the version in composer.json, read src/ before you upgrade, and wrap the facade in your own UploadService so a future replacement (e.g., pion/laravel-chunk-upload) is a one-file change.
• Extension points: likely the manager's extend() for custom drivers, the config file for disk/TTL settings, and possibly events for chunk.uploaded / upload.completed. Prefer event listeners over editing the package source for logging and metrics.
• Debugging: when chunks "disappear," check (a) the resolved disk, (b) directory permissions, (c) whether the chunk endpoint hit a different app server with local-disk storage. Enable the package's config-level logging if it provides one, otherwise Log::info around the manager calls in your controller.