Download the PHP package aftandilmmd/laravel-cacheable without Composer

Laravel Cacheable

Türkçe: README.tr.md

Add #[Cacheable] to any method. That's it — the package handles TTL, tags, locking, invalidation, and stale-while-revalidate automatically.

Requires: PHP 8.2+ · Laravel 10 / 11 / 12 / 13

Installation

Auto-discovered. No provider or alias registration needed.

Optionally publish the config file:

How it works

The package intercepts method calls and stores their return values in cache. On the next call with the same arguments, the cached value is returned without executing the method body.

There are two ways to make this interception happen.

Real-world example

The most natural fit for this package is a Repository — a class that owns all database reads for a model. Annotate the read methods, attach forget to the write methods, register the repository in auto_proxy, and the rest is invisible.

Register it once in config:

Now every injected instance is automatically cached — no change to controllers or other callers:

Calling cached methods

Option A — Auto-proxy (recommended)

Register your service in config/cacheable.php. Every container-resolved instance is then automatically wrapped — you call methods normally and caching is invisible.

Note: new UserService() bypasses the container and won't be proxied. Always resolve through DI or app().

Option B — Manual proxy

No config needed. Wrap on the spot, call methods naturally:

Option C — Explicit dispatcher

If you prefer explicit over magic, use the HasCacheableMethods trait:

Self-call limitation: PHP cannot intercept $this->method() inside the same class. Use $this->cached('method', [...]) for internal calls.

Static methods via proxy

CacheableProxy::wrapClass returns a proxy object that intercepts static calls by name:

Annotating methods

Basic TTL

Key with placeholders

Placeholders resolve to method argument values. Nested properties also work:

Cache forever

Tags

Requires a taggable store (redis, memcached, array). The file and database drivers silently ignore tags.

Conditional caching

Skip caching based on runtime conditions without changing the call site:

unless is the inverse — skip cache when the method returns true.

Exclude arguments from the key

Inject heavy objects (Request, Logger) without polluting the cache key:

Cache invalidation

On write methods

Attach forget or forgetTags to a mutating method. Cache entries are deleted automatically after the method runs:

Via facade

Manually delete a specific entry or flush a tag group:

Version bump

Bump the version parameter to invalidate everything at once without touching the cache store:

Or per attribute:

Stampede protection

When many concurrent requests miss the same key, only one should hit the database. Use a distributed lock:

To spread expiration times across many keys and avoid simultaneous cache misses, add jitter:

Stale-while-revalidate

Serve cached data immediately while refreshing in the background. refreshAhead: 0.2 means "trigger a refresh in the final 20% of the TTL window":

For async refresh via the queue, enable it in config:

Events

Listen in app/Providers/AppServiceProvider.php:

Disable all events globally: set cacheable.events.enabled = false in config.

Debugging

If the key looks like a hash, set an explicit key: template in the attribute for human-readable keys.

Configuration

Publish and edit config/cacheable.php to set global defaults. Every attribute parameter that accepts null falls back to these values.

Attribute reference

All parameters are optional. Omitting a parameter uses the config default.

Extending

Custom key resolver

Custom argument normalizer

You can also swap the entire caching pipeline by implementing CacheAspect.

Troubleshooting

$this->method() isn't cached. PHP can't intercept self-calls. Use $this->cached('method', [...]) or inject a proxy.

Static method isn't cached. auto_proxy and Cacheable::proxy() only wrap instances. Use HasCacheableMethods + cached('method', [...]) or CacheableProxy::wrapClass(MyClass::class)->method().

Tags do nothing. Tags require a taggable store (redis, memcached, array). Switch the store or use forget keys instead.

Cache isn't cleared between tests. Add Cache::flush() to your test's setUp().

License

MIT © Aftandilmmd. See LICENSE.md.