Cache Plugin Laravel Package

Technical Evaluation

Architecture fit

• A caching plugin for Saloon sits in the HTTP-client layer, not the domain layer. For a TPM this is the cheapest possible insertion point: it changes no contracts, no schemas, no service boundaries — it changes how many times an outbound call is made. That makes it a configuration decision, not an architecture decision, which is precisely when a package like this delivers the most leverage per unit of political capital.
• Scope of leverage is narrow but real: idempotent, read-heavy, low-volatility outbound APIs (catalog/reference data, pricing snapshots, profile/config reads, third-party rate-limited endpoints). It is not a fit for write paths, per-user personalised responses with mixed cache keys, or real-time data — and a TPM should say so up front to prevent someone applying it as a general performance strategy.
• The v3.3.0 clearCache() addition is the commercially interesting change. Without it, caching is a latency/cost trade paid for with staleness — a trade that product owners almost always veto. With explicit, request-free purge, the trade becomes: cache aggressively, invalidate on a known event. That converts a "should we cache?" debate into a "which events invalidate this?" design exercise, which is a far easier conversation and a far cheaper one.
• Plugin over platform: this is per-request opt-in, so a single team can adopt it inside one integration without a platform-wide mandate or shared cache infrastructure. Politically cheap, technically reversible — the two properties you most want in a first adoption.

Integration feasibility

• Integration surface is small: opt a request into caching, set a TTL, optionally define a cache key, call clearCache() (or bypass) where freshness matters. Realistically a 1–3 day ticket for a competent Laravel engineer on one endpoint, plus test coverage. That is well under any threshold where a buy/build analysis needs to be escalated.
• Hard prerequisites — treat these as gating checks, not notes: Saloon v4 (v3.1.0+ requires it; v3.x is the only line you should run), PHP 8.1+ (8.5 supported as of v3.0.1), and a PSR-16 cache store. If the platform standard is Redis, you already have the store; if it is file cache, verify performance and eviction behaviour before committing.
• Vendor-name churn is a real historical signal: the package moved Sammyjo20/saloon-cache-plugin → saloonhttp/cache-plugin → saloonphp/cache-plugin across v1.1.0/v1.2.0 and v2.2.0/v2.3.0. No functional breakage, but it means composer constraints and lockfiles must pin exact versions and any internal documentation must reference the current namespace. Cheap to handle, embarrassing if missed during an audit.
• Build-vs-buy is genuinely favourable: a hand-rolled equivalent (key derivation, TTL, invalidation, PSR-16 adapter, test doubles) is maybe 300 lines plus ongoing ownership. The package is MIT, so the fallback position is "fork it," not "renegotiate." A TPM should frame it as buy with a fork option, and record that in the ADR.

Technical risk

• Bus factor of one. 13 stars, zero Packagist dependents, single primary maintainer, and a contributor base measured in ones. Zero dependents is the number to be honest about internally: it does not mean unused, it means no downstream package will catch a regression for you, and no ecosystem pressure exists to fix one.
• No commercial SLA, no security disclosure process visible in the sources reviewed. Mitigations are organisational, not technical: pin versions, run composer audit in CI, avoid auto-merging minor bumps in production integration, and keep a fork-ready posture. Budget roughly 0.5–1 day per quarter of a senior engineer's attention as the carrying cost.
• Cache-key correctness is the highest-severity risk and it is ours, not theirs. Query strings and bodies are included in the key (v0.3.0, v2.1.0), but authorisation scope, tenant identity, locale, and version headers must be explicitly considered. A key that omits user/tenant context on an authenticated endpoint is a cross-tenant data exposure, not a performance bug. This needs a security review sign-off before any endpoint carrying user-specific data is cached.
• No documented stale-serving / failover semantics. Do not let a stakeholder assume this doubles as a resilience feature ("serve cached data when the vendor is down") without verifying behaviour on origin errors. If resilience is the goal, that is a separate design and a separate ticket.
• Three live major lines (1.x, 2.x, 3.x) is a support-matrix trap. Documentation, Stack Overflow answers, and blog posts will be a mix of all three. Mandate v3.x and state it in the ADR.

Key questions

1. Which specific endpoints are candidates, and what is the measured call volume, p95 latency, and vendor cost per call for each? Without this, the business case is anecdotal.
2. What is the volatility of each candidate dataset, and what invalidation events exist (webhook, admin action, deploy hook, upstream sync job)? If no invalidation hook exists, clearCache() buys nothing.
3. Do any candidate responses vary by user, tenant, role, locale, or currency? If yes, who owns proving the cache key covers every discriminator?
4. Is there an existing cache standard (Redis, Memcached, file) and does the chosen TTL policy align with data-freshness obligations in any customer contract or SLA?
5. Who is the named owner of this dependency — for version bumps, fork decisions, and incident response?
6. Has Saloon v4 adoption itself been approved? If we are mid-migration on Saloon v3, this plugin's v3 line does not help us yet.

Integration Approach

Stack fit

• Assumes Laravel/Lumen with Saloon as the outbound HTTP layer and an existing PSR-16 store. If the team is on Guzzle or Symfony HTTP Client directly, this package is irrelevant and the correct answer is a middleware, not a plugin — say so and close the ticket rather than forcing an adapter.
• Best first targets, ranked by leverage-to-risk: (1) third-party reference/catalog data with a nightly sync, (2) rate-limited vendor APIs where quota, not latency, is the constraint, (3) config/feature-flag style reads, (4) vendor endpoints with published ETags/updated_at so freshness is objectively verifiable.
• Explicitly out of scope for the pilot: anything with user-specific payloads, anything under a contractual real-time obligation, anything on a payment or authorisation path.

Migration path

• Greenfield: add the plugin at integration creation; no legacy considerations. This is the cheapest path and the one to prefer — the plugin supports Saloon v4 from v3.1.0, so new integrations get caching for free.
• Brownfield on Saloon v3: two moves, and the order matters. First upgrade Saloon to v4 and the plugin to v3.x, verified with existing integration tests; only then introduce caching. Bundling both into one change makes it impossible to attribute a regression.
• Brownfield with homegrown caching: migrate endpoint by endpoint, not wholesale. Run the old path behind a feature flag alongside the plugin on one endpoint, compare hit ratio and payload equality, then delete the old code. Never run two caching layers over the same endpoint simultaneously.

Compatibility

• Pin the plugin to an exact v3.x version in composer.json; do not use a caret range across a major. Lockfile diffs touching saloonphp/* should be a reviewed change, not incidental.
• Verify PSR-16 store compatibility and TTL granularity on the actual production store — file caches and Redis differ on eviction, serialisation, and key-length limits.
• Check the cache-key implementation against the platform's auth model before enabling on any endpoint that forwards a user token upstream to the vendor.
• Confirm PHP version support against the platform's supported-runtime policy (8.5 support landed in v3.0.1; older minors should be already retired).

Sequencing

1. Week 0 — ADR and guardrails. Record the decision, the pinned version, the named owner, the fork trigger conditions, and the exclusion list. Get security sign-off on key derivation for authenticated endpoints. This document is the deliverable that survives staff turnover.
2. Week 1 — Instrumented pilot on one endpoint. Deploy with hit/miss metrics and origin-call volume captured before the change as a baseline. One endpoint, one team, feature-flagged.
3. Week 2–3 — Measure against gate criteria (below). If the gate fails, stop; the sunk cost is one engineer-week and the learning is real.
4. Week 3–4 — Invalidation wiring. Add clearCache() to the events identified in design (post-sync, admin refresh, webhook). This is where the product value actually lands; skipping it leaves you with TTL-only caching and the staleness argument returns.
5. Week 5 — Expand to the ranked candidate list, one endpoint per PR, with the key-derivation review repeated each time.
6. Ongoing — quarterly dependency review, including a check on whether the upstream project still justifies the fork-avoidance position.

Gate criteria for expanding beyond the pilot (agree these before starting, or the pilot will be judged on vibes):

• Cache hit ratio above an agreed floor (typically 40–60% for these workloads — set it from the baseline, not from a benchmark).
• p95 latency improvement on the cached path demonstrable in production, not just locally.
• Zero correctness defects; payload equality verified on cached vs uncached responses.
• Origin call volume reduction translated into a currency figure for the vendor invoice or quota headroom — this is the number that gets the next team's attention.

Operational Impact

Maintenance

• Carrying cost is genuinely low but not zero: roughly 2–4 hours per quarter for version review, plus one engineer-day per Saloon major upgrade. Compare against the ongoing ownership of an in-house cache layer, which is a permanent, unglamorous tax.
• Vendor renames have happened twice. Any internal runbook, architecture diagram, or onboarding doc referencing saloonhttp/cache-plugin is now wrong. Include a doc-grep in the adoption checklist; it is a five-minute task that prevents a genuinely confusing support ticket.
• Assign a named owner and a secondary. Single-maintainer upstream plus unnamed internal owner is the combination that turns a two-hour fix into a two-week outage.

Support

• No commercial support, no SLA, no visible security disclosure channel in the reviewed material. Internal escalation path therefore ends at "the team that adopted it." Set that expectation with stakeholders before the first incident, not during it.
• Practical support policy: we fix or fork; we do not wait. For a scoped MIT plugin that is a defensible posture — but only if someone has actually read the source. Make that a task in the pilot, not an aspiration.
• Route all issues through one internal channel so pattern-level problems (e.g., a store behaving differently in production) are visible rather than rediscovered per team.

Scaling

• Scaling characteristics are dominated by the cache store, not the plugin. Redis: fine to very high throughput. File cache: fine for low volume, a liability under load and across multiple app servers — never let a file store ship to a horizontally scaled environment.
• Cache stampede is the scaling failure that matters operationally: many concurrent misses on a cold key can produce an origin-call spike precisely when the vendor is already struggling. Confirm whether the plugin provides any request coalescing or locking; if not, plan for it (staggered TTLs, jitter, or warm-on-deploy) before traffic scales.
• Cache volume and eviction policy need a dashboard. Unbounded key growth from high-cardinality cache keys is the quiet way this becomes an infrastructure cost centre instead of a saving.
• Multi-tenant scale raises key-cardinality by an order of magnitude; model that before enabling on tenant-scoped endpoints.

Failure modes

• Stale data served as current — the headline product risk. Mitigation: explicit invalidation events, conservative TTLs on high-volatility data, and a visible updated_at on any UI consuming cached data. If a customer-facing price is wrong, the root cause will be described as "the cache," regardless of the technical truth.
• Cross-tenant leakage via under-specified cache key — low probability, severe impact, entirely our fault. Mitigation: mandatory security review per endpoint class, plus a test that asserts two different auth contexts produce different keys.
• Silent cache-store outage — depending on behaviour, a failed store either fails the request (availability incident) or bypasses the cache (origin-call surge and possible quota exhaustion). Establish which, and add vendor-quota alerting so the second case is caught by the invoice rather than by a customer.
• Upstream vendor changes response shape — a cached payload can outlive a contract change, so clients see two shapes in one TTL window. Mitigation: include an API-version discriminator in the cache key, and purge on vendor version bumps as part of the release checklist.
• Abandonment — the maintainer stops shipping. Not an outage, a decay: security patches stop, Saloon majors pass it by. Mitigation: fork-readiness assessment at each quarterly review, with the trigger condition written down in advance.

Ramp-up

• A Laravel engineer who already knows Saloon needs 2–4 hours to be productive: opt-in, TTL, key, purge. The API is small, which is a genuine advantage — the risk here is not learning curve, it is overconfidence about key design.
• The knowledge that actually needs transfer is not "how to use the plugin" but "how to decide what may be cached." Write a one-page internal standard: the candidate criteria, the key-derivation checklist, the mandatory invalidation hook, and the exclusion list. That page is worth more than any amount of upstream documentation and is the TPM's most durable contribution here.
• Onboarding artefact: the pilot's before/after numbers (hit ratio, latency, origin calls, cost delta) alongside the ADR. New joiners absorb a business case faster than an API reference, and it pre-answers the "why are we doing this?" question the next team will ask.
• Keep the ramp-up cheap deliberately — this package's value proposition is that it costs almost nothing to try and almost nothing to abandon. Preserve that property: feature-flagged, one endpoint at a time, no platform-wide mandate until the numbers justify one.