| 1 |
<?php |
| 2 |
/** |
| 3 |
* Health — shared diagnostic checks consumed by both Onboarding's |
| 4 |
* environment surface and the Health module's dashboard panel. |
| 5 |
* |
| 6 |
* Each check returns: |
| 7 |
* [ |
| 8 |
* 'id' => 'wp_version', |
| 9 |
* 'tone' => 'ok' | 'warn' | 'fail' | 'info', |
| 10 |
* 'label' => 'WordPress 6.6', |
| 11 |
* 'detail' => 'Meets the 6.0+ minimum.', |
| 12 |
* ] |
| 13 |
* |
| 14 |
* Pure reads — never writes to disk, never makes outbound HTTP calls. |
| 15 |
* Safe to call from any request including the loading dashboard. |
| 16 |
* |
| 17 |
* @package XSpeed |
| 18 |
*/ |
| 19 |
|
| 20 |
declare(strict_types=1); |
| 21 |
|
| 22 |
namespace XSpeed; |
| 23 |
|
| 24 |
defined( 'ABSPATH' ) || exit; |
| 25 |
|
| 26 |
final class Health { |
| 27 |
|
| 28 |
public const OK = 'ok'; |
| 29 |
public const WARN = 'warn'; |
| 30 |
public const FAIL = 'fail'; |
| 31 |
public const INFO = 'info'; |
| 32 |
|
| 33 |
private const SERVER_LABELS = array( |
| 34 |
'apache' => 'Apache', |
| 35 |
'litespeed' => 'LiteSpeed', |
| 36 |
'nginx' => 'nginx', |
| 37 |
'iis' => 'IIS', |
| 38 |
'unknown' => 'Unknown', |
| 39 |
); |
| 40 |
|
| 41 |
/** |
| 42 |
* Full check list used by the Health module's dashboard panel. |
| 43 |
* |
| 44 |
* @return array<int,array{id:string,tone:string,label:string,detail:string}> |
| 45 |
*/ |
| 46 |
public static function checks(): array { |
| 47 |
global $wp_version; |
| 48 |
|
| 49 |
$server_type = Server::type(); |
| 50 |
$gzip_mode = Server::gzip_mode(); |
| 51 |
$conflicts = Server::conflicts(); |
| 52 |
$cache_dir = defined( 'XSPEED_CACHE_DIR' ) ? XSPEED_CACHE_DIR : ( WP_CONTENT_DIR . '/cache/xspeed' ); |
| 53 |
|
| 54 |
$out = array(); |
| 55 |
|
| 56 |
// WordPress version |
| 57 |
$wp_ok = version_compare( (string) $wp_version, '6.0', '>=' ); |
| 58 |
$out[] = array( |
| 59 |
'id' => 'wp_version', |
| 60 |
'tone' => $wp_ok ? self::OK : self::FAIL, |
| 61 |
'label' => sprintf( 'WordPress %s', (string) $wp_version ), |
| 62 |
'detail' => $wp_ok ? 'Meets the 6.0+ minimum.' : 'Upgrade to WordPress 6.0 or higher.', |
| 63 |
); |
| 64 |
|
| 65 |
// PHP version |
| 66 |
$php_ok = version_compare( PHP_VERSION, '7.4', '>=' ); |
| 67 |
$php_modern = version_compare( PHP_VERSION, '8.1', '>=' ); |
| 68 |
$out[] = array( |
| 69 |
'id' => 'php_version', |
| 70 |
'tone' => $php_modern ? self::OK : ( $php_ok ? self::WARN : self::FAIL ), |
| 71 |
'label' => sprintf( 'PHP %s', PHP_VERSION ), |
| 72 |
'detail' => $php_modern |
| 73 |
? 'Modern PHP — full speed.' |
| 74 |
: ( $php_ok |
| 75 |
? 'Works, but 8.1+ is recommended for best performance.' |
| 76 |
: 'Upgrade to PHP 7.4 or higher.' ), |
| 77 |
); |
| 78 |
|
| 79 |
// Server |
| 80 |
$out[] = array( |
| 81 |
'id' => 'server', |
| 82 |
'tone' => self::INFO, |
| 83 |
'label' => sprintf( 'Server: %s', self::SERVER_LABELS[ $server_type ] ?? 'Unknown' ), |
| 84 |
'detail' => 'auto' === $gzip_mode |
| 85 |
? 'GZIP can be auto-configured via .htaccess.' |
| 86 |
: 'GZIP requires a manual server-config snippet (shown in the GZIP module).', |
| 87 |
); |
| 88 |
|
| 89 |
// Cache directory writable |
| 90 |
$dir_writable = wp_mkdir_p( $cache_dir ) && wp_is_writable( $cache_dir ); |
| 91 |
$out[] = array( |
| 92 |
'id' => 'cache_dir', |
| 93 |
'tone' => $dir_writable ? self::OK : self::FAIL, |
| 94 |
'label' => 'Cache directory writable', |
| 95 |
'detail' => $dir_writable |
| 96 |
? $cache_dir |
| 97 |
: sprintf( 'Cannot write to %s. Adjust file permissions before enabling cache.', $cache_dir ), |
| 98 |
); |
| 99 |
|
| 100 |
// Drop-in installed (only when cache is enabled — otherwise N/A) |
| 101 |
$cache_enabled = (bool) Settings::get()['cache_enabled']; |
| 102 |
if ( $cache_enabled ) { |
| 103 |
$dropin_path = WP_CONTENT_DIR . '/advanced-cache.php'; |
| 104 |
$dropin_match = file_exists( $dropin_path ) && false !== strpos( (string) file_get_contents( $dropin_path ), 'xspeed' ); |
| 105 |
$out[] = array( |
| 106 |
'id' => 'dropin', |
| 107 |
'tone' => $dropin_match ? self::OK : self::FAIL, |
| 108 |
'label' => 'advanced-cache.php drop-in', |
| 109 |
'detail' => $dropin_match |
| 110 |
? 'Installed and owned by xSpeed.' |
| 111 |
: 'Drop-in missing or owned by another plugin. Toggle Enable Cache off and on to reinstall.', |
| 112 |
); |
| 113 |
} |
| 114 |
|
| 115 |
// WP_CACHE constant |
| 116 |
$wp_cache_const = defined( 'WP_CACHE' ) && WP_CACHE; |
| 117 |
if ( $cache_enabled ) { |
| 118 |
$out[] = array( |
| 119 |
'id' => 'wp_cache_constant', |
| 120 |
'tone' => $wp_cache_const ? self::OK : self::WARN, |
| 121 |
'label' => 'WP_CACHE constant', |
| 122 |
'detail' => $wp_cache_const |
| 123 |
? 'Defined and truthy in wp-config.php.' |
| 124 |
: 'Not set. Cache is configured but WordPress will not load the drop-in until WP_CACHE = true is added to wp-config.php.', |
| 125 |
); |
| 126 |
} |
| 127 |
|
| 128 |
// Static-rewrite probe. Active end-to-end check: writes a probe |
| 129 |
// file under the static-cache dir, fetches it over HTTP, and |
| 130 |
// confirms the web server (nginx OR Apache/LiteSpeed) served |
| 131 |
// the raw file. Result is throttled to a 5-minute transient |
| 132 |
// inside Cache::probe_static_rewrite so we never hit the |
| 133 |
// network per-paint. |
| 134 |
if ( $cache_enabled ) { |
| 135 |
$server_type = Server::type(); |
| 136 |
// The live loopback probe only matters where a server-level static |
| 137 |
// rewrite is actually used (nginx snippet / Apache .htaccess). |
| 138 |
// LiteSpeed serves hits via the drop-in (see below), so skip the |
| 139 |
// probe there entirely — no needless self-request. Health is the |
| 140 |
// right place to pay for the probe when we DO run it (the admin |
| 141 |
// bootstrap reads cache-only so it never blocks); the 5-minute |
| 142 |
// transient still throttles repeat runs. (FBS-82142) |
| 143 |
$probe = ( Server::LITESPEED === $server_type ) |
| 144 |
? array( 'active' => false ) |
| 145 |
: Cache::probe_static_rewrite( true ); |
| 146 |
$is_active = (bool) ( $probe['active'] ?? false ); |
| 147 |
|
| 148 |
$block_reason = Cache::static_rewrite_block_reason(); |
| 149 |
$mobile_block = ( 'mobile_separate' === $block_reason ) |
| 150 |
? ' Note: Separate Mobile Cache is on, which disables the device-blind static rewrite — if your site serves the same HTML to all devices, turn it off (Cache settings) for much faster cache hits.' |
| 151 |
: ''; |
| 152 |
|
| 153 |
if ( Server::NGINX === $server_type ) { |
| 154 |
$out[] = array( |
| 155 |
'id' => 'static_rewrite_nginx', |
| 156 |
'tone' => $is_active ? self::OK : self::WARN, |
| 157 |
'label' => 'Static-file rewrite (nginx server config)', |
| 158 |
'detail' => $is_active |
| 159 |
? 'nginx is serving cache hits directly — PHP bypassed (~5-15ms TTFB).' |
| 160 |
: ( 'mobile_separate' === $block_reason |
| 161 |
? 'nginx detected, but the static rewrite is disabled because Separate Mobile Cache is on.' . $mobile_block |
| 162 |
: 'nginx detected but not yet routing to the cache. Paste the snippet below into your site\'s server { } block, then reload nginx.' ), |
| 163 |
// Always ship the snippet — even when active, so the |
| 164 |
// admin has it handy for re-pasting after a server |
| 165 |
// rebuild without having to find it elsewhere. Mirror |
| 166 |
// the SAME unified block the "Server config" panel |
| 167 |
// renders (cache + gzip + browser-cache directives), |
| 168 |
// not the cache-only snippet — otherwise Health and |
| 169 |
// the Cache panel disagree on what to paste. |
| 170 |
'snippet' => Cache::full_nginx_server_block(), |
| 171 |
); |
| 172 |
} elseif ( Server::LITESPEED === $server_type ) { |
| 173 |
// LiteSpeed intentionally does NOT use the .htaccess static |
| 174 |
// rewrite: OpenLiteSpeed's .htaccess engine ignores |
| 175 |
// mod_headers (so we can't stamp X-XSpeed-Cache: HIT) and has |
| 176 |
// no per-rule access_log (so a static hit can't be counted). |
| 177 |
// We route LiteSpeed hits through the PHP drop-in instead, so |
| 178 |
// every hit is both visible (X-XSpeed-Cache: HIT) and counted |
| 179 |
// in the hit-ratio — see Cache::static_rewrite_allowed(). This |
| 180 |
// is the healthy, expected state on LiteSpeed, not a fallback. |
| 181 |
$out[] = array( |
| 182 |
'id' => 'static_rewrite_litespeed', |
| 183 |
'tone' => self::OK, |
| 184 |
'label' => 'Cache serving (LiteSpeed)', |
| 185 |
'detail' => 'Cache hits are served by xSpeed\'s drop-in and tagged X-XSpeed-Cache: HIT — so every hit is visible and counted in your hit-ratio. (LiteSpeed\'s .htaccess can\'t add that header or log static hits, so xSpeed serves them itself for accurate reporting.)', |
| 186 |
); |
| 187 |
} elseif ( Server::APACHE === $server_type ) { |
| 188 |
$installed = Cache::rewrite_installed(); |
| 189 |
if ( $is_active ) { |
| 190 |
$tone = self::OK; |
| 191 |
$detail = 'Block installed and serving cache hits directly — PHP bypassed.'; |
| 192 |
} elseif ( 'mobile_separate' === $block_reason ) { |
| 193 |
$tone = self::WARN; |
| 194 |
$detail = 'Static rewrite disabled because Separate Mobile Cache is on.' . $mobile_block; |
| 195 |
} elseif ( ! $installed ) { |
| 196 |
$tone = self::WARN; |
| 197 |
$detail = 'Block missing from .htaccess. Toggle Enable Cache off and on to reinstall it.'; |
| 198 |
} else { |
| 199 |
$tone = self::WARN; |
| 200 |
$detail = sprintf( 'Block installed but probe failed (%s). Confirm the .htaccess block is at the TOP of the file, and that AllowOverride is enabled for your site so mod_rewrite reads it.', (string) ( $probe['reason'] ?? 'unknown' ) ); |
| 201 |
} |
| 202 |
$out[] = array( |
| 203 |
'id' => 'static_rewrite', |
| 204 |
'tone' => $tone, |
| 205 |
'label' => 'Static-file rewrite (.htaccess)', |
| 206 |
'detail' => $detail, |
| 207 |
); |
| 208 |
} |
| 209 |
} |
| 210 |
|
| 211 |
// Cache expiry vs preloader schedule (deterministic rule, issue #31): |
| 212 |
// pages that expire faster than the preloader re-warms them leave the |
| 213 |
// cache cold for most real traffic — the classic "24.8% hit ratio with |
| 214 |
// everything on" misconfiguration. Pure logic in |
| 215 |
// expiry_preload_check() so it's unit-testable. |
| 216 |
if ( $cache_enabled ) { |
| 217 |
$cache_opts = Settings_Manager::get( 'cache' ); |
| 218 |
$pre_opts = Settings_Manager::get( 'preloader' ); |
| 219 |
$schedule = (string) ( $pre_opts['schedule'] ?? 'manual' ); |
| 220 |
$mismatch = self::expiry_preload_check( |
| 221 |
(int) ( $cache_opts['cache_expiry'] ?? 24 ), |
| 222 |
$schedule, |
| 223 |
! empty( $pre_opts['enabled'] ), |
| 224 |
self::schedule_interval_hours( $schedule ) |
| 225 |
); |
| 226 |
if ( null !== $mismatch ) { |
| 227 |
$out[] = $mismatch; |
| 228 |
} |
| 229 |
} |
| 230 |
|
| 231 |
// Permalinks |
| 232 |
$permalinks_ok = (bool) get_option( 'permalink_structure' ); |
| 233 |
$out[] = array( |
| 234 |
'id' => 'permalinks', |
| 235 |
'tone' => $permalinks_ok ? self::OK : self::WARN, |
| 236 |
'label' => 'Permalinks', |
| 237 |
'detail' => $permalinks_ok |
| 238 |
? 'Pretty permalinks active.' |
| 239 |
: 'Set permalinks to anything other than "Plain" — page caching needs URL paths to key on.', |
| 240 |
); |
| 241 |
|
| 242 |
// Cache-poisoning Set-Cookie detection (issue #33): a plugin emitting |
| 243 |
// Set-Cookie on anonymous pageviews forces CDN/edge BYPASS for all |
| 244 |
// HTML (Cloudflare never caches a response carrying Set-Cookie). Probe |
| 245 |
// is transient-throttled inside Cookie_Inspector, same pattern as the |
| 246 |
// static-rewrite probe above — Health is the right place to pay for it. |
| 247 |
// Cached-only: Health runs inside the dashboard REST request and the |
| 248 |
// MCP get_health tool, so this must never block on an HTTP call. |
| 249 |
// A cold verdict schedules a background refresh and reports nothing |
| 250 |
// this paint. See Cookie_Inspector::probe_cached(). |
| 251 |
$cookie_probe = Cookie_Inspector::probe_cached(); |
| 252 |
if ( $cookie_probe['checked'] ) { |
| 253 |
$offenders = $cookie_probe['cookies']; |
| 254 |
if ( empty( $offenders ) ) { |
| 255 |
$out[] = array( |
| 256 |
'id' => 'set_cookie_poisoning', |
| 257 |
'tone' => self::OK, |
| 258 |
'label' => 'No cache-poisoning cookies', |
| 259 |
'detail' => 'Anonymous pages are served without Set-Cookie, so CDN/edge caches can store them.', |
| 260 |
); |
| 261 |
} else { |
| 262 |
$named = array(); |
| 263 |
foreach ( $offenders as $c ) { |
| 264 |
$named[] = null !== $c['plugin'] |
| 265 |
? sprintf( '%s is setting %s', $c['plugin'], $c['name'] ) |
| 266 |
: sprintf( 'an unidentified plugin is setting %s', $c['name'] ); |
| 267 |
} |
| 268 |
$out[] = array( |
| 269 |
'id' => 'set_cookie_poisoning', |
| 270 |
'tone' => self::WARN, |
| 271 |
'label' => 'Set-Cookie on cacheable pages', |
| 272 |
'detail' => sprintf( |
| 273 |
'%s — this prevents CDN edge caching (Cloudflare returns BYPASS for any response with Set-Cookie). Configure the plugin to set its cookie via JavaScript instead, or exclude it from anonymous pageviews.', |
| 274 |
implode( '; ', $named ) |
| 275 |
), |
| 276 |
); |
| 277 |
} |
| 278 |
} |
| 279 |
|
| 280 |
// Conflicting plugins |
| 281 |
$out[] = array( |
| 282 |
'id' => 'conflicts', |
| 283 |
'tone' => empty( $conflicts ) ? self::OK : self::WARN, |
| 284 |
'label' => 'Caching plugin conflicts', |
| 285 |
'detail' => empty( $conflicts ) |
| 286 |
? 'No other caching plugins detected.' |
| 287 |
: sprintf( 'Active: %s. Deactivate before enabling xSpeed cache to avoid double-caching.', implode( ', ', $conflicts ) ), |
| 288 |
); |
| 289 |
|
| 290 |
return $out; |
| 291 |
} |
| 292 |
|
| 293 |
/** |
| 294 |
* Hours between recurring preloader crawls, per schedule option. |
| 295 |
* `twicedaily` is a WordPress core schedule — omitting it meant a site |
| 296 |
* using it got no check at all, not even a pass. |
| 297 |
*/ |
| 298 |
public const PRELOAD_INTERVALS = array( |
| 299 |
'hourly' => 1, |
| 300 |
'twicedaily' => 12, |
| 301 |
'daily' => 24, |
| 302 |
'weekly' => 168, |
| 303 |
); |
| 304 |
|
| 305 |
/** |
| 306 |
* Interval in hours for a cron schedule slug, or null when it isn't a |
| 307 |
* recurring schedule (`manual`) or can't be resolved. |
| 308 |
* |
| 309 |
* Falls back to `wp_get_schedules()` so custom crons registered by a |
| 310 |
* theme or another plugin are covered too, rather than silently |
| 311 |
* skipping the check. |
| 312 |
*/ |
| 313 |
public static function schedule_interval_hours( string $schedule ): ?int { |
| 314 |
if ( isset( self::PRELOAD_INTERVALS[ $schedule ] ) ) { |
| 315 |
return self::PRELOAD_INTERVALS[ $schedule ]; |
| 316 |
} |
| 317 |
if ( '' === $schedule || 'manual' === $schedule || ! function_exists( 'wp_get_schedules' ) ) { |
| 318 |
return null; |
| 319 |
} |
| 320 |
$schedules = wp_get_schedules(); |
| 321 |
if ( ! isset( $schedules[ $schedule ]['interval'] ) ) { |
| 322 |
return null; |
| 323 |
} |
| 324 |
$hours = (int) round( (int) $schedules[ $schedule ]['interval'] / HOUR_IN_SECONDS ); |
| 325 |
return $hours > 0 ? $hours : 1; |
| 326 |
} |
| 327 |
|
| 328 |
/** |
| 329 |
* Deterministic rule: warn when cache_expiry is shorter than the |
| 330 |
* preloader's recurring interval (pages go cold between crawls). |
| 331 |
* |
| 332 |
* Pure — no WP calls — so it can be unit-tested directly. |
| 333 |
* |
| 334 |
* @param int $expiry_hours Cache expiry in hours. |
| 335 |
* @param string $schedule Preloader schedule (manual|hourly|twicedaily|daily|weekly|custom). |
| 336 |
* @param bool $preloader_enabled Whether the preloader module is on. |
| 337 |
* @param int|null $interval_hours Pre-resolved interval, for schedules |
| 338 |
* outside PRELOAD_INTERVALS. Keeps this |
| 339 |
* function pure — the caller does the |
| 340 |
* wp_get_schedules() lookup. |
| 341 |
* @return array{id:string,tone:string,label:string,detail:string}|null Check |
| 342 |
* row, or null when the rule doesn't apply (preloader off/manual). |
| 343 |
*/ |
| 344 |
public static function expiry_preload_check( int $expiry_hours, string $schedule, bool $preloader_enabled, ?int $interval_hours = null ): ?array { |
| 345 |
if ( ! $preloader_enabled ) { |
| 346 |
return null; |
| 347 |
} |
| 348 |
$interval = $interval_hours ?? ( self::PRELOAD_INTERVALS[ $schedule ] ?? null ); |
| 349 |
if ( null === $interval || $interval < 1 ) { |
| 350 |
return null; |
| 351 |
} |
| 352 |
if ( $expiry_hours < $interval ) { |
| 353 |
return array( |
| 354 |
'id' => 'expiry_preload_mismatch', |
| 355 |
'tone' => self::WARN, |
| 356 |
'label' => 'Cache expiry shorter than the preload schedule', |
| 357 |
'detail' => sprintf( |
| 358 |
'Pages expire after %dh but the preloader only re-warms them every %dh (%s), so most visits hit a cold cache. Raise Cache Expiry to at least %dh (Cache settings), or preload more often (Preloader settings).', |
| 359 |
$expiry_hours, |
| 360 |
$interval, |
| 361 |
$schedule, |
| 362 |
$interval |
| 363 |
), |
| 364 |
); |
| 365 |
} |
| 366 |
return array( |
| 367 |
'id' => 'expiry_preload_mismatch', |
| 368 |
'tone' => self::OK, |
| 369 |
'label' => 'Cache expiry covers the preload schedule', |
| 370 |
'detail' => sprintf( 'Expiry %dh ≥ preload interval %dh (%s) — preloaded pages stay warm between crawls.', $expiry_hours, $interval, $schedule ), |
| 371 |
); |
| 372 |
} |
| 373 |
|
| 374 |
/** |
| 375 |
* Lightweight environment payload for the onboarding wizard. Keeps |
| 376 |
* the legacy shape Onboarding::env_payload returned so the Welcome |
| 377 |
* step's HealthRow rendering doesn't change. |
| 378 |
*/ |
| 379 |
public static function env_payload(): array { |
| 380 |
global $wp_version; |
| 381 |
$cache_dir = defined( 'XSPEED_CACHE_DIR' ) ? XSPEED_CACHE_DIR : ( WP_CONTENT_DIR . '/cache/xspeed' ); |
| 382 |
return array( |
| 383 |
'wp' => array( |
| 384 |
'version' => (string) $wp_version, |
| 385 |
'ok' => version_compare( (string) $wp_version, '6.0', '>=' ), |
| 386 |
), |
| 387 |
'php' => array( |
| 388 |
'version' => PHP_VERSION, |
| 389 |
'ok' => version_compare( PHP_VERSION, '7.4', '>=' ), |
| 390 |
'modern' => version_compare( PHP_VERSION, '8.1', '>=' ), |
| 391 |
), |
| 392 |
'server' => array( |
| 393 |
'type' => Server::type(), |
| 394 |
'gzip_mode' => Server::gzip_mode(), |
| 395 |
), |
| 396 |
'cache_dir' => array( |
| 397 |
'path' => $cache_dir, |
| 398 |
'writable' => wp_mkdir_p( $cache_dir ) && wp_is_writable( $cache_dir ), |
| 399 |
), |
| 400 |
'wp_config' => array( |
| 401 |
'writable' => self::wp_config_writable(), |
| 402 |
), |
| 403 |
'permalinks_ok' => (bool) get_option( 'permalink_structure' ), |
| 404 |
'conflicts' => Server::conflicts(), |
| 405 |
); |
| 406 |
} |
| 407 |
|
| 408 |
private static function wp_config_writable(): bool { |
| 409 |
$path = ABSPATH . 'wp-config.php'; |
| 410 |
if ( ! file_exists( $path ) ) { |
| 411 |
$path = dirname( ABSPATH ) . '/wp-config.php'; |
| 412 |
} |
| 413 |
return file_exists( $path ) && wp_is_writable( $path ); |
| 414 |
} |
| 415 |
} |
| 416 |
|
