Cachelet Query Laravel Package

Getting Started

v0.1.0 is the first public release, and the release notes are deliberately thin — they tell you the package is a read-only split published from the main Cachelet monorepo (https://github.com/oxhq/cachelet). That single fact should shape your first hour with it:

1. Read the monorepo first, not this repo. Splits typically contain the package source and a generated/synced README, but the authoritative docs, examples, changelog, and issue tracker live in oxhq/cachelet. Start at the monorepo README and any docs/ folder there.
2. Install via Composer using the package name shown on its Packagist page (vendor is oxhq; confirm the exact package name before running composer require). Pin it explicitly — see Gotchas on pre-1.0 versioning.
3. Check what Laravel does for you automatically. Most Laravel packages of this shape register a service provider via auto-discovery and optionally ship a config file. After install, check php artisan about / vendor/oxhq/ for a config/ directory, and try php artisan vendor:publish --provider="Oxhq\...\...ServiceProvider" (get the exact FQCN from the package's composer.json extra.laravel.providers block rather than guessing).
4. Verify the wiring before writing code. A pre-1.0 caching package is easy to install and easy to leave misconfigured — confirm the default cache store it targets (config/cache.php default) and that your store supports whatever features the package advertises.

First use case: take one read-heavy, low-volatility query in your app — a settings lookup, a category tree, a "featured products" list — and route it through the package rather than reaching for Cache::remember() by hand. That's the smallest change that proves the integration end-to-end (key generation, serialization, TTL, invalidation) without committing your architecture to it.

Implementation Patterns

Because v0.1.0 ships no documented API surface in the release notes, treat the patterns below as the integration checklist to map onto whatever the package actually exposes:

• Wrap, don't scatter. Create one thin abstraction (a repository method or a CacheletQuery-backed trait on the model) and call it from controllers/jobs. If the package's API shifts in v0.2, you change one file instead of forty.
• Cache the query, not the model instance. Eloquent models serialize poorly across deploys (attribute casts, relations, stale $appends). Prefer caching arrays/collections from ->get()->toArray() or a DTO unless the package explicitly handles model hydration and versioning.
• Key discipline. Derive keys from the query's inputs (filters, pagination, locale, tenant/branch ID) plus a schema version constant. Bump the version constant on deploy when you change selected columns — otherwise old serialized payloads get rehydrated into new shapes.
• Pair with write-side invalidation. Use model observers or saved/deleted events to bust relevant keys. If the package offers tag-like grouping (driver-dependent — see Gotchas), key off a domain concept (products, tenant:42) rather than raw SQL hashes.
• Layer TTLs by volatility. Short TTLs (30–300s) for listings and dashboards, longer for reference data, and an explicit forever-style option only for data you can deterministically invalidate.
• Background warm-up. For expensive queries, run a scheduled command that primes the cache before traffic peaks rather than letting the first request pay the cost.
• Testing. In tests, set CACHE_STORE=array so each test starts cold and assertions reflect real query behavior; add one integration test against your production store (Redis/Memcached) for the invalidation path, since that's where driver semantics differ.
• Observability. Log cache hits/misses (or expose them via a metrics middleware) for the queries you've wrapped — you need hit-rate data to justify the TTLs you picked.

Gotchas and Tips

• This repo is read-only. Issues, PRs, and feature requests almost certainly belong in the monorepo. Opening a PR here will likely be closed without review, and the split may be force-synced, overwriting local commits. Never vendor-patch it in place — use a fork or a Composer patch plugin.
• Split repos lag. Tags here can trail the monorepo, and the README may be a trimmed copy. When debugging an odd behavior, cross-check the monorepo at the corresponding tag before filing anything.
• Pre-1.0 semver. 0.x releases are allowed to break on minor bumps. Pin with a tight constraint ("^0.1" is fine; "*" or "dev-main" is not) and read the monorepo changelog before every update. Budget for the v1.0 migration.
• Cache driver feature gaps. If the package uses cache tags, they are unsupported by the file and database stores — BadMethodCallException at runtime, usually only in production because dev used array. Confirm driver support up front and mirror prod's store in staging.
• Silent config drift. If you publish the config, it's now yours to maintain — re-publish and diff on upgrades, or you'll miss new options. If you don't publish it, remember defaults can change between versions.
• Stale reads after writes. The classic failure: write to the DB, then the next request serves a cached list including the old row. Invalidate after the transaction commits (DB::afterCommit or an event listener), not inside it — otherwise a rollback leaves you with a busted cache and no data change.
• Cache stampede. Popular keys expiring simultaneously under load will hammer the DB. Prefer jittered TTLs or a short lock/Cache::lock around regeneration if the package doesn't handle this for you.
• Serialization surprises. Cached values must survive a deploy: closures, resources, and anonymous classes don't serialize. Keep cached payloads to scalars and arrays.
• Environment leakage. Ensure cache prefixes differ per environment and per app instance sharing a Redis database — key collisions between staging and prod on shared infrastructure are a genuinely nasty debugging session.
• Where to extend. If the package allows custom key generators, serializers, or stores, register them in a service provider rather than forking; that's the seam that keeps you upgradeable through the 0.x churn.