Improve Post Stats cache handling for invalid or error data #46211

dognose24 · 2025-12-05T20:44:10Z

This PR fixes an issue where the post stats cache could get stuck on invalid data or a WP_Error and never refresh. When corrupted or malformed cache entries exist in post meta, subsequent calls to fetch_post_stats() would always return that bad data instead of refetching from WPCOM.

With this change, invalid or error cache entries trigger a fresh remote fetch and a self-healing cache update, while still honoring the existing cache expiration mechanism for valid data.

Proposed changes:

Introduce the refresh_post_stats_cache() helper to handle the fetch from WPCOM + update post meta flow
Detect and recover from invalid cache entries in fetch_post_stats()

Other information:

Have you written new tests for your changes, if applicable?
Have you checked the E2E test CI results, and verified that your changes do not break them?
Have you tested your changes on WordPress.com, if applicable (if so, you'll see a generated comment below with a script to run)?

Jetpack product discussion

Does this pull request change what data or activity we track or use?

No.

Testing instructions:

Test on the case in the issue from the support ticket
Ensure the This individual post views count of Blog Stats in any post is correctly aligned with /stats/post/{post-id}/{site-slug}.

github-actions · 2025-12-05T20:45:08Z

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the update/blog_stats_debug branch.
To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/blog_stats_debug

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/blog_stats_debug

Interested in more tips and information?

In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
Read more about our development workflow here: PCYsg-eg0-p2
Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

github-actions · 2025-12-05T20:45:22Z

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

✅ Include a description of your PR changes.
✅ Add a "[Status]" label (In Progress, Needs Review, ...).
✅ Add a "[Type]" label (Bug, Enhancement, Janitorial, Task).
✅ Add testing instructions.
✅ Specify whether this PR includes any changes to data or privacy.
✅ Add changelog entries to affected projects

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

Follow this PR Review Process:

Ensure all required checks appearing at the bottom of this PR are passing.
Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
You can use GitHub's Reviewers functionality to request a review.
When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

jp-launch-control · 2025-12-05T20:58:21Z

Code Coverage Summary

This PR did not change code coverage!

That could be good or bad, depending on the situation. Everything covered before, and still is? Great! Nothing was covered before? Not so great. 🤷

Full summary · PHP report · JS report

kangzj · 2025-12-08T21:07:33Z

projects/packages/stats/src/class-wpcom-stats.php

-		update_post_meta( $post_id, $meta_name, array( time() => $wpcom_stats ) );
+
+		// Don't write error or empty results to cache.
+		if ( ! is_wp_error( $wpcom_stats ) && ! empty( $wpcom_stats ) ) {


I would lean to caching even if it's an error, so that we don't put too much pressure on the backend when something goes wrong. However, we need to make sure the data expires no matter it's an error or not. What do you think?

Yeah, that's also what I thought about as an alternative. We can always respect the cache for 5 minutes, regardless of whether it was an error or invalid data. That means even if the data is incorrect, it would last at most 5 minutes, wouldn't it?

Updated in 4ba2b0e.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

projects/packages/stats/src/class-wpcom-stats.php:560

The new refresh_post_stats_cache() function and the cache recovery logic in fetch_post_stats() lack test coverage. The existing test suite has comprehensive tests for other stats methods (e.g., test_get_post_views, test_get_stats, etc.) but none for the post meta caching path.

Consider adding tests for:

Cache recovery when malformed data exists in post meta
Cache recovery when WP_Error is cached
Cache recovery when non-array, non-time-keyed data exists
The new refresh_post_stats_cache() function behavior

	protected function fetch_post_stats( $args, $post_id ) {
		$endpoint    = $this->build_endpoint();
		$meta_name   = '_' . self::STATS_CACHE_TRANSIENT_PREFIX;
		$stats_cache = get_post_meta( $post_id, $meta_name, false );

		if ( $stats_cache ) {
			$data = reset( $stats_cache );

			// Check if we have a valid cache structure with a time key.
			if ( is_array( $data ) && ! empty( $data ) ) {
				$time = key( $data );

				// If we have a numeric time, check if cache is still valid.
				if ( is_numeric( $time ) ) {
					/** This filter is already documented in projects/packages/stats/src/class-wpcom-stats.php */
					$expiration = apply_filters(
						'jetpack_fetch_stats_cache_expiration',
						self::STATS_CACHE_EXPIRATION_IN_MINUTES * MINUTE_IN_SECONDS
					);

					// If within cache period, return cached data regardless of validity.
					if ( ( time() - $time ) < $expiration ) {
						$cached_value = $data[ $time ];

						// If it's a WP_Error, return it directly.
						if ( is_wp_error( $cached_value ) ) {
							return $cached_value;
						}

						// If it's an array, merge with cached_at timestamp.
						if ( is_array( $cached_value ) ) {
							return array_merge( array( 'cached_at' => $time ), $cached_value );
						}

						// For any other type, return as-is.
						return $cached_value;
					}
				}
			}
		}

		// Cache doesn't exist, is expired, or is malformed - refresh it.
		return $this->refresh_post_stats_cache( $endpoint, $args, $post_id, $meta_name );
	}

	/**
	 * Force fetch stats from WPCOM, and update cache if needed.
	 *
	 * @param string $endpoint The stats endpoint.
	 * @param array  $args The query arguments.
	 * @param int    $post_id The post ID.
	 * @param string $meta_name The meta name.
	 *
	 * @return array|WP_Error
	 */
	protected function refresh_post_stats_cache( $endpoint, $args, $post_id, $meta_name ) {
		$wpcom_stats = $this->fetch_remote_stats( $endpoint, $args );

		// Always cache the result, even if it's an error or empty.
		update_post_meta( $post_id, $meta_name, array( time() => $wpcom_stats ) );

		return $wpcom_stats;
	}

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-09T03:42:39Z

projects/packages/stats/src/class-wpcom-stats.php


-			$time  = key( $data );
-			$views = $data[ $time ] ?? null;
+					// If within cache period, return cached data regardless of validity.


The comment "return cached data regardless of validity" is misleading. The code immediately validates the cached value by checking if it's a WP_Error or array (lines 522-530). Consider updating the comment to: "If within cache period, return cached data after type validation."

Suggested change

// If within cache period, return cached data regardless of validity.

// If within cache period, return cached data after type validation.

Copilot · 2025-12-09T03:42:39Z

projects/packages/stats/src/class-wpcom-stats.php

+						// For any other type, return as-is.
+						return $cached_value;


Lines 532-533 will return any non-array, non-WP_Error cached value as-is, which could perpetuate invalid cached data (e.g., null, string, boolean) for the entire cache period. This contradicts the PR's goal of "detecting and recovering from invalid cache entries."

Consider either:

Only returning the cached value if it's an array or WP_Error, falling through to refresh otherwise

Adding explicit validation that cached_value is an expected type

Example:

// For any other unexpected type, treat as malformed cache. // Fall through to refresh.

Then remove the return statement and let execution continue to line 540.

Suggested change

// For any other type, return as-is.

return $cached_value;

// For any other unexpected type, treat as malformed cache.

// Fall through to refresh.

Agree with Copilot here - other cases should all fall to malformed types?

other cases should all fall to malformed types?

Looks reasonable to me, like only leave expected WP_Error thrown from cache.

Updated in 68d3fe3.

kangzj · 2025-12-09T03:49:15Z

projects/packages/stats/src/class-wpcom-stats.php

+						// If it's a WP_Error, return it directly.
+						if ( is_wp_error( $cached_value ) ) {
+							return $cached_value;
+						}

-			/** This filter is already documented in projects/packages/stats/src/class-wpcom-stats.php */
-			$expiration = apply_filters(
-				'jetpack_fetch_stats_cache_expiration',
-				self::STATS_CACHE_EXPIRATION_IN_MINUTES * MINUTE_IN_SECONDS
-			);
+						// If it's an array, merge with cached_at timestamp.
+						if ( is_array( $cached_value ) ) {
+							return array_merge( array( 'cached_at' => $time ), $cached_value );
+						}


I guess we don't have to tell them apart - for those two cases we could both return:

return array_merge( array( 'cached_at' => $time ), $cached_value );

Suggested change

// If it's a WP_Error, return it directly.

if ( is_wp_error( $cached_value ) ) {

return $cached_value;

}

/** This filter is already documented in projects/packages/stats/src/class-wpcom-stats.php */

$expiration = apply_filters(

'jetpack_fetch_stats_cache_expiration',

self::STATS_CACHE_EXPIRATION_IN_MINUTES * MINUTE_IN_SECONDS

);

// If it's an array, merge with cached_at timestamp.

if ( is_array( $cached_value ) ) {

return array_merge( array( 'cached_at' => $time ), $cached_value );

}

// If it's an array or WP_Error, add cached time and return to user.

if ( is_array( $cached_value ) || is_wp_error( $cached_value ) ) {

return array_merge( array( 'cached_at' => $time ), (array)$cached_value );

}

Updated in 68d3fe3.

Co-authored-by: Copilot <[email protected]>

Copilot · 2025-12-09T05:45:18Z

@dognose24 I've opened a new pull request, #46235, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

projects/packages/stats/src/class-wpcom-stats.php

Co-authored-by: Copilot <[email protected]>

kangzj

Looks good and tests well! Thanks so much for all the efforts 👍

dognose24 added 2 commits December 6, 2025 04:33

Remove post stats cache

e0ceb39

changelog

8877038

dognose24 self-assigned this Dec 5, 2025

dognose24 added [Status] In Progress [Block] Blog Stats labels Dec 5, 2025

github-actions bot added the [Package] Stats Data label Dec 5, 2025

dognose24 added the [Type] Bug When a feature is broken and / or not performing as intended label Dec 5, 2025

Improve post stats cache handling for invalid or error data

a736465

dognose24 changed the title ~~Debug missing Blog Stats post views~~ Improve Post Stats cache handling for invalid or error data Dec 5, 2025

dognose24 requested a review from Copilot December 5, 2025 22:18

dognose24 added [Status] Needs Review This PR is ready for review. and removed [Status] In Progress labels Dec 5, 2025

Copilot started reviewing on behalf of dognose24 December 5, 2025 22:18 View session

This comment was marked as outdated.

Sign in to view

Update changelog

ffe8c0c

dognose24 requested review from a team, jeherve and kangzj December 5, 2025 22:50

kangzj reviewed Dec 8, 2025

View reviewed changes

dognose24 added 2 commits December 9, 2025 08:51

Merge branch 'trunk' into update/blog_stats_debug

3c3624b

Respect the cache first and return errors or invalid data as they were

4ba2b0e

dognose24 requested review from Copilot and kangzj December 9, 2025 03:36

Copilot started reviewing on behalf of dognose24 December 9, 2025 03:37 View session

Copilot AI reviewed Dec 9, 2025

View reviewed changes

kangzj reviewed Dec 9, 2025

View reviewed changes

Keep WP errors from cache along with the valid response

68d3fe3

dognose24 requested review from Copilot and kangzj December 9, 2025 04:33

Copilot started reviewing on behalf of dognose24 December 9, 2025 04:33 View session

This comment was marked as outdated.

Sign in to view

Update annotations

3bbe021

dognose24 requested a review from Copilot December 9, 2025 05:00

Copilot started reviewing on behalf of dognose24 December 9, 2025 05:01 View session

This comment was marked as outdated.

Sign in to view

Update annotations

5b9fc39

Co-authored-by: Copilot <[email protected]>

Copilot AI mentioned this pull request Dec 9, 2025

Add test coverage for post stats cache handling improvements #46235

Draft

3 tasks

dognose24 requested a review from Copilot December 9, 2025 06:22

Copilot started reviewing on behalf of dognose24 December 9, 2025 06:22 View session

Copilot AI reviewed Dec 9, 2025

View reviewed changes

projects/packages/stats/src/class-wpcom-stats.php Outdated Show resolved Hide resolved

Apply suggestions from code review

bd5a7b1

Co-authored-by: Copilot <[email protected]>

kangzj approved these changes Dec 9, 2025

View reviewed changes

dognose24 merged commit 2982a5f into trunk Dec 9, 2025
71 checks passed

dognose24 deleted the update/blog_stats_debug branch December 9, 2025 13:24

github-actions bot removed the [Status] Needs Review This PR is ready for review. label Dec 9, 2025

	// If within cache period, return cached data regardless of validity.
	// If within cache period, return cached data after type validation.

Improve Post Stats cache handling for invalid or error data #46211

Improve Post Stats cache handling for invalid or error data #46211

Uh oh!

Conversation

dognose24 commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed changes:

Other information:

Jetpack product discussion

Does this pull request change what data or activity we track or use?

Testing instructions:

Uh oh!

github-actions bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jp-launch-control bot commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Summary

Uh oh!

This comment was marked as outdated.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dognose24 Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI commented Dec 9, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

kangzj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dognose24 commented Dec 5, 2025 •

edited

Loading

github-actions bot commented Dec 5, 2025 •

edited

Loading

github-actions bot commented Dec 5, 2025 •

edited

Loading

jp-launch-control bot commented Dec 5, 2025 •

edited

Loading

dognose24 Dec 9, 2025 •

edited

Loading