Restrict invalidates_query_cache to post meta, add reasoning comments

Rename wp_meta_key_invalidates_query_cache to
wp_post_meta_invalidates_query_cache with a required post_type
parameter. Reject the flag for non-post object types in register_meta.

In WP_Meta_Query, only refuse non-cacheable keys when the post type
is known from the parent WP_Query context. Without context, allow the
query through — it is better to allow a query than to incorrectly
block a legitimate one. Cache correctness is guaranteed by the
invalidation side (wp_cache_set_posts_last_changed), which always
knows the post type from the object ID.

Add comments explaining this reasoning throughout the code and tests.

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Author: ellatrix

src/wp-includes/class-wp-meta-query.php

@@ -561,8 +561,8 @@ protected function get_sql_for_query( &$query, $depth = 0 ) {
 	public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) {
 		global $wpdb;
 
-		// Refuse to query by a meta key registered as non-query-cacheable.
-		if ( $this->object_type
+		// Refuse to query by a post meta key registered as non-query-cacheable.
+		if ( 'post' === $this->object_type
 			&& isset( $clause['key'] )
 			&& is_string( $clause['key'] )
 			&& $this->is_non_cacheable_meta_key( $clause['key'] )
@@ -860,28 +860,39 @@ public function get_clauses() {
 	/**
 	 * Checks whether a meta key is registered as non-query-cacheable.
 	 *
-	 * When object subtypes are known (e.g. post types from the parent WP_Query),
-	 * checks each subtype individually. If any subtype has the key registered as
-	 * non-cacheable, returns true. Falls back to searching across all subtypes
-	 * when no subtypes are available.
+	 * This check is deliberately conservative: it only refuses a meta key
+	 * when the post type is known from the parent WP_Query context. When
+	 * no post type context is available (e.g. direct WP_Meta_Query usage
+	 * without a WP_Query, or post_type set to 'any'), the key is allowed
+	 * through. This avoids incorrectly blocking legitimate queries.
+	 *
+	 * Correctness is guaranteed by the cache invalidation side
+	 * (wp_cache_set_posts_last_changed), which always has the post type
+	 * from the object ID. That side is authoritative — it ensures
+	 * non-cacheable meta never invalidates query caches. This query-side
+	 * check is a safety net to warn developers and prevent obviously
+	 * broken queries, not the primary enforcement mechanism.
+	 *
+	 * When multiple post types are queried, the key is refused if any
+	 * of them has it registered as non-cacheable.
 	 *
 	 * @since 7.0.0
 	 *
 	 * @param string $meta_key Meta key to check.
 	 * @return bool True if the meta key is non-cacheable, false otherwise.
 	 */
 	protected function is_non_cacheable_meta_key( $meta_key ) {
-		if ( ! empty( $this->object_subtypes ) ) {
-			foreach ( $this->object_subtypes as $subtype ) {
-				if ( ! wp_meta_key_invalidates_query_cache( $this->object_type, $meta_key, $subtype ) ) {
-					return true;
-				}
-			}
+		if ( empty( $this->object_subtypes ) ) {
 			return false;
 		}
 
-		// No subtypes available — fall back to checking all subtypes.
-		return ! wp_meta_key_invalidates_query_cache( $this->object_type, $meta_key );
+		foreach ( $this->object_subtypes as $subtype ) {
+			if ( ! wp_post_meta_invalidates_query_cache( $meta_key, $subtype ) ) {
+				return true;
+			}
+		}
+
+		return false;
 	}
 
 	/**

src/wp-includes/meta.php

@@ -1509,6 +1509,12 @@ function register_meta( $object_type, $meta_key, $args, $deprecated = null ) {
 		}
 	}
 
+	if ( ! $args['invalidates_query_cache'] && 'post' !== $object_type ) {
+		_doing_it_wrong( __FUNCTION__, __( 'The invalidates_query_cache parameter is only supported for post meta.' ), '7.0.0' );
+
+		return false;
+	}
+
 	// If `auth_callback` is not provided, fall back to `is_protected_meta()`.
 	if ( empty( $args['auth_callback'] ) ) {
 		if ( is_protected_meta( $meta_key, $object_type ) ) {
@@ -1646,47 +1652,34 @@ function registered_meta_key_exists( $object_type, $meta_key, $object_subtype =
 }
 
 /**
- * Checks whether a meta key invalidates query caches when updated.
+ * Checks whether a post meta key invalidates query caches when updated.
  *
- * Meta keys registered with `'invalidates_query_cache' => false` will not
+ * Post meta keys registered with `'invalidates_query_cache' => false` will not
  * cause query cache invalidation when added, updated, or deleted. This is
- * useful for high-frequency meta that is never used in query filters, such
+ * useful for high-frequency post meta that is never used in query filters, such
  * as real-time collaboration sync data.
  *
  * Unregistered meta keys are assumed to invalidate query caches.
  *
  * @since 7.0.0
  *
- * @param string $object_type    Type of object metadata is for. Accepts 'post', 'comment', 'term', 'user',
- *                               or any other object type with an associated meta table.
- * @param string $meta_key       Metadata key.
- * @param string $object_subtype Optional. The subtype of the object type. Default empty string.
+ * @param string $meta_key  Metadata key.
+ * @param string $post_type Post type to check.
  * @return bool True if the meta key invalidates query caches, false otherwise.
  */
-function wp_meta_key_invalidates_query_cache( $object_type, $meta_key, $object_subtype = '' ) {
-	global $wp_meta_keys;
-
-	$meta_keys = get_registered_meta_keys( $object_type, $object_subtype );
+function wp_post_meta_invalidates_query_cache( $meta_key, $post_type ) {
+	// Check keys registered for this specific post type.
+	$meta_keys = get_registered_meta_keys( 'post', $post_type );
 
 	if ( isset( $meta_keys[ $meta_key ] ) ) {
 		return $meta_keys[ $meta_key ]['invalidates_query_cache'];
 	}
 
-	// Also check keys registered without a subtype.
-	if ( '' !== $object_subtype ) {
-		$meta_keys = get_registered_meta_keys( $object_type );
-		if ( isset( $meta_keys[ $meta_key ] ) ) {
-			return $meta_keys[ $meta_key ]['invalidates_query_cache'];
-		}
-	}
+	// Also check keys registered for all post types.
+	$meta_keys = get_registered_meta_keys( 'post' );
 
-	// When no subtype is given, search across all registered subtypes.
-	if ( '' === $object_subtype && is_array( $wp_meta_keys ) && isset( $wp_meta_keys[ $object_type ] ) ) {
-		foreach ( $wp_meta_keys[ $object_type ] as $registered_keys ) {
-			if ( isset( $registered_keys[ $meta_key ] ) ) {
-				return $registered_keys[ $meta_key ]['invalidates_query_cache'];
-			}
-		}
+	if ( isset( $meta_keys[ $meta_key ] ) ) {
+		return $meta_keys[ $meta_key ]['invalidates_query_cache'];
 	}
 
 	// Unregistered keys default to invalidating caches.

src/wp-includes/post.php

@@ -8461,6 +8461,11 @@ function wp_add_trashed_suffix_to_post_name_for_post( $post ) {
  * the cache is not invalidated. This allows high-frequency meta writes (e.g.
  * real-time collaboration data) to avoid invalidating query caches site-wide.
  *
+ * This is the authoritative check — meta actions always provide both the
+ * object ID and meta key, so the exact post type is always known. This
+ * guarantees that non-cacheable meta never incorrectly invalidates caches,
+ * regardless of how the meta key was registered (globally or per post type).
+ *
  * @since 5.0.0
  * @since 7.0.0 Added the `$meta_id`, `$object_id`, and `$meta_key` parameters.
  *
@@ -8469,9 +8474,9 @@ function wp_add_trashed_suffix_to_post_name_for_post( $post ) {
  * @param string $meta_key  Optional. Meta key. Passed by meta action hooks.
  */
 function wp_cache_set_posts_last_changed( $meta_id = 0, $object_id = 0, $meta_key = '' ) {
-	if ( $meta_key ) {
-		$post_type = $object_id ? get_post_type( $object_id ) : '';
-		if ( ! wp_meta_key_invalidates_query_cache( 'post', $meta_key, $post_type ? $post_type : '' ) ) {
+	if ( $meta_key && $object_id ) {
+		$post_type = get_post_type( $object_id );
+		if ( $post_type && ! wp_post_meta_invalidates_query_cache( $meta_key, $post_type ) ) {
 			return;
 		}
 	}

tests/phpunit/tests/meta/invalidatesQueryCache.php

@@ -2,6 +2,18 @@
 /**
  * Tests for the `invalidates_query_cache` parameter of `register_meta()`.
  *
+ * 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 post type
+ *    is always known. This guarantees non-cacheable meta never incorrectly
+ *    bumps the 'posts' last_changed timestamp.
+ *
+ * 2. Meta query blocking (WP_Meta_Query): a conservative safety net. It only
+ *    refuses a non-cacheable key when the post type is known from the parent
+ *    WP_Query context. Without context, the key is allowed through — it's
+ *    better to allow a query than to incorrectly block a legitimate one.
+ *
  * @group meta
  * @group cache
  *
@@ -152,7 +164,8 @@ public function test_registered_cacheable_meta_still_invalidates_cache() {
 	}
 
 	/**
-	 * WP_Meta_Query should refuse to query by a non-cacheable meta key.
+	 * WP_Meta_Query should refuse to query by a non-cacheable meta key
+	 * when the WP_Query context provides a post type.
 	 *
 	 * @expectedIncorrectUsage WP_Meta_Query::get_sql_for_clause
 	 */
@@ -163,6 +176,9 @@ public function test_meta_query_refuses_non_cacheable_key() {
 			array( 'invalidates_query_cache' => false )
 		);
 
+		$query = new WP_Query();
+		$query->query_vars['post_type'] = 'post';
+
 		$meta_query = new WP_Meta_Query(
 			array(
 				array(
@@ -172,12 +188,39 @@ public function test_meta_query_refuses_non_cacheable_key() {
 			)
 		);
 
-		$sql = $meta_query->get_sql( 'post', 'wp_posts', 'ID' );
+		$sql = $meta_query->get_sql( 'post', 'wp_posts', 'ID', $query );
 
 		$this->assertStringNotContainsString( 'nocache_meta', $sql['where'], 'Non-cacheable meta key should not appear in WHERE clause.' );
 		$this->assertStringNotContainsString( 'nocache_meta', $sql['join'], 'Non-cacheable meta key should not appear in JOIN clause.' );
 	}
 
+	/**
+	 * WP_Meta_Query should allow a non-cacheable meta key when no WP_Query
+	 * context is available. Without knowing the post type, refusing the query
+	 * could incorrectly block legitimate usage. Cache correctness is still
+	 * guaranteed by the invalidation side, which always knows the post type.
+	 */
+	public function test_meta_query_allows_non_cacheable_key_without_context() {
+		register_post_meta(
+			'',
+			'nocache_meta',
+			array( 'invalidates_query_cache' => false )
+		);
+
+		$meta_query = new WP_Meta_Query(
+			array(
+				array(
+					'key'   => 'nocache_meta',
+					'value' => 'test',
+				),
+			)
+		);
+
+		$sql = $meta_query->get_sql( 'post', 'wp_posts', 'ID' );
+
+		$this->assertStringContainsString( 'nocache_meta', $sql['where'], 'Non-cacheable meta key should be allowed without WP_Query context.' );
+	}
+
 	/**
 	 * WP_Meta_Query should work normally for regular meta keys.
 	 */
@@ -248,7 +291,10 @@ public function test_subtype_registration_refuses_meta_query_for_matching_post_t
 
 	/**
 	 * A key registered as non-cacheable for one post type should be allowed
-	 * in meta queries targeting a different post type.
+	 * in meta queries targeting a different post type. The query-side check
+	 * is conservative — it only refuses when the post type is known to be
+	 * non-cacheable. Cache correctness for the other post type is enforced
+	 * by the invalidation side.
 	 */
 	public function test_subtype_registration_allows_meta_query_for_different_post_type() {
 		register_post_meta(
@@ -305,8 +351,10 @@ public function test_subtype_registration_refuses_meta_query_for_array_with_matc
 	}
 
 	/**
-	 * A key registered for a specific post type should not skip cache invalidation
-	 * when written to a different post type.
+	 * A key registered as non-cacheable for one post type should still
+	 * invalidate the cache when written to a different post type. The
+	 * invalidation side always knows the exact post type from the object ID,
+	 * so per-post-type behavior is always correct.
 	 */
 	public function test_subtype_registration_does_not_skip_cache_for_different_post_type() {
 		register_post_meta(