Psr7 Cache Laravel Package

Product Decisions This Supports

• API write-safety (optimistic concurrency) — now the headline capability. The 0.5 release adds If-Match / If-Unmodified-Since support via $util->hasStateValidator($request) and $util->hasCurrentState($request, $eTag, $lastModified). This turns the package from a read-side caching helper into a way to prevent lost updates (two editors or two clients overwriting each other) without inventing a bespoke version column, advisory locks, or hand-rolled precondition parsing in every controller. That's a feature decision you can make now and a roadmap decision you can defer: you no longer need to budget a sprint for concurrency control on PATCH/PUT endpoints.
• Build vs. buy on HTTP semantics. Preconditions (RFC 9110 §13) are deceptively fiddly: header parsing, wildcard * handling, precedence between If-Match and If-Unmodified-Since, correct 412 Precondition Failed vs 304 Not Modified responses, and entity-tag comparison rules. Adopting a small, focused package is cheaper and lower-risk than owning that logic in-house.
• Bandwidth and infrastructure cost. Correct If-None-Match / 304 handling on GETs reduces egress and origin work for mobile clients, public APIs, and CDN-fronted responses. This is a directly measurable line item, useful when justifying work that otherwise looks like plumbing.
• Caching correctness as a product-quality lever. Weak ETag comparison for If-None-Match is a subtle but meaningful addition: it aligns behavior with proxies and compression layers that legitimately weaken tags, reducing "stale content served" and "cache never hits" bug classes that are painful to reproduce and often misattributed to the CDN.
• Use cases to prioritize: multi-user editing surfaces (CMS, dashboards, admin panels), idempotent/safe retry semantics for partner and webhook integrations, mobile-first APIs on metered networks, and read-heavy public endpoints where 304s pay for themselves.
• Sequencing note for the roadmap: safe-method caching (If-None-Match) and unsafe-method preconditions (If-Match) are independent rollouts. Caching can ship behind existing endpoints with near-zero client coordination; precondition enforcement is a contract change for API consumers and should be versioned, documented, and paired with a 412 error-handling story for clients.

When to Consider This Package

Adopt when:

• You expose resource-oriented HTTP endpoints (GET for reads, PUT/PATCH/DELETE for writes) and clients can reasonably hold an ETag or Last-Modified value between requests.
• You have — or expect — concurrent editors or retrying clients where silent overwrites are a real, support-ticket-generating risk.
• You want 304/412 semantics handled consistently rather than reimplemented per controller, and you value a small dependency surface over a full HTTP-caching framework.
• Your clients are first-party (your own SPA/mobile app) or well-behaved partners who can be updated in lockstep with the API contract.

Look elsewhere when:

• You need full-page or response-fragment caching, cache invalidation graphs, or tag-based purging — that's a different problem (HTTP cache / reverse proxy / Laravel response cache territory).
• Clients are uncontrolled third parties who won't send preconditions; enforcement of If-Match becomes a breaking change and you'll need a transition or opt-in strategy first.
• Your conflict resolution needs are semantic (merge, field-level diff, CRDT) rather than "reject the stale write" — preconditions give you detection, not resolution.
• Your write path is not resource-state-based (RPC-style action endpoints, event ingestion) where an ETag has no natural meaning.
• You require long-term support guarantees: at 0.x, expect API churn (see below), so pin versions and keep the integration behind a thin internal wrapper.

Risk to flag: the 0.x version number signals no stability promise. The surface is small, but wrapping the two utility calls behind your own abstraction costs little and buys you insulation from renames and signature changes in 1.0.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, low-cost library that makes our API behave the way HTTP is supposed to behave. Two concrete payoffs: (1) clients that already have the latest copy of a resource get a cheap "nothing changed" response instead of a full payload, cutting bandwidth and server load; (2) when two people or two automated clients try to modify the same record, the second write is rejected instead of silently clobbering the first. The second capability is new in this release and removes a class of data-loss bugs we would otherwise have to engineer around ourselves. Cost is a single dependency and modest integration work; risk is contained because the package is small, the behavior is standardized, and we can wrap it so a future version bump doesn't ripple through our code.

For engineering (one paragraph): Version 0.5 adds unsafe conditional request support — If-Match and If-Unmodified-Since — exposed as $util->hasStateValidator($request) (does this request carry a precondition?) and $util->hasCurrentState($request, $eTag, $lastModified) (is that precondition satisfied?). Together these give us optimistic concurrency control on writes: validate, return 412 Precondition Failed on mismatch, and clients get a standard, well-understood retry contract rather than a custom conflict payload. It also adds weak ETag comparison for If-None-Match, which fixes incorrect cache misses when intermediaries or compression weaken tags. Recommended integration: wrap both calls in a single internal trait or middleware so the package's pre-1.0 API churn is absorbed in one place, emit ETags on read endpoints first (low risk, immediate measurable benefit), then layer precondition enforcement onto mutating endpoints as a documented, versioned API contract change with client-side 412 handling shipped before enforcement is mandatory.