Laravel Imgproxy Laravel Package

Technical Evaluation

Architecture fit

• v2.2.0 is a purely additive intent layer on the existing immutable builder. cover(), fit(), toWebp()/toJpg()/toPng()/toAvif(), optimize(), orient(), flips, and storePublicly() are ergonomic compilers down to the same processing-option segments already emitted by the typed option layer. No new wire format, no new service dependency, no config surface.
• The layered-API decision (intent methods on top, withOption() as the wire-level escape hatch) is the right shape for a shared internal package: product code reads in domain terms, while platform work retains an exact imgproxy escape hatch. It is explicitly recorded (ADR 0002, CONTEXT.md, API reference), which is the main thing I want to see for a package several teams will depend on.
• The deliberate non-goals (contain(), scale(), coordinate crop(), grayscale()) are defensible and documented, but they mean the intent surface is deliberately incomplete. Expect the README's intent-first framing to generate "how do I contain / grayscale?" questions; the mitigation is that advanced-usage now documents the contain composition.
• Risk of two overlapping vocabularies: resize() vs cover()/fit(), and optimize() vs explicit toWebp() + quality option. This is a governance question more than a code question — the ADR/naming policy exists, which reduces the chance of a third dialect appearing.

Integration feasibility

• Consuming teams can take this with a normal composer update inside the existing ^2.x constraint. No BC break declared, no config publish, no migration step, no runtime flag.
• Imgproxy::fromStorage(path, disk, ?instance) and fromPath() / fromUrl() reduce caller-side boilerplate and remove the "which of the five entry points do I use?" ambiguity that usually surrounds image URL builders. fromStorage reuses the same public-disk → url() / private-disk → temporaryUrl() resolution as the existing Storage macro, which is consistent — and is also a coupling point to verify.
• Low-effort adoption path: new code uses intent methods, existing code untouched, resize() still runs identically. This is the cheapest possible upgrade shape and should not require a scheduled migration window.

Technical risk

• Silent-no-op risk with Conditionable on an immutable builder. when() / unless() invoke the callback and fall back to $this when the callback returns nothing useful. Arrow functions (fn ($b) => $b->cover(...)) are fine; a statement-style closure that forgets to return the new instance will silently discard the change. Same concern applies to the higher-order proxy form (->when($cond)->cover(...)). I want a test asserting these forms actually produce the expected segment, plus a docs line stating the return-the-new-instance contract. This is the single most likely source of "my image isn't resized" bug reports.
• optimize() has implicit compound defaults. Defaulting to f:webp and q:70 means one call changes both format and quality. Teams expecting "optimize the JPEG I already have" will get WebP and a fixed quality instead. That is a content-type/Accept negotiation and cache-key concern, not just an aesthetic one.
• fromStorage() public/private classification is a security-relevant branch. A file on a disk treated as public resolves to a durable url(); a misclassification turns a private asset into a guessable, non-expiring URL. The behaviour mirrors the Storage macro, so this is inherited risk — but a new, easier entry point broadens the blast radius. Similarly, storePublicly() writes with public visibility and should be gated by a data-classification conversation, not just a convenience method.
• Pre-signed URL expiry for private disks is baked into generated URLs. Any downstream caching of rendered HTML or image URLs will hold URLs that expire — a latent production failure mode that scales with adoption of fromStorage.
• Docblock-only deprecation of resize() gives no runtime signal, no IDE/static-analysis error, and no usage telemetry. We cannot measure remaining resize() usage to forecast a 3.0 rename. That is a planning blind spot, not a correctness bug.
• Semantic drift under the intent names. Intent methods are a promise about imgproxy option semantics ("fit never enlarges"). If upstream imgproxy changes behaviour or we pin a different instance version, the promise breaks silently and the name lies. Needs a compatibility note tied to the imgproxy version range we actually run.
• Conditionable adds when/unless to the builder's public surface. Low collision risk, but confirm nothing in our own subclassing/decoration of the builder already defines those names.

Key questions

1. What is the supported matrix (PHP, Laravel/illuminate/support versions, imgproxy versions) and is it tested in CI, or inferred? Conditionable availability is version-bound.
2. Is resize() → cover()/fit() targeted at a 3.0 with a real removal, and will there be a runtime deprecation notice or usage telemetry before then?
3. Does fromStorage() handle non-temporaryUrl-capable disks (local/local driver) gracefully, or does it throw? What is the documented behaviour?
4. Is the callback-return contract for when()/unless() on the immutable builder documented and tested in all three call styles?
5. Is optimize()'s WebP-by-default intentional for consumers who have not opted into format negotiation, and what is the recommended pattern for quality?
6. Test coverage and quality gates for this release — do the new intent methods have parity tests asserting exact emitted segments?
7. Maintenance model: bus factor, release cadence, and who owns the advanced-usage compositions if imgproxy semantics shift?

Integration Approach

Stack fit

• Fits our Laravel services directly; no new infrastructure, no sidecar, no config changes. Value is concentrated in application code readability and in fromStorage() removing hand-rolled disk/visibility logic.
• Best fit where image URLs are constructed in application code (controllers, resources, Blade). Services that already centralise image URL generation in one helper see less benefit and less churn.

Migration path

• Treat as an opt-in ergonomics release, not a migration. Pin ^2.2, upgrade, ship.
• Explicitly do not bulk-rewrite resize() call sites. Adopt cover()/fit() for new code and for files touched for other reasons.
• Add a static-analysis or code-review convention that flags new resize() usage, since the deprecation is docblock-only and tooling may surface it only as an annotation.
• Adopt fromStorage() after confirming private-disk temporaryUrl behaviour in each consuming service's disk configuration; do not let it become the default for asset types we have not classified.

Compatibility

• Verify our minimum Laravel/PHP support against the trait dependency before rollout; if any service sits below the Conditionable floor, it stays on the prior 2.x patch and that must be a recorded decision, not an accident.
• Confirm the pinned imgproxy version matches the semantics the intent names promise (particularly fit non-enlargement and format handling).
• Review any caching layer that stores generated URLs, for the pre-signed-expiry interaction.

Sequencing

1. Upgrade one low-risk service; run existing test suite and static analysis; confirm no drift and no resize() regressions.
2. Add tests for the three when() call styles and for fromStorage() on both a public and a private disk.
3. Land a short internal note mapping old → new methods (resize → cover/fit, explicit format options → toWebp() etc.), plus the optimize() defaults warning.
4. Adopt intent methods in new code; leave existing call sites alone.
5. Revisit a resize() sweep only once a removal or runtime deprecation is announced.

Operational Impact

Maintenance

• Low ongoing cost in code, moderate in surface area: two spellings for the same output means two things to keep tested and documented. The ADR and glossary are what keep that from becoming three spellings; they need to be maintained as first-class artifacts, not a one-off.
• Upstream maintenance burden on us is minimal — no new runtime, no new config, no versioned service contract.

Support

• Expect a predictable wave of "how do I contain / grayscale / coordinate-crop?" questions. Pre-empt with an internal FAQ pointing at advanced-usage and withOption(), framed as "intent methods cover the common cases; the typed layer covers the rest."
• Expect a second wave of "my image didn't change" reports traced to non-returning when() callbacks. One clear docs sentence plus a support runbook entry closes most of it.
• optimize() surprises (WebP + q=70) will present as "wrong file type" or "quality regression" tickets. Document the defaults prominently.

Scaling

• No scaling impact: this is URL construction only. No added I/O, no added network calls, no change to imgproxy load or cache behaviour beyond what the emitted options already cause.
• The one scaling-adjacent effect is indirect: optimize()'s WebP default will shift cache keys and content types across consuming surfaces if adopted broadly. Roll it out deliberately per surface rather than uniformly.

Failure modes

• Silently dropped builder mutations via when()/unless() (highest likelihood, lowest severity).
• Misclassified disk visibility producing durable public URLs for assets that should be private (lowest likelihood, highest severity) — inherited from the Storage macro but newly reachable via an easier entry point.
• Expired pre-signed URLs served from a cache (latent; appears as intermittent broken images after deploy or after cache TTLs).
• optimize() changing format where the consumer assumed format preservation (client-visible content-type / quality regressions).
• Intent-name/semantic drift if the imgproxy version range moves without re-validating the promised behaviours.

Ramp-up

• Low. Intent methods are the more teachable API and should shorten onboarding for engineers writing image URLs — cover(), toWebp(), storePublicly() are self-describing.
• Ramp-up cost sits with reviewers, not authors: reviewers must know when to send someone to withOption() rather than inventing a new intent method, and must know the when() return contract. A one-page internal convention note plus the ADR reference is sufficient.
• No training, tooling, or infrastructure work required to adopt.