Model Cache Laravel Package

Product Decisions This Supports

• Read-heavy feature scaling ("can we survive 10× traffic?"): this package caches Hyperf model query results and invalidates them automatically on create/update/delete, so a spike on catalogue pages, CMS content, dashboards, or hot profile endpoints becomes a TTL/prefix configuration conversation instead of a re-architecture sprint. It buys headroom for one or two quarters while the real bottleneck is prioritised.
• Build vs. buy on the caching layer: the alternative is hand-rolled cache-key generation, TTL policy, and invalidation observers per model. That work is undifferentiated, easy to get subtly wrong, and its failure mode is a public stale-data incident. Adopting a maintained library is the cheaper risk.
• Making staleness an explicit product parameter: the useful decision is not "is caching good" but "what staleness can this feature tolerate?" A ~24h default TTL with event-driven invalidation is fine for editorial content and catalogue detail; it is unacceptable for balances, stock counts, or permission material (roles, bans, API tokens), where a missed invalidation becomes privilege escalation or a wrong price. That line-drawing is a PM call, documented as a per-model policy, not an engineering afterthought.
• Sequencing infrastructure investment: a caching tier here can justify deferring read replicas, a CDN tier, or aggregate tables — but only where profiling shows query-layer time as the dominant cost. It is a deferral argument, not a substitute for the bottleneck work.
• Multi-tenant / multi-service isolation decisions: cache tags and a configurable key prefix let each service or tenant be purged independently. This supports launch decisions about sharing a Redis instance across services and environments without one team's flush evicting another's data.
• Incident-response posture: the existence of a kill switch (MODEL_CACHE_ENABLE=false, which degrades findFromCache to find) means a cache-related outage has a one-flag rollback. That materially lowers the severity class of the decision to adopt.
• Framework caveat that shapes the decision: this is a Hyperf 3.x package (Swoole/Swow coroutines), not a Laravel package. It cannot be composer required into a Laravel app. If the estate is Laravel, treat it as a reference design for genealabs/laravel-model-caching — the patterns map almost 1:1 — and make the adoption decision on the Laravel equivalent. Choosing this package is effectively a framework decision.

When to Consider This Package

Consider it when:

• The service already runs on Hyperf (or a migration to it is genuinely funded and scheduled). Otherwise the integration cost is a framework bet, not a library bet.
• Read/write ratios on hot models are heavily skewed (roughly 10:1 or worse) and profiling points at the database as the dominant cost.
• The dominant access shape is a keyed single-row or batched lookup — user profile, product detail, feature-flag/config row — read hundreds of times per write. That is the only shape this package optimises for; it does not cache paginate(), count(), or aggregates (use hyperf/cache there).
• You want invalidation owned by model lifecycle events rather than scattered manual Cache::forget() calls, and the team will route all mutations through hydrated models (save(), delete(), destroy()).
• Redis (with a verified cluster flag) and cache-hit-rate monitoring are already in place. An unmonitored cache is a silent stale-data generator.

Look elsewhere when:

• The stack is Laravel, Symfony, or plain PHP — pick the idiomatic equivalent rather than fighting an incompatible ecosystem.
• Writes are frequent relative to reads, or the feature needs read-your-own-write semantics (ledgers, balances, checkout inventory). Event-driven invalidation still leaves race windows, including inside DB::transaction() where a backfill can read an uncommitted row.
• Write paths bypass model events — Model::query()->where(...)->update(), increment()/decrement() on the builder, upsert(), raw DB::update(). These are the number-one source of stale data here and require manual invalidation discipline the team may not sustain.
• Soft deletes are load-bearing: findFromCache() builds from cached attributes and does not run global scopes, so a delete path that skipped an event keeps serving the row.
• Models use composite primary keys (unsupported — only the single key column is used for mget).
• You are caching authorization material.
• Adoption-risk reading of the numbers: 2 GitHub stars and a bare changelog-only patch release (v3.2.3, covering v3.2.0 → v3.2.3) mean thin public community signal. The Hyperf org backing and MIT licence mitigate this, but for a critical path, budget for the option of forking or maintaining the HandlerInterface seam yourself. Small stars is not disqualifying in-framework — it does mean "buy" here is really "buy from the framework vendor."

On v3.2.3 specifically: patch-level, no stated breaking changes, no deprecations, no new capability. It is a maintenance signal (the project is alive and patching), not a feature signal. Do not let it shift roadmap priority or trigger an upgrade scramble — pin ^3.2 and run it through the normal dependency cycle.

How to Pitch It (Stakeholders)

For executives (one paragraph): We can absorb a meaningful spike in read traffic on our data-heavy pages without new infrastructure by adding a caching layer that stays automatically in sync with our data — a configuration and dependency change rather than a re-architecture, with a one-flag rollback if anything goes wrong. The main risk is stale data if we cache the wrong things, so we would scope it to content and catalogue reads first and explicitly exclude money-, stock-, and permission-critical paths. Two caveats: the package under review targets the Hyperf framework, so if we remain on Laravel we should adopt the equivalent library rather than this one; and its public community footprint is small, so the realistic posture is "adopt the framework vendor's component and keep the handler layer as our extension seam."

For engineering (short): query-result caching tied to model events, with lifecycle-based invalidation instead of hand-written keys. Reads are explicit and opt-in at the call site (findFromCache, findFromCacheMany) — the trait does not hijack find(), so adoption is incremental and reversible per endpoint. Before we adopt: (1) confirm framework fit — Hyperf only; (2) agree a per-model TTL and key-prefix policy, plus an explicit deny-list of models that must never be cached; (3) audit write paths for builder-level bypasses and decide the invalidation-after-commit pattern for transactional writes; (4) namespace prefix per app/env/service so staging can never flush production; (5) bind ArrayHandler in tests so suites don't touch Redis. Latest release is a patch bump with no documented breaking changes or features — upgrade on the normal cycle, not urgently.

Definition of success, first 30 days: a measurable drop in database load and p95 latency on the hot endpoints we cache, with no increase in stale-data incidents. Instrument hit rate and the specific mc:* key space before launch, run a warm-up command post-deploy to avoid a cold-cache stampede, and review the deny-list once traffic data is in. If a "cache bug" appears, flipping the kill switch tells us within minutes whether the read path is fine and the problem is invalidation — that triage speed is part of the value.