Image Cache Laravel Package

Technical Evaluation

Architecture fit. bagisto/image-cache is a thin caching decorator around the Intervention Image class — it intercepts transformation closures, hashes the source path plus parameters into a key, writes the derivative to disk or a cache store, and serves it on subsequent requests. Architecturally that is a very small surface area: one service provider, a config file, and a hash-to-file layer. It does not introduce a new runtime, a new datastore, or a network hop. For a Laravel/PHP commerce stack already using Intervention Image v2, this is a natural insert into an existing pipeline rather than a new subsystem. For anything else, it is not an integration problem, it is a porting problem.

Integration feasibility. The gating condition is version compatibility, and it is binary. This lineage depends on ImageManagerStatic and Intervention\Image\Response, both removed in Intervention Image v3. A v3 shop is not installing this package; it is rewriting it (or writing the ~150-line equivalent). Secondary feasibility checks: confirm the service provider FQCN, because forks frequently retain the upstream Intervention\Image\ImageCacheServiceProvider namespace for drop-in compatibility while the Composer package name differs — auto-discovery may or may not fire correctly. Confirm the config is genuinely published and configurable (route, paths, templates, lifetime, cache driver) rather than hardcoded; that single fact determines whether the rollout is configuration or surgery.

Technical risk. Ranked:

1. Zero stars, zero dependents, no upstream. This is effectively an internal component of Bagisto published as a standalone package. There is no issue tracker to escalate to and no community to have already found the bugs. We own it if it breaks. That is a decision, not a risk to be mitigated — it must be explicitly accepted.
2. Stale derivatives on source replacement. If the cache key is source path + parameters, swapping a product photo does not change the key. Customers see the old image until TTL expiry. This is the highest-severity product-visible defect and requires us to inject a version token (mtime, updated_at, or content hash) into the key. Non-negotiable before go-live.
3. Silent degradation to 100% miss. A Laravel or Intervention upgrade can break static resolution without throwing; you simply stop hitting cache and start regenerating. Latency degrades, nothing alerts. This needs instrumentation we add ourselves.
4. Path traversal / cache poisoning on the route endpoint. Route-based delivery takes a filename from the URL. With no external audit, we must independently verify the paths config is an allow-list and filenames are normalised.
5. No eviction, no locking. Unbounded disk growth and a cold-cache thundering herd on campaign launch are both foreseeable and both ours to handle.

Key questions for the team.

• Which Intervention major version are we on, across every service that renders images?
• Is this package actually coupled to Bagisto's config, paths, and storage conventions, or is it genuinely framework-generic? (If coupled, the honest comparison is "write our own decorator.")
• Does it use file_put_contents or the Storage facade? This determines whether we get per-node caches and deploy-time cold starts.
• Who owns the escape hatch, and is it costed? The whole dependency is replaceable in roughly half a day.
• What is our measured derivative count per SKU and total catalog size — the storage number, not a guess.

Integration Approach

Stack fit. Good only under specific conditions: Laravel, PHP, Intervention Image v2, self-hosted images, multiple derivative sizes per asset, meaningful but not extreme traffic. Under those conditions the fit is tight — the package decorates a library we already depend on and adds no new moving parts. Outside them (v3, non-Bagisto with heavy coupling to Bagisto conventions, or a managed-service-first strategy) the fit is poor and the correct answer is either a port or a CDN with edge transforms.

Migration path. Treat this as an additive change behind an abstraction, not a substitution. Sequence:

1. Verification gate first — composer show intervention/image must report ^2.x. If it reports v3, stop and re-scope to "port" or "build our own"; do not proceed.
2. Read the source before installing. It is small. Twenty minutes in src/ and composer.json is worth more than the README, which is not authoritative here.
3. Introduce a domain helper (ProductImage::url($sku, $template)) as the only call site. Every view and controller goes through it. This is the single most important sequencing decision: it gives us one place to add key versioning, placeholders, instrumentation, and — if we need it — a swap to our own implementation without touching call sites.
4. Migrate one low-risk, high-fan-out surface first: category listing thumbnails. Measure the hit rate and TTFB delta before expanding.
5. Define derivative presets in config (thumb, pdp_zoom, cart, og) rather than inline dimensions. This turns "how many sizes per SKU" into a reviewable config diff and gives product a governed lever.
6. Expand to PDP and cart, then admin previews. Keep the route-based delivery mode for public storefront assets (CDN/browser cacheable); use closure mode with $returnObj = true for anything post-processed or streamed.

Compatibility. Pin the exact version (1.0.x), commit the lock file, and vendor the source. Budget a standing hour per quarter to re-check against Laravel and Intervention upgrades — this is the maintenance tax of a zero-dependency-graph package. Also verify lifetime units: this lineage defaults to minutes, while Laravel's cache TTL is seconds. Getting that wrong produces a cache that expires five seconds after warm-up, which looks identical to a cache that does not work.

Sequencing constraint. Do the key-versioning change and the instrumentation before the first production expansion — not after. Both are cheap to add at the start and expensive to retrofit once there are call sites in views.

Operational Impact

Maintenance. Low volume, non-zero, and entirely ours. No upstream to file against means every compatibility break is a work item we triage internally. Realistic cost: a small quarterly review plus ad-hoc source reading when something misbehaves. The offsetting fact is the escape hatch — the entire surface is a hash-to-file decorator, so inlining a ~150-line equivalent with Storage-facade writes, a version token in the key, and an eviction command is roughly half a day. That should be a documented, costed fallback plan, not a hypothetical.

Support. There is no support relationship. Zero stars and zero dependents means no community triage, no Stack Overflow corpus, no security advisories. Support model is "we own it," which must be stated plainly to stakeholders rather than softened. The mitigating factor is code size: small enough to read entirely, which is rarely true of dependencies we accept.

Scaling. Two axes, and they fail differently.

• CPU scales well: derivatives are computed once and re-served, which is the point. This is the lever that keeps web nodes small and survives a campaign spike without a render storm.
• Storage scales linearly and without a ceiling. Five derivatives per SKU at 1200×1200 is a predictable number of gigabytes — calculate it from the real catalog before rollout, not after. Nothing in the package caps growth; we write the find -mtime sweep or a scheduled prune command.
• Multi-node behaviour depends on the write mechanism. If it writes with file_put_contents to a local filesystem, hit rate falls roughly with node count, and every deploy cold-starts the cache. Neither breaks the app; both invalidate capacity assumptions.

Failure modes. In rough order of likelihood:

1. Silent 100% miss after an upgrade — no exception, just regeneration on every request and degraded latency. Mitigation: emit a hit/miss metric from the helper so a latency alert has a cause attached. This is the highest-value operational addition we make.
2. Stale images after replacement — customer-visible, persists until TTL. Mitigation: version token in the cache key, shipped before go-live.
3. Cold-cache thundering herd — N concurrent requests regenerate the same derivative; no locking, no atomic-write coordination. Mitigation: queued warm-up for the two or three hottest templates only, rate-limited, after imports and deploys. Everything else stays on-demand.
4. Disk exhaustion — slow, predictable, and entirely preventable with a prune job.
5. Path traversal / cache poisoning on the route endpoint — low probability, high severity, and un-audited by anyone else. We verify the paths allow-list ourselves.

Ramp-up. Small. Any Laravel developer productive within a day; the mental model is "closure in, hashed file out." The two things that must be taught explicitly rather than discovered: the whole edit chain goes inside the closure (chaining outside silently bypasses the cache and is the most common misuse), and lifetime is minutes not seconds. Testing should assert on the key — identical requests produce one file, changed dimensions produce two, replaced source produces whichever behaviour we chose — because that last assertion is the only proof we have an invalidation story.

Scope discipline. This is not an optimizer, not a DAM, not a CDN. No WebP/AVIF Accept negotiation, no compression tuning, no signed URLs, no responsive srcset. Those are separate roadmap items with separate owners. Bundling them into this bet is how an image initiative absorbs three sprints with no clear accountability.