Laravel Imageup Laravel Package

Product Decisions This Supports

• Feature scoping and time-to-market. For the common "one image per record" needs — user avatar, profile cover, company logo, CMS thumbnail, marketplace listing photo — this package collapses what is typically a multi-day task (upload handling, validation, resize/crop, disk paths, old-file cleanup, URL rendering) into a trait plus a config array. That is a decision to ship the feature in this sprint rather than schedule it, and to spend the saved effort on differentiated work.
• Build vs. buy for media handling. It provides a concrete "buy" answer for commodity image plumbing: MIT-licensed, Composer-installable, no vendor contract, no per-image cost. The decision it enables is to not build an internal upload utility, and to not buy a media SaaS for a product whose image needs are still field-level.
• Roadmap gating on "media as a product surface." The package's ceiling is a useful forcing function: if the roadmap starts asking for galleries, multiple images per record, image collections, transformations on the fly, or CDN delivery, that is the signal that media has become a product capability and deserves its own investment — not another field option.
• Admin and internal-tool prioritization. Because it hooks Model::saved() and reads from the request automatically, it is well suited to back-office CRUD, staff tooling, and low-traffic internal panels where a conventional form post is the whole interaction model. It is a poor fit for anything with a designed upload UX (progress, drag-and-drop, client-side crop with server-side coordinates is the one supported exception via cropTo()).
• Deferral decisions. Explicitly not solving: image optimization (WebP/AVIF), responsive/srcset generation, async processing, moderation queues, asset versioning, and audit history. Naming these non-goals up front prevents scope creep into the trait and keeps the adoption reversible.
• Compliance and lifecycle scope. The documented behavior deletes the previous file when a new one is uploaded, but there is no model-delete cleanup described. That makes "what happens to a user's avatar when the account is deleted?" a product decision you must make deliberately rather than inherit — it touches privacy/GDPR obligations and storage cost.

When to Consider This Package

Adopt when most of these hold:

• Standard Laravel monolith (or a modular monolith) with conventional server-rendered or simple JSON form submissions; no separate media service.
• A small, bounded set of image fields (roughly under ten) that are genuinely single-valued per record.
• The team wants the fastest credible path and is comfortable with convention-over-configuration and a "magic" trait.
• Disk-based storage (local public or S3) with public-read semantics is acceptable; signed/private URLs are not a requirement.
• Image sizes are modest and synchronous resize-on-save is tolerable for your latency budget — the trait processes images inside the request/response cycle, so large uploads directly extend response time under load.
• Intervention Image v2-era APIs are acceptable in your dependency graph (the documented hooks use $image->blur(), $image->resize()), or you have verified a v3-compatible fork/pin.

Look elsewhere when any of these are true:

• Multiple images per record, galleries, or ordered media collections — this is a schema mismatch, not a config gap. Consider spatie/laravel-medialibrary or a dedicated media model.
• Async or heavy processing — you need queued jobs, chunked uploads, or large originals retained alongside derivatives.
• Delivery at scale — CDN, on-the-fly transforms, responsive derivatives; an image proxy (imgproxy/Cloudinary/imgix) is the right tool.
• Testability is a hard requirement. Auto-upload depends on the global request() helper and fires on model save, which pushes you toward HTTP-level tests and makes domain logic harder to isolate. If your team enforces fast unit-test suites, this coupling is a real tax.
• Maintenance risk tolerance is low. Signals to weigh: a single maintainer, a CI badge pointing at the retired travis-ci.org, zero listed dependents, and sporadic release cadence. For a customer-facing, revenue-adjacent surface, that combination argues for either forking it internally or writing the ~150 lines yourself.
• Security review will be strict. Validation is opt-in per field via a rules string, and the documented filename-override example interpolates $file->getClientOriginalName() straight into a storage path — user-controlled input reaching a filesystem path. Verify defaults, add explicit image|mimes|max rules on every field, and prefer the default hashed filenames.

How to Pitch It (Stakeholders)

For executives (one paragraph): Image upload is table stakes and undifferentiated — every product needs avatars and covers, and none of them win customers on how they store a JPEG. This package lets us deliver that capability in days instead of a sprint, at zero licensing cost, with no vendor lock-in and no new infrastructure. It is deliberately scoped to single images per record, which covers the large majority of our near-term needs. The trade-off we are accepting is a small maintenance dependency and a modest ceiling: when media becomes a genuine product differentiator — galleries, transformations, CDN delivery — we will graduate to a purpose-built media layer, and that migration is contained because the package's surface is a trait plus a config array rather than a proprietary schema.

For engineering (the ask): Add HasImageUploads to the relevant models, declare $imageFields with explicit rules on every field, pin Intervention Image to a compatible major, and keep uploads out of any latency-sensitive path. Two deliberate guardrails: (1) do not use the getClientOriginalName() filename pattern in the docs — the default hash is safer; (2) set auto_upload => false anywhere we need explicit control, and prefer uploadImage() calls so behavior is visible at the call site rather than implied by a saved() hook. We should also decide, and document, what happens to stored images on model deletion — the package does not handle it, and we own that gap.

Decision recommendation: Adopt now for internal tools and non-critical profile surfaces. Do not adopt for anything in the customer-facing content pipeline or anything behind a strict security/compliance review until the validation defaults and path handling have been reviewed. Revisit if the roadmap adds multi-image or transformation requirements.