Laravel Guided Image Laravel Package

Product Decisions This Supports

• Build vs. buy for image derivatives: this package is a thin, opinionated Laravel wrapper around Intervention Image for template/guide-driven image generation (crop, resize, and derivative variants from a defined image guide). It removes the need to hand-roll crop math, driver configuration, and per-template rendering logic — a build-vs-buy decision that usually favors buy for standard media pipelines.
• Feature scope for media/upload workflows: supports user avatars, product/catalog imagery, CMS thumbnails and hero variants, listing cards, and any surface where the same source image must be emitted at multiple aspect ratios or crop anchors. Useful input to roadmap decisions on media management, DAM, and CDN work.
• Platform upgrade sequencing: v5.0.0 requires Laravel 11+ and moves to Intervention Image v3. This makes the package a dependent variable in the Laravel 10 → 11 upgrade plan; teams still on Laravel 10 must either pin v4.x or sequence the framework upgrade first.
• Reduce bespoke maintenance: replaces in-house image helper classes and per-project Intervention wiring with a maintained package, lowering long-term ownership cost and test surface for a non-differentiating capability.
• Consistency of output: guide-based templates let design/product define crop behavior once and reuse it across channels, reducing ad-hoc "this image looks wrong on mobile" defects.

When to Consider This Package

Adopt when:

• The application is on Laravel 11 or newer (PHP 8.2+), with the GD or Imagick PHP extension available — Intervention Image v3 requires PHP 8.1+ and a configured image driver.
• You need declarative, template/guide-based image generation (fixed aspect ratios, crop anchors, multiple derivative sizes) rather than one-off resizing calls scattered through controllers.
• Your team wants a small, Laravel-native dependency instead of a full DAM, media library, or external transformation service.
• You are comfortable with Intervention Image v3 as the underlying engine and can absorb its API changes in your own code and tests (driver setup, ImageManager, read/encode calls).

Look elsewhere when:

• You are on Laravel 10 or below and are not upgrading soon — v5 is a hard break; stay on v4.4.x or defer.
• You need dynamic, URL-driven transformations at the edge (Imgix, Cloudinary, Glide, Cloudflare Images) or a full DAM/media library with storage abstraction, responsive sets, and conversions (e.g. Spatie Media Library). Those overlap heavily and mixing them creates duplicate pipelines.
• You need capabilities beyond deterministic crop/resize — AI subject-aware cropping, background removal, format negotiation/AVIF policy, or video.
• Bus factor and release cadence are concerns: this is a single-maintainer package, and v5 is a major-version jump tied to a framework major. If your organization requires vendor SLAs or long support windows per major, budget for a fork or an internal wrapper.

Migration notes for existing adopters: v5.0.0 is breaking — dropping Laravel ≤10 and adopting Intervention Image v3 means reviewing any code that touches the underlying image objects, re-validating driver config and cache paths, and regression-testing rendered variants (dimensions, quality, EXIF orientation) before rollout.

How to Pitch It (Stakeholders)

For executives: This package is a small, low-cost dependency that standardizes how our product images are cropped and resized, so the same source image renders correctly across web, mobile, and marketing surfaces. The new v5 release aligns it with Laravel 11 and the current Intervention Image engine — good for security and supportability, but it forces us onto Laravel 11 and is a breaking upgrade, so it should be scheduled as part of the framework upgrade, not as a standalone change. Risk is contained: the package is a thin wrapper, replacing it would be a few weeks of engineering, and it is not customer-facing on its own.

For engineering: v5.0.0 upgrades to Intervention Image v3 and requires Laravel ^11 (drops Laravel 10 and below). Plan the bump alongside the Laravel 11 upgrade; pin v4.4.2 on any service that cannot move yet. Expect work in three places: driver/config initialization for Intervention v3, any direct use of image objects in our own code, and snapshot/visual tests for generated derivatives (dimensions, crop anchors, quality, EXIF). Validate GD vs. Imagick availability per environment and clear cached/config artifacts. Because it is single-maintainer, keep our integration behind a thin internal service so we can swap engines without touching feature code.

Decision requested: approve the Laravel 11 upgrade window as the trigger for this package's v5 adoption, and confirm we are standardizing on Intervention Image v3 rather than introducing a second image pipeline.