Laravel Chunky Laravel Package

Product Decisions This Supports

• Build vs. buy for large-file upload. Chunked, resumable uploads are a deceptively expensive feature: chunk protocol, retry/backoff, fingerprint-based resume, server-side assembly, expiry/cleanup, typed error envelopes, plus four frontend adapters (Vue 3, React, Alpine, Livewire). This package collapses what is typically a multi-sprint build into composer require + npm install. That is a roadmap-capacity decision: it buys back engineering weeks for the features that actually differentiate the product.
• Feature scope: where resumability is a requirement, not a nicety. Decide which surfaces need it — video/media submissions, document intake (contracts, claims, KYC), LMS assignments, field/ops apps on mobile networks, marketplace asset uploads. For sub-5 MB avatar-only flows, native uploads are still the cheaper answer.
• Infrastructure sequencing. Default auto mode means files under 256 MB assemble in-request with no queue worker and no broadcasting. This supports launching the feature without touching ops: no new worker, no Reverb/Echo, no capacity review. Queue and direct-to-S3 are config-level escalations later — the client API (upload/pause/resume/cancel/subscribe) does not change, so the scale decision is deferred without accruing rework debt.
• Direct-to-S3 as a later cost lever. If egress/compute on PHP becomes the bottleneck, transport() => 'direct_s3' moves bytes out of Laravel entirely (assembly is CompleteMultipartUpload). Useful for deciding when to invest in S3 multipart plumbing — the answer can be "not now, and not by rebuilding the client."
• UX investment in upload completion rates. Server-tracked chunk state + file fingerprint resume means reloads and SPA navigation don't destroy progress (module-level manager means a component unmount only unsubscribes). This directly supports funnel metrics: upload abandonment, retry success rate, support tickets per 1,000 uploads, and completion rate on degraded networks.
• Multi-framework roadmap hedging. If the product has a Laravel/Livewire admin plus a React or Vue customer app, one backend serves both. That avoids a per-framework upload implementation and the driver drift that follows.
• Vendor-risk posture decision. With 0 stars, 0 dependents and a single maintainer, the real decision is not "adopt vs. not" but "adopt as a fork-ready internal dependency." MIT licensing makes that viable: copy, pin, own the tests. Treat it as an in-house component with upstream sync, not as a community-supported library.

When to Consider This Package

Consider it when:

• You are on PHP 8.3+ and Laravel 12/13 — the hard compatibility gate. Anything older is out immediately.
• Users upload large or frequently-interrupted files (roughly >20–50 MB, or any size on mobile/flaky networks) and abandonment is a measurable problem.
• You would otherwise hand-roll the protocol and the frontend adapters; the wrappers plus framework-agnostic core are the bulk of the saved effort.
• You want no new infrastructure to ship v1 — auto mode plus chunky:doctor (which exits non-zero on failures, usable as a CI/deploy gate) fits a small team with limited ops capacity.
• You accept fork ownership: MIT license, documented wire protocol (docs/en/protocol.md), OpenAPI spec, and make:chunky-profile scaffolding make an internal fork realistically maintainable.

Look elsewhere when:

• You are pinned to Laravel 10/11 or PHP < 8.3.
• You need enterprise support, an SLA, security review precedent, or a long release history. There is one maintainer, zero dependents, zero download signal — no community vetting of edge cases or CVEs.
• Your storage target isn't S3-compatible. The direct_s3 path covers S3, MinIO, and R2 best-effort; GCS/Azure would be custom work.
• Your uploads are small and simple — the package is more surface area than the problem warrants.
• You cannot absorb upstream abandonment. If nobody on the team can own a PHP + TypeScript fork, the maintenance risk outweighs the build savings.
• You need compliance certifications or a formal vendor questionnaire answered — there's no vendor here, only a repository.

Adoption gate (do before committing): run chunky:doctor in staging, integrate against the OpenAPI/protocol docs with contract tests, verify the direct_s3 CORS ExposeHeaders: ETag requirement if that transport is on the roadmap, and time-box a spike that exercises resume-after-reload, cancel, and checksum mismatch.

How to Pitch It (Stakeholders)

For executives: This replaces a custom large-file upload subsystem — the kind of plumbing that consumes three to six engineering weeks and still ships with edge-case bugs — with an MIT-licensed package we install and control. It removes "large uploads fail on bad connections" as a support category and as a conversion leak, and it launches with no new infrastructure: no queue worker, no websocket service, no capacity spend. If volume grows, the scaling path (queued assembly, direct-to-S3) is a configuration change, not a rewrite — so we are not pre-paying for scale we don't have.

For engineering: Small, typed backend on ports & adapters (PHPStan max), strict TypeScript frontend, one state machine with database and filesystem tracker drivers sharing a contract and a test suite. Sync/queue/auto assembly modes, streaming assembly that never buffers the whole file, typed error codes (checksum_mismatch, lock_timeout, upload_expired) for retry logic, 404-not-403 on non-owner status/cancel to prevent ID enumeration, sanitized and versioned broadcast payloads, chunky:cleanup for scheduled hygiene, and an OpenAPI-documented protocol. Integration surface is a profile class: rules(), directory(), authorize(), completed().

The honest risk statement: the package is young — single maintainer, zero dependents, zero stars, so no crowd-sourced hardening. We mitigate by treating it as fork-ready internal code: MIT license, pin the version, vendor the source, run chunky:doctor in CI, and keep protocol-level contract tests so we can patch or replace it without a client migration. That converts the risk from "dependency on an unknown vendor" to "a component we own with a head start."