Documentation

Cache
in package
implements ArrayAccess, CacheInterface uses ValidatesKey

Cache class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
5.0.0

Table of Contents

Interfaces

ArrayAccess
CacheInterface

Properties

$adapter  : AdapterInterface|null
Cache adapter
$clock  : ClockInterface
Clock used for stampede-protection bookkeeping (remember()'s $beta parameter)

Methods

__construct()  : mixed
Constructor
__get()  : mixed
Magic get method to return an item from cache
__isset()  : bool
Determine if the item is in cache
__set()  : void
Magic set method to save an item in the cache
__unset()  : void
Delete value from cache
adapter()  : AdapterInterface|null
Get the adapter
clear()  : bool
Clear all stored values from cache
decrementItem()  : int
Atomically decrement a counter in cache, creating it at $initial if it doesn't exist
delete()  : bool
Delete an item from the cache (PSR-16)
deleteItem()  : void
Delete an item in cache
deleteItems()  : void
Delete items in cache
deleteMultiple()  : bool
Delete multiple cache items in a single operation (PSR-16)
destroy()  : void
Destroy cache resource
get()  : mixed
Fetch a value from the cache (PSR-16)
getAvailableAdapters()  : array<string|int, mixed>
Determine available adapters
getItem()  : mixed
Get an item from cache
getItemTtl()  : int
Get item cache TTL
getMultiple()  : iterable<string|int, mixed>
Obtain multiple cache items by their unique keys (PSR-16)
getTtl()  : int
Get global cache TTL
has()  : bool
Determine whether an item is present in the cache (PSR-16)
hasItem()  : bool
Determine if the item is in cache
incrementItem()  : int
Atomically increment a counter in cache, creating it at $initial if it doesn't exist
invalidateTag()  : void
Delete every item currently tagged with $tag, and the tag's own bookkeeping
invalidateTags()  : void
Invalidate multiple tags in a single operation
isAvailable()  : bool
Determine if an adapter is available
offsetExists()  : bool
ArrayAccess offsetExists
offsetGet()  : mixed
ArrayAccess offsetGet
offsetSet()  : void
ArrayAccess offsetSet
offsetUnset()  : void
ArrayAccess offsetUnset
remember()  : mixed
Get an item from cache, or compute and cache it via the callback if it isn't already cached
saveItem()  : void
Save an item to cache
saveItems()  : void
Save items to cache
saveTaggedItem()  : void
Save an item to cache under one or more tags for later bulk invalidation via invalidateTag()
set()  : bool
Persist a value in the cache, with an optional TTL (PSR-16)
setMultiple()  : bool
Persist a set of key => value pairs in the cache, with an optional TTL (PSR-16)
addToTagIndex()  : void
Add $id to $tag's member index, creating the index if it doesn't exist yet
rememberMetaKey()  : string
Get the internal bookkeeping key for an id's stampede-protection metadata
removeFromTagIndex()  : void
Remove $id from $tag's member index, deleting the index entirely if it becomes empty
tagIndexKey()  : string
Get the internal bookkeeping key for a tag's member index
tagsForKey()  : string
Get the internal bookkeeping key for an id's own current tag list
validateKey()  : void
Validate a cache key (throws on reserved characters or an empty string)

Properties

$clock

Clock used for stampede-protection bookkeeping (remember()'s $beta parameter)

protected ClockInterface $clock

Methods

__get()

Magic get method to return an item from cache

public __get(string $name) : mixed
Parameters
$name : string

__isset()

Determine if the item is in cache

public __isset(string $name) : bool
Parameters
$name : string
Return values
bool

__set()

Magic set method to save an item in the cache

public __set(string $name, mixed $value) : void
Parameters
$name : string
$value : mixed

__unset()

Delete value from cache

public __unset(string $name) : void
Parameters
$name : string

clear()

Clear all stored values from cache

public clear() : bool
Return values
bool

decrementItem()

Atomically decrement a counter in cache, creating it at $initial if it doesn't exist

public decrementItem(string $id[, int $amount = 1 ][, int $initial = 0 ][, int|null $ttl = null ]) : int
Parameters
$id : string
$amount : int = 1
$initial : int = 0
$ttl : int|null = null
Tags
throws
InvalidArgumentException
Return values
int

delete()

Delete an item from the cache (PSR-16)

public delete(string $key) : bool
Parameters
$key : string
Tags
throws
InvalidArgumentException
Return values
bool

deleteItems()

Delete items in cache

public deleteItems(array<string|int, mixed> $ids) : void
Parameters
$ids : array<string|int, mixed>
Tags
throws
InvalidArgumentException

deleteMultiple()

Delete multiple cache items in a single operation (PSR-16)

public deleteMultiple(iterable<string|int, mixed> $keys) : bool
Parameters
$keys : iterable<string|int, mixed>
Tags
throws
InvalidArgumentException
Return values
bool

destroy()

Destroy cache resource

public destroy() : void

get()

Fetch a value from the cache (PSR-16)

public get(string $key[, mixed $default = null ]) : mixed
Parameters
$key : string
$default : mixed = null
Tags
throws
InvalidArgumentException

getAvailableAdapters()

Determine available adapters

public static getAvailableAdapters() : array<string|int, mixed>
Return values
array<string|int, mixed>

getItem()

Get an item from cache

public getItem(string $id[, mixed $default = false ]) : mixed
Parameters
$id : string
$default : mixed = false
Tags
throws
InvalidArgumentException

getItemTtl()

Get item cache TTL

public getItemTtl(string $id[, int $default = 0 ]) : int
Parameters
$id : string
$default : int = 0
Return values
int

getMultiple()

Obtain multiple cache items by their unique keys (PSR-16)

public getMultiple(iterable<string|int, mixed> $keys[, mixed $default = null ]) : iterable<string|int, mixed>
Parameters
$keys : iterable<string|int, mixed>
$default : mixed = null
Tags
throws
InvalidArgumentException
Return values
iterable<string|int, mixed>

getTtl()

Get global cache TTL

public getTtl() : int
Return values
int

has()

Determine whether an item is present in the cache (PSR-16)

public has(string $key) : bool
Parameters
$key : string
Tags
throws
InvalidArgumentException
Return values
bool

hasItem()

Determine if the item is in cache

public hasItem(string $id) : bool
Parameters
$id : string
Tags
throws
InvalidArgumentException
Return values
bool

incrementItem()

Atomically increment a counter in cache, creating it at $initial if it doesn't exist

public incrementItem(string $id[, int $amount = 1 ][, int $initial = 0 ][, int|null $ttl = null ]) : int
Parameters
$id : string
$amount : int = 1
$initial : int = 0
$ttl : int|null = null
Tags
throws
InvalidArgumentException
Return values
int

invalidateTag()

Delete every item currently tagged with $tag, and the tag's own bookkeeping

public invalidateTag(string $tag) : void

Non-atomic: see saveTaggedItem() and docs/POP-CACHE.md for the full mechanism and known limitations.

Parameters
$tag : string
Tags
throws
InvalidArgumentException

invalidateTags()

Invalidate multiple tags in a single operation

public invalidateTags(array<string|int, mixed> $tags) : void

Validates every tag before invalidating any of them (all-or-nothing), matching this codebase's existing getMultiple()/setMultiple()/deleteMultiple() precedent.

Parameters
$tags : array<string|int, mixed>
Tags
throws
InvalidArgumentException

isAvailable()

Determine if an adapter is available

public static isAvailable(string $adapter) : bool
Parameters
$adapter : string
Return values
bool

offsetExists()

ArrayAccess offsetExists

public offsetExists(mixed $offset) : bool
Parameters
$offset : mixed
Return values
bool

offsetGet()

ArrayAccess offsetGet

public offsetGet(mixed $offset) : mixed
Parameters
$offset : mixed

offsetSet()

ArrayAccess offsetSet

public offsetSet(mixed $offset, mixed $value) : void
Parameters
$offset : mixed
$value : mixed

offsetUnset()

ArrayAccess offsetUnset

public offsetUnset(mixed $offset) : void
Parameters
$offset : mixed

remember()

Get an item from cache, or compute and cache it via the callback if it isn't already cached

public remember(string $id, callable $callback[, int|null $ttl = null ][, float $beta = 0.0 ]) : mixed

Any exception thrown by $callback propagates unchanged, and nothing is written to cache in that case.

$beta enables probabilistic early recomputation (the XFetch algorithm) to reduce stampedes on steady-state re-computation: as a cached item approaches its TTL, reads have an increasing chance of triggering recomputation before hard expiry, so one caller refreshes the value while concurrent readers keep getting served the still-valid cached copy. $beta = 0.0 (the default) disables this entirely — mathematically equivalent to remember()'s behavior before this parameter existed, with zero extra adapter calls. This does NOT protect a key's true first-ever call (no cached value, no bookkeeping yet) — every concurrent caller on a genuine cold miss still recomputes; that requires locking, which this method deliberately does not implement. Never-expiring items (a resolved TTL of 0, whether explicit or from the adapter's global TTL) are not eligible for early recomputation — there's no expiry to recompute ahead of, so $beta has no effect on them. A callback that completes in under one second still gets a minimum effective delta of 1 second for the XFetch calculation, so $beta needs to be scaled accordingly for very fast callbacks to see meaningful early-recompute lead time (roughly delta × beta seconds before real expiry). See docs/POP-CACHE.md for the full algorithm and why the bookkeeping key's TTL policy differs from saveTaggedItem()'s.

Parameters
$id : string
$callback : callable
$ttl : int|null = null
$beta : float = 0.0
Tags
throws
InvalidArgumentException

saveItem()

Save an item to cache

public saveItem(string $id, mixed $value[, int|null $ttl = null ]) : void
Parameters
$id : string
$value : mixed
$ttl : int|null = null
Tags
throws
InvalidArgumentException

saveItems()

Save items to cache

public saveItems(array<string|int, mixed> $items) : void
Parameters
$items : array<string|int, mixed>
Tags
throws
InvalidArgumentException

saveTaggedItem()

Save an item to cache under one or more tags for later bulk invalidation via invalidateTag()

public saveTaggedItem(string $id, mixed $value, array<string|int, mixed> $tags[, int|null $ttl = null ]) : void

Non-atomic: every step here is a plain read-modify-write via the adapter's own getItem()/saveItem()/ deleteItem(), with no locking. Mixing plain saveItem()/deleteItem() calls with saveTaggedItem() on the same id leaves tag bookkeeping stale — see docs/POP-CACHE.md for the full mechanism and known limitations. Both the tag index and this id's own tags-for bookkeeping are saved with ttl=0 (never expire) regardless of $ttl, so re-tagging reconciliation always has an accurate view of an id's prior tags even after the item itself has naturally expired — see docs/POP-CACHE.md for why an asymmetric policy here is a correctness bug, not just a minor inconsistency.

Parameters
$id : string
$value : mixed
$tags : array<string|int, mixed>
$ttl : int|null = null
Tags
throws
InvalidArgumentException

set()

Persist a value in the cache, with an optional TTL (PSR-16)

public set(string $key, mixed $value[, null|int|DateInterval $ttl = null ]) : bool

A $ttl of null uses the adapter's configured global TTL. A $ttl (or a \DateInterval resolved to seconds) that is zero or negative deletes the item instead of caching it, per the PSR-16 spec — note this differs from saveItem()'s own "0 = never expires" convention, which is unaffected by this method and remains available via saveItem() directly.

Parameters
$key : string
$value : mixed
$ttl : null|int|DateInterval = null
Tags
throws
InvalidArgumentException
Return values
bool

setMultiple()

Persist a set of key => value pairs in the cache, with an optional TTL (PSR-16)

public setMultiple(iterable<string|int, mixed> $values[, null|int|DateInterval $ttl = null ]) : bool
Parameters
$values : iterable<string|int, mixed>
$ttl : null|int|DateInterval = null
Tags
throws
InvalidArgumentException
Return values
bool

addToTagIndex()

Add $id to $tag's member index, creating the index if it doesn't exist yet

protected addToTagIndex(string $tag, string $id) : void

Reads/writes the index directly via the adapter (not $this->getItem()/saveItem()), since the internally-generated key uses '@', a character validateKey() forbids in user-supplied keys. The index is always saved with ttl=0 (never expires), regardless of any individual tagged item's TTL, since multiple items with different TTLs can share one tag.

Parameters
$tag : string
$id : string

rememberMetaKey()

Get the internal bookkeeping key for an id's stampede-protection metadata

protected rememberMetaKey(string $id) : string
Parameters
$id : string
Return values
string

removeFromTagIndex()

Remove $id from $tag's member index, deleting the index entirely if it becomes empty

protected removeFromTagIndex(string $tag, string $id) : void
Parameters
$tag : string
$id : string

tagIndexKey()

Get the internal bookkeeping key for a tag's member index

protected tagIndexKey(string $tag) : string
Parameters
$tag : string
Return values
string

tagsForKey()

Get the internal bookkeeping key for an id's own current tag list

protected tagsForKey(string $id) : string
Parameters
$id : string
Return values
string

validateKey()

Validate a cache key (throws on reserved characters or an empty string)

protected validateKey(string $key) : void
Parameters
$key : string
Tags
throws
InvalidArgumentException 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results