xspeed / includes / modules / Health / HealthModule.php

HealthModule.php in xSpeed Cache: AI-Powered Performance Hub with MCP, Caching & CDN 1.0.3, at includes/modules/Health/HealthModule.php

190 lines 7.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Health module — read-only diagnostic surface for the dashboard.
4	*
5	* No settings_schema (this is a status panel, not a configuration
6	* surface). The React side renders a custom panel (HealthCard, declared
7	* via `ui_metadata.custom_panel`) instead of going through ModulePanel's
8	* schema-driven path.
9	*
10	* Data sources are all existing services:
11	* - Health::checks() — diagnostic rows
12	* - Cache::get_stats() — cached_pages / size / last_purge /
13	* hits_24h / misses_24h / hit_ratio
14	* - Hit_Counter::buckets() — 24 hourly buckets for the sparkline
15	* - Activity_Log::entries() — newest-first event log
16	*
17	* Tier: Free (per FEATURES.md "Cache Insights" — Cache Performance +
18	* Last 24h chart are Free; Recommendations + Frequently-missed-URLs
19	* stay Pro).
20	*
21	* @package XSpeed
22	*/
23
24	declare(strict_types=1);
25
26	namespace XSpeed\Modules\Health;
27
28	use XSpeed\Activity_Log;
29	use XSpeed\Cache;
30	use XSpeed\Health;
31	use XSpeed\Hit_Counter;
32	use XSpeed\Module;
33
34	final class HealthModule extends Module {
35
36	public const SLUG = 'health';
37	public const TIER = self::TIER_FREE;
38	public const VERSION = '1.0.0';
39
40	/**
41	* Surface the most important diagnostics in WordPress's built-in
42	* Site Health screen (Tools → Site Health → Status). Admins who
43	* never open the xSpeed dashboard still get a heads-up when
44	* static-rewrite is missing on Apache/LiteSpeed or when the nginx
45	* snippet hasn't been pasted yet — both lead to a 5-10× slowdown
46	* vs the optimal cache hit path.
47	*/
48	public function boot(): void {
49	add_filter( 'site_status_tests', array( $this, 'register_site_status_tests' ) );
50	}
51
52	public function register_site_status_tests( array $tests ): array {
53	$tests['direct']['xspeed_static_rewrite'] = array(
54	'label' => __( 'xSpeed static-rewrite cache', 'xspeed' ),
55	'test' => array( $this, 'site_status_static_rewrite' ),
56	);
57	return $tests;
58	}
59
60	/**
61	* Site Health test row. Reports green when the .htaccess block is
62	* present (Apache/LiteSpeed) or yellow with the nginx snippet
63	* embedded when nginx is detected. Skipped entirely when cache is
64	* disabled — no point telling the user to install a rewrite they
65	* haven't opted into.
66	*/
67	public function site_status_static_rewrite(): array {
68	$result = array(
69	'label' => __( 'xSpeed static-rewrite cache is active', 'xspeed' ),
70	'status' => 'good',
71	'badge' => array(
72	'label' => __( 'Performance', 'xspeed' ),
73	'color' => 'blue',
74	),
75	'description' => '<p>' . esc_html__( 'Cache hits bypass PHP for ~5-15ms TTFB.', 'xspeed' ) . '</p>',
76	'test' => 'xspeed_static_rewrite',
77	);
78
79	$cache_enabled = (bool) ( \XSpeed\Settings::get()['cache_enabled'] ?? false );
80	if ( ! $cache_enabled ) {
81	$result['label'] = __( 'xSpeed cache is disabled', 'xspeed' );
82	$result['status'] = 'recommended';
83	$result['description'] = '<p>' . esc_html__( 'Enable the page cache in the xSpeed dashboard to start serving cached HTML for non-logged-in visitors.', 'xspeed' ) . '</p>';
84	return $result;
85	}
86
87	$server_type = \XSpeed\Server::type();
88	if ( \XSpeed\Server::APACHE === $server_type \|\| \XSpeed\Server::LITESPEED === $server_type ) {
89	if ( ! \XSpeed\Cache::rewrite_installed() ) {
90	$result['label'] = __( 'xSpeed .htaccess rewrite block is missing', 'xspeed' );
91	$result['status'] = 'recommended';
92	$result['description'] = '<p>' . esc_html__( 'Without the static-rewrite block, cache hits go through the PHP drop-in (~85ms TTFB) instead of the web server (~5-15ms). Toggle Enable Cache off and on in xSpeed to reinstall the block.', 'xspeed' ) . '</p>';
93	}
94	return $result;
95	}
96
97	if ( \XSpeed\Server::NGINX === $server_type ) {
98	$snippet = \XSpeed\Cache::nginx_snippet();
99	$result['label'] = __( 'xSpeed nginx server config required', 'xspeed' );
100	$result['status'] = 'recommended';
101	$result['description'] = '<p>' . esc_html__( 'xSpeed can\'t write nginx config from PHP. Paste this snippet into your site\'s server { } block, then reload nginx so cache hits serve without booting PHP:', 'xspeed' ) . '</p>'
102	. '<pre style="white-space:pre;overflow-x:auto;background:#f6f7f7;border:1px solid #c3c4c7;border-radius:4px;padding:12px;font-size:12px;line-height:1.4;">'
103	. esc_html( (string) $snippet )
104	. '</pre>';
105	return $result;
106	}
107
108	// Unknown / IIS — no server-level rewrite path available; PHP
109	// drop-in is the best we can offer. Don't flag as broken.
110	$result['label'] = __( 'xSpeed PHP drop-in cache active', 'xspeed' );
111	$result['status'] = 'recommended';
112	$result['description'] = '<p>' . esc_html__( 'Static-rewrite caching needs Apache, LiteSpeed, or nginx. The PHP drop-in is still serving cache hits at ~85ms TTFB on this server.', 'xspeed' ) . '</p>';
113	return $result;
114	}
115
116	public function ui_metadata(): array {
117	return array(
118	'label' => 'Health',
119	'icon' => 'HeartPulse',
120	'description' => 'Diagnostics, hit ratio, and recent cache activity.',
121	// Tells the React side to render HealthCard instead of
122	// schema-driven settings (SETTINGS.md §6.2 allows custom
123	// panels for non-settings surfaces).
124	'custom_panel' => 'HealthCard',
125	);
126	}
127
128	// No settings — explicit empty so Module::rest_routes() doesn't
129	// auto-wire the schema-driven GET+POST.
130	public function settings_schema(): array {
131	return array();
132	}
133
134	public function rest_routes(): array {
135	return array(
136	array(
137	'path' => '/',
138	'methods' => 'GET',
139	'callback' => array( $this, 'rest_get_payload' ),
140	),
141	);
142	}
143
144	public function cli_commands(): array {
145	return array(
146	array(
147	'name' => 'xspeed health',
148	'callback' => array( $this, 'cli_handler' ),
149	'shortdesc' => 'Print diagnostic checks + cache stats + recent activity.',
150	'synopsis' => array(),
151	),
152	);
153	}
154
155	/**
156	* Single endpoint that backs the dashboard panel. Refreshed lazily by
157	* the React side; cheap enough that aggregating into one response is
158	* the right call (the buckets array is at most 24 entries; activity
159	* is capped at 50).
160	*/
161	public function rest_get_payload( \WP_REST_Request $request ) {
162	return rest_ensure_response( $this->payload() );
163	}
164
165	public function payload(): array {
166	return array(
167	'checks' => Health::checks(),
168	'stats' => Cache::get_stats(),
169	'buckets' => Hit_Counter::buckets(),
170	'activity' => Activity_Log::entries(),
171	);
172	}
173
174	public function cli_handler( array $args, array $assoc ): void {
175	$payload = $this->payload();
176	\WP_CLI::log( '== Checks ==' );
177	foreach ( $payload['checks'] as $c ) {
178	\WP_CLI::log( sprintf( '[%s] %s — %s', strtoupper( $c['tone'] ), $c['label'], $c['detail'] ) );
179	}
180	\WP_CLI::log( '' );
181	\WP_CLI::log( '== Stats (24h) ==' );
182	\WP_CLI::log( sprintf( 'Hits %d · Misses %d · Hit ratio %.2f%%', $payload['stats']['hits_24h'], $payload['stats']['misses_24h'], $payload['stats']['hit_ratio'] * 100 ) );
183	\WP_CLI::log( '' );
184	\WP_CLI::log( '== Recent activity ==' );
185	foreach ( array_slice( $payload['activity'], 0, 10 ) as $e ) {
186	\WP_CLI::log( sprintf( '%s [%s] %s', gmdate( 'Y-m-d H:i:s', $e['ts'] ), $e['severity'], $e['message'] ) );
187	}
188	}
189	}
190