Options, Transients and Object Cache

Anything that would be lost for good if it disappeared belongs in an option, meta or a table. Transients and the object cache are caches: code that reads them must always be able to rebuild the value.

Values are serialized with maybe_serialize(), so arrays and objects can be stored directly; do not call serialize() or json_encode() yourself unless another program reads the row. An option name is at most 191 characters (the option_name column), and it must carry the plugin’s prefix, because every plugin and core share one namespace. The names alloptions and notoptions are reserved: wp_protect_special_option() stops any write to them.

A transient is a named value with an optional expiration in seconds. The API has three functions per scope:

Values are serialized like options. Use a prefix (lumen_ for the catalogue) and, for derived keys, a short hash: 'lumen_search_' . md5( $query ) stays well under the length limit.

The object cache is the layer the other two use: options are cached in the options group (with the alloptions and notoptions entries), transients in transient with a drop-in, and core caches posts, meta, terms, users, comments and, since 6.1, WP_Query results (post-queries group). Plugins use the same functions.

Keys are strings or integers (an empty key triggers _doing_it_wrong since 6.1) and are unique per group. On Multisite, a non-global group is also scoped per site; switch_to_blog() switches it.

A cached value is only correct if every change to its source removes or outdates it. Three patterns cover most cases:

Flushing a whole group with wp_cache_flush_group() works too, but it removes unrelated keys of the group and depends on backend support; the last-changed salt costs one key read.

The catalogue’s Lumen\Catalog\Cache class, booted from Plugin::boot() (see Plugin Fundamentals), caches the latest book IDs with a salt and the card data of each book under its own key, and clears both from hooks. save_post_lp_book is the dynamic save_post_{$post->post_type} action; it fires for every save of a book, including Quick Edit and REST, but not for its revisions, whose post type is revision; deleted_post_lp_book (6.6) covers permanent deletion. The lumen/latest-books block in Static and Dynamic Blocks can render from these two methods.

Source: Code Reference: wp_cache_get_salted(), Code Reference: save_post_{$post->post_type}

The salted functions arrived in 6.9, which is the plugin’s Requires at least; on older versions the same pattern is written by putting the last_changed value into the key ("latest:{$count}:{$salt}"), as core did before 6.9. Old keys are then never deleted, only left to expire or be evicted, which is why the $expire argument is set. Two limits of hook-based invalidation: a direct SQL write ($wpdb->update(), an import tool) fires no hook, and update_post_meta() with an unchanged value fires no updated_post_meta. Code that writes that way calls wp_cache_set_last_changed() itself.

A wp eval-file script counted the queries of Cache::latest_book_ids( 3 ) called twice, then again after renaming the newest book with wp_update_post(), and read its card. With two books (IDs 4 and 5), both backends printed:

Deleting a book with wp_delete_post( $id, true ) changed the salt as well. Across requests the backends differ: a following wp eval of the same call counted 0 database queries for the whole request with Redis and 8 without it.

The lp_catalog_sync_stock cron job of WP-Cron and Scheduled Tasks downloads the distributor’s stock list. Other code needs the same list within minutes: the per-book sync queued on save_post_lp_book, wp lumen import and the stock endpoint of the REST API. The distributor rate-limits its API, so the list is fetched once and kept in a transient, lumen_distributor_stock, for 15 minutes. The HTTP client that fetches and caches it, lumen_catalog_fetch_stock() in includes/distributor.php, is the one of HTTP and Filesystem APIs, which also defines the LP_CATALOG_STOCK_TRANSIENT constant and normalizes ISBNs to digits. It never caches a failure. Because the transient can vanish, and the distributor can be down, the function below wraps it and keeps the last good answer in a non-autoloaded option, lp_catalog_stock_snapshot. Page views never call either function; they read the lp_stock meta that the job writes.

Source: Common APIs Handbook: Transients, Plugin Handbook: HTTP API

The lp_catalog_sync_stock() job of the cron page changes in one place: instead of its own wp_remote_get() and json_decode(), it loops over lp_catalog_get_distributor_stock( true ) as $isbn => $quantity, so the job always fetches a fresh list, refreshes the transient for every other caller and keeps the snapshot current. When the distributor is down, the job gets the snapshot back and rewrites the values the books already have. Design choices:

A must-use plugin answered https://distributor.example/ through the pre_http_request filter with two books, counted the calls, and answered 503 while an option was set. The check script deleted the transient, called lp_catalog_get_distributor_stock() three times and printed the number of HTTP calls, then forced a refresh with the distributor down and printed the result, and finally ran the lp_catalog_sync_stock action. Output, identical without and with the Redis drop-in:

The failed refresh returned the snapshot instead of an empty list. With Redis, redis-cli ttl 'lumenpress:wp:transient:lumen_distributor_stock' returned 899 right after the job ran and the database held no transient row; without Redis, the value and timeout rows were both stored with autoload off.

Cache keys built from request data must not let one user read another’s data: include the user ID in the key, or use a non-persistent group, and never cache output that contains a nonce or private content in a shared group. Cached values are trusted only as much as their source: the distributor answer is sanitized before it is stored and escaped on output. Never unserialize() values from outside, and keep Redis private (Redis: Security).