public Memcached $mc;

private string $cache_key_salt_hash = '';

// Array of group_name => true

private array $global_groups;

// Temporary cache that vanishes at

// the end of script execution.

private array $local_cache;

// Marker object used to represent missing cache items

private readonly object $local_missing_marker;

// Array of group_name => array of keys => values

private array $non_persistent_groups;

// Array of pre-seeded keys

private ?array $preseed_keys = null;

public function __construct(

string $persistent_id,

callable $get_servers,

/**

private readonly string $non_global_prefix,

string $cache_key_salt = '',

/**

private readonly string $global_prefix = 'global',

) {

if ( $cache_key_salt !== '' ) {

$this->cache_key_salt_hash = md5( $cache_key_salt );

}

$this->global_groups = [];

$this->local_cache = [];

$this->local_missing_marker = new stdClass();

$this->non_persistent_groups = [];

// https://www.php.net/manual/en/memcached.construct.php

$mc = new Memcached( $persistent_id );

// We can only enable binary protocol for new connections

if ( $mc->isPristine() ) {

$result = $mc->setOptions(

[

Memcached::OPT_CONNECT_TIMEOUT => 500,

Memcached::OPT_RETRY_TIMEOUT => 0,

]

);

if ( $result === false ) {

error_log( 'Failed to set connection options for Memcached' );

}

if ( SNAPCACHE_MEMCACHED_USE_BINARY === true ) {

$result = $mc->setOptions(

[

Memcached::OPT_BINARY_PROTOCOL => true,

// Binary protocol is very slow without this

Memcached::OPT_TCP_NODELAY => true,

]

);

if ( $result === false ) {

error_log( 'Failed to enable binary protocol for Memcached' );

}

}

}

$admin = is_admin();

$server_list = $mc->getServerList();

// Since the Memcached instance persists across

// requests, we must take care not to add servers

// that are already in the list.

if ( $admin || empty( $server_list ) ) {

try {

$servers = $get_servers();

} catch ( Exception $e ) {

error_log( 'Invalid memcached server format: ' . $e->getMessage() );

// If we can't set servers, we just return with no

// server list. This class will still work as an

// in-memory object cache. The admin UI logic can

// detect an invalid config and prompt the admin to

// fix it.

}

if ( ! is_array( $servers ) ) {

error_log( 'Invalid memcached server format' );

} elseif ( count( $servers ) !== count( $server_list ) ) {

if ( ! ( $mc->resetServerList() && $mc->addServers( $servers ) ) ) {

error_log( 'Memcached addServers failed' );

}

} else {

$comparator = function ( array $a, array $b ): int {

if ( array_is_list( $a ) ) {

return $a[0] === $b['host'] && $a[1] === $b['port'] ? 0 : -1;

}

return $b[0] === $a['host'] && $b[1] === $a['port'] ? 0 : 1;

};

if ( ( array_udiff( $servers, $server_list, $comparator ) !== []

|| array_udiff( $server_list, $servers, $comparator ) !== [] )

) {

if ( $mc->resetServerList() && $mc->addServers( $servers ) ) {

// If servers were changed, then some data is probably

// out of sync.

if ( ! empty( $server_list ) ) {

$mc->flush();

}

} else {

error_log( 'Memcached addServers failed' );

}

}

}

}

$this->mc = $mc;

}

/**

public static function parseServerToArray( mixed $data ): array {

if ( is_array( $data ) ) {

// Ensure array has at least server, port defaults to 11211, weight defaults to 0

$server = $data[0] ?? null;

if ( $server === null ) {

throw new Exception( 'Invalid server data: missing server' );

}

$port = isset( $data[1] ) && $data[1] !== '' ? (int) $data[1] : 11211;

$weight = isset( $data[2] ) && $data[2] !== '' ? (int) $data[2] : 0;

return [ $server, $port, $weight ];

}

if ( is_string( $data ) ) {

// We intentionally leave values after extra spaces

// uninterpreted and reserved for future use.

$parts = explode( ' ', $data );

$weight = isset( $parts[1] ) && $parts[1] !== '' ? (int) $parts[1] : 0;

if ( ! isset( $parts[0] ) ) {

throw new Exception( 'Invalid server data' );

}

$parts = explode( ':', $parts[0] );

if ( ! isset( $parts[0] ) ) {

throw new Exception( 'Invalid server data' );

}

$server = $parts[0];

$port = isset( $parts[1] ) && $parts[1] !== '' ?

(int) $parts[1] : 11211;

return [ $server, $port, $weight ];

}

throw new Exception(

'Invalid server data. Expected array or string. '

);

}

/**

public static function getServersFromConfig(): array {

if ( defined( 'SNAPCACHE_MEMCACHED_SERVERS' ) ) {

return array_map( self::parseServerToArray( ... ), SNAPCACHE_MEMCACHED_SERVERS );

}

// If SNAPCACHE_MEMCACHED_SERVERS is not set,

// try to look up an option from the

// DB. We can do this because any competent

// host will keep persistent connections,

// so we won't do this query for most requests.

// WP-CLI doesn't keep connections, but that's ok

// because this is a very cheap query to do.

global $wpdb;

// We can't use get_option because it tries

// to call us. We have to do a direct query.

// phpcs:ignore WordPress.DB.DirectDatabaseQuery

$result = $wpdb->get_var(

$wpdb->prepare(

"SELECT option_value FROM {$wpdb->options} WHERE option_name = %s",

'snapcache_memcached_servers'

)

);

$raw = $result ? maybe_unserialize( $result ) : 'localhost:11211';

// Since the admin may type servers in a textarea, we want

// to ignore blank lines and extra whitespace.

$lines = array_map( trim( ... ), explode( "\n", $raw ) );

$non_blank_lines = array_filter( $lines, fn( $line ): bool => $line !== '' );

return array_map( self::parseServerToArray( ... ), $non_blank_lines );

}

/**

public static function initAndBuild(): self {

if ( ! defined( 'WP_CACHE_KEY_SALT' ) ) {

define( 'WP_CACHE_KEY_SALT', '' );

}

if ( ! defined( 'SNAPCACHE_MEMCACHED_PERSISTENT_ID' ) ) {

define( 'SNAPCACHE_MEMCACHED_PERSISTENT_ID', 'snapcache' );

}

if ( ! defined( 'SNAPCACHE_PRESEEDS' ) ) {

define(

'SNAPCACHE_PRESEEDS',

[

[ 'is_blog_installed', 'default' ],

[ 'alloptions', 'options' ],

[ 'notoptions', 'options' ],

[ get_current_blog_id() . ':notoptions', 'site-options', true ],

[ 'doing_cron', 'transient' ],

[ 'wp_core_block_css_files', 'transient' ],

[ 'wp_styles_for_blocks', 'transient' ],

]

);

}

if ( ! defined( 'SNAPCACHE_MEMCACHED_USE_BINARY' ) ) {

// The binary protocol has severe perfomance issues

// See https://github.com/memcached/memcached/issues/775

define( 'SNAPCACHE_MEMCACHED_USE_BINARY', false );

}

return new SnapCacheMemcached(

SNAPCACHE_MEMCACHED_PERSISTENT_ID,

self::getServersFromConfig( ... ),

(string) get_current_blog_id(),

WP_CACHE_KEY_SALT,

);

}

private function can_add(): bool

{

return ! wp_suspend_cache_addition();

}

private function cache_key(

int|string $key,

string $group,

bool $force_global = false,

): string {

if ( $key === '' ) {

throw new Exception( 'Cache key cannot be empty' );

}

// For compatibility with WordPress

if ( $group === '' ) {

$group = 'default';

}

$prefix = ( $force_global || isset( $this->global_groups[ $group ] ) )

? $this->global_prefix

: $this->non_global_prefix;

$key = $prefix . $group . ':' . $key . $this->cache_key_salt_hash;

// Unfortunately WordPress uses a lot of keys with spaces,

// and the memcached text protocol doesn't allow that.

if ( ! SNAPCACHE_MEMCACHED_USE_BINARY && str_contains( $key, ' ' ) ) {

$key = str_replace( ' ', '_', $key );

}

// Truncate long keys and add a hash.

// Memcached only allows 250 bytes for keys.

if ( strlen( $key ) >= 250 ) {

// Preserve as much of the key as we can.

// Split the key without breaking up any

// multi-byte characters.

$key_start = mb_substr( $key, 0, 218 );

$sl = strlen( $key_start );

while ( $sl > 218 ) {

$key_start = mb_substr(

$key_start,

0,

218 - ( $sl - 218 ),

);

$sl = strlen( $key_start );

}

// Append the key's hash to the part of the

// key that we were able to keep.

$key = $key_start . md5( $key );

}

return $key;

}

/**

public static function to_memcache_expiration(

int $expire,

): int {

// Number of seconds in 30 days

if ( $expire <= 2592000 ) {

return $expire;

}

return $expire + time();

}

/**

public static function maybe_clone(

mixed $data,

): mixed {

if ( is_object( $data ) ) {

return clone $data;

}

return $data;

}

/**

public function add(

int|string $key,

mixed $data,

string $group = '',

int $expire = 0,

): bool {

if ( ! $this->can_add() ) {

return false;

}

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] )

&& ! array_key_exists( $k, $this->non_persistent_groups[ $group ] ) ) {

$data = self::maybe_clone( $data );

$this->non_persistent_groups[ $group ][ $k ] = $data;

return true;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$expire = self::to_memcache_expiration( $expire );

if ( $this->mc->add( $k, $data, $expire ) ) {

$this->local_cache[ $k ] = self::maybe_clone( $data );

return true;

}

// We don't know the state of the memcached item

unset( $this->local_cache[ $k ] );

return false;

}

/**

public function add_multiple(

array $data,

string $group = '',

int $expire = 0,

): array {

if ( ! $this->can_add() || $data === [] ) {

return [];

}

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

$arr = [];

foreach ( array_keys( $data ) as $key ) {

$k = $this->cache_key( $key, $group );

if ( array_key_exists( $k, $this->non_persistent_groups[ $group ] ) ) {

$arr[ $key ] = false;

} else {

$data = self::maybe_clone( $data );

$this->non_persistent_groups[ $group ][ $k ] = $data;

$arr[ $key ] = true;

}

}

return $arr;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$expire = self::to_memcache_expiration( $expire );

$arr = [];

// Memcached doesn't support addMulti, so we

// iterate over many add() calls.

foreach ( $data as $key => $v ) {

$k = $this->cache_key( $key, $group );

if ( $this->mc->add( $k, $v, $expire ) ) {

$this->local_cache[ $k ] = self::maybe_clone( $v );

$arr[ $key ] = true;

} else {

// We don't know the state of the memcached item

unset( $this->local_cache[ $k ] );

$arr[ $key ] = false;

}

}

return $arr;

}

public function add_global_groups(

array $groups,

): void {

$this->global_groups = array_merge(

$this->global_groups,

array_fill_keys( $groups, true ),

);

}

public function add_non_persistent_groups(

array $groups,

): void {

$this->non_persistent_groups = array_merge(

$this->non_persistent_groups,

array_fill_keys( $groups, [] ),

);

}

/**

public function decr(

int|string $key,

int $offset = 1,

string $group = '',

): int|false {

return $this->incr( $key, -$offset, $group );

}

/**

public function delete(

int|string $key,

string $group = '',

): bool {

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

unset( $this->non_persistent_groups[ $group ][ $k ] );

return true;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

if ( $this->mc->delete( $k ) ) {

$this->local_cache[ $k ] = $this->local_missing_marker;

return true;

}

return false;

}

/**

public function delete_multiple(

array $keys,

string $group = '',

): array {

if ( $keys === [] ) {

return [];

}

$ks = array_map(

fn( int|string $k ): string => $this->cache_key( $k, $group ),

$keys,

);

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

foreach ( $ks as $k ) {

unset( $this->non_persistent_groups[ $group ][ $k ] );

}

return array_fill_keys( $ks, true );

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$results = $this->mc->deleteMulti( $ks );

foreach ( $results as $k => $v ) {

if ( $v === true ) {

$this->local_cache[ $k ] = $this->local_missing_marker;

} else {

// We aren't sure of the state of the item

unset( $this->local_cache[ $k ] );

// Turn Memcached::RES_* constants into false

$results[ $k ] = false;

}

}

return $results;

}

/**

private function fetch_all(): void {

$results = $this->mc->fetchAll();

if ( $results === false ) {

return;

}

$preseed_map = array_fill_keys(

$this->preseed_keys,

true,

);

$this->preseed_keys = null;

foreach ( $results as $result ) {

$k = $result ['key'];

$this->local_cache[ $k ] = $result['value'];

unset( $preseed_map[ $k ] );

}

// We want to seed misses as well because the extra

// processing to track misses is cheap compared to

// the cost of making an extra memcached request.

foreach ( array_keys( $preseed_map ) as $miss ) {

$this->local_cache[ $miss ] = $this->local_missing_marker;

}

}

/**

public function flush(): bool {

return $this->mc->flush() && $this->flush_runtime();

}

/**

public function flush_runtime(): bool {

$this->local_cache = [];

$this->non_persistent_groups =

array_fill_keys(

array_keys( $this->non_persistent_groups ),

[]

);

return true;

}

/**

public function get(

int|string $key,

string $group = '',

bool $force = false,

?bool &$found = null

): mixed {

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

if ( array_key_exists( $k, $this->non_persistent_groups[ $group ] ) ) {

$found = true;

return self::maybe_clone( $this->non_persistent_groups[ $group ][ $k ] );

}

$found = false;

return false;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

if ( ! $force && array_key_exists( $k, $this->local_cache ) ) {

$v = $this->local_cache[ $k ];

if ( $v === $this->local_missing_marker ) {

$found = false;

return false;

}

$found = true;

return self::maybe_clone( $v );

}

$data = $this->mc->get( $k );

$found = $data !== false || $this->mc->getResultCode() === Memcached::RES_SUCCESS;

$this->local_cache[ $k ] = $found

? self::maybe_clone( $data )

: $this->local_missing_marker;

return $data;

}

/**

public function get_multiple(

array $keys,

string $group = '',

bool $force = false,

): mixed {

if ( $keys === [] ) {

return [];

}

$ks = array_map(

fn( int|string $k ): string => $this->cache_key( $k, $group ),

$keys,

);

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

$arr = [];

foreach ( $ks as $k ) {

if ( array_key_exists( $k, $this->non_persistent_groups[ $group ] ) ) {

$arr[ $k ] = self::maybe_clone(

$this->non_persistent_groups[ $group ][ $k ],

);

} else {

$arr[ $k ] = false;

}

}

return $arr;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

if ( ! $force ) {

// Look up as many locally cached keys as we can

$local = [];

foreach ( $ks as $k ) {

if ( array_key_exists( $k, $this->local_cache ) ) {

$v = $this->local_cache[ $k ];

$local[ $k ] = $v === $this->local_missing_marker

? false

: self::maybe_clone( $v );

}

}

} else {

$local = null;

}

// Don't hit memcached for items we found locally

if ( $local !== null && $local !== [] ) {

$ks_to_keys = array_combine( $ks, $keys );

$arr = [];

foreach ( $ks_to_keys as $k => $key ) {

if ( array_key_exists( $k, $local ) ) {

$arr[ $key ] = $local[ $k ];

}

}

$ks = array_diff( $ks, array_keys( $local ) );

// All keys were found locally

if ( $ks === [] ) {

return $arr;

}

$local = $arr;

}

$result = $this->mc->getMulti( $ks );

if ( $result === false ) {

if ( $local === null || $local === [] ) {

return array_fill_keys( $keys, false );

}

return array_merge(

array_fill_keys( $keys, false ),

$local,

);

}

if ( ! isset( $ks_to_keys ) ) {

$ks_to_keys = array_combine( $ks, $keys );

}

// These do essentially the same thing if $local is

// empty, but the then branch can skip the lookups.

if ( $local === null || $local === [] ) {

$arr = [];

foreach ( $ks_to_keys as $k => $key ) {

if ( isset( $result[ $k ] ) ) {

$v = $result[ $k ];

$this->local_cache[ $k ] = self::maybe_clone( $v );

$arr[ $key ] = $v;

} else {

unset( $this->local_cache[ $k ] );

$arr[ $key ] = false;

}

}

return $arr;

}

$arr = [];

foreach ( $ks_to_keys as $k => $key ) {

if ( isset( $result[ $k ] ) ) {

$v = $result[ $k ];

$this->local_cache[ $k ] = self::maybe_clone( $v );

$arr[ $key ] = $v;

} elseif ( isset( $local[ $key ] ) ) {

$arr[ $key ] = $local[ $key ];

} else {

unset( $this->local_cache[ $k ] );

$arr[ $key ] = false;

}

}

return $arr;

}

/**

public function get_seeds(): void {

if ( empty( SNAPCACHE_PRESEEDS ) ) {

return;

}

$preseed_keys = array_map(

fn( array $preseed ): string => $this->cache_key(

$preseed[0],

$preseed[1],

$preseed[2] ?? false,

),

SNAPCACHE_PRESEEDS,

);

if ( $this->mc->getDelayed( $preseed_keys ) ) {

$this->preseed_keys = $preseed_keys;

}

}

/**

public function incr(

int|string $key,

int $offset = 1,

string $group = '',

): int|false {

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

$v = $this->non_persistent_groups[ $group ][ $k ] ?? null;

if ( is_numeric( $v ) ) {

$v += $offset;

$this->non_persistent_groups[ $group ][ $k ] = $v;

return $v;

}

return false;

}

$result = $this->mc->increment( $k, $offset );

if ( $result === false ) {

// We don't know the state of the memcached item

unset( $this->local_cache[ $k ] );

return false;

}

$this->local_cache[ $k ] = $result;

return $result;

}

/**

public function replace(

int|string $key,

mixed $data,

string $group = '',

int $expire = 0,

): bool {

if ( ! $this->can_add() ) {

return false;

}

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] )

&& array_key_exists( $k, $this->non_persistent_groups[ $group ] ) ) {

$data = self::maybe_clone( $data );

$this->non_persistent_groups[ $group ][ $k ] = $data;

return true;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$expire = self::to_memcache_expiration( $expire );

$result = $this->mc->replace( $k, $data, $expire );

if ( $result === false ) {

// We don't know the state of the memcached item

unset( $this->local_cache[ $k ] );

return false;

}

$this->local_cache[ $k ] = self::maybe_clone( $data );

return true;

}

/**

public function set(

int|string $key,

mixed $data,

string $group = '',

int $expire = 0,

): bool {

if ( ! $this->can_add() ) {

return false;

}

$k = $this->cache_key( $key, $group );

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

$data = self::maybe_clone( $data );

$this->non_persistent_groups[ $group ][ $k ] = $data;

return true;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$expire = self::to_memcache_expiration( $expire );

$result = $this->mc->set( $k, $data, $expire );

if ( $result === false ) {

// We don't know the state of the memcached item

unset( $this->local_cache[ $k ] );

return false;

}

$this->local_cache[ $k ] = self::maybe_clone( $data );

return true;

}

/**

public function set_multiple(

array $data,

string $group = '',

int $expire = 0,

): array {

if ( ! $this->can_add() || $data === [] ) {

return [];

}

if ( isset( $this->non_persistent_groups[ $group ] ) ) {

$arr = [];

foreach ( array_keys( $data ) as $key ) {

$k = $this->cache_key( $key, $group );

$data = self::maybe_clone( $data );

$this->non_persistent_groups[ $group ][ $k ] = $data;

$arr[ $key ] = true;

}

return $arr;

}

if ( $this->preseed_keys ) {

$this->fetch_all();

}

$expire = self::to_memcache_expiration( $expire );

$d = [];

foreach ( $data as $key => $v ) {

$k = $this->cache_key( $key, $group );

$d[ $k ] = $v;

}

$result = $this->mc->setMulti( $d, $expire );

$arr = [];

if ( $result ) {

foreach ( $data as $key => $v ) {

$k = $this->cache_key( $key, $group );

$this->local_cache[ $k ] = self::maybe_clone( $v );

$arr[ $key ] = true;

}

} else {

foreach ( array_keys( $data ) as $key ) {

$k = $this->cache_key( $key, $group );

// We don't know the state of the memcached items

unset( $this->local_cache[ $k ] );

$arr[ $key ] = false;

}

}

return $arr;

}

/**

public function supports(

string $feature,

): bool {

return match ( $feature ) {

'add_multiple',