Improvements to the Cache API in WordPress 6.3

As part of the release of WordPress 6.3, the new Performance team has been working on several improvements to the coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. There are a few new additions to the WordPress Cache APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways., improved validation, and new actions. 

Change cache groups for all query caches

There are a number of places in WordPress where the results of queries are cached, for example, all the major query classes like WP_Query, WP_Comment_Query, and WP_Term_Query. As of WordPress 6.3, the class WP_User_Query also caches the result of queries. In previous versions, the query results were stored in the same cache group as the corresponding object. For instance, post query data would be stored in the “posts” group. However, starting from WordPress 6.3, this approach has been modified.

The update introduces new cache groups specific to queries, offering developers greater control over the handling of objects within these groups. Core functionality now enables developers to specify the expiration time for a cache group, allowing them to set a duration of, for instance, one day. If desired, developers can also use the wp_cache_flush_group() function to clear a specific cache group (if their object cache implementation supports it). Additionally, this change allows developers to designate a cache group as non-persistent, if needed. The following are the newly added cache groups:

  • post-queries
  • term-queries
  • comment-queries
  • networknetwork (versus site, blog)-queries ( global cache group )
  • site-queries  ( global cache group )
  • user-queries ( global cache group )

For sites with persistent object caching enabled, ensure that it supports wp_cache_add_global_groups function (added in WP 2.6) to add global cache groups . If not, you will have to manually add the three new global cache groups. 

See #57625 and #40613 for additional context.

New utility function wp_cache_set_last_changed()

A new utility function, wp_cache_set_last_changed(), has been introduced in WordPress 6.3. This function is utilized to update the last updated value in the cache. It complements the existing wp_cache_get_last_changed() function, which was added in WordPress 4.7. In the core codebase, all instances where the last changed value was updated have been replaced with calls to this new function.

In addition to the new utility function, a corresponding action called wp_cache_set_last_changed has been introduced. This action provides valuable information such as the cache group, the newly updated value, and the old value. Developers can leverage this action to implement custom cache invalidation strategies. When combined with the new cache groups mentioned earlier and the wp_cache_flush_group() function, it becomes possible to clear an entire cache group programmatically.

Here is some sample code of this action that can be used along with the wp_cache_flush_group() function. 

function wpdocs_cache_clear_query_groups( $group ){

  switch( $group ){

     case 'comment':

        $cache_group = 'comment-queries';


     case 'sites':

        $cache_group = 'site-queries';


     case 'networks':

        $cache_group = 'network-queries';


     case 'posts':

        $cache_group = 'post-queries';


     case 'terms':

        $cache_group = 'term-queries';


     case 'users':

        $cache_group = 'user-queries';



        $cache_group = false;


  if( $cache_group ){

     wp_cache_flush_group( $cache_group );



add_action( 'wp_cache_set_last_changed', 'wpdocs_cache_clear_query_groups' );

Validation added to  _get_non_cached_ids() for  invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. IDs

The _get_non_cached_ids() function has been updated to perform validation, ensuring that only an array of unique integers are passed as input. In the previous version, no validation was conducted on the input, leading to potential validation errors and even PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher fatal errors. This function now only supports passing an array of integers. If incorrect values are passed, a _doing_in_wrong message is triggered to inform developers of the error. See #57593

Misc changes 

The PHPUnit test suite now calls wp_cache_flush_runtime() instead of manually resetting class properties of the object cache. The wp_cache_flush_runtime() function was added into core back in WordPress 6.0. If you are running the WordPress core unit tests with an object cache drop-in enabled, please ensure that the wp_cache_flush_runtime() function is present. See #31463

The function wp_cache_get_multiple was introduced in WordPress 5.5., and in WordPress 6.3, it is now in a couple of new places. It is now used to prime network options in wp_load_core_site_options in a single cache call. The wp_cache_get_multiple was also implemented in fill_descendants in WP_Comment_Query. This method is used to fill in descendant comments. This increases the performance of sites that heavily use nested comments. See #57803 and #56913

Props to @flixos90 and @joemcgill for peer review, to @stevenlinx, @leonnugraha and @jyolsna for review.

#6-3, #dev-notes, #dev-notes6-3