feat: implement negative caching

[binaryfire]

This PR adds new methods that support caching null-returning callback results, so "we looked and there's nothing" becomes a legitimate cache entry instead of being mistaken for a miss. Four new methods - rememberNullable, rememberForeverNullable, searNullable, flexibleNullable - sit alongside the existing the existing remember methods. When these new methods are used, they substitute a sentinel when the callback returns null. Everything else passes through unchanged.

Why this matters

Laravel's default remember() intentionally treats null as a miss, so it re-runs the callback on the next call. That makes sense when null means “not ready yet.” It’s wasteful when null is the real answer. In those cases the callback keeps running on every request and the thing you were trying to protect (the database, an external API, an expensive query etc) keeps getting hit for no reason. This can be really useful for third-party API lookups that legitimately 404 (product not found, repo not found, user not found). Without negative caching, every retry is another paid request.

For background on the general pattern, GeeksforGeeks has a decent overview.

How it works

The new methods are drop-in replacements for their non-nullable siblings:

$user = Cache::rememberNullable("user:{$id}", 300, fn () => User::find($id));

// works with tags too
$report = Cache::tags(['reports'])->rememberNullable('weekly', 3600, fn () => $expensiveQuery());

If the callback returns a real value, it's stored and returned like any other cache entry. If the callback returns null, the cache stores a sentinel (an internal marker value) which is recognised as a hit on subsequent reads and unwrapped back to null before returning. Callers never see the sentinel.

Plain remember() still behaves the way Laravel documents: null callback returns aren't cached, so polling patterns keep polling. Only the new nullable wrappers opt into the substitution. Mixing both in the same codebase is safe.

The other public accessors behave how you'd expect once a negative result has been cached:

• Cache::get('k') returns null
• Cache::get('k', 'default') returns 'default', matching the put('k', null) convention
• Cache::has('k') returns false (Laravel's null-as-absence rule)
• Cache::pull('k') returns null and forgets the key
• Cache::forget('k') clears it; the next rememberNullable call runs the callback again
• tag flush invalidates the entry like any other tagged value

Already useful for 0.4

EloquentUserProvider already hand-rolls this pattern: an auth-local NULL_SENTINEL array constant, a manual === self::NULL_SENTINEL check on reads, and a separate put() call that substitutes the sentinel when the user wasn't found. After this PR, it becomes much cleaner:

Before (retrieveById):

public function retrieveById(mixed $identifier): ?UserContract
{
    if (! $this->cache) {
        return $this->fetchUserById($identifier);
    }

    $key = $this->buildCacheKey($identifier);
    $cached = $this->cache->get($key);

    if ($cached === self::NULL_SENTINEL) {
        return null;
    }

    if ($cached !== null) {
        return $cached;
    }

    $user = $this->fetchUserById($identifier);

    $this->resolveWriteCache()->put($key, $user ?? self::NULL_SENTINEL, $this->cacheTtl);

    return $user;
}

After:

public function retrieveById(mixed $identifier): ?UserContract
{
    if (! $this->cache) {
        return $this->fetchUserById($identifier);
    }

    return $this->resolveWriteCache()->rememberNullable(
        $this->buildCacheKey($identifier),
        $this->cacheTtl,
        fn () => $this->fetchUserById($identifier),
    );
}

The NULL_SENTINEL class constant and the manual sentinel can be removed.

What changed internally

The sentinel is a plain array constant, not an object. This keeps it immune to the unserialize(..., ['allowed_classes' => ...]) restrictions some stores apply when cache.serializable_classes is configured. An object sentinel would silently become __PHP_Incomplete_Class under restrictive configs and the identity check would fail; that isn't an issue with an array.

getRaw() and manyRaw() helpers have been added to Repository, documented @internal, and exposed via a new Hypervel\Contracts\Cache\RawReadable interface. The existing get, many, remember, rememberForever, and flexible methods route through it so a cached sentinel is recognised as a hit at the store boundary and unwrapped at the public return boundary. has, missing, pull, and the typed getters (string, integer, etc.) inherit the right behaviour automatically because they all go through get.

The two Redis tagged-cache subclasses (AllTaggedCache, AnyTaggedCache) have an unwrap on their remember and rememberForever return paths. AnyTaggedCache also got getRaw / manyRaw overrides that throw, preserving the existing any-mode "tagged reads are rejected" logic.

The two wrapper stores (MemoizedStore, FailoverStore) implement RawReadable. Without that, a cached sentinel would get unwrapped by the inner Repository before the wrapper could see it, and rememberNullable on a memoized or failover stack would re-run the callback on every call.

Events (CacheHit, KeyWritten, etc.) fire exactly as before for all existing cases. The one difference is that a cached sentinel fires CacheHit (because the key is present) with the sentinel as the event's value field. Metrics or tracing listeners that inspect payloads can check === NullSentinel::VALUE if needed. The sentinel is never visible through any public cache method.

Store contract

Unchanged. Plain stores (Redis, File, Database, Array, Swoole, Null, Session, Stack) don't know about sentinels. They store and retrieve arrays like any other value. The sentinel-aware logic lives in Repository plus the two Redis tagged-cache subclasses plus the two wrapper stores.

Breaking changes

None. Existing remember, rememberForever, sear, and flexible behave the same as before. The Store contract is the same. Plain drivers are the same. The nullable methods are opt-in; code that doesn't use them will never see a sentinel anywhere.

Test coverage

Unit-level coverage across Repository, both Redis tagged-cache subclasses, the wrapper stores, and per-driver round-trips (ArrayStore under default and restrictive serializable_classes configs, SwooleStore, StackStore). NullStore gets its own check to make sure rememberNullable re-runs the callback every time, since NullStore never retains anything. Also added several mixed-usage scenarios (get / has / many / pull / plain remember on sentinel-stored keys), events-with-sentinel-payload, TTL expiry, put-overwrite, and forget interaction.

Added integration coverage against real Redis for both tag modes, Repository end-to-end, failover-backed stacks, memoized-backed stacks, and the flexibleNullable stale-hit deferred-refresh path.

[binaryfire]

@albertcht Could you review this when you have a second? Let me know what you think.