Laravel Image Laravel Package

Product Decisions This Supports

• Build vs. buy for the image pipeline. v2 covers the full path a product team would otherwise hand-roll: presets, responsive variants (width × format with exact dimensions from source metadata), signed URLs, render-once locking, disk storage, and CDN-friendly caching headers. That is a credible "buy/adopt" answer against a multi-sprint internal build.
• Roadmap sequencing for a platform upgrade. The package now hard-requires PHP 8.3+ and Laravel 12+, so adopting it is coupled to (or gated by) your framework modernization track. Treat it as a dependency of that initiative, not a standalone ticket.
• Performance and cost bets. AVIF/WebP output, immutable year-long caching on versioned URLs, ETag/304s, and correct responsive widths directly affect LCP/Core Web Vitals and image egress cost. This is the evidence needed to justify prioritizing an image-delivery workstream.
• Access-control product features. Signed, expiring URLs plus strict mode mean paid, gated, or private media can be served from the same pipeline without a separate auth proxy — useful for member content, downloads, and previews.
• Feature scope decisions on the client. The deliberate removal of the JavaScript package puts URL construction and signing entirely server-side. If a roadmap item depends on client-side transforms or in-browser cropping, that capability is explicitly out of scope here and needs another owner.
• Migration planning. The 1.x API returns as a compatibility layer, but only in the beta — so alpha is not a viable upgrade window for existing 1.x consumers. Schedule migration evaluation at beta, not now.
• Operational readiness as a launch gate. image:doctor (driver/formats, FFI/libvips, disk read-write-delete, lock store, signing key, route session-cookie leakage, URL host) is a concrete pre-launch checklist item for release management.
• Extensibility for a platform team. Published contracts with contract-test traits (ImageSpec, UrlCodec, Signer, SourceResolver, Renderer, DerivativeStore) mean custom renderers or stores can be owned internally without forking.
• Testability as a delivery-risk reducer. Image::fake() with an in-memory derivative store lets feature work proceed on the pipeline without real rendering in CI.

When to Consider This Package

Consider it when:

• You are on, or committed to, Laravel 12+ and PHP 8.3+ in the delivery window (CI covers 8.3–8.5 × Laravel 12–13 × GD/Imagick/libvips).
• You need first-party control of image derivatives: presets, responsive variant sets, on-the-fly formats, and a CDN in front — without operating your own image service.
• Your media lives on Laravel disks, including S3-compatible storage (ETag-derived versions, cached version_ttl), and you want one resolver for local and cloud sources.
• You serve private or entitlement-gated assets and want signed, short-lived URLs and enforcement of limits as a built-in rather than a bolt-on.
• You need render stampede protection — one render per derivative under a lock, with 503 + Retry-After instead of thundering-herd load on origin.
• You want a testing story and an ops diagnostic (Image::fake(), image:doctor) before you commit engineering time.

Look elsewhere or wait when:

• You need a production-stable dependency now. This is 2.0.0-alpha.1; it also depends on laravel-mediatheque 2 at its alpha and intervention/image >= 4.3.4. Two alpha dependencies in the critical path is a schedule risk, not a shipping plan.
• You are still on 1.x and expecting a drop-in upgrade — the compatibility layer is beta-scoped, so alpha is a hard break (1.x code and Imagine removed).
• Your roadmap depends on client-side image behavior (JS-driven transforms, browser cropping/preview); 2.x intentionally ships no JavaScript package.
• You already pay for a managed image CDN (Cloudinary, imgix, Cloudflare Images) and the marginal win doesn't justify owning renderer, lock store, and disk lifecycle.
• You run non-Laravel services alongside — the value proposition is Laravel-native and doesn't extend across the stack.
• Your team has no appetite for libvips/FFI/Imagick operational surface; image:doctor helps, but the driver matrix is still yours to support.

Recommended posture: pilot on a non-critical surface at alpha, plan the 1.x migration evaluation for beta, and gate GA adoption on a green image:doctor run in staging plus a documented PHP/Laravel upgrade path.

How to Pitch It (Stakeholders)

To executives: Image delivery is a measurable performance and cost line — page speed, SEO ranking, and CDN bandwidth. This package moves that capability in-house on infrastructure we already run (Laravel disks plus our CDN), with immutable caching and modern formats (WebP/AVIF) that cut bytes served. It also adds signed, expiring URLs so paid and private media ride the same pipeline instead of a bespoke proxy. The trade-off is timing: v2 is alpha, requires PHP 8.3+ and Laravel 12+, and pulls in two alpha-stage dependencies. Recommend funding a contained pilot now and committing to the upgrade at beta, not at GA.

To engineering: v2 is a clean rewrite around explicit contracts — ImageSpec, presets and their versions, UrlCodec/v2 URL syntax, Signer, SourceResolver, Renderer, DerivativeStore — each with contract-test traits, so custom implementations are supported rather than forked. The builder (Image::for($ref) → immutable PendingImage) gives presets, dimensions, fit/ratio, format, quality, signing, host, then url()/variant()/variants()/render(). Rendering is Intervention Image 4 with an auto driver (libvips → Imagick → GD), EXIF-uprighted, sRGB-converted, metadata-stripped. Delivery is a per-derivative lock with 503 + Retry-After, streaming or redirect, and correct Cache-Control/ETag/304 semantics. Config is split so you publish only what you change; signing keys derive from APP_KEY/APP_PREVIOUS_KEYS. Testing via Image::fake(), ops via image:doctor, CI is a full PHP × Laravel × driver matrix with Larastan at max.

To security/compliance: Signed URLs expire; private sources only ever get expiring signed URLs; strict mode forces signatures on free specs; limits are validated at URL-build time; the optional route checks signature and expiry (403) and, per image:doctor, flags whether it sets session cookies. Derivative metadata is stripped and color normalized — both privacy-positive defaults.

Risks to socialize: alpha status and alpha-pinned dependencies; a breaking jump with no 1.x compatibility layer until beta; PHP 8.3/Laravel 12 as a prerequisite that may itself be an unplanned program of work; and the operational surface of the driver stack (libvips/FFI/Imagick) that the team now owns.