wp_cache_get( int|string $key, string $group = '', bool $force = false, bool|null $found = null ): mixed|false
- Since
- 2.0.0
- Source
wp-includes/cache.php:151
Reads a value stored under a given key and cache group, returning false when nothing is found. Because false is also a legitimate cached value, the fourth parameter $found is the only reliable way to tell a stored false apart from a genuine cache miss. Pair it with wp_cache_set() to write the value in the first place.
Compatibility
- WordPress
- since 2.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$keyint|string- The key under which the cache contents are stored.
$groupstringoptional- Where the cache contents are grouped. Default empty.Default:
'' $forcebooloptional- Whether to force an update of the local cache from the persistent cache. Default false.Default:
false $foundbool|nulloptional- Whether the key was found in the cache (passed by reference).
Disambiguates a return of false, a storable value. Default null.Default:null
Return value
mixed|false- The cache contents on success, false on failure to retrieve contents.
Code examples
Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.
Cache an expensive calculation and check whether it was actually stored
Cache the word count of post 1's content under a custom group so a page render doesn't recompute it on every call.
$post = get_post( 1 );
$cache_key = 'word_count_' . $post->ID;
$cache_group = 'my_plugin_stats';
$found = null;
$count = wp_cache_get( $cache_key, $cache_group, false, $found );
if ( ! $found ) {
printf( "Cache miss, computing now.\n" );
$count = str_word_count( wp_strip_all_tags( $post->post_content ) );
wp_cache_set( $cache_key, $count, $cache_group );
} else {
printf( "Cache hit, reused stored value.\n" );
}
echo esc_html( sprintf( 'Post %d has %d words (found flag: %s)', $post->ID, $count, var_export( $found, true ) ) );On a fresh install with no persistent object cache drop-in, this only avoids recomputation within the same request, it does not survive a page reload.
Distinguish a cached false value from a true cache miss
Cache the boolean result of a price check on post 2's meta, which can legitimately be false, and show why checking the return value alone is unsafe.
$price = get_post_meta( 2, 'price', true );
$has_price = ! empty( $price );
wp_cache_set( 'post_2_has_price', $has_price, 'pricing_flags' );
$found = null;
$cached = wp_cache_get( 'post_2_has_price', 'pricing_flags', false, $found );
if ( false === $cached && ! $found ) {
echo esc_html( 'No cached value exists yet for this key.' );
} elseif ( false === $cached && $found ) {
echo esc_html( 'Cached value is false, and it really is false, not missing.' );
} else {
echo esc_html( sprintf( 'Cached value: %s', var_export( $cached, true ) ) );
}Common problems and fixes · 4
- Why does wp_cache_get() return the right value in my code but nothing shows up on the next page load?
- How do I tell a cached false value apart from a cache miss?
- What does the $force parameter actually do?
- Why is my cached value showing up under the wrong feature?
Why does wp_cache_get() return the right value in my code but nothing shows up on the next page load?
How do I tell a cached false value apart from a cache miss?
What does the $force parameter actually do?
Why is my cached value showing up under the wrong feature?
Alternatives and related functions
wp_cache_set- When you need to write or refresh the value that a later wp_cache_get() call should retrieve.
wp_cache_add- When you want to store a value only if the key does not already exist, instead of overwriting it.
wp_cache_delete- When cached data has become stale and needs to be invalidated so the next wp_cache_get() forces a miss.
get_transient- When the cached value must survive across requests even without a persistent object cache, since transients fall back to the options table.
Performance profile
How much work a call to wp_cache_get() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 12
- Plugin surface
- None
- Called by
- 50
Only touches the object cache, via wp_cache_get().
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5. The body compiles to 12.
Nothing here hands control to plugin code.
50 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- cacheobject cache
wp_cache_get()this function does it
What one call costs · 1 distinct outcome
One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_cache_get() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 12 | ->get() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 12 instructions, 12 executed per call, 0 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Used by · 50
- Twenty_Eleven_Ephemera_Widget::update()Updates widget settings.
- Twenty_Eleven_Ephemera_Widget::widget()Outputs the HTML for this widget.
- WP_AI_Client_Cache::get()Fetches a value from the cache.
- WP_AI_Client_Cache::has()Determines whether an item is present in the cache.
- WP_Comment::get_instance()Retrieves a WP_Comment instance.
- WP_Customize_Manager::find_changeset_post_id()Finds the changeset post ID for a given changeset UUID.
- WP_Embed::find_oembed_post_id()Finds the oEmbed cache post ID for a given cache key.
- WP_MS_Sites_List_Table::column_users()Handles the users column output.
- WP_Network::get_instance()Retrieves a network from the database by its ID.
- WP_Post::get_instance()Retrieve WP_Post instance.
- WP_Privacy_Requests_Table::get_request_counts()Counts the number of requests for each status.
- WP_Site::get_details()Retrieves the details for this site.
Show all 50
- WP_Site::get_instance()Retrieves a site from the database by its ID.
- WP_Term::get_instance()Retrieve WP_Term instance.
- WP_Textdomain_Registry::get_language_files_from_path()Retrieves translation files from the specified path.
- WP_Theme::cache_get()Gets theme data from cache.
- WP_User::get_data_by()Returns only the main user fields.
- _get_cron_lock()Retrieves the cron lock.
- _get_last_post_time()Gets the timestamp of the last time any post was modified or published.
- _wp_image_editor_choose()Tests which editors are capable of supporting the request.
- add_network_option()Adds a new network option.
- add_option()Adds a new option.
- delete_network_option()Removes a network option by name.
- delete_option()Removes an option by name. Prevents removal of protected WordPress options.
- get_all_page_ids()Gets a list of page IDs.
- get_blog_details()Retrieves the details for a blog from the blogs table and blog options.
- get_blog_id_from_url()Gets a blog's numeric ID from its URL.
- get_bookmark()Retrieves bookmark data.
- get_bookmarks()Retrieves the list of bookmarks.
- get_calendar()Displays calendar with days that have posts as links.
- get_lastcommentmodified()Retrieves the date the last comment was modified.
- get_metadata_raw()Retrieves raw metadata value for the specified object.
- get_network_option()Retrieves a network's option value based on the option name.
- get_object_term_cache()Retrieves the cached term objects for the given object ID.
- get_option()Retrieves an option value based on an option name.
- get_plugins()Checks the plugins directory and retrieve all plugin files with plugin data.
- get_site_transient()Retrieves the value of a site transient.
- get_transient()Retrieves the value of a transient.
- get_usermeta()Retrieve user metadata.
- is_blog_installed()Determines whether WordPress is already installed.
- metadata_exists()Determines if a meta field with the given key exists for the given object ID.
- ms_load_current_site_and_network()Identifies the network and site of a requested domain and path and populates the corresponding network and site global objects as part of the multisite bootstrap process.
- update_network_option()Updates the value of a network option that was already added.
- update_option()Updates the value of an option that was already added.
- wp_cache_get_last_changed()Gets last changed date for the specified cache group.
- wp_cache_get_multiple()Retrieves multiple values from the cache in one call.
- wp_cache_get_salted()Retrieves cached data if valid and unchanged.
- wp_cache_set_last_changed()Sets last changed date for the specified cache group to now.
- wp_count_attachments()Counts number of attachments for the mime type(s).
- wp_count_comments()Retrieves the total comment counts for the whole site or a single post.
Source code
function wp_cache_get( $key, $group = '', $force = false, &$found = null ) { global $wp_object_cache; return $wp_object_cache->get( $key, $group, $force, $found );}Changelog
Introduced in 2.0.0. One change between 6.7.7 and 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
$found retyped from bool to bool|null.verified against sourceAbout this page
- Parsed data
- Generated from the wordpress-develop 7.0.4 tag, from
src/wp-includes/cache.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.