Cachelet Model Laravel Package

Getting Started

Cachelet Model v0.1.0 is the first public release of the Eloquent integration for Cachelet. Important context up front: this repository is a read-only split generated from the main monorepo at https://github.com/oxhq/cachelet. That means the split repo gives you installable code and tags, but not the authoritative docs, issue tracker, or contribution path.

Minimal steps:

1. Find the real package name. Because the split is auto-published, confirm the exact vendor/name in the split repo's composer.json rather than assuming it from the repo title, then composer require that name at ^0.1.
2. Read the monorepo README first. All usage documentation lives upstream in oxhq/cachelet. The split repo will not carry its own guides, and any README there is likely a generated pointer back to the monorepo.
3. Check for a publishable config and a model trait/base class. A model-level cache integration typically ships a config file (php artisan vendor:publish) and a trait or base model you opt into. Identify both before writing code — v0.1.0 gives you no migration path if you wire it in the wrong layer.
4. First use case: take one read-heavy Eloquent query — a dashboard aggregate, a lookup table, a "recent activity" list — and route it through the package rather than hand-rolling Cache::remember() around it. That is the lowest-risk way to evaluate whether the abstraction earns its place over Laravel's native cache facade.

Treat v0.1.0 as an evaluation release. At 0.1.x, the public API surface is by definition unstable, so prototype on a branch rather than baking it into a shared base model.

Implementation Patterns

Because the release notes contain no API detail, the patterns below describe how to approach the integration and what to verify, rather than exact calls.

• Scope the cache to the model layer, not the controller. The value of an Eloquent-aware cache over raw Cache::remember() is that it can hook model events (saved, deleted, restored) for invalidation. Confirm the package registers those hooks; if it doesn't, you are paying abstraction cost for nothing and should stay on the facade.
• Start with read paths you can measure. Wrap a query, add a DB::listen counter or Telescope tag, and confirm hit rates before expanding. A v0.1 cache layer is easy to add everywhere and hard to reason about afterwards.
• Isolate behind a repository or scope. Keep the package's calls inside a small number of repository methods or query scopes so a 0.1 → 0.2 API change is a one-file diff, not a codebase-wide sweep.
• Pair with a testing strategy early. Set CACHE_DRIVER=array in phpunit.xml so cached reads don't leak across tests, and add a test that asserts the cache is invalidated after a model update — this is the failure mode that bites in production and is invisible in local dev.
• Watch the raw-query escape hatch. Any DB::table(...)->update() or bulk Model::query()->update() bypasses model events, so event-driven invalidation won't fire. Route writes through Eloquent instances, or flush explicitly.

Gotchas and Tips

• Do not open issues or PRs against the split repo. It is machine-generated and read-only; anything you file there will be lost. Go to oxhq/cachelet.
• Split tags can lag the monorepo. A monorepo commit may exist well before the split publishes a matching tag. If a fix "isn't in" v0.1.0, check upstream before assuming it's not implemented — and conversely, don't pin to a split commit hash if you can avoid it.
• Cache key collisions. If you run multiple models through the same cache store, verify how the package namespaces keys per model, per connection, and per tenant. Multi-tenant apps should test this explicitly before rollout.
• Serialization behaviour. Cached Eloquent models or collections get serialized; check what happens when the underlying table's schema changes between deploy and cache flush. The safe habit is to flush the relevant namespace as part of deploy.
• Debugging stale reads: the fastest triage is to bypass the cache entirely (drive the same query through Model::query() with the cache disabled) and compare. If the uncached path is correct, the problem is invalidation, not the query.
• Extension points to look for (and to check the monorepo docs on): a configurable store/connection, a TTL default, a key-prefix/namespace setting, and whether the integration is opt-in per model via a trait versus applied globally. The per-model trait is strongly preferable at 0.1 — it lets you roll back incrementally.
• Pin conservatively. Use "vendor/cachelet-model": "0.1.*" rather than ^0.1 if you're deploying anywhere that matters; pre-1.0 minor bumps are allowed to break under semver and this package has exactly one release of history to judge from.

Given the thinness of the v0.1.0 notes, the most useful next step is a short spike: install it, wrap one query, and read the upstream monorepo docs in full. Revisit this assessment once 0.2 or a documented API reference lands.