Download the PHP package trm42/cache-decorator without Composer

(Magical) Cache Decorator for Laravel

A transparent caching decorator for any Laravel-side class — services, API clients, query objects, repositories, you name it. Sub-class CacheDecorator, point it at the object you want to cache, and every public method call is automatically cached on first run and served from the cache on subsequent calls.

Stop writing boilerplate like this for every class whose results you want to cache:

With CacheDecorator the above shrinks to:

TTL is read from config, not from a $ttl property. The constructor calls getConfig(), which overwrites $ttl from cache_decorator.ttl (default 300 seconds; repository_cache.ttl for RepositoryCacheDecorator). To override it per-instance, call ->ttl(...) after construction (e.g. in your subclass constructor) — it accepts int seconds, a DateInterval, a DateTimeInterface, or null to bypass the cache entirely. See Fluent configuration for the full chainable grammar.

…and use it like this:

The decorator forwards any method not listed in $excludes to the underlying object via __call() and caches the result. Forwarding goes through Laravel's ForwardsCalls trait, so calls also reach methods the decorated object exposes through its own __call() magic — not just declared methods. Calling a method that exists nowhere on the decorated object throws UndefinedMethodException (see Object arguments in cache keys.

Fluent configuration

Every configuration setter is chainable (returns the decorator) and there's an expressive, self-documenting grammar for tuning an instance at runtime — no subclass property edits required:

If you add your own public methods to a CacheDecorator subclass, remember that any method not listed in $excludes is forwarded to the inner object by __call(). The fluent methods above are already excluded by the base class, so chaining always resolves on the decorator and never leaks to the inner instance.

Object arguments in cache keys

Method arguments may be scalars, arrays, or objects — the decorator folds each argument into the cache key through a stable identity rule:

1. Scalars / null / bool — cast as-is (existing scalar-only keys are byte-identical, so upgrading invalidates nothing).
2. UrlRoutable (Eloquent models, etc.) — uses getRouteKey(), the model's natural stable identity. Two distinct instances with the same route key share a cache entry.
3. BackedEnum — uses its ->value; Stringable / __toString — string-cast.
4. Anything else (plain objects, nested arrays of objects) — a bounded, stable hash (json_encode, falling back to md5(serialize(...))).

Arrays are flattened (Arr::dot) and each leaf runs through the same rule, so nested objects are handled too.

To customize how a given argument type contributes to the key, override the protected normalizeArgument(mixed $value): string seam in your subclass — it sits alongside generateCacheKey(), getCache(), and putCache() as a first-class extension point.

Fluent / self-returning methods

forwardDecoratedCallTo() rewrites a fluent return $this; from the inner object back to the decorator, so method chaining stays on the cached surface instead of escaping to the bare inner instance.

Two conventions make this transparent and type-safe:

• List fluent methods in $excludes. They aren't cache candidates anyway, and excluding them keeps them on the always-forward path. (On a cache miss __call() stores callMethod()'s return — now the decorator instance — and a later hit would return that cached decorator directly, bypassing the rewrite. Excluding avoids caching a decorator object.)
• Type fluent methods : static behind a shared interface. Have the inner class implement an interface whose fluent methods return static. A caller then sees the same type whether it holds the inner instance or the decorator, and the decorator standing in for $this on self-returning calls is type-coherent.

Optional: have the decorator instantiate the inner class for you

If you don't want to wire the inner instance yourself, override decoratedClass() to return its FQCN and you can construct the decorator with no arguments:

The FQCN returned by decoratedClass() is resolved through Laravel's service container (via resolve()), so the decorated class may declare constructor dependencies (they are auto-wired), and decoratedClass() may return an interface that's bound in the container.

Custom caching logic for a single method

If a particular method needs hand-tuned caching, override it in the subclass and use the protected helpers:

getCache() returns the cacheMiss() sentinel (a shared stdClass instance) when the entry is absent — comparing with === against cacheMiss() lets the override round-trip falsy payloads (0, '', [], false, null) correctly. Don't use truthiness checks like if (!$res): they would treat a legitimately cached false/0/[] as a miss and refetch on every call.

Cache tags

If your cache driver supports tags, declare which methods invalidate the tag bucket:

Exceptions

All errors thrown by the package live in the Trm42\CacheDecorator\Exceptions namespace and extend a single abstract base, CacheDecoratorException. Catch that base type to handle any cache-decorator-specific failure in one place, or catch a concrete subclass to distinguish the failure mode:

Breaking change. These types previously surfaced as the SPL exceptions LogicException (missing decorated object) and BadMethodCallException (undefined method). They now extend \Exception via CacheDecoratorException and are not instances of those SPL classes — update any catch (LogicException ...) / catch (BadMethodCallException ...) blocks that relied on the old types.

Using with repositories

For repository-flavored use cases the package ships RepositoryCacheDecorator. It behaves exactly like CacheDecorator but reads its config from the repository_cache.* namespace instead of cache_decorator.*, so repository caches can be tuned independently of other decorators.

Install

Install with composer:

Publish whichever config you need (or both):

Environment variables:

Upgrading

From the previous 0.x line

A few breaking changes tightened the public contract:

• TTL bypass uses null, not false. The "skip the cache" sentinel for $ttl is now null. The property type is int|DateInterval|DateTimeInterface|null (default null) and ttl() has the same typed signature — replace any protected $ttl = false; with protected $ttl = null; and any ttl(false) with ttl(null).
• The void setters were dropped for a fluent grammar. setTtl() / setEnabled(bool) have been removed in favor of the chainable ttl(), enable(), and disable() methods (see Fluent configuration). Replace setTtl($n) with ttl($n), setEnabled(true) with enable(), and setEnabled(false) with disable().
• $tags and $tag_cleaners are plain arrays. Both default to [] (no longer array|false). If the cache driver doesn't support tags (or use_tags is disabled in config), they are reset to [] rather than false. Custom subclasses that initialized either property to false should switch to [].
• Falsy cached values round-trip correctly. Previously a method returning 0, '', [], or false would look like a cache miss and be refetched on every call. getCache() now returns a cacheMiss() sentinel (a shared stdClass) on a true miss, and __call() compares with === — so falsy results are cached and served from cache as expected. If you wrote a custom method override with if (!$res) around getCache(), switch it to if ($res === $this->cacheMiss()) (see the override example above).
• The enabled flag now actually short-circuits caching. Setting $enabled = false (via the property, disable(), or {$config_key}.enabled = false) now causes __call() to forward straight to the decorated object, skipping cache reads, writes, and tag flushing.

From the repository-only version

The base class is now generic and the repository-specific glue has been removed in favor of the generic hooks:

• Replace extends CacheDecorator with extends RepositoryCacheDecorator if you want to keep reading config from the repository_cache.* namespace.
• Rename your repository() method to decoratedClass() (return type ?string). The old repository() abstract has been removed.
• In custom method overrides, replace $this->repository->… with $this->decorated->…. The $this->repository alias has been removed.
• initRepository() has been removed; pass the instance via the constructor, or override decoratedClass().

From Laravel 5.x versions

This release targets Laravel 12 and 13 on PHP 8.2+. A few breaking changes:

• TTL semantics changed from minutes to seconds (matching Laravel 5.8+'s Cache::put API). Update any $ttl property and the repository_cache.ttl config value accordingly — e.g. 5 (minutes) becomes 300 (seconds).
• $ttl may now also be a DateInterval or DateTimeInterface, in addition to int and null (which bypasses the cache entirely).
• Minimum PHP version is 8.2.

Tested with Laravel 12 and Laravel 13.