Livewire Upload Handler Laravel Package

Product Decisions This Supports

Build vs. buy on upload UX. The recurring PM question — "do we spend two sprints building drag-and-drop, chunked uploads, progress states, cancel/resume, image previews, and sortable ordering, or do we buy it?" — this package is a credible buy answer, with caveats. The feature surface it covers is genuinely expensive to build well: chunked transfer, Glide-backed thumbnails, compressor.js hooks, i18n, theming, event contracts. A competent team would spend 10–15 engineer-days replicating 80% of it. The PM decision is therefore not "is this good?" but "is the maintenance and platform cost of this specific dependency lower than that build cost, given its adoption profile?"

Roadmap unlock for large-file workflows. The differentiating feature is chunked uploads, not the widget polish. That capability gates any roadmap item involving video, high-resolution imagery, scanned PDFs, or bulk document intake — areas where a naive <input type="file"> fails on proxy body limits and browser timeouts. If the roadmap contains such a feature, this package moves it from "needs infrastructure work" to "needs a config value." That is the strongest reason to evaluate it at all.

MVP scope compression. Because it integrates with Spatie Media Library via MediaGroup/MediaItem with autoSave, teams already using media() relationships can shave upload CRUD — persistence, ordering, deletion, thumbnail retrieval — out of an MVP. This matters most in time-boxed discovery or pilot phases where scope discipline is the constraint, not architecture purity.

Form-heavy admin and back-office surfaces. Sortable multi-file galleries, avatar/logo fields with dimension constraints (minWidth, maxWidth, minHeight), and document collections are the bread-and-butter of internal tooling. These are low-blast-radius, high-annoyance areas where a drop-in component is a legitimate velocity play.

Prioritizing the PHP 8.4 platform upgrade. This is a decision informed by the package rather than supported by it: the PHP 8.4+/Laravel 12+/Livewire 3.1+ floor is a hard gate, not a preference. If the org is already planning that upgrade, this package is nearly free to adopt afterward. If it isn't, adopting this package silently becomes an infrastructure program — a roadmap-level decision that should never be buried inside a feature ticket.

Explicitly not supported: AV scanning, quarantine, retention policy, legal hold, audit logging, transcoding pipelines, or any compliance-grade file governance. If those are requirements, this package is one component of a larger design, not the answer.

When to Consider This Package

Adopt when all of these are true:

• The target application is a Laravel 12+/Livewire 3.1+ monolith already committed to PHP 8.4, and the upgrade is either done or independently funded as its own milestone.
• At least two of the following are real requirements: chunked large-file upload, image previews, drag-and-drop, sortable ordering, Spatie Media Library persistence. A single small avatar field does not clear this bar.
• You already run Spatie Media Library, or you are prepared to adopt it deliberately rather than by accident.
• The work can be pinned to an exact version with a named owner who reads UPGRADE.md on every bump.
• A vendored-fork contingency is acceptable — MIT license, small codebase, 2–5 engineer-days to establish a patch workflow. Name a person, not a team.

Look elsewhere when any of these are true:

• Non-Livewire front end. Inertia/Vue/React stacks pay a Livewire tax for a widget that FilePond or Uppy handle without runtime coupling.
• PHP 8.4 cannot be mandated across every service in the composer lock. This is the hardest gate; the package uses asymmetric visibility, enums, and typed exceptions and cannot be backported by configuration.
• Procurement, SOC 2, or vendor-risk review requires demonstrated adoption or a support contract. A 1-star repository with 0 dependents and a single corporate maintainer fails that screen today, regardless of feature fit.
• You already run Cloudinary, imgix, or an Intervention-based pipeline. Glide coupling means a second image pipeline and two cache-invalidation stories.
• Compliance-grade file handling is in scope. MIME and dimension checks are partly client-side and must be re-enforced server-side before you treat them as a control. Nothing here scans, quarantines, or audits.
• The only path to a fix in your org is filing a GitHub issue. There is no SLA, no CVE process, no LTS policy. Escalation is "read the source," which is feasible but requires an engineer comfortable in Livewire internals on the adopting team.

Adoption shape if you proceed: pilot a single <livewire:upload-handler.item> on one screen with no auto-save and no Media Library; then one media-group against an existing model and collection; only then extend or standardize theming. Sequenced value first, risk later — and never bundle the PHP upgrade into the same milestone as the feature that motivated the package.

How to Pitch It (Stakeholders)

To executives: "We have a roadmap item that requires large-file uploads — video, high-res images, scanned documents. Building that well is roughly two sprints of engineering. There's an MIT-licensed Laravel component that covers it, so the build-versus-buy math favors buying. The catch is maturity: it's a small open-source project with one corporate maintainer, a handful of users, and no support contract. It also requires us to be on PHP 8.4, which we should treat as a separate decision with its own cost and rollback plan. My recommendation is a time-boxed pilot on one non-critical screen behind a feature flag — two weeks, one engineer — before we commit it to a customer-facing flow. If the pilot holds, we save roughly a sprint and a half. If it doesn't, we've spent two weeks and we've de-risked the PHP upgrade conversation along the way."

To engineering: "This is a Livewire-native component library, not a service — two parallel hierarchies, Group/Item for storage you implement and MediaGroup/MediaItem for Spatie auto-save, with subclass hooks and php artisan make:upload-handler scaffolding. Install is composer require plus two Blade stacks, and two gitignore items that are easy to miss and irritating to discover late: livewire-tmp/ and a self-ignoring Glide cache directory under storage/app. The real constraints are the runtime floor — PHP 8.4, Laravel 12, Livewire 3.1 — and the release history, which ships breaking changes on minor and patch versions. Version 1.3.0 renamed all four public events, 1.2.0 changed the extension API and flipped savedFileDisk to null, 1.1.0 renamed a public method. So we pin the exact version, read UPGRADE.md on every bump, and treat each bump as a change request. We also need a named fork owner and a patch workflow, because self-support is the only support."

To design and content: "Themes are configurable (bootstrap-5 + fontawesome-7 by default) via publishable CSS-class and icon maps, so visual alignment is a configuration exercise, not a rewrite. Image previews, file-size display, dimension validation messages, and a temporary-file warning are per-component props — default the warning off and turn it on only in flows where losing an unsaved upload is a real risk. English and French translations ship in the box; anything else is a translation file we own."

To security and compliance: "This is a UI component, not a file governance layer. MIME and dimension checks are enforced partly client-side and must be re-validated server-side. There is no AV scanning, quarantine, retention, legal hold, or audit trail, and adding them is a separate design. Glide introduces a second cache with its own invalidation lifecycle on delete and replace — someone must own that. On the vendor side: one maintainer, no CVE process, no SLA, no third-party review. Treat it as a named risk-register entry with a quarterly review, not a one-time note."