includes/Cache/class-object-cache.php
Object Cache Manager.
Class Object_Cache
Class Object_Cache
class Object_CacheConstants
| Constant | Visibility | Value | Line |
|---|---|---|---|
DROPIN_MARKER | public | \'Redis Object Cache Drop-in for Performance Optimisation\' | 30 |
LEGACY_DROPIN_MARKER | public | \'Redis Object Cache Drop-in\' | 38 |
CIRCUIT_OPTION | public | \'wppo_object_cache_circuit\' | 51 |
FAIL_TRANSIENT | public | \'wppo_redis_failures\' | 60 |
CIRCUIT_NOTICE_TRANSIENT | public | \'wppo_object_cache_circuit_notice\' | 69 |
CIRCUIT_DISMISSED_OPTION | public | \'wppo_object_cache_circuit_dismissed\' | 79 |
PARKED_SUFFIX | public | \'.wppo-disabled\' | 87 |
DISABLED_STATE_FILE | public | \'wppo-redis-disabled.json\' | 95 |
FAILURES_FILE | public | \'wppo-redis-failures.json\' | 103 |
ALLOWED_KEYS | public | Redis_Config_Policy::ALLOWED_KEYS | 116 |
CONFIG_HTACCESS_MARKER | public | \'WPPO Redis Config\' | 128 |
CONFIG_FILENAME | public | \'wppo-redis-config.php\' | 142 |
NGINX_PROBE_TRANSIENT | public | \'wppo_nginx_config_probe\' | 157 |
CONFIG_TMP_SUFFIX | public | \'.tmp\' | 208 |
LAST_FAILURE_TRANSIENT | public | \'wppo_redis_last_failure\' | 2549 |
Properties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$nginx_probe_memo | private static | array<string,bool> | array() | 171 |
$circuit_state_memo | private static | array|null | null | 186 |
$circuit_state_memo_set | private static | bool | false | 194 |
$dropin_path | private | string | — | 250 |
$config_path | private | string | — | 257 |
$template_path | private | string | — | 264 |
$outage_bypassed | private static | bool | false | 949 |
$outage_blog_id | private static | int | 0 | 957 |
$outage_error | private static | \\WP_Error|null | null | 969 |
$last_flush_error | private | \\WP_Error|null | null | 2680 |
$own_dropin_memo | private | bool|null | null | 2694 |
publicstatic get_uninstall_sidecar_paths()
public static function get_uninstall_sidecar_paths(): arrayCanonical circuit-breaker sidecar paths for uninstall cleanup.
Return: string[] — Absolute paths (empty when WP_CONTENT_DIR is undefined).
public __construct()
public function __construct()Constructor function.
public get_dropin_path()
public function get_dropin_path(): stringActive drop-in path (containment-validated).
Return: string.
public get_status()
public function get_status()Retrieve current status of the object cache and Redis connectivity.
Return: array — The status array described above.
publicstatic reset_circuit_memo_for_tests()
public static function reset_circuit_memo_for_tests(): voidReset the per-request circuit-state memo (unit-test helper).
Return: void.
publicstatic reset_runtime_state()
public static function reset_runtime_state(): voidReset all per-blog Object Cache runtime memos.
Return: void.
public get_circuit_state()
public function get_circuit_state(): arrayRead the merged circuit-breaker state.
Return: array — Shape { open: bool, tripped_at: int, reason: string, error_code: string, failures: int }.
public auto_disable_circuit()
public function auto_disable_circuit(string=\'\' $reason)Trip the circuit from fully-booted WordPress: park the drop-in. Parameter Type Default Description $reasonstring=\'\'— Human-readable trip reason.
Return: bool|\\WP_Error — True on success, WP_Error for foreign drop-ins or filesystem failures.
public probe_recovery()
public function probe_recovery()Probe Redis and close the circuit when it recovers.
Return: bool|\\WP_Error — True when the circuit is closed (or was never open), WP_Error while Redis is still unreachable.
public clear_circuit_state()
public function clear_circuit_state(): voidClear every circuit-breaker artefact: option, notice transient, failure counter, disabled-state bridge, and parked drop-in sibling.
Return: void.
publicstatic is_own_dropin_content()
public static function is_own_dropin_content($content): boolCheck whether a drop-in file content belongs to this plugin. Parameter Type Default Description $contentmixed— Raw file contents.
Return: bool — True when the content carries this plugin\’s marker.
private is_own_dropin()
private function is_own_dropin(): boolWhether the installed drop-in carries this plugin\’s marker.
Return: bool — True when the drop-in is ours (or absent), false for foreign files.
private read_json_state_file()
private function read_json_state_file(string $path)Read a small JSON state file from wp-content. Parameter Type Default Description $pathstring— Absolute file path.
Return: array|null — Decoded array, or null when missing/unreadable/invalid.
private get_parked_path()
private function get_parked_path(): stringAbsolute path of the parked drop-in sibling.
Return: string.
private get_disabled_state_path()
private function get_disabled_state_path(): stringAbsolute path of the disabled-state bridge file.
Return: string.
private get_failures_path()
private function get_failures_path(): stringAbsolute path of the drop-in failure-counter file.
Return: string.
privatestatic restricted_file_mode()
private static function restricted_file_mode(): intOwner-only file mode for Redis state/config/drop-in writes.
Return: int — File mode (0600 intersected with FS_CHMOD_FILE).
privatestatic restrict_file_mode()
private static function restrict_file_mode($wp_filesystem, string $path): voidBest-effort owner-only chmod on an already-written file. Parameter Type Default Description $wp_filesystemobject— Filesystem instance. $pathstring— Absolute file path.
Return: void.
privatestatic current_outage_blog_id()
private static function current_outage_blog_id(): intResolve the current blog ID for outage-bypass scoping (never fatals).
Return: int — Current blog ID, or 0 when unavailable.
privatestatic sync_outage_scope()
private static function sync_outage_scope(): voidReset the in-request bypass when the blog changed since arming.
Return: void.
privatestatic arm_in_request_bypass()
private static function arm_in_request_bypass($error): voidArm the in-request bypass for the current blog. Parameter Type Default Description $error\\WP_Error— Original failure to replay to repeat callers.
Return: void.
privatestatic is_transient_outage_error()
private static function is_transient_outage_error(string $code, string=\'\' $message): boolWhether a Redis failure code is a transient outage (vs permanent misconfiguration). Parameter Type Default Description $codestring— Failure code. $messagestring=\'\'— Failure message (scanned for auth signals).
Return: bool — True when the failure may heal without config changes.
privatestatic scrub_redis_message()
private static function scrub_redis_message(string $message): stringScrub a Redis failure/circuit message before admin/REST surfacing. Parameter Type Default Description $messagestring— Raw message.
Return: string — Scrubbed message (max 200 chars).
private connect_internal()
private function connect_internal($config)Internal helper to connect to Redis based on config. Parameter Type Default Description $configarray— Configuration array.
Return: \\Redis|\\RedisCluster|\\WP_Error.
public wppo_redis_outage_fallback()
public function wppo_redis_outage_fallback(=array() $config)Single-call Redis outage fallback helper (class-layer fail-open). Parameter Type Default Description $config=array()— Connection configuration (pre-filtered).
Return: \\Redis|\\RedisCluster|\\WP_Error — Connected client, or WP_Error (including `redis_bypassed` while bypassed).
publicstatic is_outage_bypassed()
public static function is_outage_bypassed(): boolWhether the in-request outage bypass is armed (current site).
Return: bool — True when subsequent cache calls short-circuit to uncached in this request.
publicstatic reset_outage_bypass()
public static function reset_outage_bypass(): voidReset the in-request outage bypass (tests and explicit recovery).
Return: void.
public is_outage_flagged()
public function is_outage_flagged(): boolWhether the persistent outage status flag is set.
Return: bool — True when Redis was recorded as bypassed until recovery.
private arm_outage_flag()
private function arm_outage_flag(): boolArm the persistent outage status flag (additive settings key).
Return: bool — True on the unarmed → armed transition (callers log only then); false when already armed or unavailable.
private clear_outage_flag()
private function clear_outage_flag(): voidClear the persistent outage status flag on recovery.
Return: void.
private trip_circuit_on_outage()
private function trip_circuit_on_outage($error): voidTrip the plugin-side circuit after a transient outage (fail open, never fatal). Parameter Type Default Description $error\\WP_Error— Original transient failure.
Return: void.
privatestatic ensure_redis_helper()
private static function ensure_redis_helper(string $helper_function): boolEnsure the Redis connection helper file is loaded and a helper function from it is available. Parameter Type Default Description $helper_functionstring— Helper function name that must exist after loading.
Return: bool — True when the helper function is available.
privatestatic safe_filesize()
private static function safe_filesize(string $path)Race-tolerant filesize(): clears the stat cache and suppresses the TOCTOU warning when the file vanishes between checks. Parameter Type Default Description $pathstring— File path.
Return: int|false — Size in bytes or false.
public get_redis_config()
public function get_redis_config(): arrayGet the merged Redis configuration with filter.
Return: array — The Redis configuration.
public ping()
public function ping(=array() $config)Ping the Redis server to test connection. Parameter Type Default Description $config=array()— Connection configuration.
Return: bool|\\WP_Error — True if connected, WP_Error on failure.
publicstatic is_valid_config_content()
public static function is_valid_config_content($contents): boolWhether rendered Redis config source looks structurally valid. Parameter Type Default Description $contentsmixed— Candidate config source.
Return: bool — True when the source has the expected config shape.
private write_config_atomic()
private function write_config_atomic(string $content, $wp_filesystem)Publish Redis config source atomically via tmp-write + verify + rename. Parameter Type Default Description $contentstring— Rendered config PHP source. $wp_filesystemmixed— Filesystem object from `Util::init_filesystem()`.
Return: bool|\\WP_Error — True on verified publish, WP_Error on any failure.
private delete_config_tmp_quietly()
private function delete_config_tmp_quietly($wp_filesystem, string $path): voidBest-effort delete of a staging tmp path; never throws. Parameter Type Default Description $wp_filesystemmixed— Filesystem object. $pathstring— Tmp path to remove.
Return: void.
private sweep_orphan_config_tmp()
private function sweep_orphan_config_tmp($wp_filesystem): voidSweep orphan config staging files left by an interrupted write. Parameter Type Default Description $wp_filesystemmixed— Filesystem object.
Return: void.
private publish_dropin_atomic()
private function publish_dropin_atomic($wp_filesystem)Publish the object-cache drop-in atomically with a foreign re-check. Parameter Type Default Description $wp_filesystemmixed— Filesystem object from Util::init_filesystem().
Return: bool|\\WP_Error — True on verified publish, WP_Error (foreign_dropin/write_error) on failure.
private sweep_orphan_dropin_tmp()
private function sweep_orphan_dropin_tmp($wp_filesystem, string=\'\' $current_tmp): voidSweep orphan object-cache drop-in staging siblings (best-effort, never throws). Parameter Type Default Description $wp_filesystemmixed— Filesystem object. $current_tmpstring=\'\'— Tmp path just consumed (already moved; skipped when still listed).
Return: void.
public enable()
public function enable($config)Install the Redis object-cache drop-in by writing the plugin config and copying the drop-in into place. Parameter Type Default Description $configarray— Connection configuration used to generate the Redis config file.
Return: bool|\\WP_Error — `true` on success, `WP_Error` on failure (possible error codes: `missing_extension`, `foreign_dropin`, `write_error`).
public disable()
public function disable()Disable the object cache by deleting the drop-in file.
Return: bool|\\WP_Error — True on success, WP_Error on failure.
privatestatic protect_config_file()
private static function protect_config_file(): voidWrite Apache/LiteSpeed deny rules shielding the redis config file.
Return: void.
public log_redis_failure()
public function log_redis_failure(string $code, string $message): voidRecord a Redis failure in-app (activity log + admin-notice transient). Parameter Type Default Description $codestring— Machine-readable failure code. $messagestring— Human-readable failure description.
Return: void.
public get_serializer_support()
public function get_serializer_support(): arrayReport which serializers the current phpredis build can safely use.
Return: array — Shape { active: string, igbinary: bool, msgpack: bool, php: bool }.
public get_last_failure_payload()
public function get_last_failure_payload()Read the latest recorded Redis failure for admin/REST surfacing.
Return: array|null — Shape { code: string, message: string, time: int } or null.
public get_last_flush_error()
public function get_last_flush_error()Latest flush failure, if any.
Return: \\WP_Error|null — The WP_Error set by the last failed flush(), or null.
public flush()
public function flush()Flush the complete object cache with best-effort memory-delta logging.
Return: bool — True when flushed, false otherwise.
publicstatic get_config_path()
public static function get_config_path(): stringAbsolute path of the Redis config file (\’\’ when undeterminable).
Return: string.
publicstatic is_nginx_config_exposed()
public static function is_nginx_config_exposed(): boolWhether the Redis config file is directly fetchable over HTTP on Nginx.
Return: bool — True when the config file looks directly fetchable.
privatestatic probe_transient_key()
private static function probe_transient_key(string $suffix): stringBlog-prefixed probe transient key with back-compat fallback. Parameter Type Default Description $suffixstring— Key suffix after the base transient name.
Return: string — Prefixed key, or the raw key when Util is unavailable.
publicstatic clear_nginx_probe_cache()
public static function clear_nginx_probe_cache(): voidDrop the cached Nginx exposure probe verdict.
Return: void.
public flush_scoped()
public function flush_scoped(): boolFlush the object cache scoped to the current blog on multisite.
Return: bool — True when the scoped flush succeeded, false otherwise.
private read_redis_memory_bytes()
private function read_redis_memory_bytes()Read Redis used_memory in bytes via INFO (best-effort).
Return: int|null — Bytes used, or null when unreachable/unavailable.
Hooks
Hooks referenced in includes/Cache/class-object-cache.php: Hook Type Line Notes wppo_object_cache_dropin_pathfilter 274 — wppo_object_cache_configfilter 1675 @param ×1 wppo_object_cache_configfilter 1710 @param ×1 wppo_object_cache_configfilter 2302 — wppo_nginx_probe_clear_sitesfilter 3000 @param ×1