thinkrank / includes / api / class-seo-score-endpoint.php

class-seo-score-endpoint.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 2.0.0, at includes/api/class-seo-score-endpoint.php

450 lines 16.5 KB

Raw Download Zip

1	<?php
2	/**
3	* SEO Score REST API Endpoint
4	*
5	* Handles REST API endpoints for SEO score calculation and history
6	*
7	* @package ThinkRank\API
8	* @since 1.0.0
9	*/
10
11	declare(strict_types=1);
12
13	namespace ThinkRank\API;
14
15	use ThinkRank\AI\SEOScoreCalculator;
16	use ThinkRank\Core\Database;
17	use WP_REST_Request;
18	use WP_REST_Response;
19	use WP_Error;
20
21	// Prevent direct access
22	if (!defined('ABSPATH')) {
23	exit;
24	}
25
26	/**
27	* SEO Score Endpoint Class
28	*
29	* Provides REST API endpoints for:
30	* - /wp-json/thinkrank/v1/seo-score/calculate
31	* - /wp-json/thinkrank/v1/seo-score/history
32	*
33	* @since 1.0.0
34	*/
35	class SEOScoreEndpoint {
36
37	/**
38	* SEO Score Calculator instance
39	*
40	* @var SEOScoreCalculator
41	*/
42	private SEOScoreCalculator $calculator;
43
44	/**
45	* Constructor
46	*
47	* @param SEOScoreCalculator $calculator SEO Score Calculator instance
48	*/
49	public function __construct(SEOScoreCalculator $calculator) {
50	$this->calculator = $calculator;
51	}
52
53	/**
54	* Initialize the endpoint
55	*
56	* @return void
57	*/
58	public function init(): void {
59	add_action('rest_api_init', [$this, 'register_routes']);
60	}
61
62	/**
63	* Register REST API routes
64	*
65	* @return void
66	*/
67	public function register_routes(): void {
68	// Calculate SEO score endpoint
69	register_rest_route('thinkrank/v1', '/seo-score/calculate', [
70	'methods' => 'POST',
71	'callback' => [$this, 'calculate_score'],
72	'permission_callback' => [$this, 'check_permissions'],
73	'args' => [
74	'post_id' => [
75	'required' => true,
76	'type' => 'integer',
77	'validate_callback' => [$this, 'validate_post_id'],
78	],
79	'target_keyword' => [
80	'required' => false,
81	'type' => 'string',
82	'sanitize_callback' => 'sanitize_text_field',
83	],
84	'target_keywords' => [
85	'required' => false,
86	'type' => 'array',
87	'items' => ['type' => 'string'],
88	'sanitize_callback' => function ($value) {
89	if (!is_array($value)) {
90	return [];
91	}
92	return array_map('sanitize_text_field', $value);
93	},
94	],
95	'save_score' => [
96	'required' => false,
97	'type' => 'boolean',
98	'default' => true,
99	],
100	'live_content' => [
101	'required' => false,
102	'type' => 'string',
103	'sanitize_callback' => 'wp_kses_post',
104	],
105	// Unsaved SEO title/description straight from the editor. Both
106	// are scored factors, and without them an "Apply" that changes
107	// the title scores against the stale saved value — the score
108	// only moved once the post was saved, which read as the score
109	// updating minutes later on its own. Omitted (null) means "use
110	// what's saved"; an empty string means the user cleared the
111	// field, which must fall back to the rendered pattern exactly
112	// as an empty stored value does.
113	'live_title' => [
114	'required' => false,
115	'type' => 'string',
116	'sanitize_callback' => 'sanitize_text_field',
117	],
118	'live_description' => [
119	'required' => false,
120	'type' => 'string',
121	'sanitize_callback' => 'sanitize_text_field',
122	],
123	// The permalink field as it stands in the editor, so an unsaved
124	// slug edit scores immediately instead of matching the old URL.
125	'live_slug' => [
126	'required' => false,
127	'type' => 'string',
128	// NOT sanitize_title: REST calls a sanitize_callback as
129	// ($value, $request, $param), and sanitize_title()'s second
130	// parameter is $fallback_title — so an empty slug returned
131	// the WP_REST_Request object, which fataled on the string
132	// cast below. The editor sends an empty slug whenever the
133	// permalink field is blank (every draft), so this fired on
134	// ordinary use. Sanitized with a single-argument
135	// sanitize_title() where it is consumed instead.
136	'sanitize_callback' => 'sanitize_text_field',
137	],
138	'readability_score' => [
139	'required' => false,
140	'type' => 'string',
141	'sanitize_callback' => 'sanitize_text_field',
142	],
143	'content_quality' => [
144	'required' => false,
145	'type' => 'string',
146	'sanitize_callback' => 'sanitize_text_field',
147	],
148	],
149	]);
150
151	// Get existing SEO score endpoint
152	register_rest_route('thinkrank/v1', '/seo-score/get', [
153	'methods' => 'GET',
154	'callback' => [$this, 'get_existing_score'],
155	'permission_callback' => [$this, 'check_permissions'],
156	'args' => [
157	'post_id' => [
158	'required' => true,
159	'type' => 'integer',
160	'validate_callback' => [$this, 'validate_post_id'],
161	],
162	],
163	]);
164
165	// Get score history endpoint
166	register_rest_route('thinkrank/v1', '/seo-score/history', [
167	'methods' => 'GET',
168	'callback' => [$this, 'get_score_history'],
169	'permission_callback' => [$this, 'check_permissions'],
170	'args' => [
171	'post_id' => [
172	'required' => true,
173	'type' => 'integer',
174	'validate_callback' => [$this, 'validate_post_id'],
175	],
176	'limit' => [
177	'required' => false,
178	'type' => 'integer',
179	'default' => 10,
180	'minimum' => 1,
181	'maximum' => 50,
182	],
183	],
184	]);
185
186	// Get latest score endpoint
187	register_rest_route('thinkrank/v1', '/seo-score/latest', [
188	'methods' => 'GET',
189	'callback' => [$this, 'get_latest_score'],
190	'permission_callback' => [$this, 'check_permissions'],
191	'args' => [
192	'post_id' => [
193	'required' => true,
194	'type' => 'integer',
195	'validate_callback' => [$this, 'validate_post_id'],
196	],
197	],
198	]);
199	}
200
201	/**
202	* Calculate SEO score for a post
203	*
204	* @param WP_REST_Request $request Request object
205	* @return WP_REST_Response\|WP_Error Response object
206	*/
207	public function calculate_score(WP_REST_Request $request) {
208	try {
209	$post_id = $request->get_param('post_id');
210	$target_keyword = $request->get_param('target_keyword') ?? '';
211	$target_keywords = $request->get_param('target_keywords');
212	$save_score = $request->get_param('save_score') ?? true;
213	$live_content = $request->get_param('live_content') ?? '';
214	$readability_score = $request->get_param('readability_score') ?? null;
215	$content_quality = $request->get_param('content_quality') ?? null;
216
217	// Analyze content - use live content if provided, otherwise saved content
218	if (!empty($live_content)) {
219	$content_data = $this->calculator->analyze_live_content($live_content, $post_id);
220	} else {
221	$content_data = $this->calculator->analyze_post_content($post_id);
222	}
223
224	if (empty($content_data)) {
225	return new WP_Error(
226	'post_not_found',
227	'Post not found or has no content',
228	['status' => 404]
229	);
230	}
231
232	// Get post metadata. Score against the FINAL rendered SEO title/
233	// description — resolve any variable tags in a custom value, and fall
234	// back to the rendered Global/Bulk pattern when the field is empty, so
235	// the length-based scoring matches what the frontend actually outputs.
236	// Prefer the editor's live values when the request carried them, so
237	// an unsaved title/description edit scores immediately instead of
238	// waiting for the post to be saved. `null` means the request said
239	// nothing about the field, which keeps the saved value.
240	$live_title = $request->get_param('live_title');
241	$live_description = $request->get_param('live_description');
242
243	// Score the slug the editor is showing. Omitted (null) keeps the
244	// saved slug; an empty string means the field was cleared, which
245	// falls back to the title-derived slug exactly as an unsaved draft
246	// does inside the calculator.
247	$live_slug = $request->get_param('live_slug');
248	if ($live_slug !== null) {
249	$content_data['slug'] = sanitize_title((string) $live_slug);
250	}
251
252	$raw_title = $live_title !== null
253	? (string) $live_title
254	: get_post_meta($post_id, '_thinkrank_seo_title', true);
255	$raw_description = $live_description !== null
256	? (string) $live_description
257	: get_post_meta($post_id, '_thinkrank_meta_description', true);
258	$metadata = [
259	'title' => \ThinkRank\SEO\Pattern_Resolver::effective_value($raw_title, $post_id, 'title'),
260	'description' => \ThinkRank\SEO\Pattern_Resolver::effective_value($raw_description, $post_id, 'description'),
261	// Fallback source for the scorer when the request carries no
262	// keyword (e.g. a plain "score this post" call). An explicit
263	// request keyword still wins, so the editor keeps scoring
264	// unsaved keyword edits live.
265	'focus_keywords' => \ThinkRank\SEO\Focus_Keywords::get($post_id),
266	];
267
268	// Calculate score. Prefer the multi-keyword list when provided; the
269	// calculator scores each keyword and returns the highest as final.
270	//
271	// Only forward keyword options when the request actually carried
272	// them. The editor always sends its live keyword state (including
273	// empty, when the user clears the field) and that must be honored
274	// verbatim; a request that mentions no keyword at all leaves the
275	// options untouched so the calculator falls back to the keywords
276	// stored on the post.
277	$score_options = [];
278	if ($request->get_param('target_keyword') !== null) {
279	$score_options['target_keyword'] = (string) $target_keyword;
280	}
281	if (is_array($target_keywords)) {
282	$score_options['target_keywords'] = $target_keywords;
283	}
284	$score_data = $this->calculator->calculate_score(
285	$content_data,
286	$metadata,
287	$score_options
288	);
289
290	// Add readability_score and content_quality from frontend if provided
291	if (!empty($readability_score)) {
292	$score_data['readability_score'] = $readability_score;
293	}
294	if (!empty($content_quality)) {
295	$score_data['content_quality'] = $content_quality;
296	}
297
298	// Save score if requested
299	if ($save_score) {
300	$user_id = get_current_user_id();
301	$score_id = $this->calculator->save_score($post_id, $user_id, $score_data);
302
303	if ($score_id) {
304	$score_data['score_id'] = $score_id;
305	}
306	}
307
308	return new WP_REST_Response([
309	'success' => true,
310	'data' => $score_data,
311	], 200);
312
313	} catch (\Exception $e) {
314	return new WP_Error(
315	'calculation_failed',
316	'Failed to calculate SEO score: ' . $e->getMessage(),
317	['status' => 500]
318	);
319	}
320	}
321
322	/**
323	* Get existing SEO score for a post
324	*
325	* @param WP_REST_Request $request Request object
326	* @return WP_REST_Response\|WP_Error Response object
327	*/
328	public function get_existing_score(WP_REST_Request $request) {
329	try {
330	$post_id = $request->get_param('post_id');
331
332	// Get existing score data from database
333	$existing_data = $this->calculator->get_existing_score_data($post_id);
334
335	if ($existing_data) {
336	return new WP_REST_Response([
337	'success' => true,
338	'data' => $existing_data,
339	'message' => __('Existing SEO score retrieved successfully', 'thinkrank')
340	], 200);
341	} else {
342	return new WP_REST_Response([
343	'success' => false,
344	'data' => null,
345	'message' => __('No existing SEO analysis found', 'thinkrank')
346	], 200); // 200 because it's not an error, just no data
347	}
348
349	} catch (\Exception $e) {
350	return new WP_Error('get_score_error', $e->getMessage(), ['status' => 500]);
351	}
352	}
353
354	/**
355	* Get score history for a post
356	*
357	* @param WP_REST_Request $request Request object
358	* @return WP_REST_Response\|WP_Error Response object
359	*/
360	public function get_score_history(WP_REST_Request $request) {
361	try {
362	$post_id = $request->get_param('post_id');
363	$limit = $request->get_param('limit') ?? 10;
364
365	$history = $this->calculator->get_score_history($post_id, $limit);
366
367	return new WP_REST_Response([
368	'success' => true,
369	'data' => $history,
370	], 200);
371
372	} catch (\Exception $e) {
373	return new WP_Error(
374	'history_failed',
375	'Failed to retrieve score history: ' . $e->getMessage(),
376	['status' => 500]
377	);
378	}
379	}
380
381	/**
382	* Get latest score for a post
383	*
384	* @param WP_REST_Request $request Request object
385	* @return WP_REST_Response\|WP_Error Response object
386	*/
387	public function get_latest_score(WP_REST_Request $request) {
388	try {
389	$post_id = $request->get_param('post_id');
390
391	$latest_score = $this->calculator->get_latest_score($post_id);
392
393	return new WP_REST_Response([
394	'success' => true,
395	'data' => $latest_score,
396	], 200);
397
398	} catch (\Exception $e) {
399	return new WP_Error(
400	'latest_failed',
401	'Failed to retrieve latest score: ' . $e->getMessage(),
402	['status' => 500]
403	);
404	}
405	}
406
407	/**
408	* Check permissions for API access
409	*
410	* @param WP_REST_Request $request Request object
411	* @return bool True if user has permission
412	*/
413	public function check_permissions(WP_REST_Request $request): bool {
414	// Check if user is logged in
415	if (!is_user_logged_in()) {
416	return false;
417	}
418
419	// Check if user can edit posts
420	if (!current_user_can('edit_posts')) {
421	return false;
422	}
423
424	// For specific post operations, check if user can edit the specific post
425	$post_id = $request->get_param('post_id');
426	if ($post_id && !current_user_can('edit_post', $post_id)) {
427	return false;
428	}
429
430	return true;
431	}
432
433	/**
434	* Validate post ID parameter
435	*
436	* @param mixed $value Parameter value
437	* @param WP_REST_Request $request Request object
438	* @param string $param Parameter name
439	* @return bool True if valid
440	*/
441	public function validate_post_id($value, WP_REST_Request $request, string $param): bool {
442	if (!is_numeric($value) \|\| $value <= 0) {
443	return false;
444	}
445
446	$post = get_post((int) $value);
447	return $post !== null;
448	}
449	}
450