Reloquent Laravel Package

Getting Started

v0.1.9 is a small but useful release: it adds a cache entity and ships PhpStorm generics for Collection and Repository. Both changes target day-to-day ergonomics rather than architecture, so existing code should keep working.

1. Update and re-publish config if the package ships one:

   composer require <vendor>/<package>:^0.1.9
   php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider" --tag=config
   

2. Read the config file first — the cache entity almost certainly reads its store, TTL, and key prefix from there. Check whether a new cache block appeared after the update.
3. Read src/Entities and src/Repositories (or the package's equivalent namespaces) before writing your own. The cache entity is the reference implementation for anything you subclass.
4. First use case: pick one read-heavy entity (settings, categories, static lookups), swap its repository to the caching variant, and verify with php artisan tinker that a second find() no longer hits the database.

Implementation Patterns

Entity + Repository pairing. Keep the established split: entities own state and hydration, repositories own querying. Don't put cache logic in the entity; put it in the repository so the caching variant is a drop-in replacement.

Caching reads through the repository. The new cache entity is meant to wrap retrieval, not to be a general-purpose cache facade:

$category = $this->categories->find($id);      // cached
$this->categories->update($id, $payload);      // must bust the entry

Wire it as a decorator around your existing repository rather than branching on a config flag inside every method — that keeps non-cached and cached code paths honest and testable.

Generics for editor support. The PhpStorm generics are docblock-only annotations. Use them on your own subclasses so ->all(), ->find(), and iteration resolve to your entity type instead of mixed:

/**
 * @extends Repository<\App\Entities\Category>
 */
class CategoryRepository extends Repository { ... }

/** @var Collection<\App\Entities\Category> $categories */
$categories = $this->categories->all();

Replicate the pattern on any custom Collection subclass; this is where most of the everyday payoff lands, since it removes the /** @var */ noise from controllers and jobs.

Integration tips.

• Bind repository interfaces in a service provider and inject them — cached vs. uncached then becomes a one-line container change per environment.
• In tests, bind the non-cached repository so assertions aren't sensitive to a warm cache from a prior test.
• When composing repositories (one repository calling another), resolve the cache key from the outer entity's identity, not from an intermediate query object.

Gotchas and Tips

• Pre-1.0 API surface. At v0.1.9, method names and constructor signatures can still shift in a patch release. Pin the version ("^0.1.9" at most, ideally exact) and read the diff before bumping.
• Generics do nothing at runtime. They are purely for the IDE. A wrong @extends annotation will silently mislead auto-completion and static analysis — verify against the actual return types in src/.
• Cache invalidation is on you. The cache entity caches reads; it will not automatically notice writes made via DB::table(), raw queries, seeders, or another service. Any write path that bypasses the repository must bust the key explicitly, otherwise you get stale reads that only appear after deploy.
• Serializability. Whatever gets stored must survive the cache driver. Entities holding closures, resources, or open connections will fail on Redis/file but might appear to work with the array driver. Test with the production driver.
• Key collisions. Confirm the key prefix includes the entity class and the tenant/scope, not just the ID. Two repositories sharing an ID space is the classic bug here.
• Debugging. Start with Cache::getStore() and the configured prefix, then php artisan cache:clear to prove the issue is cache-related. If results change after a flush, the bug is invalidation, not querying.
• Extension points. The base repository and collection are the intended seams: override hydration/mapping in a subclass rather than editing vendor code, and swap the cache store via config rather than hardcoding Cache::store() inside the repository.