Cache::once() — auto-keyed caching based on callsite

[plumthedev]

🎯 Motivation

In day-to-day Laravel development, caching frequently-used results is a common performance optimization. However, it almost always requires manually defining a cache key:

$key = 'user:' . $user->id . ':stats';
Cache::remember($key, 600, fn () => $user->calculateStats());

This approach leads to:

• 🧱 Repetitive, boilerplate code,
• 🧨 Risk of inconsistencies and hard-to-track cache misses,
• 🔁 Duplication of logic around key generation.

But what if the key could be automatically generated based on where the cache was invoked?

---

💡 Insight: The callsite is the key

We can use debug_backtrace() to capture the context of the callsite:

• Calling class and method (or function),
• Whether it’s a method call or a static/global function,
• Plus optional arguments provided by the developer.

This forms a unique and predictable identity for the cached computation.

---

✅ API Proposal

Cache::once(Carbon|int $ttl, callable $callback, array $args = []): mixed

Where:

• $ttl: any value accepted by remember(),
• $callback: the actual computation to be cached,
• $args: optional; used to vary the key if input differs.

---

🧠 Example usage

return Cache::once(now()->addMinutes(10), fn () => $user->calculateStats(), [$user->id]);

No need to build or worry about keys — the system generates them deterministically based on:

• Class + method/function name where once() was called,
• Closure-provided $args.

---

🛠 Internals

Internally, once() would:

1. Use debug_backtrace() to extract class/method context,
2. Normalize and serialize this along with $args,
3. Create a hashed key (e.g., md5(json_encode(...))),
4. Use Cache::remember($key, $ttl, $callback) under the hood.

Argument processing (for stable keys):

• If an object is an Eloquent model, use $model->getKey(),
• If it’s a Request, serialize its inputs,
• If it implements __toString(), use the string,
• Otherwise, fallback to json_encode() of primitives/arrays.

---

🔄 Optional Extensions

• Hookable KeyGeneratorInterface for custom strategies.

---

⚙️ Benefits

✅ Zero boilerplate – no key-building
✅ Predictable, context-based identity
✅ Clean, Laravel-style API
✅ Easier to generalize across codebases
✅ Fully extendable/customizable under the hood

---

🧪 Summary

Cache::once() introduces a cleaner, safer, and more elegant way to handle caching in Laravel. It leverages Laravel's expressive syntax and conventions while abstracting key management.

I'd be happy to open a PR implementing this as a native method in the CacheManager — not just a macro. I believe it fits Laravel’s philosophy and would improve developer experience significantly.

[henzeb]

We already have a memo feature. Does this modify the existing code, or did you simply miss it? https://laravel.com/docs/12.x/cache#cache-memoization

[henzeb]

Because that is what memoization is. Your proposal describes the once function... You could propose a variation on that if you need it to store in cache.

Cache::once(mixed|callable, $value, Carbon|int $expiresAt = null);

Although once might not be the correct name. Remember is already used and callsite feels to tech...

[henzeb]

I keep thinking about this, you can simply add a helper function that generates the key.

Cache::remember(key(), fn() =>/*... */);
// or
Cache::remember(Cache::key(), fn() =>/*... */);

This way it can be used with any cache method.

[plumthedev]

That's right as well, I just wanted to add one more abstraction, to just hide the one more argument in remember
Cache::key() is good, key() is too generic and means absolutely nothing without the callsite

Basically, maybe the function should be called callsite_id() and cache method Cache::byCallsiteId(cb, ttl)

[henzeb]

The thing with laravel function naming is that they are short and simple and preferably single words. byCallsiteId is ugly IMHO. Just like the new whereBetween function uses an array for the values while SQL generally has a column and just 2 values.

I agree the function should describe what it is doing, but using callsite is way to technical...

I'd opt for once, after some consideration. Once is a known concept which does what you want. In Cache it should just behave like remember, with memo()->once() it actually adds memoization.

Key() might be to general, indeed, but maybe you can add in a helper function with a better name, because I think it can be used for more than just Cache.

[plumthedev]

You're right that what I'm proposing closely resembles memoization, but in this case the distinction is intentional: instead of in-memory-only memoization (memo()), this is persistent cache memoization with key generation based on the callsite and contextual args.

I agree that callsiteId() or byCallsiteId() feels too technical for Laravel. After thinking it through, I now propose we simply call the method:

Cache::once($ttl, $callback, $args);

It’s short, elegant, semantically meaningful, and communicates the intention: run this once and cache the result.
Behind the scenes, the cache key is auto-generated from the place it's called — which handles most developer needs without requiring manual keys.

This makes caching expressive and removes a huge chunk of repetitive key-management boilerplate we all write day-to-day.

I have updated the proposal description.

[plumthedev]

@nunomaduro @taylorotwell @crynobone @driesvints if you have a moment, would love your thoughts on this approach 😃