Meta: Allow registering post meta keys that skip query cache invalidation

[ellatrix]

Trac ticket: https://core.trac.wordpress.org/ticket/64696

Alternative approach to the cache invalidation problem: instead of a new table, allow post meta keys to be registered as non-query-cacheable via register_meta() / register_post_meta().

What it does

Adds an invalidates_query_cache parameter to register_meta() (post meta only). Keys registered with false:

• Do not bump the last_changed timestamp in the posts cache group when added, updated, or deleted
• Are refused in WP_Meta_Query clauses (with _doing_it_wrong) when the post type is known, to prevent stale cached results
• Can still be read/written normally via get_post_meta() / update_post_meta() / etc.

Design

Cache correctness relies on two complementary mechanisms:

1. Cache invalidation (wp_cache_set_posts_last_changed): the authoritative check. Meta write hooks always provide the object ID, so the exact post type is always known. Non-cacheable meta never incorrectly bumps last_changed.

2. Meta query blocking (WP_Meta_Query): a conservative safety net. Only refuses non-cacheable keys when the post type is known from the parent WP_Query context. Without context, allows the query through — better to allow a query than incorrectly block a legitimate one.

Supports per-post-type registration: a key can be non-cacheable for one post type but cacheable for another.

Testing

15 unit tests covering registration, cache invalidation (add/update/delete), meta query blocking (with/without context, per-post-type, multi-post-type), and the _doing_it_wrong notice.

phpunit --filter Tests_Meta_InvalidatesQueryCache

Use of AI Tools

Co-authored with Claude Code (Opus 4.6).

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props ellatrix, paulkevan, peterwilsoncc, czarate.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[peterwilsoncc]

Dropping this here rather than on the ticket as it's a implimentation consideration rather than a architectural consideration. One of the risks we'd need to consider is demonstrated by these two tests

public function test_wp_query_side_effects_one() {
	register_post_meta(
		'post',
		'uncached_meta_key',
		array( 'invalidates_query_cache' => false )
	);

	add_post_meta( self::$post_id, 'uncached_meta_key', 'uncached_meta_value' );
	$query1 = new WP_Query(
		array(
			'fields'     => 'ids',
			'meta_value' => 'uncached_meta_value',
		)
	);
	$this->assertEmpty( $query1->posts, 'WP_Query should not query non-cacheable meta data.' );
}

public function test_wp_query_side_effects_two() {
	register_post_meta(
		'post',
		'uncached_meta_key',
		array( 'invalidates_query_cache' => false )
	);

	add_post_meta( self::$post_id, 'uncached_meta_key', 'uncached_meta_value' );
	$query1 = new WP_Query(
		array(
			'fields'     => 'ids',
			'meta_value' => 'uncached_meta_value',
		)
	);

	delete_post_meta( self::$post_id, 'uncached_meta_key' );
	$query2 = new WP_Query(
		array(
			'fields'     => 'ids',
			'meta_value' => 'uncached_meta_value',
		)
	);
	$this->assertEmpty( $query2->posts, 'WP_Query should not cache non-cacheable meta queries.' );
}

Results:

$ phpunit --filter test_wp_query_side_effects
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml
Not running ajax tests. To execute these, use --group ajax.
Not running ms-files tests. To execute these, use --group ms-files.
Not running external-http tests. To execute these, use --group external-http.
PHPUnit 9.6.34 by Sebastian Bergmann and contributors.

Warning:       Your XML configuration validates against a deprecated schema.
Suggestion:    Migrate your XML configuration using "--migrate-configuration"!

FF                                                                  2 / 2 (100%)

Time: 00:00.206, Memory: 235.92 MB

There were 2 failures:

1) Tests_Meta_InvalidatesQueryCache::test_wp_query_side_effects_one
WP_Query should not query non-cacheable meta data.
Failed asserting that an array is empty.

/vagrant/wordpress-develop/tests/phpunit/tests/meta/invalidatesQueryCache.php:391

2) Tests_Meta_InvalidatesQueryCache::test_wp_query_side_effects_two
WP_Query should not cache non-cacheable meta queries.
Failed asserting that an array is empty.

/vagrant/wordpress-develop/tests/phpunit/tests/meta/invalidatesQueryCache.php:417

[ellatrix]

@peterwilsoncc Right, there's a decision to be made there for those queries that only provide a meta value to query without a key. Either we alter the query (commit), which tbh I find a little too aggressive and risky, or we are ok with this edge case. Either way, it's probably rare to have queries by meta value only?

[pkevan]

@ellatrix and I discussed the complexity addition of a NOT IN query here. It seems like it would be not more complex with it since it would be a query on value only.

[ellatrix]

I do lean towards removing the query modification and just leaving it as an edge case with a note. These kinds of meta value only queries should anyway be rare and discouraged (imo).

[aaronjorbin]

Have you checked how plugins are using meta_query to know how much of an edge case this is?

I agree it should be discouraged, but I don't know how prevalent this is.

[ellatrix]

How would you search for plugins using meta_value without meta_key?

[aaronjorbin]

I can't think of a specific regex for that, so I would suggest manually checking the code. Otherwise, I think we shoud lean towards being as defensive as possible and not assuming it's an edge case.

[ellatrix]

How would you check them manually other than just a few?
What does defensive mean in this case? I guess you're arguing for keeping the query adjustment and excluding these keys?

[chriszarate]

I just tested this and compared against trunk. I can confirm that this PR prevents query cache invalidation for the two RTC post meta.

Before

before.mov

After

after.mov