Laravel Imgproxy Laravel Package

Product Decisions This Supports

• Faster image-feature delivery: The new intent methods (cover(), fit(), orient(), flipVertically(), flipHorizontally(), toWebp(), toJpg(), toPng(), toAvif(), optimize(), storePublicly()) let product and engineering scope common image requirements in domain terms rather than imgproxy wire options. This shortens discovery and reduces coupling between product specs and low-level processing syntax.
• Build-vs-buy confidence: For Laravel teams already running or willing to run imgproxy, the package now covers the common product cases—cover crops, fit-without-enlarging, auto-orient, flips, format conversion, quality optimisation, and public storage—without custom image-processing code. That strengthens the case to buy/use imgproxy plus this package instead of building a bespoke transformation layer.
• Roadmap alignment for modern image delivery: toWebp(), toAvif(), and optimize(?format, q = 70) directly support performance and format-modernisation roadmaps. PMs can plan WebP/AVIF rollouts, quality budgets, and responsive-image work with less engineering translation.
• Storage and access-policy decisions: Imgproxy::fromStorage(path, disk, ?instance) and storePublicly(disk, path, options) make disk-based sources and public visibility first-class. This helps decide how product surfaces handle public vs private media, pre-signed URLs, and storage workflows.
• Conditional transformation use cases: The Conditionable trait (when() / unless()) supports product rules such as “optimise only non-GIF uploads” or “apply format conversion only when the source is eligible,” keeping conditional image logic readable.
• Lower-risk incremental adoption: The release is additive on the 2.x line with no BC break. PMs can adopt intent methods for new features while leaving existing resize() usage in place; resize() is docblock-deprecated only, so migration can be scheduled rather than forced.
• Clear product boundaries: The documented non-goals (contain(), scale(), coordinate crop(), grayscale(), storePubliclyAs) and the contain composition in advanced usage clarify what is intentionally not abstracted. PMs should not promise CSS-like contain/scale as first-class API without confirming the advanced composition or withOption() escape hatch.

When to Consider This Package

• Consider it when you are building a Laravel application with image-heavy product surfaces—avatars, product catalogues, CMS media, social thumbnails, user uploads—and want on-the-fly transformations without hand-rolling image processing.
• Consider it when your team is already using or prepared to operate imgproxy and wants a Laravel-native, immutable builder with semantic intent methods plus a typed processing-option escape hatch.
• Consider it when you need common transformations expressed as product intent: cover crop with gravity, fit within bounds, auto-orient, flips, WebP/JPEG/PNG/AVIF conversion, quality optimisation, and public-disk storage.
• Consider it when storage integration matters: resolving sources from Laravel Storage disks, handling public vs private disk URL behaviour, and storing publicly with visibility options.
• Look elsewhere when you are not on Laravel, cannot run or depend on imgproxy, or need a purely local/synchronous image-processing library with no external service.
• Look elsewhere when your product requires first-class support for transformations this release deliberately does not add as intent methods—CSS-like contain, scale, coordinate-based crop, or grayscale—unless you are comfortable using the documented withOption() escape hatch or advanced composition patterns.
• Look elsewhere when you need client-side/CDN-native transformations, a non-Laravel storage abstraction, or a package that avoids pre-signed URL behaviour for private disks.
• Adopt with normal caution when you have existing resize() usage: runtime is unchanged, but the docblock deprecation signals a future naming discussion. Plan to prefer cover() / fit() for new work and schedule cleanup only when the team is ready.

How to Pitch It (Stakeholders)

For executives: This release makes the Laravel imgproxy package easier to use for common product image needs—cropping, fitting, orientation, flips, modern format conversion, optimisation, and public storage. It is additive on 2.x with no BC break, so it reduces delivery risk while accelerating image-heavy features. It supports build-vs-buy decisions by lowering the cost of using imgproxy instead of building custom image processing, and it aligns with performance and format-modernisation goals such as WebP/AVIF and quality tuning.

For engineering: v2.2.0 adds a thin intent-method layer over the existing immutable builder. Methods like cover(), fit(), orient(), flipVertically(), flipHorizontally(), toWebp(), toJpg(), toPng(), toAvif(), optimize(), and storePublicly() compile down to existing processing-option segments; the typed option layer and withOption() remain the precise escape hatch. New entry points fromStorage(), fromPath(), and fromUrl() clarify source handling, and Conditionable supports conditional transform chains. resize() is docblock-deprecated only, with runtime unchanged. The documented non-goals and ADR make the layering and naming policy explicit, so teams can adopt intent methods for new work without a forced migration.