Download the PHP package duckdev/wp-cache-helper without Composer

WP Cache Helper

WP Cache Helper is a small WordPress library that wraps the object cache and transient APIs with a callback-style remember() helper, group-flush support for the object cache (delegating to core's wp_cache_flush_group() on WP 6.1+ backends that support it, with a version-sentinel fallback for backends that don't), and per-prefix scoping so multiple consumers on the same site never collide.

Inspired by WP Cache Remember.

📖 Full documentation: docs.foxelabs.com

Requirements

• PHP 7.4 or higher
• WordPress 6.1+
• Composer

Installation

The library autoloads under the FoxeLabs\Cache\ namespace via PSR-4.

Architecture

The library is organised as a tiny container wired up by the entry class FoxeLabs\Cache\Cache. The folder layout mirrors the namespace:

Services receive their collaborators by constructor injection so they can be unit-tested without WordPress in the loop. Construction has no side effects.

Usage

Initialisation

Each container instance is scoped to a single prefix. Pass any non-empty string the first time you ask for it; the same prefix returns the same instance on subsequent calls:

You can also instantiate directly (useful for tests where you want to inject custom drivers):

Every key, group, and the {prefix}_can_cache toggle filter are namespaced under the supplied prefix.

Provided helpers

Every callback-based helper checks the return value with is_wp_error() and skips caching when one is returned, so a transient API failure is not memorised.

Disabling caching

For debugging, return false from the {prefix}_can_cache filter:

The second argument is the cache type — 'object' or 'transient' — so the two can be toggled independently.

Cache::remember()

Retrieve a value from the object cache. If it doesn't exist, run the $callback to generate and cache the value.

Unlike a naive wp_cache_get()-then-fall-back pattern, remember() distinguishes a legitimately cached 0, '', [], or false from a true miss — the callback only runs when nothing was cached.

Cache::forget()

Retrieve a value from the object cache then delete it. Returns $default on miss.

Cache::persist()

Same shape as remember() but backed by the transient API.

Pass true for the third argument to use site-wide (multisite) transients.

Note: transients use boolean false as the miss sentinel, so a legitimately cached false value is indistinguishable from a miss. Reach for remember() if you need to cache false.

Cache::cease()

Transient counterpart to forget().

Cache::flush_group()

Invalidate every entry stored under a group, without touching the rest of the object cache. On WP 6.1+ with a persistent object cache backend that advertises flush_group support (via wp_cache_supports( 'flush_group' )), this delegates straight to wp_cache_flush_group(). Otherwise it falls back to incrementing a per-group version sentinel — old entries become unreadable on next access.

Cache::flush()

Wrapper for wp_cache_flush() with a fallback to $wp_object_cache->flush() when the function is disabled by a drop-in. Clears every group on the site, so use only as a last resort.

Upgrading from 2.x

3.0.0 is the DuckDev → Foxe Labs rebrand. Update your composer.json require entry and every use statement:

• Package duckdev/wp-cache-helper → foxelabs/wp-cache-helper.
• Namespace DuckDev\Cache\ → FoxeLabs\Cache\.

[!NOTE] No cache data migration is needed. Keys, groups and the can_cache filter are all built from your own prefix, not from a vendor name, so nothing the library reads or writes changes.

Upgrading from 1.x

• PHP minimum is now 7.4. PHP 5.6/7.0–7.3 are no longer supported.
• The constructor now requires a prefix: new Cache( 'my_plugin' ). In 1.x the prefix was a hardcoded duckdev_cache shared across every consumer.
• The can_cache filter is now {prefix}_can_cache (e.g. my_plugin_can_cache) rather than the shared duckdev_cache_can_cache.
• remember() and forget() now correctly treat a cached 0 / '' / [] / false as a hit instead of re-running the callback.

The public method surface (remember, forget, persist, cease, flush_group, flush) is otherwise unchanged.

[!WARNING] The 1.x prefix change orphans data rather than losing it, and the two stores behave differently. Object cache entries under duckdev_cache_* are non-persistent and simply vanish on the next flush or restart — ignore them. Transients are the ones to clean up: those written without an expiry persist as wp_options rows that nothing will ever read or expire again. Clear them once from your upgrade routine:

Direct SQL is correct here — this deletes rows nothing reads, and wp_cache_flush() afterwards drops any stale copies from a persistent object cache. There is no data worth carrying forward: every entry is a rebuildable cache value, so let remember() repopulate on the next request rather than migrating.

Development

Credits

• Maintained by Joel James

License

GPLv2+