wp_cache_delete( int|string $key, string $group = '' ): bool
- Since
- 2.0.0
- Source
wp-includes/cache.php:190
Deletes a single item from the WordPress object cache identified by its key and, optionally, its group. Use it after any operation that invalidates a value you previously stored with wp_cache_set(), otherwise stale data may keep being served from cache. It only removes one key at a time and always returns a boolean, so check the return value rather than assuming success.
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- What the contents in the cache are called.
$groupstringoptional- Where the cache contents are grouped. Default empty.Default:
''
Return value
bool- True on successful removal, false on failure.
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.
Invalidate a cached value after updating post meta
Cache a computed value keyed to a post's price meta, then remove it manually once the meta changes so the next read recomputes it.
$post_id = 2;
$cache_group = 'shop_prices';
$cache_key = 'formatted_price_' . $post_id;
$price = get_post_meta( $post_id, 'price', true );
wp_cache_set( $cache_key, '$' . $price, $cache_group );
echo 'Cached value before update: ' . esc_html( wp_cache_get( $cache_key, $cache_group ) ) . "\n";
update_post_meta( $post_id, 'price', '24.99' );
$deleted = wp_cache_delete( $cache_key, $cache_group );
echo 'wp_cache_delete() returned: ' . esc_html( $deleted ? 'true' : 'false' ) . "\n";
echo 'Cache lookup after delete: ';
print_r( wp_cache_get( $cache_key, $cache_group ) );wp_cache_get() returns false when the key is missing, so print_r() shows the boolean rather than a stored value.
Check whether a cache key existed before deleting it
Compare the return value of wp_cache_delete() for a key that was never set against one that was, to see how it signals success or failure.
$group = 'sandbox_demo';
$missing_result = wp_cache_delete( 'never_set_key', $group );
echo 'Deleting a key that was never cached: ' . esc_html( $missing_result ? 'true' : 'false' ) . "\n";
wp_cache_set( 'greeting_key', 'Hello world!', $group );
$existing_result = wp_cache_delete( 'greeting_key', $group );
echo 'Deleting a key that was cached: ' . esc_html( $existing_result ? 'true' : 'false' ) . "\n";Common problems and fixes · 3
- Why does wp_cache_delete return false even though I set the value earlier in the same request?
- Do I still need wp_cache_delete on a site without a persistent object cache plugin?
- How do I clear more than one cached key at once?
Why does wp_cache_delete return false even though I set the value earlier in the same request?
Do I still need wp_cache_delete on a site without a persistent object cache plugin?
How do I clear more than one cached key at once?
Alternatives and related functions
wp_cache_set- When you need to store or update the value in the cache rather than remove it.
wp_cache_get- When you want to read the current cached value, including checking whether a key still exists after a delete.
wp_cache_flush_group- When you need to invalidate every key in a group at once instead of tracking each key individually.
clean_post_cache- When the goal is to invalidate WordPress's own post-related caches rather than a key your own code created.
Performance profile
How much work a call to wp_cache_delete() 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
- 8
- Plugin surface
- None
- Called by
- 37
Reaches the database via ->delete().
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 8.
Nothing here hands control to plugin code.
37 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- cacheobject cache
wp_cache_delete()this function does it - sqldatabase query
->delete()called directly
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_delete() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 8 | ->delete() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 8 instructions, 8 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 · 37
- Twenty_Eleven_Ephemera_Widget::flush_widget_cache()Flushes widget cache.
- WP_AI_Client_Cache::delete()Delete an item from the cache by its unique key.
- WP_Textdomain_Registry::invalidate_mo_files_cache()Invalidate the cache for .mo files.
- WP_Theme::cache_delete()Clears the cache for the theme.
- _transition_post_status()Hook for managing future post transitions to published.
- _wp_upgrade_revisions_of_post()Upgrades the revisions author, adds the current post as a revision and sets the revisions version to 1.
- add_metadata()Adds metadata for the specified object.
- add_user_to_blog()Adds a user to a blog, along with specifying the user's role.
- clean_attachment_cache()Will clean the attachment in the cache.
- clean_blog_cache()Clean the blog cache
- clean_bookmark_cache()Deletes the bookmark cache.
- clean_post_cache()Will clean the post in the cache.
Show all 37
- clean_site_details_cache()Cleans the site details cache for a site.
- clean_taxonomy_cache()Cleans the caches for a taxonomy.
- clean_user_cache()Cleans all user caches.
- delete_get_calendar_cache()Purges the cached results of get_calendar.
- delete_metadata_by_mid()Deletes metadata by meta ID.
- delete_network_option()Removes a network option by name.
- delete_option()Removes an option by name. Prevents removal of protected WordPress options.
- delete_site_transient()Deletes a site transient.
- delete_transient()Deletes a transient.
- delete_usermeta()Remove user meta data.
- get_blog_details()Retrieves the details for a blog from the blogs table and blog options.
- populate_network_meta()Creates WordPress network meta and sets the default values.
- populate_site_meta()Creates WordPress site meta and sets the default values.
- update_core()Upgrades the core of WordPress.
- update_metadata()Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.
- update_metadata_by_mid()Updates metadata by meta ID.
- update_option()Updates the value of an option that was already added.
- update_usermeta()Update metadata of user.
- wp_cache_delete_multiple()Deletes multiple values from the cache in one call.
- wp_clean_plugins_cache()Clears the plugins cache used by get_plugins() and by default, the plugin updates cache.
- wp_clean_theme_json_cache()Cleans the caches under the theme_json group.
- wp_remove_object_terms()Removes term(s) associated with a given object.
- wp_set_object_terms()Creates term and taxonomy relationships.
- wp_set_option_autoload_values()Sets the autoload values for multiple options in the database.
- wp_update_comment_count_now()Updates the comment count for the post.
Source code
function wp_cache_delete( $key, $group = '' ) { global $wp_object_cache; return $wp_object_cache->delete( $key, $group );}Changelog
Introduced in 2.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 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.