Cachelet Core Laravel Package

Getting Started

Cachelet Core v0.1.0 is the first public cut of a read-only split from the oxhq/cachelet monorepo. That detail matters more than it looks: the code you composer require is generated, and all issues, PRs, and discussion live upstream at https://github.com/oxhq/cachelet. Start there, not at the split repo.

1. Read the upstream README first. The split carries the runtime, not necessarily the docs, examples, or tests. The release notes for v0.1.0 contain no feature list at all — the README and the source are your documentation.
2. Confirm the package name and namespace. The release refers to it as the "core runtime," which implies sibling packages exist in the monorepo. Check composer.json in the split repo before assuming oxhq/cachelet-core is the name to require.
3. Pin the exact version. At 0.1.0 there are no semver guarantees. Use "0.1.0", not ^0.1 — a 0.2.0 is fully entitled to break you.
4. Find the entry point before writing app code. Look for a service provider and config/cachelet.php in the package root. Those two files tell you more about the package's real surface than any release note will.
5. Publish and inspect the config: php artisan vendor:publish --tag=cachelet-config. Read every key — the defaults reveal what the package expects to be doing.

First use case: don't adopt it globally. Put it behind one expensive, well-understood read path — a dashboard aggregate, a slow third-party API call, or a heavy Eloquent query — so you can measure hit rate and invalidation behaviour against a baseline you already know. Breadth can come after you trust it.

Implementation Patterns

• Resolve through the container, not new. Bind the Cachelet client/facade so tests can swap it and so config changes actually take effect. Static or direct instantiation defeats both.
• Wrap it in one app-level service. This is the single most valuable pattern for a 0.x dependency. A thin App\Support\Cache\... class means a rename in 0.2.0 costs you one file, not two hundred call sites.
• Cache at the response boundary, not the model. Cache the array your controller or API resource actually returns. Invalidation becomes obvious and you stop serialising relationships nobody reads.
• Deterministic, self-describing keys. Build them through a helper (cachelet_key('orders.total', $tenantId)) and version them (v2:). When something is stale at 2am, being able to reason about the key from redis-cli is the difference between a five-minute fix and an hour.
• Invalidate via jobs, not inline. Writes that touch cached data should dispatch a small forget-job. It keeps the request path fast and gives you one place to log invalidations.
• Test against your wrapper. Assert on your service's behaviour, not the package's internals — your suite should survive the package's churn.

Gotchas and Tips

• 0.x is not a compatibility promise. Read the upstream changelog before every bump, and be aware the split repo may lag behind the monorepo. Treat "no release notes" as "unknown deltas."
• Read-only split means read-only contribution. You cannot open an issue or PR here. Reproduce bugs against the monorepo, and expect the split's issue tracker to be disabled entirely.
• Verify which store you actually got. Caching abstractions frequently fall back to the array store when config is missing — 100% hit rate locally, 0% in production, and no error to warn you. Log the resolved driver on boot in staging.
• Grep the source for env(. It's the fastest smoke test of any new Laravel package. Direct env() reads outside config files silently return null once php artisan config:cache runs, which is exactly what production does.
• Debug beneath the package. When values look stale, bypass Cachelet and inspect Redis or the database cache table directly. You need the key naming scheme; the serialised value format will only confuse you.
• Look for real extension points before decorating. A store manager, an extend()-style hook, or cache events are the correct home for metrics and tracing. If none exist, that's a meaningful fact about the package's maturity — and a reason to keep your wrapper defensive.
• Ship an off switch. Put usage behind a config flag so a single deploy disables the layer. On a 0.1.0 dependency that isn't paranoia, it's basic hygiene.