NamespacedTaggedCache
class NamespacedTaggedCache extends TaggedCache
Tagged cache for namespaced tag semantics.
Item keys are namespaced by the tag set: values must be read, written, and deleted through the same ordered tag set used to store them.
Traits
Constants
| FLEXIBLE_CREATED_KEY_PREFIX |
The cache key prefix used to track when a flexible cache value was last refreshed. |
Properties
| static protected array | $macros | The registered string macros. |
from Macroable |
| protected Store | $store | The cache store implementation. |
from Repository |
| protected Dispatcher|null | $events | The event dispatcher implementation. |
from Repository |
| protected int|null | $default | The default number of seconds to store items. |
from Repository |
| protected array | $config | The cache store configuration. |
from Repository |
| static protected Closure|null | $unserializableClassHandler | The callback to invoke when an unserializable class is encountered. |
from Repository |
| protected NamespacedTagSet | $tags | The tag set instance. |
Methods
Get the number of seconds until the given DateTime.
Get the "available at" UNIX timestamp.
If the given value is an interval, convert it to a DateTime instance.
Given a start time, format the total run time for human readability.
Mix another object into the class.
Dynamically handle calls to the class.
Dynamically handle calls to the class.
Retrieve an item from the cache by key.
Retrieve multiple items from the cache by key.
Retrieve an item from the cache and delete it.
Retrieve a string item from the cache.
Retrieve an integer item from the cache.
Retrieve a float item from the cache.
Retrieve a boolean item from the cache.
Retrieve an array item from the cache.
Store an item in the cache.
Store an item in the cache.
Store multiple items in the cache for a given number of seconds.
Store multiple items in the cache.
Store an item in the cache if the key does not exist.
Increment the value of an item in the cache.
Decrement the value of an item in the cache.
Store an item in the cache indefinitely.
Get an item from the cache, or execute the given Closure and store the result.
Get an item from the cache, or execute the given Closure and store the result.
Retrieve an item for remember operations without unwrapping sentinels.
Get an item from the cache, or execute the given Closure and store the result.
Get an item from the cache, or execute the given Closure and store the result forever.
Get an item from the cache, or execute the given Closure and store the result forever.
Get an item from the cache, or execute the given Closure and store the result forever.
Get an item from the cache, or execute the given Closure and store the result forever.
Retrieve an item from the cache by key, refreshing it in the background if it is stale.
Retrieve an item from the cache by key, refreshing it in the background if it is stale.
Set the expiration of a cached item.
Execute a callback while holding an atomic lock on a cache mutex to prevent overlapping calls.
Funnel a callback for a maximum number of simultaneous executions.
Begin executing a new tags operation if the store supports it.
Determine if the current store supports flushing locks.
Set the default cache time in seconds.
Register a callback to be invoked when an unserializable class is encountered.
Set the cache store name before sharing the repository.
Store an item in the cache for the default time.
Handle a result for the "many" method.
Format the key for a cache item.
Handle a cache value that contains an incomplete class.
Calculate the number of seconds for the given TTL.
Retrieve an item from the cache by key without unwrapping sentinels.
Retrieve an item without serving it from a non-authoritative read layer.
Retrieve multiple items from the cache by key without unwrapping sentinels.
Get a fully-qualified key for a tagged item.
Details
in
InteractsWithTime at line 17
protected int
secondsUntil(DateInterval|DateTimeInterface|int $delay)
Get the number of seconds until the given DateTime.
in
InteractsWithTime at line 29
protected int
availableAt(DateInterval|DateTimeInterface|int|null $delay = 0)
Get the "available at" UNIX timestamp.
in
InteractsWithTime at line 47
protected DateTimeInterface|int
parseDateInterval(DateInterval|DateTimeInterface|int|null $delay)
If the given value is an interval, convert it to a DateTime instance.
in
InteractsWithTime at line 63
protected int
currentTime()
Get the current system time as a UNIX timestamp.
in
InteractsWithTime at line 71
protected string
runTimeForHumans(float $startTime, float|null $endTime = null)
Given a start time, format the total run time for human readability.
in
Macroable at line 30
static void
macro(string $name, callable|object $macro)
Register a custom macro.
Macros persist in a static property for the worker lifetime and apply to every subsequent call on the macroable class.
in
Macroable at line 44
static void
mixin(object $mixin, bool $replace = true)
Mix another object into the class.
Delegates to macro() for each method; registered macros persist in a static property for the worker lifetime.
in
Macroable at line 61
static bool
hasMacro(string $name)
Check if macro is registered.
in
Macroable at line 72
static void
flushMacros()
Flush the existing macros.
Clears worker-wide macros; concurrent coroutines may resolve different methods depending on timing.
in
Macroable at line 83
static mixed
__callStatic(string $method, array $parameters)
Dynamically handle calls to the class.
in
Macroable at line 108
mixed
__call(string $method, array $parameters)
Dynamically handle calls to the class.
in
Repository at line 108
bool
has(array|UnitEnum|string $key)
Determine if an item exists in the cache.
in
Repository at line 126
bool
missing(UnitEnum|string $key)
Determine if an item doesn't exist in the cache.
in
Repository at line 137
mixed
get(array|UnitEnum|string $key, mixed $default = null)
Retrieve an item from the cache by key.
When an array is given, return a key-value map. Numeric entries are requested keys, while string-keyed entries use their values as defaults.
in
Repository at line 153
array
many(array $keys)
Retrieve multiple items from the cache by key.
Items not found in the cache will have a null value.
in
Repository at line 176
iterable
getMultiple(iterable $keys, mixed $default = null)
Retrieve multiple items from the cache by key.
in
Repository at line 195
mixed
pull(UnitEnum|string $key, mixed $default = null)
Retrieve an item from the cache and delete it.
in
Repository at line 209
string
string(UnitEnum|string $key, callable|string|null $default = null)
Retrieve a string item from the cache.
in
Repository at line 230
int
integer(UnitEnum|string $key, callable|int|null $default = null)
Retrieve an integer item from the cache.
in
Repository at line 256
float
float(UnitEnum|string $key, callable|float|null $default = null)
Retrieve a float item from the cache.
in
Repository at line 282
bool
boolean(UnitEnum|string $key, callable|bool|null $default = null)
Retrieve a boolean item from the cache.
in
Repository at line 305
array
array(UnitEnum|string $key, callable|array|null $default = null)
Retrieve an array item from the cache.
in
Repository at line 322
bool
put(array|UnitEnum|string $key, mixed $value, DateInterval|DateTimeInterface|int|null $ttl = null)
Store an item in the cache.
in
Repository at line 374
bool
set(UnitEnum|string $key, mixed $value, DateInterval|DateTimeInterface|int|null $ttl = null)
Store an item in the cache.
in
TaggedCache at line 39
bool
putMany(array $values, DateInterval|DateTimeInterface|int|null $ttl = null)
Store multiple items in the cache for a given number of seconds.
in
Repository at line 443
bool
setMultiple(iterable $values, DateInterval|DateTimeInterface|int|null $ttl = null)
Store multiple items in the cache.
in
Repository at line 451
bool
add(UnitEnum|string $key, mixed $value, DateInterval|DateTimeInterface|int|null $ttl = null)
Store an item in the cache if the key does not exist.
in
TaggedCache at line 57
bool|int
increment(UnitEnum|string $key, int $value = 1)
Increment the value of an item in the cache.
in
TaggedCache at line 67
bool|int
decrement(UnitEnum|string $key, int $value = 1)
Decrement the value of an item in the cache.
in
Repository at line 515
bool
forever(UnitEnum|string $key, mixed $value)
Store an item in the cache indefinitely.
in
Repository at line 558
mixed
remember(UnitEnum|string $key, Closure|DateInterval|DateTimeInterface|int|null $ttl, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result.
in
Repository at line 575
array
rememberWithWarmth(UnitEnum|string $key, Closure|DateInterval|DateTimeInterface|int|null $ttl, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result.
in
Repository at line 598
protected mixed
getRawForRemember(UnitEnum|string $key)
Retrieve an item for remember operations without unwrapping sentinels.
in
Repository at line 617
mixed
rememberNullable(UnitEnum|string $key, DateInterval|DateTimeInterface|int|null $ttl, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result.
Unlike remember(), a null return from $callback is stored (as the internal NullSentinel::VALUE marker) and returned as null on subsequent calls rather than triggering re-execution. Public accessors (get, many, pull, has, etc.) unwrap the sentinel automatically — callers never see it.
in
Repository at line 631
mixed
sear(UnitEnum|string $key, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result forever.
in
Repository at line 647
mixed
searNullable(UnitEnum|string $key, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result forever.
Alias for rememberForeverNullable().
in
Repository at line 661
mixed
rememberForever(UnitEnum|string $key, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result forever.
in
Repository at line 688
mixed
rememberForeverNullable(UnitEnum|string $key, Closure $callback)
Get an item from the cache, or execute the given Closure and store the result forever.
Unlike rememberForever(), a null return from $callback is stored (as the internal NullSentinel::VALUE marker) and returned as null on subsequent calls rather than triggering re-execution. Public accessors unwrap the sentinel automatically.
in
Repository at line 703
mixed
flexible(UnitEnum|string $key, array $ttl, mixed $callback, array|null $lock = null, bool $alwaysDefer = false)
Retrieve an item from the cache by key, refreshing it in the background if it is stale.
in
Repository at line 769
mixed
flexibleNullable(UnitEnum|string $key, array $ttl, mixed $callback, array|null $lock = null, bool $alwaysDefer = false)
Retrieve an item from the cache by key, refreshing it in the background if it is stale.
Unlike flexible(), a null return from $callback is stored (as the internal NullSentinel::VALUE marker) and returned as null on subsequent calls rather than triggering re-execution. Public accessors unwrap the sentinel automatically.
Inherits flexible()'s support matrix: unsupported on any-mode tagged caches (tags()->flexibleNullable() on a TagMode::Any store throws the same BadMethodCallException that tags()->flexible() does, because flexible() internally reads via manyRaw() (initial batched read) and getAuthoritativeRaw() (acquired-lock refresh read), both of which AnyTaggedCache overrides to throw in any-mode).
in
Repository at line 777
bool
touch(UnitEnum|string $key, DateInterval|DateTimeInterface|int $ttl)
Set the expiration of a cached item.
in
Repository at line 800
mixed
withoutOverlapping(UnitEnum|string $key, callable $callback, int $lockFor = 0, int $waitFor = 10, string|null $owner = null)
Execute a callback while holding an atomic lock on a cache mutex to prevent overlapping calls.
in
Repository at line 810
ConcurrencyLimiterBuilder
funnel(UnitEnum|string $name)
Funnel a callback for a maximum number of simultaneous executions.
in
Repository at line 824
bool
forget(array|UnitEnum|string $key)
Remove an item from the cache.
in
Repository at line 860
bool
delete(UnitEnum|string $key)
Remove an item from the cache.
in
Repository at line 870
bool
deleteMultiple(iterable $keys)
Delete multiple items from the cache by key.
in
TaggedCache at line 109
bool
clear()
Remove all items from the cache.
A tagged cache's PSR clear() scope is the tag set, not the whole store.
in
Repository at line 918
bool
flushLocks()
Flush all locks from the cache store.
in
Repository at line 957
TaggedCache
tags(mixed $names)
Begin executing a new tags operation if the store supports it.
in
Repository at line 985
bool
supportsTags()
Determine if the current store supports tags.
in
Repository at line 993
bool
supportsFlushingLocks()
Determine if the current store supports flushing locks.
in
Repository at line 1001
int|null
getDefaultCacheTime()
Get the default cache time.
in
Repository at line 1015
Repository
setDefaultCacheTime(int|null $seconds)
Set the default cache time in seconds.
Persists on the cached repository for the worker lifetime and applies to every subsequent write that falls back to the default TTL; per-request use races across coroutines.
in
Repository at line 1026
Store
getStore()
Get the cache store implementation.
in
Repository at line 1040
Repository
setStore(Store $store)
Set the cache store implementation.
Replaces the backing store on the cached repository for the worker lifetime; per-request use races and every concurrent read/write through this repository would hit the wrong store.
in
Repository at line 1051
Dispatcher|null
getEventDispatcher()
Get the event dispatcher instance.
in
Repository at line 1063
void
setEventDispatcher(Dispatcher $events)
Set the event dispatcher instance.
Persists on the cached repository for the worker lifetime; per-request use races across coroutines. Reached by CacheManager::refreshEventDispatcher() from Event::fake() / fakeFor().
in
Repository at line 1075
static void
handleUnserializableClassUsing(callable|null $callback)
Register a callback to be invoked when an unserializable class is encountered.
The callback persists for the worker lifetime and affects every subsequent cache read.
in
Repository at line 1086
string|null
getName()
Get the cache store name.
in
Repository at line 1100
Repository
setName(string $name)
| internal |
Set the cache store name before sharing the repository.
Changing a shared repository's name affects cache events and queued unique-lock cleanup in every coroutine using that repository.
in
Repository at line 1112
bool
offsetExists(string|UnitEnum $offset)
Determine if a cached value exists.
in
Repository at line 1122
mixed
offsetGet(string|UnitEnum $offset)
Retrieve an item from the cache by key.
in
Repository at line 1133
void
offsetSet(string|UnitEnum $offset, mixed $value)
Store an item in the cache for the default time.
in
Repository at line 1143
void
offsetUnset(string|UnitEnum $offset)
Remove an item from the cache.
in
Repository at line 1151
protected mixed
handleManyResult(array $keys, string $key, mixed $value)
Handle a result for the "many" method.
in
Repository at line 1166
protected bool
putManyForever(array $values)
Store multiple items in the cache indefinitely.
at line 51
protected string
itemKey(string $key)
Format the key for a cache item.
in
Repository at line 1190
protected mixed
handleIncompleteClass(string $key, mixed $value)
Handle a cache value that contains an incomplete class.
in
Repository at line 1208
protected int
getSeconds(DateInterval|DateTimeInterface|int $ttl)
Calculate the number of seconds for the given TTL.
in
TaggedCache at line 125
protected void
event(object $event)
Fire an event for this cache instance.
in
Repository at line 1247
mixed
getRaw(UnitEnum|string $key)
| internal | For cache-layer sentinel-aware reads. Application code should use get(), which unwraps NullSentinel::VALUE to null. Fires the same RetrievingKey / CacheHit / CacheMissed events as get(), so observability is unchanged — cached-null entries still fire CacheHit, but the event payload is unwrapped to null to match the public API. Delegates to $this->store->getRaw() when the underlying store implements RawReadable (wrapper stores that need to preserve sentinels across their own internal indirection). Otherwise calls $this->store->get(), which plain stores already implement as a raw read. See getAuthoritativeRaw() for coordination reads that must bypass a non-authoritative wrapper layer. |
Retrieve an item from the cache by key without unwrapping sentinels.
in
Repository at line 1291
mixed
getAuthoritativeRaw(UnitEnum|string $key)
| internal | Used by cache coordination. Application code should use get(). See getRaw() for ordinary sentinel-aware reads that may use an upper layer. |
Retrieve an item without serving it from a non-authoritative read layer.
in
Repository at line 1356
array
manyRaw(array $keys)
| internal | For cache-layer internal use. App code should use many(), which unwraps sentinels via handleManyResult(). Batched raw-read counterpart to getRaw(). Used by flexible() to preserve its single batched store read (avoiding a hot-path regression from splitting into sequential get() calls), while still returning raw sentinels so the caller can distinguish "cached sentinel = hit" from "genuinely absent = miss". Applies itemKey() to each key so tag-namespacing works correctly on TaggedCache / AllTaggedCache (which prepend hash('xxh128', $tagNamespace) . ':'). AnyTaggedCache overrides this method to throw, preserving the any-mode invariant that reads through tags are rejected. Fires RetrievingManyKeys + per-key CacheHit/CacheMissed events, matching the event shape of public many() calls. Store-read and incomplete-class handler failures emit ManyKeysRetrievalFailed; success-listener failures occur after retrieval has completed and are not relabeled as read failures. Delegates to $this->store->manyRaw() when the underlying store implements RawReadable (MemoizedStore / FailoverStore). Otherwise calls $this->store->many(), which plain stores already implement as a raw read. |
Retrieve multiple items from the cache by key without unwrapping sentinels.
in
Repository at line 1420
static void
flushState()
Flush all static state.
in
TaggedCache at line 137
void
__clone()
Give the cloned tagged cache a tag set on its cloned store.
in
TaggedCache at line 77
bool
flush()
Remove all items from the cache.
at line 43
TagSet
getTags()
Get the tag set instance.
at line 35
string
taggedItemKey(string $key)
Get a fully-qualified key for a tagged item.