Nova Advanced Image Field Laravel Package

Product Decisions This Supports

• Build vs. buy for admin media tooling. This is a Nova field package, not a DAM. The v2.1.0 addition — a method to specify an output/conversion format per field — lets a team ship derived-format assets (e.g. WebP) from images uploaded through the Nova admin without writing or maintaining a custom field. That directly shrinks the scope of a “media management” epic: buy the admin UX, keep ownership of storage, transcoding policy, and delivery.
• Roadmap: image performance and bandwidth. Field-level format conversion is the enabling primitive for a “serve modern formats” initiative. It lets you decide where conversion happens — upload-time in the field vs. a queued job vs. an edge/CDN transform — with a working implementation to prototype against rather than a blank page.
• Editorial and content-ops use cases. Marketing and hero imagery, multi-tenant admin panels, and any workflow where non-technical users upload images and need consistent, predictable output. The core value is admin ergonomics (crop-before-upload, configurable aspect ratios, live preview, multi-image support); the conversion API extends that to output correctness. Concretely: a hero image field pinned to a 16:9 crop with a bounded output size removes the recurring “image is the wrong shape / too large” class of content bugs.
• Requirements definition and acceptance criteria. Useful as a reference implementation when writing specs for your own media pipeline: what “format selection” means at the field level, how it interacts with previews, and what the admin user actually sees. Also a concrete, low-cost way to test whether format conversion is a real user-facing win before committing roadmap capacity.
• Scope discipline — the decision this package forces. Where does image transformation live? If a media pipeline already exists (Spatie Media Library, a queued intervention/image job, or a CDN transform service such as imgix/Cloudinary/Glide), scope this to cropping and preview only and keep conversion downstream so two systems aren’t writing derived assets into the same storage paths. Pick one place that writes derived assets; make that explicit in the spec.
• Not a substitute for a delivery strategy. Responsive srcset generation, versioned assets, on-the-fly transforms at scale, and CDN rules remain your decisions. Treat this as admin-surface tooling, not a media architecture.

When to Consider This Package

Adopt when:

• You are already on Laravel Nova and the gap is specifically image handling in the admin — preview quality, crop control, output format. This package is Nova-only and not portable to Filament or a custom admin.
• You want a focused field rather than pulling in a full media library or DAM.
• The format-conversion capability removes a meaningful chunk of custom code from your backlog — it turns format conversion into a fluent field configuration rather than a bespoke field class.
• You accept ownership of the image-processing dependency and its runtime cost. Confirm driver (GD vs. Imagick), whether target encoders are compiled in, memory limits, and whether conversion runs synchronously on upload. A missing encoder that silently falls back to an unconverted file is the failure mode to design against.
• Integration is low-friction and additive: composer require, auto-discovered provider, optional config publish, then swap the field on affected resources. Because it extends Nova’s stock Image field, it is a drop-in replacement — no migration, no model change — and the revert is a one-line diff per resource. That reversibility is the strongest adoption argument.

Look elsewhere when:

• You need responsive image generation, on-demand transformation at scale, or asset governance — reach for Glide, imgix, Cloudinary, or a dedicated DAM.
• Your admin is not Nova. There is no portability path.
• You cannot accept a single-maintainer community dependency on an admin-critical path. Signals to weigh: ~100 stars, zero dependents, last tagged release August 2023, and one maintainer. This is a Nova field, not a Laravel one, so expect to revisit it on every Nova major. Mitigate by pinning the version, centralizing field configuration in one factory/helper, and not subclassing deeply or overriding fill/resolve logic — that keeps the revert cheap if maintenance lapses.
• Your images are large enough that synchronous upload-time processing will hit memory_limit / max_execution_time, and you are not prepared to cap upload sizes or move transformation to a queue. “Upload failed on a large image” becomes the default support ticket otherwise.
• Transparency matters and your editors upload PNGs with alpha — converting those to JPEG produces black or white boxes. Constrain accepted types or stay on PNG/WebP.
• You expect a format change to retroactively reprocess existing media. It does not (verify, but assume upload-only). Backfilling old assets is its own workstream with its own rollback; never fold it into the field rollout.

How to Pitch It (Stakeholders)

To executives: This is a low-cost swap of an existing admin field that closes a real content-quality gap — consistent crops, bounded file sizes, and modern output formats on images uploaded by our own team — without a media-management project or a new vendor contract. It is MIT-licensed, a drop-in replacement for the image field we already use, and reversible in a single file per resource if it disappoints. The one thing to be clear about is that it is admin tooling, not a media architecture: it does not replace our CDN or delivery strategy, and it does not clean up images already in the system.

To engineering: Adopt it as a Nova Image replacement on a small set of resources, not as infrastructure. It inherits Nova’s Image API, so existing chain methods (disk, path, storeAs, prunable, rules) keep working. Pilot on one low-traffic resource with ->croppable()->aspectRatio()->resize() and verify end-to-end: file on disk, stored MIME, public URL, browser render. Then add format conversion on that same single resource before widening. Two conditions before broad rollout: (1) confirm the runtime image driver can actually encode the target format and fails loudly rather than silently emitting an unconverted file, and (2) decide whether upload-time transformation is acceptable or must move to a queue. Keep disk and conversion policy in config, centralize field chains in a small factory class, and avoid overriding fillUsing/resolveUsing so upstream behavior stays available.

Risks to state up front, not later: single maintainer and a 2023 release — pin the version and budget time on each Nova upgrade; extension/MIME drift will break anything downstream that assumes .jpg (Blade views, API resources, sitemaps, email templates, PDF exports, external consumers), so run that audit in parallel with the environment work; and the field cannot stop an editor uploading a 300px image and cropping it to a 1920px hero — dimension validation rules are the only guardrail on source quality.