Image Bundle Laravel Package

Getting Started

• Install/upgrade with composer require id-sign/image-bundle:^0.3.0 (or composer update id-sign/image-bundle). No template or config changes are required for this release.
• Immediately after upgrading, purge the derivative cache: bin/console image:purge --force. This is not optional — stale EXIF-rotated metadata and old contain/scale-down breakpoint variants will otherwise keep being served.
• Look first at three things: your bundle config (source paths, max_source_bytes, cache directory), the <twig:Image> component, and the image_url() helper. Those cover ~90% of day-to-day usage; the processor is an implementation detail.
• First use case to wire up: a responsive hero/CMS image with fit="scale-down" plus autoDimensions and blur, because that combination exercises every behaviour changed in 0.3.0 (effective dimensions, orientation, missing sources, breakpoints).

Implementation Patterns

• fit="scale-down" for user-uploaded or unknown-size media. It never upscales; as of 0.3.0 the emitted width/height and the w descriptors reflect the actual delivered pixels (source dimensions when the source fits the box), so you can trust them for sizes, layout reservation, and aspect-ratio CSS without a second getimagesize() call.
• contain / scale-down srcsets for art-directed layouts. Breakpoint heights are now rounded up, so every candidate is at least as wide as its descriptor. You can stop hand-computing breakpoint boxes or post-processing srcset strings.
• Let render-time metadata do the work. With autoDimensions and blur enabled, don't duplicate orientation/dimension logic in your own view models — the renderer now applies EXIF orientation identically to the processor, so attributes and placeholder always agree with the served file.
• Treat missing sources as a normal state in templates. Since 0.3.0 a missing/invalid src no longer throws; you get markup without height and without a blur placeholder, and image_url() 404s. Design the surrounding markup so a missing height degrades gracefully (fixed aspect-ratio wrapper, or a CSS background fallback).
• Validate before render, not during. Corrupt files and sources over max_source_bytes still fail loudly — catch those at upload/import time (Laravel validation rules, job-level checks) rather than discovering them in a Blade/Twig render.
• Cache warming is safe to retry. Nothing is written for a missing source, so a file uploaded after the first request is picked up on the next one — no manual invalidation needed for "upload then display" flows.

Gotchas and Tips

• Skipping the purge is the #1 upgrade trap. Old variants and EXIF-swapped blur placeholders persist in the cache indefinitely. Run image:purge --force as part of your deploy step, right after composer update.
• Duplicate variants are gone for small sources. Previously 1920/2048/2560 could all be generated from a 1408 px source; now they resolve to a single effective size. If you asserted on specific cache files or filenames in tests, update those expectations.
• Silent 404s instead of exceptions. Any monitoring or test that relied on a missing src throwing during render will now pass silently. Assert on the 404 from image_url() or on the absence of the height attribute instead.
• Corrupt files and oversized sources still throw. Distinguish "not there yet" (tolerated) from "there but broken" (fatal) in your error handling — the boundary is max_source_bytes and decodability.
• ImageMagick 6 + WebP EXIF orientation is unavailable. The processor doesn't rotate; render-time metadata doesn't either. Output is consistent but a portrait phone WebP stays sideways — normalize orientation on upload if that matters, or prefer JPEG/HEIC sources there.
• WebP files with an EXIF chunk are read in full (ping skips WebP EXIF). Expect a slightly heavier first read for those sources; the result is cached afterwards.
• Very thin sources now produce ≥1 px breakpoint heights. That's a fix, but it means you may see new, extremely small variants appear for banner/divider-style images — harmless, just not a regression.
• Extension point to watch: because render-time metadata and the processor now share orientation semantics, any custom driver or metadata override you've written must follow EXIF too, or <twig:Image> attributes will drift from the delivered file again.