Cache Plugin Laravel Package

Product Decisions This Supports

• Build vs. buy for API response caching: This is the official Saloon plugin, MIT-licensed, maintained by the framework's author, and version-tracked against Saloon releases (v3.0.0 → v3.1.0 for Saloon v4 → v3.3.0). Choosing it over a bespoke caching layer removes a small but real piece of infrastructure from our roadmap and our on-call surface.
• Roadmap sequencing around the Saloon v4 migration: Because v3.1.0 adds v4 support and v3.3.0 is purely additive, caching can be introduced during the migration rather than as a follow-up project. That lets us treat caching as part of the migration's value story ("we moved to v4 and got cheaper, faster API calls") instead of a separate line item.
• Feature bets that depend on aggressive caching being safe: The v3.3.0 clearCache() method purges a cached response without sending an outbound request. That single capability unlocks product features we would otherwise defer: an admin "refresh data" action, webhook- or event-driven invalidation after an upstream change (price update, catalog sync, profile edit), and post-deploy cache warming. Without it, invalidation required either a throwaway request or manual cache-backend surgery — a cost that quietly kills otherwise-viable caching features.
• Cost and latency modeling for read-heavy, low-volatility endpoints: Reference data, catalog and pricing snapshots, configuration, and third-party lookup calls are the natural candidates. This gives us a credible instrument for answering "what would we save if we cached this?" — and a cheap way to run that experiment in one module.
• Resilience/degradation options: Cached responses let a feature keep serving last-known-good data during an upstream outage. That is a product decision (tolerate staleness for availability) that this package makes affordable to test.
• Explicit non-decision: It does not justify a caching platform. There is no tag-based or grouped invalidation, no per-endpoint TTL policy engine, no distributed cache orchestration. If the roadmap needs those, that is a separate, larger bet.

Representative use cases: e-commerce product/pricing snapshots purged on catalog sync; SaaS profile/config reads purged on profile update; internal dashboards fronting CRM/ERP APIs with an operator-triggered refresh; any Saloon v4 client hitting a rate-limited third party.

When to Consider This Package

Adopt when most of these hold:

• The service already uses Saloon — ideally v4, which is mandatory from v3.1.0 onward. The value proposition collapses if we are not on Saloon.
• Target responses are idempotent (same inputs → same output) and low-to-moderately volatile. Caching a live stock ticker is a bug factory, not an optimization.
• We need single-entry, event-driven invalidation and are satisfied with per-request TTL. clearCache() covers the "purge this one thing now" case well.
• We already run a PSR-16 cache backend (Redis, database, filesystem via Laravel's cache). This is a thin adapter over infrastructure we own, not a new dependency to operate.
• We want zero-architecture-change adoption: withCache() on a request or connector, no refactor, no new service.
• We accept vendor concentration risk: the package is official but small (13 stars, 0 dependents). It is maintained, but its continuity is tied to one primary author and the Saloon project's health, not to a broad contributor base.

Look elsewhere — or build — when:

• We need cache taxonomies: tag-based or grouped invalidation, cascading purge across related endpoints, per-endpoint TTL policy, or cross-service cache coordination. clearCache() is single-entry; it is not a cache management layer.
• Responses are highly dynamic or personalized per user in ways the cache key does not capture. Note that request body and query-string support in the cache key arrived incrementally (v0.3.0, v2.1.0) — key correctness for our specific request shapes must be verified, not assumed, especially for POST-style lookups.
• We are not on Saloon, or we are pinned to Saloon v2/v3 and cannot move. v3.1.0 made v4 the target; this is a dependency-pinning constraint, not a soft preference.
• Compliance, PII, or audit obligations apply to cached payloads — data residency, retention limits, encryption at rest, or a requirement that every cache purge be attributable to a person or event. These are solvable, but they are our work, not the package's, and they change the effort estimate materially.
• We need scale evidence. Adoption is thin. The package is production-plausible but not production-proven at volume; treat stampede/thundering-herd behavior under concurrent misses as unverified until we test it.

How to Pitch It (Stakeholders)

For executives — the decision in one paragraph: "We are already paying for every outbound API call, in money and in latency. This is the official, MIT-licensed caching plugin for Saloon, the HTTP layer we already use, and it now supports Saloon v4 plus on-demand cache purging. That combination matters: it means we can cache read-heavy third-party data aggressively without accepting stale data as the price of admission — a webhook or an admin action clears the entry immediately. It is a small dependency over cache infrastructure we already run, requires no architectural change, and can be piloted inside one module. The honest caveat is that the project is small and effectively single-maintainer; the mitigation is that it is a thin adapter we could replace in days, not a platform we would be trapped in. Recommendation: approve a scoped pilot, not a company-wide mandate."

For engineering — what it is and what we'd own:

• Drop-in integration: caching is declared per request or per connector (withCache()), with clearCache() for explicit purge. No middleware plumbing to write, no changes to how requests are defined.
• Storage is our choice: PSR-16, so Redis/DB/file backends we already operate. No new datastore.
• The real win is lifecycle: v3.3.0 lets us invalidate without firing a request, which removes the "fake request to bust the cache" hack and makes write-then-invalidate flows clean.
• What we take on: cache-key correctness for our request shapes (body/query inclusion must be verified case by case), TTL policy per endpoint, and — if purges are user-triggered — wiring invalidation into our audit trail.
• What we don't get: tag/group invalidation, distributed coordination, or stampede protection. If the pilot succeeds and traffic grows, budget for these explicitly rather than assuming the plugin absorbs them.
• Version note: v3.1.0+ requires Saloon v4. Pin deliberately; this is a coordinated upgrade, not a drop-in for legacy clients.
• Proposal: two-week proof of concept on one endpoint (suggest: highest-volume, lowest-volatility call), with clearCache() wired to a real invalidation event. Success criteria: measured reduction in outbound calls, p95 latency improvement, and zero stale-data incidents across the pilot window. Exit criteria defined up front, and a fallback that is a same-sprint swap back to uncached calls.