Documentation

Memcached extends AbstractAdapter
in package
uses NamespacedVersionedKeys

Memcached cache adapter 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

Properties

$clock  : ClockInterface
Clock used to resolve the current time
$memcached  : Memcached|null
Memcached object
$namespace  : string
Cache namespace
$ttl  : int
Global time-to-live
$version  : string|null
Memcached version

Methods

__construct()  : mixed
Constructor
addServer()  : Memcached
Get the current version of memcached.
addServers()  : Memcached
Get the current version of memcached.
clear()  : Memcached
Clear all stored values from cache
decrementItem()  : int
Atomically decrement a counter in cache, creating it at $initial if it doesn't exist
deleteItem()  : Memcached
Delete a value in cache
destroy()  : Memcached
Destroy cache resource
getItem()  : mixed
Get an item from cache
getItemTtl()  : int
Get the time-to-live for an item in cache
getTtl()  : int
Get the global time-to-live for the cache object
getVersion()  : string|null
Get the current version of memcached.
hasItem()  : bool
Determine if the item exist in cache
incrementItem()  : int
Atomically increment a counter in cache, creating it at $initial if it doesn't exist
memcached()  : Memcached
Get the memcached object.
saveItem()  : Memcached
Save an item to cache
setTtl()  : AbstractAdapter
Set the global time-to-live for the cache adapter
fetchVersion()  : mixed
Fetch the raw version value from memcached, or false if it isn't set
isFresh()  : bool
Determine if a cache envelope (with 'start'/'ttl' keys) is still within its time-to-live
key()  : string
Build the versioned, namespaced storage key for an item id
resolveVersion()  : int
Resolve the current version for this namespace, defaulting to 1
versionKey()  : string
Get the storage key for this namespace's version counter

Properties

$memcached

Memcached object

protected Memcached|null $memcached = null

$namespace

Cache namespace

protected string $namespace = 'pop_cache'

$version

Memcached version

protected string|null $version = null

Methods

__construct()

Constructor

public __construct([int $ttl = 0 ][, string $host = 'localhost' ][, int $port = 11211 ][, int $weight = 1 ][, string $namespace = 'pop_cache' ][, ClockInterface $clock = new ClockSystemClock() ]) : mixed

Instantiate the memcached cache object

Parameters
$ttl : int = 0
$host : string = 'localhost'
$port : int = 11211
$weight : int = 1
$namespace : string = 'pop_cache'
$clock : ClockInterface = new ClockSystemClock()
Tags
throws
Exception

addServer()

Get the current version of memcached.

public addServer(string $host[, int $port = 11211 ][, int $weight = 1 ]) : Memcached
Parameters
$host : string
$port : int = 11211
$weight : int = 1
Return values
Memcached

addServers()

Get the current version of memcached.

public addServers(array<string|int, mixed> $servers) : Memcached
Parameters
$servers : array<string|int, mixed>
Return values
Memcached

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

Stored as a raw scalar, bypassing the start/ttl/value envelope used by saveItem()/getItem() entirely — a counter key and a saveItem()-managed key are two incompatible storage formats on this adapter, and a counter is not readable via getItem(). Unlike Redis/Apc, Memcached::decrement() clamps its result at 0 (unsigned 64-bit wire protocol) rather than going negative — a documented, accepted quirk of this adapter specifically.

Deviation from the original plan: seeds via Memcached::add() before Memcached::decrement(), for the same reasons as incrementItem() above (see that method's docblock) — symmetry, and so a newly-created counter reflects $amount applied on top of $initial rather than $initial alone.

Parameters
$id : string
$amount : int = 1
$initial : int = 0
$ttl : int|null = null
Tags
throws
Exception
Return values
int

getItem()

Get an item from cache

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

getItemTtl()

Get the time-to-live for an item in cache

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

getTtl()

Get the global time-to-live for the cache object

public getTtl() : int
Return values
int

getVersion()

Get the current version of memcached.

public getVersion() : string|null
Return values
string|null

hasItem()

Determine if the item exist in cache

public hasItem(string $id) : bool
Parameters
$id : string
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

Stored as a raw scalar, bypassing the start/ttl/value envelope used by saveItem()/getItem() entirely — a counter key and a saveItem()-managed key are two incompatible storage formats on this adapter, and a counter is not readable via getItem(). Requires the binary protocol (enabled in the constructor) — the default ASCII protocol silently ignores a non-default initial value. $ttl is honored only when the counter is first created; a later call does not refresh an existing counter's expiry.

Deviation from the original plan: Memcached::increment() alone, when creating a new counter, seeds it at $initial only and silently discards $amount (verified empirically: incrementItem('x', 5, 100) on a fresh key yields 100, not 105) — unlike Apc/Redis, where the equivalent single primitive folds both together. It also leaves the value stored as a raw ASCII wire-protocol counter, which Memcached::get() then returns as a string, not an int. So, mirroring the Apc adapter's apcu_add()+apcu_inc() pattern, this seeds via Memcached::add() (a no-op if the key already exists) and then unconditionally applies Memcached::increment() on top — this also happens to make Memcached::get() return a proper int thereafter, since add() stores through the normal serializer.

Parameters
$id : string
$amount : int = 1
$initial : int = 0
$ttl : int|null = null
Tags
throws
Exception
Return values
int

memcached()

Get the memcached object.

public memcached() : Memcached
Return values
Memcached

saveItem()

Save an item to cache

public saveItem(string $id, mixed $value[, int|null $ttl = null ]) : Memcached
Parameters
$id : string
$value : mixed
$ttl : int|null = null
Return values
Memcached

fetchVersion()

Fetch the raw version value from memcached, or false if it isn't set

protected fetchVersion(string $key) : mixed
Parameters
$key : string

isFresh()

Determine if a cache envelope (with 'start'/'ttl' keys) is still within its time-to-live

protected isFresh(array<string|int, mixed> $envelope) : bool
Parameters
$envelope : array<string|int, mixed>
Return values
bool

key()

Build the versioned, namespaced storage key for an item id

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

resolveVersion()

Resolve the current version for this namespace, defaulting to 1

protected resolveVersion() : int
Return values
int

versionKey()

Get the storage key for this namespace's version counter

protected versionKey() : string
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results