← All changes | includes/seo/class-llms-txt-manager.php +313 -36 2.1.0 → 2.13.0 View file →

		@@ -14,8 +14,13 @@
14	14	declare(strict_types=1);
15	15
16	16	namespace ThinkRank\SEO;
17	17
	18	+// Prevent direct access
	19	+if (!defined('ABSPATH')) {
	20	+ exit;
	21	+}
	22	+
18	23	// Ensure dependencies are loaded
19	24	if (!class_exists('ThinkRank\\SEO\\Abstract_SEO_Manager')) {
20	25	require_once THINKRANK_PLUGIN_DIR . 'includes/seo/class-abstract-seo-manager.php';
21	26	}
		@@ -85,9 +90,9 @@
85	90	],
86	91	'key_features' => [
87	92	'title' => 'Key Features',
88	93	'required' => true,
89		- 'description' => 'Main features and functionality of the website',
	94	+ 'description' => 'Main features and functionality of the website, one feature per line. Commas are part of a feature, not separators.',
90	95	'max_length' => 300
91	96	],
92	97	'architecture' => [
93	98	'title' => 'Architecture & Components',
		@@ -198,8 +203,20 @@
198	203	*/
199	204	private const DELIVERY_MODES = ['auto', 'static', 'dynamic'];
200	205
201	206	/**
	207	+ * One-time marker for {@see LLMs_Txt_Manager::maybe_migrate_legacy_key_features()}.
	208	+ *
	209	+ * Public so the activator can record it on a fresh install, which has no
	210	+ * value saved under the old comma rule and must never be migrated.
	211	+ *
	212	+ * @since 2.10.0
	213	+ * @var string
	214	+ */
	215	+ public const KEY_FEATURES_MIGRATION_OPTION = 'thinkrank_llms_key_features_migration';
	216	+ public const KEY_FEATURES_MIGRATION_VERSION = '1';
	217	+
	218	+ /**
202	219	* Business type templates for content generation
203	220	*
204	221	* @since 1.0.0
205	222	* @var array
		@@ -291,8 +308,13 @@
291	308	'validation' => [],
292	309	'file_info' => []
293	310	];
294	311
	312	+ // Generating from saved settings (the MCP ability passes an empty
	313	+ // payload) can happen before any admin request has run the upgrade,
	314	+ // so make sure a legacy comma list has been converted first.
	315	+ self::maybe_migrate_legacy_key_features();
	316	+
295	317	// Get current settings
296	318	$settings = $this->get_settings('site');
297	319
298	320	// Merge saved settings underneath the provided input so that empty or
		@@ -536,8 +558,18 @@
536	558	if ('static' === $mode || 'dynamic' === $mode) {
537	559	return $mode;
538	560	}
539	561
	562	+ // A root PHP cannot write to has no static path at all: publishing
	563	+ // would simply fail and /llms.txt would 404. The sitemap's `auto`
	564	+ // already resolves this way (#754); llms.txt did not, so on an
	565	+ // Apache/LiteSpeed host with a read-only root — a managed stack such as
	566	+ // Flywheel, where ABSPATH is the locked core folder — `auto` chose
	567	+ // static and then could not deliver it (#756).
	568	+ if (!wp_is_writable(ABSPATH)) {
	569	+ return 'dynamic';
	570	+ }
	571	+
540	572	// $is_apache also covers LiteSpeed, which reads .htaccess the same way.
541	573	if (empty($GLOBALS['is_apache'])) {
542	574	return 'dynamic';
543	575	}
		@@ -745,15 +777,38 @@
745	777	return is_string($content) ? $content : '';
746	778	}
747	779
748	780	/**
	781	+ * Whether /llms.txt is currently being served, in either delivery mode.
	782	+ *
	783	+ * `static` publishes a file at ABSPATH; `dynamic` keeps the document in
	784	+ * an option and answers from serve_llms_txt(). Callers that only need
	785	+ * this yes/no must use it in preference to get_llms_txt_status(), which
	786	+ * resolves the delivery mode, may fire a loopback delivery probe, asks
	787	+ * the filesystem API whether ABSPATH is writable, reads the document and
	788	+ * writes a transient — far too much work for a boolean, and not
	789	+ * something a dashboard summary should be triggering.
	790	+ *
	791	+ * @since 2.2.1
	792	+ *
	793	+ * @return bool
	794	+ */
	795	+ public function is_published(): bool {
	796	+ return file_exists(ABSPATH . 'llms.txt')
	797	+ || '' !== trim($this->get_published_content());
	798	+ }
	799	+
	800	+ /**
749	801	* Ask the common page/CDN cache layers to drop their copy of /llms.txt.
750	802	*
751	803	* A cached response outlives a republish, so without this a mode switch or
752	804	* a content change keeps serving the old document (and, on the static path,
753		- * the old headers). Every call is guarded — a site running none of these
754		- * simply gets the action hook, which integrations can use.
	805	+ * the old headers).
755	806	*
	807	+ * The layer-by-layer work moved to Cache_Purger in 2.10.1, once alt-text
	808	+ * writes needed the same thing (#763). The llms.txt-specific hook stays
	809	+ * here because it names this document, which a generic URL purge cannot.
	810	+ *
756	811	* @since 2.1.0
757	812	*
758	813	* @return void
759	814	*/
		@@ -769,22 +824,9 @@
769	824	* @param string $url Public URL of the llms.txt document.
770	825	*/
771	826	do_action('thinkrank_llms_txt_updated', $url);
772	827
773		- // LiteSpeed Cache and Nginx Helper both listen on their own actions.
774		- // These are third-party hook names we fire, not ours to prefix.
775		- do_action('litespeed_purge_url', $url); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound
776		- do_action('rt_nginx_helper_purge_all'); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound
777		-
778		- if (function_exists('rocket_clean_files')) {
779		- rocket_clean_files([$url]);
780		- }
781		- if (function_exists('w3tc_flush_url')) {
782		- w3tc_flush_url($url);
783		- }
784		- if (function_exists('wpsc_delete_url_cache')) {
785		- wpsc_delete_url_cache($url);
786		- }
	828	+ Cache_Purger::purge_urls([$url]);
787	829	}
788	830
789	831	/**
790	832	* Unpublish llms.txt: drop the stored document and any physical file.
		@@ -1169,9 +1211,9 @@
1169	1211	$status = [
1170	1212	'file_exists' => file_exists($llms_file),
1171	1213	// Whether /llms.txt is actually being served, either mode. Prefer
1172	1214	// this over file_exists, which is only meaningful in static mode.
1173		- 'published' => file_exists($llms_file) || '' !== trim($stored),
	1215	+ 'published' => $this->is_published(),
1174	1216	'delivery_mode' => $mode,
1175	1217	'file_path' => 'dynamic' === $mode ? '' : $llms_file,
1176	1218	'file_url' => home_url('/llms.txt'),
1177	1219	'writable' => $this->is_directory_writable(dirname($llms_file)),
		@@ -1207,12 +1249,11 @@
1207	1249	}
1208	1250
1209	1251	if (null !== $content) {
1210	1252	// Get content preview (first 200 characters) with size safety
1211		- $status['content_preview'] = substr($content, 0, 200);
1212		- if (strlen($content) > 200) {
1213		- $status['content_preview'] .= '...';
1214		- }
	1253	+ // substr()/strlen() count BYTES, so this cut a multibyte character
	1254	+ // in half and shipped an invalid UTF-8 sequence in the preview (#687).
	1255	+ $status['content_preview'] = \ThinkRank\Core\Seo_Text::trim_to_length($content, 200);
1215	1256	}
1216	1257
1217	1258	// Cache the result for 5 minutes to improve performance
1218	1259	set_transient($cache_key, $status, 5 * MINUTE_IN_SECONDS);
		@@ -1548,11 +1589,20 @@
1548	1589	}
1549	1590
1550	1591	// Check key features quality
1551	1592	if (!empty($user_input['key_features'])) {
1552		- $features = explode("\n", $user_input['key_features']);
1553		- $feature_count = count(array_filter($features, 'trim'));
	1593	+ // The same splitter the generated file uses, so the count reported
	1594	+ // here and the bullets written out can never disagree (#765).
	1595	+ $feature_count = count(self::split_key_features((string) $user_input['key_features']));
1554	1596
	1597	+ // A single line containing commas is ambiguous: it is either a
	1598	+ // legacy comma-separated list or one feature with a comma in it.
	1599	+ // Rather than guess and risk publishing "and Etsy" as a feature,
	1600	+ // say so and let the author decide.
	1601	+ if (self::looks_like_comma_list((string) $user_input['key_features'])) {
	1602	+ $validation['suggestions'][] = 'Put each key feature on its own line. Commas are treated as part of a feature, not as separators.';
	1603	+ }
	1604	+
1555	1605	if ($feature_count < 3) {
1556	1606	$validation['warnings'][] = 'Consider adding more key features (3-8 recommended) for comprehensive AI understanding';
1557	1607	$validation['score'] -= 10;
1558	1608	} elseif ($feature_count > 10) {
		@@ -2013,9 +2063,9 @@
2013	2063	],
2014	2064	'key_features' => [
2015	2065	'type' => 'string',
2016	2066	'title' => 'Key Features',
2017		- 'description' => 'Main features and functionality of your website',
	2067	+ 'description' => 'Main features and functionality of your website. One feature per line: a comma is treated as part of a feature, not as a separator.',
2018	2068	'default' => '',
2019	2069	'maxLength' => 500
2020	2070	],
2021	2071	'target_audience' => [
		@@ -2123,8 +2173,243 @@
2123	2173	return "> " . $description . "\n\n";
2124	2174	}
2125	2175
2126	2176	/**
	2177	+ * Split the Key Features field into individual features.
	2178	+ *
	2179	+ * One feature per line. Commas used to be delimiters too, which meant a
	2180	+ * single feature that happened to contain one — "Collect reviews from
	2181	+ * Trustpilot, Google, and Etsy" — was published as three bullets, one of
	2182	+ * them reading "and Etsy" (#765). Validation counted by newline only, so
	2183	+ * it reported one feature while the file showed three and never flagged
	2184	+ * the split.
	2185	+ *
	2186	+ * Commas are not a fallback delimiter even when the value has no newlines.
	2187	+ * A comma inside a feature is ordinary prose and far more likely than a
	2188	+ * deliberate comma-separated list, and guessing wrong publishes mangled
	2189	+ * text to the file AI crawlers read. A single-line value with commas is
	2190	+ * kept whole and validate_content_quality() suggests splitting it, which
	2191	+ * tells the user what to do instead of quietly deciding for them.
	2192	+ *
	2193	+ * The one splitter both generation and validation use, so the file and the
	2194	+ * feature count can no longer disagree.
	2195	+ *
	2196	+ * @since 2.10.0
	2197	+ *
	2198	+ * @param string $key_features Raw field value.
	2199	+ * @return string[] Trimmed features, empties removed.
	2200	+ */
	2201	+ public static function split_key_features(string $key_features): array {
	2202	+ $features = preg_split('/[\r\n]+/', $key_features);
	2203	+
	2204	+ if (!is_array($features)) {
	2205	+ return [];
	2206	+ }
	2207	+
	2208	+ $features = array_map('trim', $features);
	2209	+
	2210	+ return array_values(array_filter($features, static fn(string $f): bool => '' !== $f));
	2211	+ }
	2212	+
	2213	+ /**
	2214	+ * Whether a value looks like the old comma-separated list.
	2215	+ *
	2216	+ * One line, and a comma in it. That is either a legacy list saved before
	2217	+ * newlines became the delimiter, or a single feature containing a comma —
	2218	+ * indistinguishable from the outside, which is exactly why this prompts
	2219	+ * rather than splits.
	2220	+ *
	2221	+ * @since 2.10.0
	2222	+ *
	2223	+ * @param string $key_features Raw field value.
	2224	+ * @return bool
	2225	+ */
	2226	+ public static function looks_like_comma_list(string $key_features): bool {
	2227	+ $trimmed = trim($key_features);
	2228	+
	2229	+ if ('' === $trimmed || false !== strpbrk($trimmed, "\r\n")) {
	2230	+ return false;
	2231	+ }
	2232	+
	2233	+ return false !== strpos($trimmed, ',');
	2234	+ }
	2235	+
	2236	+ /**
	2237	+ * Turn a single-line comma list into one feature per line.
	2238	+ *
	2239	+ * Returns null when the value is not something to convert: it already has
	2240	+ * line breaks, has no comma, or reads as one feature containing a series.
	2241	+ *
	2242	+ * Only for text that was written under a comma rule: values saved before
	2243	+ * newlines became the only delimiter (see
	2244	+ * {@see self::maybe_migrate_legacy_key_features()}), and AI replies that
	2245	+ * ignored the one-per-line instruction. Typed input never goes through
	2246	+ * this; split_key_features() still keeps a comma inside a feature (#765).
	2247	+ *
	2248	+ * A series is the one shape the old rule demonstrably mangled: "Collect
	2249	+ * reviews from Trustpilot, Google, and Etsy" became three bullets, the
	2250	+ * last reading "and Etsy". So a value is left whole when a segment after
	2251	+ * the first opens with a conjunction (the Oxford form), or when the final
	2252	+ * segment carries one ("..., Google and Etsy", the form the field's own
	2253	+ * placeholder uses). A plain list that happens to end "X and Y" is left
	2254	+ * whole too; validation still suggests splitting it, and one intact bullet
	2255	+ * is the safer wrong answer than a sentence cut into fragments.
	2256	+ *
	2257	+ * A comma between digits ("1,000 templates") is a thousands separator,
	2258	+ * not a delimiter.
	2259	+ *
	2260	+ * @since 2.10.0
	2261	+ *
	2262	+ * @param string $key_features Raw value.
	2263	+ * @return string|null Newline-separated features, or null to leave as is.
	2264	+ */
	2265	+ public static function comma_list_to_lines(string $key_features): ?string {
	2266	+ if (!self::looks_like_comma_list($key_features)) {
	2267	+ return null;
	2268	+ }
	2269	+
	2270	+ $segments = preg_split('/\s*,(?!\d)\s*/', trim($key_features));
	2271	+
	2272	+ if (!is_array($segments)) {
	2273	+ return null;
	2274	+ }
	2275	+
	2276	+ $segments = array_values(array_filter(
	2277	+ array_map('trim', $segments),
	2278	+ static fn(string $s): bool => '' !== $s
	2279	+ ));
	2280	+
	2281	+ if (count($segments) < 2) {
	2282	+ return null;
	2283	+ }
	2284	+
	2285	+ foreach (array_slice($segments, 1) as $segment) {
	2286	+ if (preg_match('/^(?:(?:and|or|nor|plus)\b|&)/i', $segment)) {
	2287	+ return null;
	2288	+ }
	2289	+ }
	2290	+
	2291	+ if (preg_match('/\s(?:and|or|&)\s/i', (string) end($segments))) {
	2292	+ return null;
	2293	+ }
	2294	+
	2295	+ return implode("\n", $segments);
	2296	+ }
	2297	+
	2298	+ /**
	2299	+ * Coerce an AI reply for Key Features into the one-per-line field value.
	2300	+ *
	2301	+ * The prompt asks for one feature per line, but models still answer with a
	2302	+ * JSON array or a comma-separated line. An array went through
	2303	+ * sanitize_textarea_field() as '' and the field silently kept its old
	2304	+ * value; a comma line was published as a single bullet now that commas are
	2305	+ * not delimiters. Both are normalised to lines here, before sanitising.
	2306	+ *
	2307	+ * @since 2.10.0
	2308	+ *
	2309	+ * @param mixed $value Decoded `key_features` from the reply.
	2310	+ * @return string Sanitised, newline-separated features.
	2311	+ */
	2312	+ public static function normalize_ai_key_features($value): string {
	2313	+ if (is_array($value)) {
	2314	+ $features = [];
	2315	+ foreach ($value as $item) {
	2316	+ if (is_scalar($item)) {
	2317	+ $item = trim((string) $item);
	2318	+ if ('' !== $item) {
	2319	+ $features[] = $item;
	2320	+ }
	2321	+ }
	2322	+ }
	2323	+ $value = implode("\n", $features);
	2324	+ } elseif (!is_scalar($value)) {
	2325	+ return '';
	2326	+ }
	2327	+
	2328	+ $value = (string) $value;
	2329	+ $lines = self::comma_list_to_lines($value);
	2330	+
	2331	+ return sanitize_textarea_field(null === $lines ? $value : $lines);
	2332	+ }
	2333	+
	2334	+ /**
	2335	+ * Convert a Key Features value saved under the old comma rule, once.
	2336	+ *
	2337	+ * Up to 2.9.0 a comma separated features, so a site that saved
	2338	+ * "SEO audits, Schema markup, XML sitemaps" published three bullets. After
	2339	+ * #765 made newlines the only delimiter the same stored value regenerates
	2340	+ * as one bullet holding the whole line, a silent change to the file AI
	2341	+ * crawlers read. Rewriting the stored value as lines keeps that site's
	2342	+ * output what it was, in the form the field now documents.
	2343	+ *
	2344	+ * A migration rather than a runtime fallback on purpose: a fallback would
	2345	+ * keep treating commas as delimiters for every single-line value forever,
	2346	+ * which is the #765 bug. Here only values that were saved while commas
	2347	+ * really were delimiters are touched, exactly once; anything typed after
	2348	+ * this has run follows the new rule. comma_list_to_lines() still leaves a
	2349	+ * series such as the #765 value whole.
	2350	+ *
	2351	+ * Version-gated like Settings::retire_seeded_ai_provider(), and the marker
	2352	+ * is written first so a site that fails the write does not retry on every
	2353	+ * admin request. The activator records it on a fresh install.
	2354	+ *
	2355	+ * @since 2.10.0
	2356	+ *
	2357	+ * @return void
	2358	+ */
	2359	+ public static function maybe_migrate_legacy_key_features(): void {
	2360	+ if (get_option(self::KEY_FEATURES_MIGRATION_OPTION) === self::KEY_FEATURES_MIGRATION_VERSION) {
	2361	+ return;
	2362	+ }
	2363	+
	2364	+ update_option(self::KEY_FEATURES_MIGRATION_OPTION, self::KEY_FEATURES_MIGRATION_VERSION, true);
	2365	+
	2366	+ (new static())->migrate_stored_key_features();
	2367	+ }
	2368	+
	2369	+ /**
	2370	+ * Rewrite the stored Key Features as lines when it is a legacy comma list.
	2371	+ *
	2372	+ * @since 2.10.0
	2373	+ *
	2374	+ * @return bool True when a value was converted and saved.
	2375	+ */
	2376	+ public function migrate_stored_key_features(): bool {
	2377	+ $stored = $this->get_stored_settings('site');
	2378	+
	2379	+ if (!isset($stored['key_features']) || !is_string($stored['key_features'])) {
	2380	+ return false;
	2381	+ }
	2382	+
	2383	+ $lines = self::comma_list_to_lines($stored['key_features']);
	2384	+
	2385	+ if (null === $lines) {
	2386	+ return false;
	2387	+ }
	2388	+
	2389	+ // validate_settings() rejects a payload without `enabled`, so carry the
	2390	+ // stored flag along. Written through the base save, not this class's,
	2391	+ // which would also reconcile the delivery mode: a stored-value rewrite
	2392	+ // must not republish anything.
	2393	+ return $this->write_migrated_key_features([
	2394	+ 'enabled' => $stored['enabled'] ?? true,
	2395	+ 'key_features' => $lines,
	2396	+ ]);
	2397	+ }
	2398	+
	2399	+ /**
	2400	+ * Persist the converted value. Separate so tests can observe the write.
	2401	+ *
	2402	+ * @since 2.10.0
	2403	+ *
	2404	+ * @param array $settings `enabled` and `key_features`.
	2405	+ * @return bool
	2406	+ */
	2407	+ protected function write_migrated_key_features(array $settings): bool {
	2408	+ return parent::save_settings('site', null, $settings);
	2409	+ }
	2410	+
	2411	+ /**
2127	2412	* Build additional details section
2128	2413	*
2129	2414	* @since 1.0.0
2130	2415	*
		@@ -2142,18 +2427,10 @@
2142	2427	}
2143	2428
2144	2429	if (!empty($key_features)) {
2145	2430	$content .= "**Key Features:**\n";
2146		- // The UI field is a multi-line textarea and validation counts by
2147		- // newline, so split on newlines (and still tolerate commas) rather
2148		- // than commas only — otherwise newline-separated input collapses
2149		- // into one broken bullet.
2150		- $features = preg_split('/[\r\n,]+/', $key_features);
2151		- foreach ($features as $feature) {
2152		- $feature = trim($feature);
2153		- if (!empty($feature)) {
2154		- $content .= "- " . $feature . "\n";
2155		- }
	2431	+ foreach (self::split_key_features($key_features) as $feature) {
	2432	+ $content .= "- " . $feature . "\n";
2156	2433	}
2157	2434	$content .= "\n";
2158	2435	}
2159	2436
		@@ -2187,9 +2464,9 @@
2187	2464	$content .= "- [Technical Stack]({$website_url}): Built with {$stack}\n";
2188	2465	}
2189	2466
2190	2467	if (!empty($user_input['development_approach'])) {
2191		- $approach_summary = wp_trim_words($user_input['development_approach'], 10);
	2468	+ $approach_summary = \ThinkRank\Core\Seo_Text::trim_words($user_input['development_approach'], 10);
2192	2469	$content .= "- [Development Guidelines]({$website_url}): {$approach_summary}\n";
2193	2470	}
2194	2471
2195	2472	// Add robots.txt reference