Improve robustness of page cache test for Site Health by westonruter · Pull Request #10855 · WordPress/wordpress-develop

westonruter · 2026-02-03T18:48:16Z

This improves the robustness of page cache detection in Site Health by refining the response header validation and expanding support for common caching layers.

Logic & Header Improvements

Stricter Cache Hit Matching: The $cache_hit_callback now uses a word-boundary regular expression (/\bhit\b/i) instead of a simple substring check. This prevents false positives from header values like shit. 💩
X-SRCache-Store-Status Correction: Fixed the validation for this header to check for the correct value STORE (the module's indicator for a successful cache storage) instead of HIT.
Varnish Support: Added detection for the X-Varnish header, specifically identifying a hit when the header contains two request IDs (e.g., 123 456), as documented in the Varnish FAQ.
Documentation: Added detailed docblocks and source links for caching headers (e.g., srcache, Varnish) and explicitly listed supported generic proxies (Squid, Go, Fastly, LiteSpeed) in comments.

PHPUnit Test Enhancements

Comprehensive Test Cases: Added new test scenarios to Tests_Admin_wpSiteHealth to verify:
- X-Varnish hits vs. misses.
- X-SRCache-Store-Status (STORE) and X-SRCache-Fetch-Status (HIT).
- Prevention of false positives from substrings (e.g., x-cache: shit).
- Robustness of standard headers like ETag, Last-Modified, and Via.
Improved Typing: Updated the test suite with strict parameter and return types for data providers and test methods, aligning with modern PHP standards and resolving PHPStan reported issues.

Code Quality

Applied consistent formatting to class-wp-site-health.php and the test suite using composer format to ensure adherence to WordPress Coding Standards.

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

Use of AI Tooling

The above PR description was drafted by Gemini, and Gemini CLI was involved in authoring some commits (as attributed via co-authored-by).

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.

This commit updates the page cache detection in Site Health by: - Using a stricter regex (\bhit\b) for detecting cache hits in response headers, preventing false positives (e.g., 'shit'). - Adding support for the X-Varnish header, identifying a cache hit when it contains two request IDs. - Adding documentation and source links for the supported headers. - Adding PHPUnit test cases to verify the new detection logic. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

The x-srcache-store-status header uses 'STORE' or 'BYPASS', not 'HIT' or 'MISS'. This update ensures that 'STORE' is correctly identified as a positive page cache indicator. Also includes: - Documentation for srcache headers. - Explicit list of generic caching proxies (Squid, Go, Fastly, LiteSpeed) in comments. - Test cases for x-srcache-store-status and x-srcache-fetch-status. Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

github-actions · 2026-02-03T18:48:30Z

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 westonruter, dmsnell.

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

westonruter · 2026-02-03T18:52:28Z

Gemini review:

I have completed the review of the changes committed to the trac-64370 branch.

Commit Context

The changes aim to improve the robustness of page cache detection in WordPress Site Health. Key improvements include:

Using stricter regex (\bhit\b) to prevent false positives from header values like "shit".
Adding support for the X-Varnish header by detecting the specific hit format (two request IDs).
Correcting x-srcache-store-status detection to look for STORE instead of HIT.
Improving documentation and PHPStan typing for the detection methods and tests.

Code Review

`src/wp-admin/includes/class-wp-site-health.php`

Logic Improvement: The move from str_contains to preg_match( '/\bhit\b/i', ... ) is an excellent fix for substring-related false positives.
Varnish Header: The x-varnish callback correctly implements the detection of a hit by checking for two space-separated digits, matching Varnish's debugging header behavior.
SRCache Correction: Updating x-srcache-store-status to check for STORE is correct as per the module's documentation.
Coding Standards:
- The use of array shape return types (array<string, ?callable>) in docblocks aligns with current project goals for PHPStan level 10 compatibility.
- The addition of the : array return type hint is compatible with PHP 7.4.
Nitpick: The via header is restored but set to null (existence check). While standard, many proxies use Via without caching. However, given the context of other headers, this is a reasonable heuristic for WordPress core.

`tests/phpunit/tests/admin/wpSiteHealth.php`

Type Safety: The addition of strict types to properties and method signatures (private WP_Site_Health $instance;, test_get_page_cache( array $responses, ... )) is a great improvement for the test suite's reliability.
PHPStan Resolution: The return type for data_get_page_cache has been meticulously defined to match the complex array structure returned, which should resolve the reported PHPStan errors.
Test Coverage:
- New cases for false-positive-hit-in-word, varnish-header, and srcache variants provide thorough coverage for the logic changes.
- The last-modified test case uses a realistic date string, which is better than the previous "hit" value.
Consistency: The change from null to false for good_basic_auth in the data provider, coupled with the signature change to bool, ensures type consistency.

Summary

The changes are high quality, follow WordPress coding standards, and significantly improve the reliability of Site Health's page cache detection. No regressions or standards violations were identified.

Recommendation: Ready for merge.

github-actions · 2026-02-03T18:55:11Z

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

The Plugin and Theme Directories cannot be accessed within Playground.
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.

westonruter · 2026-02-03T20:18:48Z

 			'x-cache-disabled'       => static function ( $header_value ) {
 				return ( 'on' !== strtolower( $header_value ) );
 			},
-			'x-srcache-store-status' => $cache_hit_callback,


This was incorrect. Now fixed.

…into trac-64370

westonruter · 2026-02-17T18:45:53Z

 	 * @covers ::get_page_cache_headers()
 	 * @covers ::check_for_page_caching()
 	 */
-	public function test_get_page_cache( $responses, $expected_status, $expected_label, $good_basic_auth = null, $delay_the_response = false ) {


Note that $good_basic_auth was previously only either null or false, so this is now changed to be an actual boolean with true or false.

dmsnell

sorry I can’t give a more thorough review at the moment. it’s nice seeing iteration on the screen.

dmsnell · 2026-02-17T19:29:23Z

+				),
+				'expected_status' => 'good',
+				'expected_label'  => $good_label,
+			),


because I’m not familiar with all of these systems, and don’t have any in front of me, I am not reviewing or verifying these tests.

I’m trusting that you confirmed that the responses correspond to what those projects actually produce and that the values here are factually representative.

the CommonCrawl archive would potentially be a valuable archive to mine for this kind of header behavior.

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

… value Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

westonruter · 2026-02-17T20:53:18Z

+			/**
+			 * Custom caching headers.
+			 *
+			 * These do not seem to be actually used by any caching layers. There were first introduced in a Site Health
+			 * test in the AMP plugin. They were copied into the Performance Lab plugin's Site Health test before they
+			 * were merged into core.
+			 *
+			 * @link https://github.com/ampproject/amp-wp/pull/6849
+			 * @link https://github.com/WordPress/performance/pull/263
+			 * @link https://core.trac.wordpress.org/changeset/54043
+			 */
 			'x-cache-enabled'        => static function ( $header_value ) {
-				return 'true' === strtolower( $header_value );
+				return ( 'true' === strtolower( $header_value ) );
 			},
 			'x-cache-disabled'       => static function ( $header_value ) {
 				return ( 'on' !== strtolower( $header_value ) );
 			},


I'm inclined to remove these entirely since it seems they were originally introduced erroneously in the AMP plugin. I can't find any caching layers that actually use them. There are a few hundred mentions of them on GitHub, nevertheless: https://github.com/search?q=%2Fx-cache-(enabled%7Cdisabled)%2F&type=code

🤷‍♂️ if they exist out there then I wouldn’t think there’s a problem leaving them in here. all we need is a single point of evidence showing they’re in use to be valuable here. maybe someone looks at one of those projects as an example and then copies the header without knowing better?

regardless, we shouldn’t need to feel obliged to foresee every possible setup, so if we have reason to believe this is a fringe header we don’t anticipate seeing, then it seems reasonable to remove them.

I'll leave for now 👍🏻

dmsnell

although I’ve left some comments, I don’t see any reason to block this work. the header information is much more helpful with the comments you added 🙇‍♂️

dmsnell · 2026-02-20T19:14:47Z

+			 */
 			'x-cache-enabled'        => static function ( $header_value ) {
-				return 'true' === strtolower( $header_value );
+				return ( 'true' === strtolower( $header_value ) );


what’s the purpose of the added parentheses?

Just improved readability, perhaps, to avoid going down a garden path to think it returns the string 'true'. Also, it makes it consistent with the subsequent check.

dmsnell · 2026-02-20T19:19:39Z

+			/**
+			 * Custom caching headers.
+			 *
+			 * These do not seem to be actually used by any caching layers. There were first introduced in a Site Health
+			 * test in the AMP plugin. They were copied into the Performance Lab plugin's Site Health test before they
+			 * were merged into core.
+			 *
+			 * @link https://github.com/ampproject/amp-wp/pull/6849
+			 * @link https://github.com/WordPress/performance/pull/263
+			 * @link https://core.trac.wordpress.org/changeset/54043
+			 */
 			'x-cache-enabled'        => static function ( $header_value ) {
-				return 'true' === strtolower( $header_value );
+				return ( 'true' === strtolower( $header_value ) );
 			},
 			'x-cache-disabled'       => static function ( $header_value ) {
 				return ( 'on' !== strtolower( $header_value ) );
 			},


🤷‍♂️ if they exist out there then I wouldn’t think there’s a problem leaving them in here. all we need is a single point of evidence showing they’re in use to be valuable here. maybe someone looks at one of those projects as an example and then copies the header without knowing better?

regardless, we shouldn’t need to feel obliged to foresee every possible setup, so if we have reason to believe this is a fringe header we don’t anticipate seeing, then it seems reasonable to remove them.

dmsnell · 2026-02-20T19:20:08Z

+			/**
+			 * CloudFlare.
+			 *
+			 * @link https://developers.cloudflare.com/cache/concepts/cache-responses/


lovely adding these things

Co-authored-by: Dennis Snell <dmsnell@git.wordpress.org>

…ed verification logic. - Use a more precise regular expression for identifying "HIT" statuses to avoid false positives (e.g., "no-hit"). - Add specific verification logic for Varnish's `X-Varnish` header. - Use a `null` value in the header mapping to indicate a header existence check, when no callback is supplied. - Improve documentation with links for information about certain headers. Developed in #10855 Follow-up to [61355], [54043]. Props westonruter, dmsnell. See #63748. Fixes #64370. git-svn-id: https://develop.svn.wordpress.org/trunk@61711 602fd350-edb4-49c9-b593-d223f7449a82

github-actions · 2026-02-20T21:13:15Z

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 61711
GitHub commit: 839a088

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

…ed verification logic. - Use a more precise regular expression for identifying "HIT" statuses to avoid false positives (e.g., "no-hit"). - Add specific verification logic for Varnish's `X-Varnish` header. - Use a `null` value in the header mapping to indicate a header existence check, when no callback is supplied. - Improve documentation with links for information about certain headers. Developed in WordPress/wordpress-develop#10855 Follow-up to [61355], [54043]. Props westonruter, dmsnell. See #63748. Fixes #64370. Built from https://develop.svn.wordpress.org/trunk@61711 git-svn-id: http://core.svn.wordpress.org/trunk@61019 1a063a9b-81f0-0310-95a4-ce76da25c4cd

westonruter and others added 4 commits February 3, 2026 09:27

Improve docs and typing for get_page_cache_headers method

9aa2b94

Tidy test_get_page_cache

ed21256

westonruter requested a review from dmsnell February 3, 2026 18:59

westonruter commented Feb 3, 2026

View reviewed changes

westonruter added 2 commits February 11, 2026 12:19

Merge branch 'trunk' of https://github.com/WordPress/wordpress-develop …

a6ffaaf

…into trac-64370

Merge branch 'trunk' into trac-64370

f9512d5

westonruter commented Feb 17, 2026

View reviewed changes

Rename good_basic_auth to has_basic_auth since not necessarily good

5a7b2f5

dmsnell reviewed Feb 17, 2026

View reviewed changes

westonruter and others added 9 commits February 17, 2026 11:31

Fix typo in comment

de5b813

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Replace bool type cast with explicit equality for preg_match() return…

c51daae

… value Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Remove vulgarity from test

913d8cb

Co-authored-by: Dennis Snell <dennis.snell@automattic.com>

Move via header up to standard section

c63928a

Re-organized cache headers

6f1ff6a

Add nginx section and add links for Varnish

4af0c36

Move x-proxy-cache into Nginx section

1aded16

Replace word boundary for HIT with anchor, comma, or whitespace

c67ffac

Add documentation for x-cache-enabled and x-cache-disabled

40770d1

westonruter commented Feb 17, 2026

View reviewed changes

dmsnell approved these changes Feb 20, 2026

View reviewed changes

westonruter and others added 4 commits February 20, 2026 12:10

Merge branch 'trunk' into trac-64370

60c7a8d

Flesh out docs for filter

a80182c

Co-authored-by: Dennis Snell <dmsnell@git.wordpress.org>

Explain null value in return docs

82d1911

Fix typo in phpdoc

3e1610a

github-actions Bot closed this Feb 20, 2026

Conversation

westonruter commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Logic & Header Improvements

PHPUnit Test Enhancements

Code Quality

Use of AI Tooling

Uh oh!

github-actions Bot commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

westonruter commented Feb 3, 2026

Commit Context

Code Review

src/wp-admin/includes/class-wp-site-health.php

tests/phpunit/tests/admin/wpSiteHealth.php

Summary

Uh oh!

github-actions Bot commented Feb 3, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmsnell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

dmsnell left a comment

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!

github-actions Bot commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

westonruter commented Feb 3, 2026 •

edited

Loading

github-actions Bot commented Feb 3, 2026 •

edited

Loading

`src/wp-admin/includes/class-wp-site-health.php`

`tests/phpunit/tests/admin/wpSiteHealth.php`