EN · ÖZGÜN DEPO BELGESİ

Pro motoruna genel bakış

Özgün İngilizce metin. Komutlar ve kanıtlar, belgede belirtilen revizyona ve ortama aittir.

README.md

Bu sayfada

Object Cache Project

A WordPress Redis object cache project with an attributed proprietary edition and an independently implemented standalone FREE core.

The owner confirmed on October 2, 2026 that upstream reuse rights were checked and cleared. Inherited files use concise project headers; their original Rhubarb notice is retained in THIRD_PARTY_NOTICES.md. The proprietary classification remains and the upstream-referenced LICENSE is absent here. The product display name does not change upstream authorship, license terms, PHP namespaces, configuration keys or installation paths. See provenance.

The candidate includes focused stored-false/null correctness fixes, optional request-local negative caching (off by default), real Redis/Cluster/Sentinel recovery tests and deterministic private packaging. These tests establish the bounded behavior described in release evidence, rather than general production performance or all supported runtime combinations.

The current release profile uses manually verified license fulfillment. See the readiness matrix for completed software gates and the exact operator inputs still required to start a public service. Deployment templates, customer/license recovery, key rotation and conservative restore reconciliation are included; online payments and public customer accounts remain disabled.

Modernization candidate: 1.26.0-rc.1

The current working version requires PHP 8.2+ and PhpRedis 6.0+. Relay remains an optional backend; its transaction capabilities are checked at runtime. The v2 cache namespace starts cold and does not read or automatically erase legacy records. Read the v2 migration and rollback procedure before installation. Returning to old code requires a new, unused prefix.

This candidate adds bounded SCAN cleanup, optimistic alloptions transactions, bounded prefetch metadata and logs, a performance panel, a read-only cleanup preview and wp redis doctor --format=json|table. The existing WordPress API, configuration constants and integrations remain. No update server is introduced by this modernization.

The new Drop-in migration settings page adds file fingerprints, a signed downloadable backup and explicit install/restore actions. It requires cache management plus plugin-installation permission (a network super administrator on multisite). Read the migration wizard procedure for the backup’s privacy, filesystem-failure handling and fresh-namespace rollback. Its runtime/browser checks remain deferred to the final development test phase.

Current source work is tracked in the implementation inventory. After the owner’s later PHP-test authorization, the local PHP 8.3.0 suite passed 37 regression cases and 148 assertions. A subsequent authorized fresh Docker run passed the previously skipped WordPress contract, all six real integration scripts and the lifecycle suite on WordPress 6.8.3/WooCommerce 10.2.2/PhpRedis 6.1.0/Redis 7.4.2. Real topology/TLS/Relay, checkout isolation, scale and performance gates remain open. Earlier release evidence applies only to its recorded revisions. This candidate has not passed production acceptance; no performance improvement is claimed. The new benchmark harness verifies installed source/drop-in hashes, fixture data and configuration before accepting measurements.

Installation

Follow this project’s installation and update instructions. Use the release completion record to distinguish source implementation, historical tests, current acceptance and outstanding operator inputs.

The candidate’s separate Premium access administration uses an operator-fixed Go service configuration. Its configuration and explicit update workflow describe activation, signed local status and authorized WordPress update downloads. Cache reads and writes do not call this service. Automatic plugin updates remain disabled. Go operations and recovery cover private startup, backups, restore rehearsal and production tasks still required.

Documentation

Historical TTL evidence

Opt-in insights_ttl_tracking collects bounded write-TTL distributions in the existing sampled requests. Use wp redis insights --ttl-review or the explicit Load TTL history action for completed-hour reports. Existing Insights storage is unchanged; limits and final acceptance are in TTL-HISTORY.md. This does not infer an optimal TTL or change settings automatically.

Portable configuration presets

Opt into woocommerce, membership, publishing or multisite with a preset field in the existing early configuration. Explicit fields take priority, including whole arrays. Exact group_ttl caps apply to new persistent writes before jitter. wp redis preset list|show|export|import|diff and the Cache Insights preview help review the effect; import produces a fragment without changing live settings. Read configuration profiles for the candidate values, portable schema, scope, rollback and deferred final verification. These profiles have no measured performance or production acceptance yet.

Profile one real HTTP request

wp redis profile <url> --format=json|table profiles one anonymous GET within the selected site’s URL scope, using a signed one-use ticket and temporary Redis report. Only that request gets 100% sampling; it is excluded from hourly Insights. Events show component/group, API duration, Redis cost and bounded logical size coverage. Default retention is 2,000 events, configurable up to 10,000 with a 2 MiB event cap; omissions are explicit. See the HTTP profile contract for examples, prerequisites, side effects, response handling, exit codes and deferred final tests. Write events also expose requested TTL, capped/jittered TTL on confirmed writes and bounded coverage, without extra Redis probes. Counters and runtime-only writes are explicitly distinguished; these are not observed key lifetimes.

Key growth diagnostics

Key-growth diagnostics are opt-in (insights_key_tracking=false by default). wp redis key-growth --group=products --format=json reads retained sampled key fingerprints and previous scan evidence. Add --scan to explicitly start one bounded live scan. The Cache Insights screen offers the same separate actions. Approximate distinct written keys are not live-key growth. See the key-growth contract for limits, configuration, permissions, interpretation and deferred acceptance tests.

Sampled Cache Insights

The Cache Insights settings page and wp redis insights --period=7d --format=json|table attribute sampled cache activity to plugins, themes and groups. insights_sample_rate defaults to 2%; zero disables collection. Reports show coverage and missing data, rank observed Redis wait, and offer six review rules without changing settings. Site/hour storage and report aggregation are bounded. Read the measurement and storage contract for byte-size definitions, sampling/flush and partial-EXEC limits, configuration and the pending final validation gates.

wp redis insights --period=7d --ttl-review adds group-level TTL/persistence review in table output; JSON/REST and the Insights page also expose it. It combines readers and writers across components using completed hourly samples, explains insufficient or unreliable evidence and leaves settings unchanged. Exact TTLs and per-key reuse are not measured; this is the evidence/classification layer of the adaptive-TTL work, not a completed automatic optimizer.

Explain an individual cache key

wp redis why <key> --group=<group> --format=json|table explains the current scope, request-memory state, primary storage type/TTL and applicable cache rules. Optional --ttl=<seconds> shows the possible TTL range for a hypothetical new write after caps and jitter. Use WP-CLI’s global --url to select a multisite site. The probe reads metadata, not cache contents. It identifies evidence limits instead of guessing a past invalidator or reason for absence. Read the command contract for exit codes, privacy, primary/ACL requirements and deferred final verification.

Optional request-local negative cache

negative_cache defaults to false. To enable it, add 'negative_cache' => true to your existing WP_REDIS_CONFIG array. Genuine Redis misses are then remembered in the current cache instance until the request ends or its runtime cache is flushed. This can reduce repeated reads of nonexistent keys, at the cost of memory per unique miss.

After a remembered miss, another request’s write may remain invisible until a forced read (wp_cache_get($key, $group, true, $found)), runtime flush, or request end. Use this option only where that visibility tradeoff is acceptable. Long-lived workers must flush their runtime cache between jobs. Same-instance mutations invalidate misses; stored false values remain hits. Bulk reads confirm ambiguous false replies before remembering misses, so the first bulk read can cost additional Redis commands.

Optional remember leases

The separate ocp_remember($key, $expire, Closure $callback, $group, $options) API adds bounded ownership and waiting for explicitly configured stampede_groups. The group list defaults to empty. Selected groups’ normal mutations invalidate in-flight computations; every worker sharing the prefix must use the same setting. Existing wp_cache_remember()/wp_cache_sear() helpers do not acquire leases or wait, and now correctly treat stored false as a hit.

Read the API contract and configuration example before enabling the scope. It covers failure fallback, Redis capabilities, extra mutation/cleanup cost, callback restrictions and coordinated deployment. Runtime/concurrency and performance verification remain deferred to the final test phase.

Optional TTL jitter

ttl_jitter defaults to 0 (disabled). Add 'ttl_jitter' => 10 to the existing WP_REDIS_CONFIG array to shorten each finite write TTL by a random amount of up to 10%. The setting accepts an integer percentage from 0 to 100. For example, an effective 600-second TTL becomes 540 to 600 seconds, inclusive. Percentage rounding is down to whole seconds, so very short TTLs can stay unchanged.

The maximum/query TTL limits apply first. Jitter never extends that effective lifetime, never turns a finite TTL into a persistent record, and leaves effective TTL 0 and TTL 1 unchanged. Each key in a bulk write receives its own draw; split alloptions hashes use the same policy. Counter increments/decrements preserve the existing expiry, and internal metadata/prefetch retention is unchanged.

This can spread expiration times; it does not prevent concurrent requests from recomputing the same missing value. It can also increase misses by expiring data earlier. Existing records are not rewritten when the setting changes. Turning it off affects future writes and does not restore already shortened lifetimes. Runtime and performance validation are pending the final test phase.

WordPress core cache bug mitigations

Three small mitigations for WordPress core cache bugs with security impact are enabled by default (core_mitigations). They only add invalidation or bound a TTL: a stale password-reset key after sign-on, comments of unpublished posts in cached comment queries, and unbounded comment-queries keys. Set 'core_mitigations' => false to disable all of them, or pass an array such as ['comment_query_ttl' => false] to disable one. See CORE-MITIGATIONS.md.

You will find the upstream documentation on objectcache.pro/docs.

Known Issues

Query caching

https://make.wordpress.org/core/2022/10/07/improvements-to-wp_query-performance-in-6-1/

Query splitting

Local integration checks

Run python3 tests/integration/run.py --topologies from a checkout with Python and a Linux-container Docker engine. See fixture instructions for prerequisites, reports and cleanup.

Private review packaging

Run python3 tests/integration/package.py --ref HEAD to create a ZIP and SHA-256 manifest under build/. The package reads an immutable commit, includes runtime files and existing notices, and excludes development tests, fixture credentials, Git metadata and Composer development dependencies. Repeating it for the same commit produces the same archive bytes. This is a private technical candidate; packaging does not grant distribution rights. See release gates.