API Reference

This section details the public methods available on the Memcached class.

Connection & Instance Management

__construct

public function __construct( ?string $persistent_id = null, ?callable $callback = null, ?string $connection_str = null )
Creates a Memcached instance.

  • $persistent_id: Passing a string here enables persistent connections. All instances created with the same ID share the same connection pool.
  • $callback: A function triggered only when a new underlying connection is created. Useful for initializing server lists. Signature: function (Memcached $obj, string $persistent_id).
  • $connection_str: A libmemcached configuration string to auto-configure the client.

addServer

public function addServer( string $host, int $port, int $weight = 0 ): bool
Adds a single server to the connection pool. $weight determines the probability of the server being selected (higher weight = more keys routed here).

addServers

public function addServers( array $servers ): bool
Adds an array of servers. Format: [['host', port, weight], ['host', port, weight]].

getServerList / getServerByKey

public function getServerList(): array
public function getServerByKey( string $server_key ): array|false
getServerList returns the current pool. getServerByKey shows exactly which server node a specific $server_key will map to (useful for debugging hashing distributions).

quit

public function quit(): bool
Closes all open connections to memcached servers. Useful in long-running CLI scripts.

Data Operations (Write)

set / setByKey

public function set( string $key, mixed $value, int $expiration = 0 ): bool
public function setByKey( string $server_key, string $key, mixed $value, int $expiration = 0 ): bool
Stores a value. $expiration is either a TTL in seconds (up to 30 days) or a Unix timestamp. Note: setByKey forces the data to a specific server mapped by $server_key regardless of what $key hashes to.

add / replace

public function add( string $key, mixed $value, int $expiration = 0 ): bool
public function replace( string $key, mixed $value, int $expiration = 0 ): bool
  • add: Succeeds only if the key does not exist.
  • replace: Succeeds only if the key already exists.

setMulti

public function setMulti( array $items, int $expiration = 0 ): bool
Sets multiple Key-Value pairs in a single batch operation. $items is an associative array ['key1' => 'val1', 'key2' => 'val2'].

cas

public function cas( string|int|float $cas_token, string $key, mixed $value, int $expiration = 0 ): bool
Check And Set. Stores the value only if the $cas_token (retrieved via get with GET_EXTENDED) matches the one currently on the server. Fails if the data was modified by another process.

increment / decrement

public function increment( string $key, int $offset = 1, int $initial_value = 0, int $expiry = 0 ): int|false
public function decrement( string $key, int $offset = 1, int $initial_value = 0, int $expiry = 0 ): int|false
Atomically increments/decrements a numeric value. If the key does not exist, it is initialized to $initial_value.

append / prepend

public function append( string $key, string $value ): ?bool
public function prepend( string $key, string $value ): ?bool
Appends/prepends string data to an existing string value. Note: This will fail and corrupt data if compression (Memcached::OPT_COMPRESSION) is enabled.

delete / deleteMulti

public function delete( string $key, int $time = 0 ): bool
public function deleteMulti( array $keys, int $time = 0 ): array
Removes keys from the server. deleteMulti returns an array indicating the success/failure of each key.

Data Operations (Read)

get / getByKey

public function get( string $key, ?callable $cache_cb = null, int $get_flags = 0 ): mixed
Retrieves a value.

  • $cache_cb: A Read-Through cache callback. Invoked if the key is not found. Signature: function (Memcached $memc, string $key, mixed &$value, int &$expiration).
  • $get_flags: Pass Memcached::GET_EXTENDED to return an array containing value, cas, and flags.

getMulti

public function getMulti( array $keys, int $get_flags = 0 ): array|false
Retrieves multiple keys at once. Returns an associative array of found keys. Pass Memcached::GET_PRESERVE_ORDER in $get_flags to guarantee the return array order matches the $keys array input.

getDelayed / fetch / fetchAll

public function getDelayed( array $keys, bool $with_cas = false, ?callable $value_cb = null ): bool
public function fetch(): array|false
public function fetchAll(): array|false
getDelayed requests multiple keys asynchronously over the network. You must then loop through fetch() or call fetchAll() to collect the results from the buffer.

Informational & Configuration

getResultCode / getResultMessage

public function getResultCode(): int
public function getResultMessage(): string
Returns the integer code (e.g., Memcached::RES_SUCCESS, Memcached::RES_NOTFOUND) and human-readable message of the last executed operation.

getStats

public function getStats( ?string $type = null ): array|false
Returns a 2D associative array containing server statistics (uptime, memory usage, cache hits/misses, connection counts) for every server in the pool.

setOption / setOptions / getOption

public function setOption( int $option, mixed $value ): bool
public function setOptions( array $options ): bool
public function getOption( int $option ): mixed
Modify runtime behaviors (e.g., serializers, compression, consistent hashing). See Constants for available OPT_* values.

setSaslAuthData

public function setSaslAuthData( string $username, #[
SensitiveParameter] string $password ): bool
Authenticates the connection to the Memcached servers. The binary protocol (OPT_BINARY_PROTOCOL) must be enabled first.