Layer a Laravel-idiomatic intent-method API over imgproxy's processing options
The builder keeps its exhaustive "processing option" layer (every imgproxy v4 option exposes one typed method) and gains a thin "intent method" layer — cover, fit, toWebp/optimize, storePublicly, and Laravel's Conditionable when()/unless() — that expresses image outcomes in domain terms rather than imgproxy wire tokens. Names are borrowed from Laravel 13's Image API only where the imgproxy semantics genuinely align.
Why: Laravel 13 shipped a fluent Image API and this package targets Laravel 13 + PHP 8.4, so it should feel idiomatic next to it. But imgproxy is a remote processing server, so parts of the Laravel surface don't map one-to-one; the package keeps its low-level typed layer as a deliberate escape hatch for users who know the wire format.
Considered and rejected:
- Mirror every Laravel method name (
contain,scale, coordinatecrop) — rejected.containneeds a compound (fit+extend_aspect_ratio+bg), not a single option;scaleis redundant with imgproxy's defaultfit(which already never enlarges); imgproxy'scropis gravity-anchored only (no x/y pixel coordinates), so a coordinate-shapedcrop()would mislead a Laravel reader. - Add
contain/scaleanyway for parity — rejected. The composition (fit+extend_aspect_ratio+background) is documented inadvanced-usageinstead of hidden behind a name that can't faithfully honor it. - Rename/deprecate the whole typed option layer — rejected as a v2.x change. The design is purely additive; the
resizerename is deferred to a v3 discussion and onlyresizecarries@deprecated(superseded bycover/fit).
Consequences:
- Two-layer public API: intent methods as the documented headline; processing option methods as the precise, escape-hatch layer (plus raw
withOption()). orientis added as an alias ofautoRotate;flipVertically/flipHorizontallyfor readability overflip(true, false).- Docs lead with intent methods;
advanced-usagedocuments thecontaincomposition. - New glossary terms: intent method, processing option, option segment.