thinkrank / includes / seo / class-sitemap-generator.php

class-sitemap-generator.php in ThinkRank AI SEO – AI SEO Plugin for WordPress: Schema, XML Sitemaps, Meta Tags, Search Console & Local SEO 2.9.0, at includes/seo/class-sitemap-generator.php

4,123 lines 158.1 KB

Raw Download Zip

1	<?php
2	/**
3	* Sitemap Generator Class
4	*
5	* XML sitemap generation and management for search engine optimization.
6	* Implements 2025 SEO best practices with real sitemap specifications,
7	* dynamic content inclusion, and performance optimization.
8	*
9	* @package ThinkRank
10	* @subpackage SEO
11	* @since 1.0.0
12	*/
13
14	declare(strict_types=1);
15
16	namespace ThinkRank\SEO;
17
18	use InvalidArgumentException;
19
20	// Prevent direct access.
21	if ( ! defined( 'ABSPATH' ) ) {
22	exit;
23	}
24
25	// Filename derivation and web-root removal are shared with the deactivator and
26	// with uninstall.php, which runs without an autoloader — so they live in a
27	// plain function file both can require. See includes/cleanup-webroot.php.
28	require_once __DIR__ . '/../cleanup-webroot.php';
29
30	/**
31	* Sitemap Generator Class
32	*
33	* Generates and manages XML sitemaps for search engine optimization.
34	* Provides dynamic sitemap generation with content filtering, priority
35	* calculation, and change frequency optimization.
36	*
37	* @since 1.0.0
38	*/
39	class Sitemap_Generator extends Abstract_SEO_Manager {
40
41	/**
42	* Memoised WooCommerce page IDs kept out of the sitemap. Null until resolved.
43	*
44	* @since 2.0.1
45	* @var int[]\|null
46	*/
47	private ?array $woocommerce_excluded_page_ids = null;
48
49	/**
50	* Inclusion flag -> the child sitemap it controls.
51	*
52	* Shared by the child-list builder and by the "did the caller change what
53	* the sitemap includes?" check in maybe_promote_to_index().
54	*
55	* @since 1.31.0
56	* @var array<string, string>
57	*/
58	private const INCLUSION_CHILD_TYPES = [
59	'include_posts' => 'posts',
60	'include_pages' => 'pages',
61	'include_categories' => 'categories',
62	'include_tags' => 'tags',
63	];
64
65	/**
66	* Child sitemap type -> the object that actually supplies its entries.
67	*
68	* A child normally carries its object's own slug, but the sitemap presets UI
69	* writes a display name for the WooCommerce taxonomy child
70	* ('product_categories', not 'product_cat'), so a saved child list can name a
71	* type no post type or taxonomy answers to. Resolving through here lets those
72	* children take the same generic path as every other custom taxonomy instead
73	* of needing a case of their own (#690).
74	*
75	* @since 2.7.0
76	* @var array<string, string>
77	*/
78	private const CHILD_TYPE_ALIASES = [
79	'product_categories' => 'product_cat',
80	];
81
82	/**
83	* Supported sitemap types
84	*
85	* @since 1.0.0
86	* @var array
87	*/
88	/**
89	* How many post IDs to hydrate at a time while walking the sitemap set.
90	*
91	* @since 2.0.1
92	* @var int
93	*/
94	private const ID_WALK_CHUNK = 500;
95
96	/**
97	* How long a content or settings change is debounced before the sitemap is
98	* rebuilt, in seconds. Coalesces bulk edits into a single regeneration.
99	*
100	* @since 2.2.1
101	* @var int
102	*/
103	private const REGENERATION_DEBOUNCE = 30;
104
105	/**
106	* How far past its due time the scheduled rebuild may sit before a request
107	* takes it over, in seconds.
108	*
109	* WP-Cron is request-driven, so on a site running DISABLE_WP_CRON, blocking
110	* loopback requests, or seeing very little traffic the event never fires and
111	* the sitemap silently stops updating (#629). The grace keeps the fast path
112	* (cron) in charge under normal conditions.
113	*
114	* @since 2.2.1
115	* @var int
116	*/
117	private const REGENERATION_TAKEOVER_GRACE = 120;
118
119	/**
120	* Longest backoff between takeover attempts after a failed rebuild, so a
121	* persistently failing generation cannot run on every admin request.
122	*
123	* @since 2.2.1
124	* @var int
125	*/
126	private const REGENERATION_MAX_BACKOFF = 3600;
127
128	/**
129	* Option holding the rebuild that content/settings changes are still waiting
130	* on: `since`, `source` ('content'\|'settings'), `attempts`, `next_attempt`.
131	* Absent means the served sitemap is up to date with what triggered it.
132	*
133	* @since 2.2.1
134	* @var string
135	*/
136	public const REGENERATION_PENDING_OPTION = 'thinkrank_sitemap_regeneration_pending';
137
138	/**
139	* Option holding the last automatic-regeneration failure (`message`,
140	* `source`, `time`), so the failure is visible instead of swallowed.
141	*
142	* @since 2.2.1
143	* @var string
144	*/
145	public const REGENERATION_ERROR_OPTION = 'thinkrank_sitemap_regeneration_error';
146
147	/**
148	* Delivery modes accepted by the `delivery_mode` setting.
149	*
150	* Mirrors LLMs_Txt_Manager::DELIVERY_MODES, which solved the same problem
151	* for llms.txt. `auto` is the only value a site should normally need.
152	*
153	* @since 2.9.0
154	* @var string[]
155	*/
156	public const DELIVERY_MODES = ['auto', 'static', 'dynamic'];
157
158	/**
159	* Cache group for documents rendered on the dynamic path.
160	*
161	* @since 2.9.0
162	* @var string
163	*/
164	private const DYNAMIC_CACHE_PREFIX = 'thinkrank_sitemap_doc_';
165
166	/**
167	* How long a dynamically rendered document is cached.
168	*
169	* Invalidated by content and settings changes through
170	* {@see self::flush_dynamic_cache()}, so this is only the backstop for a
171	* change nothing hooked.
172	*
173	* @since 2.9.0
174	* @var int
175	*/
176	private const DYNAMIC_CACHE_TTL = 12 * HOUR_IN_SECONDS;
177
178	/**
179	* How long the render lock is held before it is assumed abandoned.
180	*
181	* Long enough for a large site's full build, short enough that a request
182	* killed mid-build does not lock the endpoint out for meaningfully long.
183	*
184	* @since 2.9.0
185	* @var int
186	*/
187	private const RENDER_LOCK_TTL = 60;
188
189	/**
190	* Cached stand-in for "this site does not publish that name".
191	*
192	* published_document_names() lists what the configuration could produce,
193	* but a child whose type is excluded produces nothing. Without a negative
194	* entry those names miss the cache forever, so every request for one
195	* rebuilt the entire sitemap — the same cost the positive cache exists to
196	* avoid, on a public endpoint (#754 review).
197	*
198	* @since 2.9.0
199	* @var string
200	*/
201	private const ABSENT_MARKER = "\0thinkrank-absent";
202
203	/**
204	* How many times, and how long, a losing request waits for the winner.
205	*
206	* Bounded at roughly a second in total: past that, building a second copy
207	* costs less than making a crawler wait.
208	*
209	* @since 2.9.0
210	* @var int
211	*/
212	private const RENDER_LOCK_WAIT_ATTEMPTS = 4;
213
214	/**
215	* @since 2.9.0
216	* @var int
217	*/
218	private const RENDER_LOCK_WAIT_MICROSECONDS = 250000;
219
220	/**
221	* Where generated documents go instead of disk, when set.
222	*
223	* Every sitemap document this class produces — segments, the index, the
224	* single flat file and local-sitemap.xml — is published through the one
225	* writer, {@see self::save_sitemap_to_file()}. Swapping that writer for a
226	* collector is therefore all it takes to render the same bytes without a
227	* filesystem, which is what dynamic delivery needs (#752). Doing it here
228	* rather than duplicating the build pipeline is deliberate: a second
229	* pipeline would drift from this one, and the index in particular is
230	* assembled from whatever the children actually produced.
231	*
232	* @since 2.9.0
233	* @var callable\|null
234	*/
235	private $document_sink = null;
236
237	/**
238	* Transient guarding against two generations running at once. Shared with
239	* Sitemap_Endpoint's manual generate route so an automatic rebuild and a
240	* manual one cannot write the same files concurrently.
241	*
242	* @since 2.2.1
243	* @var string
244	*/
245	public const GENERATION_LOCK_TRANSIENT = 'thinkrank_sitemap_generation_lock';
246
247	/**
248	* How many term IDs to hydrate at a time while walking a taxonomy.
249	*
250	* @since 2.0.1
251	* @var int
252	*/
253	private const TERM_WALK_CHUNK = 1000;
254
255	private array $sitemap_types = [
256	'posts' => [
257	'name' => 'Posts',
258	'post_types' => ['post'],
259	'priority' => 0.8,
260	'changefreq' => 'weekly'
261	],
262	'pages' => [
263	'name' => 'Pages',
264	'post_types' => ['page'],
265	'priority' => 0.9,
266	'changefreq' => 'monthly'
267	],
268	'categories' => [
269	'name' => 'Categories',
270	'taxonomy' => 'category',
271	'priority' => 0.6,
272	'changefreq' => 'weekly'
273	],
274	'tags' => [
275	'name' => 'Tags',
276	'taxonomy' => 'post_tag',
277	'priority' => 0.4,
278	'changefreq' => 'monthly'
279	]
280	];
281
282	/**
283	* Constructor
284	*
285	* @since 1.0.0
286	*
287	* @param bool $register_hooks Optional. Whether to register the auto-generation
288	* hooks. Pass false for a read-only instance built
289	* solely to query settings — the hooks are bound to
290	* `$this`, so a second hook-registering instance
291	* would run `handle_content_change()` twice per save.
292	*/
293	public function __construct(bool $register_hooks = true) {
294	parent::__construct('sitemap');
295
296	// Initialize auto-generation hooks
297	if ($register_hooks) {
298	$this->init_auto_generation_hooks();
299	}
300	}
301
302	/**
303	* Filter the args of a sitemap post query.
304	*
305	* Exists so integrations can widen what the sitemap sees — the multilingual
306	* manager uses it to include every language, since these queries otherwise
307	* run in whichever language happened to be active at generation time.
308	*
309	* @since 1.23.0
310	*
311	* @param array $args get_posts() arguments.
312	* @return array Filtered arguments.
313	*/
314	private function filter_query_args(array $args): array {
315	/**
316	* Filter the arguments of a sitemap post query.
317	*
318	* @since 1.23.0
319	*
320	* @param array $args get_posts() arguments.
321	*/
322	return (array) apply_filters('thinkrank_sitemap_query_args', $args);
323	}
324
325	/**
326	* Filter the args of a sitemap term query.
327	*
328	* @since 1.23.0
329	*
330	* @param array $args get_terms() arguments.
331	* @return array Filtered arguments.
332	*/
333	private function filter_term_query_args(array $args): array {
334	/**
335	* Filter the arguments of a sitemap term query.
336	*
337	* @since 1.23.0
338	*
339	* @param array $args get_terms() arguments.
340	*/
341	return (array) apply_filters('thinkrank_sitemap_term_query_args', $args);
342	}
343
344	/**
345	* Initialize WordPress hooks for auto-generation
346	*
347	* @since 1.0.0
348	* @return void
349	*/
350	private function init_auto_generation_hooks(): void {
351	// Content change hooks - use priority 20 to run after other plugins
352	add_action('save_post', [$this, 'handle_content_change'], 20, 2);
353	add_action('delete_post', [$this, 'handle_content_deletion'], 20);
354	add_action('wp_trash_post', [$this, 'handle_content_deletion'], 20);
355	add_action('untrash_post', [$this, 'handle_content_change_by_id'], 20);
356
357	// Taxonomy change hooks
358	add_action('created_term', [$this, 'handle_taxonomy_change'], 20, 3);
359	add_action('edited_term', [$this, 'handle_taxonomy_change'], 20, 3);
360	add_action('delete_term', [$this, 'handle_taxonomy_change'], 20, 3);
361
362	// NOTE: the WP-Cron regeneration listeners (thinkrank_regenerate_sitemap
363	// and thinkrank_regenerate_sitemap_settings) are registered at plugin
364	// bootstrap (Plugin::register_sitemap_cron_listeners(), on plugins_loaded)
365	// rather than here. A cron run never builds this class via the REST
366	// endpoint (no rest_api_init), so registering them in the constructor
367	// would leave the scheduled events with no listener at cron time.
368	}
369
370	/**
371	* Generate XML sitemap
372	*
373	* @since 1.0.0
374	*
375	* @param array $options Sitemap generation options
376	* @return string XML sitemap content
377	*/
378	public function generate_sitemap(array $options = []): string {
379	$settings = $this->get_settings('site');
380
381	$xml = $this->xml_prolog($settings, 'sitemap');
382
383	// Add image namespace if images are enabled
384	if (!empty($settings['include_images'])) {
385	$xml .= '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">' . "\n";
386	} else {
387	$xml .= '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' . "\n";
388	}
389
390	// Add homepage. Use the static front page's real modified time when set,
391	// so lastmod reflects real changes rather than the generation time.
392	$xml .= $this->generate_url_entry(home_url('/'), $this->get_homepage_lastmod(), 1.0, 'daily');
393
394	// MEMORY-EFFICIENT: Generate posts using chunked processing.
395	// Note: the single "general" sitemap includes every URL (no per-file cap);
396	// per-file chunking applies to the segmented/index model where each type
397	// gets its own paginated file (see generate_multiple_sitemaps).
398	$enabled_post_types = $this->get_enabled_post_types($settings);
399	if (!empty($enabled_post_types)) {
400	$xml .= implode('', $this->collect_post_entries($enabled_post_types, $settings));
401	}
402
403	// OPTIMIZED: Get all enabled taxonomies and fetch in single query
404	$enabled_taxonomies = $this->get_enabled_taxonomies($settings);
405	if (!empty($enabled_taxonomies)) {
406	$all_taxonomy_data = $this->fetch_taxonomies_optimized($enabled_taxonomies, $settings);
407
408	// Process each taxonomy's data
409	foreach ($enabled_taxonomies as $taxonomy) {
410	if (!empty($all_taxonomy_data[$taxonomy])) {
411	$xml .= $this->process_taxonomies_to_xml($all_taxonomy_data[$taxonomy], $taxonomy, $settings);
412	}
413	}
414	}
415
416	$xml .= '</urlset>';
417
418	return $xml;
419	}
420
421	/**
422	* Validate SEO settings (implements interface)
423	*
424	* @since 1.0.0
425	*
426	* @param array $settings Settings array to validate
427	* @return array Validation results
428	*/
429	public function validate_settings(array $settings): array {
430	$validation = [
431	'valid' => true,
432	'errors' => [],
433	'warnings' => [],
434	'suggestions' => []
435	];
436
437	try {
438	// Validate exclude_posts
439	if (!empty($settings['exclude_posts'])) {
440	$this->validate_exclude_posts($settings['exclude_posts']);
441	}
442
443	// Validate exclude_terms
444	if (!empty($settings['exclude_terms'])) {
445	$this->validate_exclude_terms($settings['exclude_terms']);
446	}
447
448	// Validate custom_url_pattern
449	if (!empty($settings['custom_url_pattern'])) {
450	$this->validate_custom_url_pattern($settings['custom_url_pattern']);
451	}
452
453	// Validate sitemap_urls
454	if (!empty($settings['sitemap_urls']) && is_array($settings['sitemap_urls'])) {
455	foreach ($settings['sitemap_urls'] as $sitemap) {
456	if (!empty($sitemap['url'])) {
457	$this->validate_sitemap_url($sitemap['url']);
458	}
459	}
460	}
461
462	// Validate numeric settings
463	if (isset($settings['links_per_sitemap'])) {
464	$this->validate_links_per_sitemap($settings['links_per_sitemap']);
465	}
466
467	} catch (InvalidArgumentException $e) {
468	$validation['valid'] = false;
469	$validation['errors'][] = $e->getMessage();
470	}
471
472	return $validation;
473	}
474
475	/**
476	* Get output data for frontend rendering (implements interface)
477	*
478	* @since 1.0.0
479	*
480	* @param string $context_type The context type
481	* @param int\|null $context_id Optional. Context ID
482	* @return array Output data ready for frontend rendering
483	*/
484	public function get_output_data(string $context_type, ?int $context_id): array {
485	$settings = $this->get_settings($context_type, $context_id);
486
487	return [
488	'sitemap_url' => home_url('/sitemap.xml'),
489	'enabled' => $settings['enabled'] ?? true,
490	'last_generated' => $settings['last_generated'] ?? '',
491	'total_urls' => $this->count_sitemap_urls($settings)
492	];
493	}
494
495	/**
496	* Sitemap keys outside the defaults.
497	*
498	* @since 2.0.1
499	*
500	* @return string[]
501	*/
502	protected function additional_setting_keys(): array {
503	return ['selected_preset'];
504	}
505
506	/**
507	* Inclusion flags are per post type and per taxonomy.
508	*
509	* A site registering a `product` post type stores `include_product`; an
510	* enumerated list would go stale on the next registration, so the family
511	* is matched instead.
512	*
513	* @since 2.0.1
514	*
515	* @return string[]
516	*/
517	protected function dynamic_setting_key_patterns(): array {
518	return ['/^include_[a-z0-9_]+$/', '/^exclude_[a-z0-9_]+$/'];
519	}
520
521	/**
522	* Get default settings for a context type (implements interface)
523	*
524	* @since 1.0.0
525	*
526	* @param string $context_type The context type to get defaults for
527	* @return array Default settings array
528	*/
529	public function get_default_settings(string $context_type): array {
530	return [
531	// Core settings
532	'enabled' => true,
533
534	// Multiple Sitemap URLs
535	'sitemap_urls' => [
536	[
537	'url' => '/sitemap.xml',
538	'type' => 'general',
539	'enabled' => true,
540	'last_checked' => null,
541	'status' => 'unknown'
542	]
543	],
544	'use_sitemap_index' => false,
545
546	// How the sitemap reaches crawlers. 'auto' keeps the historical
547	// behaviour wherever the web root is writable, and only falls back
548	// to serving the sitemap from PHP where writing a file is
549	// impossible — previously a hard failure with nothing served
550	// (#752).
551	'delivery_mode' => 'auto',
552
553	// General Settings
554	'links_per_sitemap' => 1000,
555	'include_images' => true,
556	'include_featured_images' => false,
557	'auto_generate' => true,
558	'ping_search_engines' => true,
559
560	// Content Inclusion (backward compatibility)
561	'include_posts' => true,
562	'include_pages' => true,
563	'include_categories' => true,
564	'include_tags' => false,
565
566	// Content Filtering
567	'exclude_posts' => '',
568	'exclude_terms' => '',
569	'exclude_password_protected' => true,
570	'exclude_private_posts' => true,
571
572	// Advanced Options
573	'enable_styling' => true,
574	'custom_url_pattern' => 'sitemap-{type}.xml',
575
576	// Stylesheet branding (#639). Both colours default to empty, not
577	// to the stock hexes: empty means the stylesheet's own value
578	// stands, so a site that never opens this screen renders exactly
579	// as it did before the setting existed.
580	'styling_logo' => false,
581	'styling_logo_url' => '',
582	'styling_color_main' => '',
583	'styling_color_accent' => '',
584
585	// Generation tracking
586	'last_generated' => ''
587	];
588	}
589
590	/**
591	* Normalize the stylesheet branding values on the way into the store.
592	*
593	* The generic sanitizer only runs `sanitize_text_field()` over a string,
594	* which happily keeps "red" or "rebeccapurple" as a colour. Nothing
595	* downstream can use those — {@see Sitemap_Stylesheet::render()} skips any
596	* value it cannot read as a hex colour — so storing them would report a
597	* successful save of a setting that changes nothing, and `get-sitemap-
598	* settings` would hand an agent back a colour the sitemap does not use.
599	* Reducing here instead keeps the store and the rendering in agreement.
600	*
601	* @since 2.7.0
602	*
603	* @param array $settings Settings to sanitize.
604	* @param string $context_type Context the save is for.
605	* @return array
606	*/
607	protected function sanitize_settings(array $settings, string $context_type = 'site'): array {
608	$sanitized = parent::sanitize_settings($settings, $context_type);
609
610	foreach (['styling_color_main', 'styling_color_accent'] as $key) {
611	if (array_key_exists($key, $sanitized)) {
612	$sanitized[$key] = Sitemap_Stylesheet::hex($sanitized[$key]);
613	}
614	}
615
616	if (array_key_exists('styling_logo_url', $sanitized)) {
617	$sanitized['styling_logo_url'] = esc_url_raw((string) $sanitized['styling_logo_url']);
618	}
619
620	// A mode this build cannot act on has to be stored as the fallback
621	// rather than kept verbatim, or get-sitemap-settings reports a delivery
622	// mode the site does not actually apply.
623	if (array_key_exists('delivery_mode', $sanitized)) {
624	$mode = sanitize_key((string) $sanitized['delivery_mode']);
625	$sanitized['delivery_mode'] = in_array($mode, self::DELIVERY_MODES, true) ? $mode : 'auto';
626	}
627
628	return $sanitized;
629	}
630
631	/**
632	* Get settings schema definition (implements interface)
633	*
634	* @since 1.0.0
635	*
636	* @param string $context_type The context type to get schema for
637	* @return array Settings schema definition
638	*/
639	public function get_settings_schema(string $context_type): array {
640	return [
641	'enabled' => [
642	'type' => 'boolean',
643	'title' => 'Enable Sitemap',
644	'description' => 'Generate XML sitemap for search engines',
645	'default' => true
646	],
647	'delivery_mode' => [
648	'type' => 'string',
649	'title' => 'Sitemap Delivery',
650	'description' => 'How the sitemap is served: auto picks static when the WordPress root is writable and dynamic when it is not, static writes files to the web root, dynamic serves the sitemap from WordPress with no files written',
651	'enum' => self::DELIVERY_MODES,
652	'default' => 'auto'
653	],
654	'include_posts' => [
655	'type' => 'boolean',
656	'title' => 'Include Posts',
657	'description' => 'Include blog posts in sitemap',
658	'default' => true
659	],
660	'include_pages' => [
661	'type' => 'boolean',
662	'title' => 'Include Pages',
663	'description' => 'Include static pages in sitemap',
664	'default' => true
665	],
666	'include_categories' => [
667	'type' => 'boolean',
668	'title' => 'Include Categories',
669	'description' => 'Include category pages in sitemap',
670	'default' => true
671	],
672	'include_tags' => [
673	'type' => 'boolean',
674	'title' => 'Include Tags',
675	'description' => 'Include tag pages in sitemap',
676	'default' => false
677	],
678
679	'auto_generate' => [
680	'type' => 'boolean',
681	'title' => 'Auto Generate',
682	'description' => 'Automatically regenerate sitemap when content changes',
683	'default' => true
684	],
685	'ping_search_engines' => [
686	'type' => 'boolean',
687	'title' => 'Ping Search Engines',
688	'description' => 'Notify Google and Bing when sitemap is updated',
689	'default' => true
690	],
691	'last_generated' => [
692	'type' => 'string',
693	'title' => 'Last Generated',
694	'description' => 'Timestamp of last sitemap generation',
695	'default' => ''
696	],
697	'styling_logo' => [
698	'type' => 'boolean',
699	'title' => 'Show Logo On Sitemap',
700	'description' => 'Show a logo above the sitemap heading',
701	'default' => false
702	],
703	'styling_logo_url' => [
704	'type' => 'string',
705	'title' => 'Sitemap Logo',
706	'description' => 'Logo image URL. Empty falls back to the site icon',
707	'default' => ''
708	],
709	'styling_color_main' => [
710	'type' => 'string',
711	'title' => 'Sitemap Main Color',
712	'description' => 'Hex color for the sitemap header, links and table head. Empty keeps the stock palette',
713	'default' => ''
714	],
715	'styling_color_accent' => [
716	'type' => 'string',
717	'title' => 'Sitemap Accent Color',
718	'description' => 'Hex color for the header gradient and link hovers. Empty keeps the stock palette',
719	'default' => ''
720	]
721	];
722	}
723
724	/**
725	* Generate URL entry for sitemap
726	*
727	* @since 1.0.0
728	*
729	* @param string $url URL
730	* @param string $lastmod Last modification date
731	* @param float $priority Priority (0.0 to 1.0)
732	* @param string $changefreq Change frequency
733	* @param array $images Optional array of image data
734	* @return string XML URL entry
735	*/
736	private function generate_url_entry(string $url, string $lastmod, float $priority, string $changefreq, array $images = []): string {
737	$xml = " <url>\n";
738	// Every <loc> in every sitemap passes through here, which is why the
739	// scheme preference is applied at this one point rather than at each
740	// of the dozen collectors that build URLs (#638). An http sitemap on
741	// an https site hands search engines the wrong address for the whole
742	// site at once.
743	$xml .= " <loc>" . esc_url(Url_Scheme::apply($url)) . "</loc>\n";
744	// Omit <lastmod> when unknown (empty) — a fabricated timestamp is worse
745	// than no timestamp, and an absent lastmod is valid per the spec.
746	if (!empty($lastmod)) {
747	$xml .= " <lastmod>" . esc_html($lastmod) . "</lastmod>\n";
748	}
749	$xml .= " <priority>" . number_format($priority, 1) . "</priority>\n";
750	$xml .= " <changefreq>" . esc_html($changefreq) . "</changefreq>\n";
751
752	// Add image entries if provided
753	foreach ($images as $image) {
754	$xml .= " <image:image>\n";
755	$xml .= " <image:loc>" . esc_url(Url_Scheme::apply((string) $image['url'])) . "</image:loc>\n";
756
757	if (!empty($image['title'])) {
758	$xml .= " <image:title>" . esc_html($image['title']) . "</image:title>\n";
759	}
760
761	if (!empty($image['alt'])) {
762	$xml .= " <image:caption>" . esc_html($image['alt']) . "</image:caption>\n";
763	}
764
765	$xml .= " </image:image>\n";
766	}
767
768	$xml .= " </url>\n";
769
770	return $xml;
771	}
772
773	/**
774	* Collect every post <url> entry for the given post type(s) as an array of
775	* XML strings, using memory-efficient chunked fetching.
776	*
777	* Unlike the old capped generator, this returns ALL matching entries — the
778	* links-per-sitemap limit is applied later by paginating this array into
779	* separate files (see generate_multiple_sitemaps), matching how Rank Math
780	* splits large sitemaps instead of truncating them.
781	*
782	* @since 1.14.0
783	*
784	* @param array $post_types Array of post types to fetch
785	* @param array $settings Sitemap settings
786	* @return array<string> Individual <url>…</url> entry strings
787	*/
788	/**
789	* lastmod for the homepage <url> entry: the static front page's real
790	* modification time when one is set, otherwise the generation time.
791	*
792	* @return string ISO-8601 date.
793	*/
794	private function get_homepage_lastmod(): string {
795	if (get_option('show_on_front') === 'page') {
796	$front_id = (int) get_option('page_on_front');
797	if ($front_id) {
798	$modified = get_post_field('post_modified_gmt', $front_id);
799	if (!empty($modified) && $modified !== '0000-00-00 00:00:00') {
800	return gmdate('c', strtotime($modified));
801	}
802	}
803	}
804	return gmdate('c');
805	}
806
807	private function collect_post_entries(array $post_types, array $settings): array {
808	// Materialize the streaming source for callers that need the full set
809	// (e.g. the single un-paginated "general" sitemap). The paginated index
810	// path streams collect_post_entries_iter() directly to bound memory.
811	return iterator_to_array($this->collect_post_entries_iter($post_types, $settings), false);
812	}
813
814	/**
815	* Stream <url> entries for the given post types, yielding one at a time.
816	*
817	* Same chunked query, filtering, and ordering as before, but yields each
818	* entry instead of accumulating the whole set — so the paginated index
819	* generator never holds every URL of a large post type in memory at once.
820	*
821	* @param array $post_types Post types to include.
822	* @param array $settings Sitemap settings.
823	* @return \Generator<string> <url> entry strings.
824	*/
825	private function collect_post_entries_iter(array $post_types, array $settings): \Generator {
826	if (empty($post_types)) {
827	return;
828	}
829
830	// Parse and validate exclude_posts setting
831	$exclude_ids = [];
832	if (!empty($settings['exclude_posts'])) {
833	try {
834	$exclude_ids = $this->validate_exclude_posts($settings['exclude_posts']);
835	} catch (InvalidArgumentException $e) {
836	// Continue with empty array on validation failure - error details available in exception
837	}
838	}
839
840	// The static front page is emitted once as the explicit homepage entry,
841	// so exclude it here to avoid a duplicate <loc> (its permalink equals
842	// home_url('/')).
843	if (get_option('show_on_front') === 'page') {
844	$front_id = (int) get_option('page_on_front');
845	if ($front_id) {
846	$exclude_ids[] = $front_id;
847	}
848	}
849
850	// Resolve the ordered ID list in one indexed query, then hydrate in
851	// chunks via post__in. This avoids large OFFSET windows (which MySQL
852	// must scan-and-discard, making a full walk O(n^2)) while still loading
853	// only one chunk of full post objects into memory at a time. The
854	// original order is preserved (the id query and post__in hydration both
855	// use it).
856	$all_ids = get_posts($this->filter_query_args([
857	'post_type' => $post_types,
858	'post_status' => 'publish',
859	'numberposts' => -1,
860	'exclude' => $exclude_ids,
861	'orderby' => 'post_type post_date',
862	'order' => 'ASC DESC',
863	'fields' => 'ids',
864	]));
865
866	if (empty($all_ids)) {
867	return;
868	}
869
870	// Walk the ID list with a moving window rather than array_chunk().
871	// array_chunk() builds a second array holding every element again, so
872	// peak memory was twice the ID list — on a 100k-post site that is ~16MB
873	// where ~8MB is needed, and this walk is the one part of an otherwise
874	// well-bounded routine with no ceiling (#402).
875	$total = count($all_ids);
876
877	for ($offset = 0; $offset < $total; $offset += self::ID_WALK_CHUNK) {
878	$chunk = array_slice($all_ids, $offset, self::ID_WALK_CHUNK);
879
880	$posts = get_posts($this->filter_query_args([
881	'post_type' => $post_types,
882	'post_status' => 'publish',
883	'numberposts' => count($chunk),
884	'post__in' => $chunk,
885	'orderby' => 'post__in', // preserve the resolved order
886	]));
887
888	foreach ($posts as $post) {
889	if ($this->should_include_in_sitemap($post, $settings)) {
890	/**
891	* Filter a sitemap entry's permalink.
892	*
893	* The multilingual manager uses this to generate each
894	* translation's URL in its OWN language: the sitemap query
895	* deliberately runs with suppress_filters, and the cron
896	* rebuild runs with no language context at all, so a bare
897	* get_permalink() resolved every translation to the
898	* default-language URL — N entries sharing one <loc> (#409).
899	*
900	* @since 2.0.1
901	* @param string $url Permalink as WordPress resolved it.
902	* @param \WP_Post $post Post the entry describes.
903	*/
904	$url = apply_filters('thinkrank_sitemap_post_permalink', get_permalink($post), $post);
905	$lastmod = gmdate('c', strtotime($post->post_modified_gmt));
906	$priority = $this->calculate_intelligent_priority($post, $post->post_type);
907	$changefreq = $this->calculate_change_frequency($post, $post->post_type);
908	$images = $this->extract_post_images($post, $settings);
909
910	yield $this->generate_url_entry($url, $lastmod, $priority, $changefreq, $images);
911	}
912	}
913
914	// Free the hydrated chunk before loading the next one.
915	unset($posts);
916	}
917	}
918
919	/**
920	* Resolve and bound the configured links-per-sitemap limit.
921	*
922	* @since 1.14.0
923	*
924	* @param array $settings Sitemap settings
925	* @return int Links per sitemap file (1–50000)
926	*/
927	private function get_links_per_sitemap(array $settings): int {
928	$limit = !empty($settings['links_per_sitemap']) ? intval($settings['links_per_sitemap']) : 1000;
929
930	return max(1, min(50000, $limit));
931	}
932
933	/**
934	* Stream <url> entries for a taxonomy's terms, yielding one at a time and
935	* fetching terms in bounded chunks (number/offset) — so the paginated index
936	* generator never holds every term of a large taxonomy in memory at once.
937	*
938	* @param string $taxonomy Taxonomy name.
939	* @param array $settings Sitemap settings.
940	* @return \Generator<string> <url> entry strings.
941	*/
942	private function collect_taxonomy_entries_iter(string $taxonomy, array $settings): \Generator {
943	$exclude_term_ids = [];
944	if (!empty($settings['exclude_terms'])) {
945	try {
946	$exclude_term_ids = $this->validate_exclude_terms($settings['exclude_terms']);
947	} catch (InvalidArgumentException $e) {
948	// Continue with an empty exclude list on validation failure.
949	}
950	}
951
952	// product_cat may legitimately have empty terms (products added later);
953	// every other taxonomy hides empties — matching fetch_taxonomies_optimized().
954	$hide_empty = $taxonomy !== 'product_cat';
955	$priority = $taxonomy === 'category' ? 0.6 : 0.4;
956
957	// Resolve the ordered term IDs in one query, then hydrate in chunks via
958	// include. Avoids large OFFSET windows (O(n^2) over a full walk) while
959	// holding only one chunk of full term objects at a time.
960	$all_ids = get_terms($this->filter_term_query_args([
961	'taxonomy' => $taxonomy,
962	'hide_empty' => $hide_empty,
963	'exclude' => $exclude_term_ids,
964	'orderby' => 'count',
965	'order' => 'DESC',
966	'fields' => 'ids',
967	]));
968
969	if (is_wp_error($all_ids) \|\| empty($all_ids)) {
970	return;
971	}
972
973	// Same moving window as the post walk above, for the same reason.
974	$total = count($all_ids);
975
976	for ($offset = 0; $offset < $total; $offset += self::TERM_WALK_CHUNK) {
977	$chunk = array_slice($all_ids, $offset, self::TERM_WALK_CHUNK);
978
979	$terms = get_terms($this->filter_term_query_args([
980	'taxonomy' => $taxonomy,
981	'include' => $chunk,
982	'orderby' => 'include', // preserve the resolved order
983	'hide_empty' => false, // already filtered by the id query
984	]));
985
986	if (is_wp_error($terms) \|\| empty($terms)) {
987	continue;
988	}
989
990	foreach ($terms as $term) {
991	// A term the user marked noindex must not be advertised in the
992	// sitemap: the robots tag now honours term meta, so listing it
993	// here would have the sitemap contradict the page's own tag.
994	if ($this->term_is_noindexed((int) $term->term_id)) {
995	continue;
996	}
997
998	$url = get_term_link($term);
999	if (!is_wp_error($url)) {
1000	// Omit lastmod for terms — the generation time is not a real
1001	// modification time and would mislabel every term as just-changed.
1002	yield $this->generate_url_entry($url, '', $priority, 'weekly');
1003	}
1004	}
1005
1006	unset($terms);
1007	}
1008	}
1009
1010	/**
1011	* The XML declaration, ownership marker and optional stylesheet every
1012	* sitemap document opens with.
1013	*
1014	* The marker is written unconditionally, and that is the point: removal on
1015	* deactivate and uninstall deletes a web-root sitemap only when the file
1016	* says it is ours, and our filenames are the canonical ones another SEO
1017	* plugin writes too (#515). Tying the proof to `enable_styling` — the one
1018	* marker older versions left — would mean a site with styling off either
1019	* kept a shadowing file behind (#510) or had a competitor's deleted.
1020	*
1021	* @since 2.1.1
1022	*
1023	* The stylesheet URL is served by {@see Sitemap_Stylesheet}, not read off
1024	* disk by the web server, because a static file cannot carry the site's own
1025	* logo and colours (#639). It is a fixed URL: the palette is applied per
1026	* request, so changing a brand colour needs no regeneration and shows up on
1027	* sitemaps published long before.
1028	*
1029	* @param array $settings Sitemap settings (read for `enable_styling`).
1030	* @param string $variant Stylesheet variant, `sitemap` or `index`.
1031	* @return string Prolog lines, newline-terminated.
1032	*/
1033	private function xml_prolog(array $settings, string $variant): string {
1034	$xml = '<?xml version="1.0" encoding="UTF-8"?>' . "\n";
1035	$xml .= THINKRANK_SITEMAP_MARKER . "\n";
1036
1037	// The stylesheet is presentation only, so it stays opt-in.
1038	if (!empty($settings['enable_styling'])) {
1039	$xml .= '<?xml-stylesheet type="text/xsl" href="' . esc_url(Sitemap_Stylesheet::url($variant)) . '"?>' . "\n";
1040	}
1041
1042	return $xml;
1043	}
1044
1045	/**
1046	* Wrap a set of <url> entry strings in a complete <urlset> document.
1047	*
1048	* @since 1.14.0
1049	*
1050	* @param array<string> $entries Entry strings
1051	* @param array $settings Sitemap settings
1052	* @param bool $with_image_ns Include the image sitemap namespace
1053	* @return string Full sitemap XML
1054	*/
1055	private function wrap_urlset(array $entries, array $settings, bool $with_image_ns): string {
1056	$xml = $this->xml_prolog($settings, 'sitemap');
1057
1058	if ($with_image_ns && !empty($settings['include_images'])) {
1059	$xml .= '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">' . "\n";
1060	} else {
1061	$xml .= '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' . "\n";
1062	}
1063
1064	$xml .= implode('', $entries);
1065	$xml .= '</urlset>';
1066
1067	return $xml;
1068	}
1069
1070	/**
1071	* Derive the filename/URL for a given pagination page.
1072	*
1073	* Page 1 keeps the base URL (e.g. /sitemap-posts.xml); pages 2+ insert the
1074	* page number before the extension (e.g. /sitemap-posts-2.xml).
1075	*
1076	* @since 1.14.0
1077	*
1078	* @param string $url Base sitemap URL
1079	* @param int $page 1-based page number
1080	* @return string Paginated URL
1081	*/
1082	private function paginate_url(string $url, int $page): string {
1083	if ($page <= 1) {
1084	return $url;
1085	}
1086
1087	return (string) preg_replace('/\.xml$/i', '-' . $page . '.xml', $url);
1088	}
1089
1090
1091
1092	/**
1093	* Extract images from post for sitemap
1094	*
1095	* @since 1.0.0
1096	*
1097	* @param \WP_Post $post Post object
1098	* @param array $settings Sitemap settings
1099	* @return array Array of image data
1100	*/
1101	private function extract_post_images(\WP_Post $post, array $settings): array {
1102	$images = [];
1103
1104	// Skip if images are disabled
1105	if (empty($settings['include_images'])) {
1106	return $images;
1107	}
1108
1109	// Get featured image if enabled
1110	if (!empty($settings['include_featured_images'])) {
1111	$featured_image = $this->get_featured_image($post->ID);
1112	if ($featured_image) {
1113	$images[] = $featured_image;
1114	}
1115	}
1116
1117	// Extract images from content
1118	$content_images = $this->extract_content_images($post->post_content);
1119	$images = array_merge($images, $content_images);
1120
1121	// Remove duplicates based on URL
1122	$unique_images = [];
1123	$seen_urls = [];
1124	foreach ($images as $image) {
1125	if (!in_array($image['url'], $seen_urls, true)) {
1126	$unique_images[] = $image;
1127	$seen_urls[] = $image['url'];
1128	}
1129	}
1130
1131	return $unique_images;
1132	}
1133
1134	/**
1135	* Get featured image data
1136	*
1137	* @since 1.0.0
1138	*
1139	* @param int $post_id Post ID
1140	* @return array\|null Featured image data or null
1141	*/
1142	private function get_featured_image(int $post_id): ?array {
1143	$thumbnail_id = get_post_thumbnail_id($post_id);
1144	if (!$thumbnail_id) {
1145	return null;
1146	}
1147
1148	$image_url = wp_get_attachment_image_url($thumbnail_id, 'full');
1149	if (!$image_url) {
1150	return null;
1151	}
1152
1153	$image_title = get_the_title($thumbnail_id);
1154	$image_alt = get_post_meta($thumbnail_id, '_wp_attachment_image_alt', true);
1155
1156	return [
1157	'url' => $image_url,
1158	'title' => $image_title ?: '',
1159	'alt' => $image_alt ?: ''
1160	];
1161	}
1162
1163	/**
1164	* Extract images from post content
1165	*
1166	* @since 1.0.0
1167	*
1168	* @param string $content Post content
1169	* @return array Array of image data
1170	*/
1171	private function extract_content_images(string $content): array {
1172	$images = [];
1173
1174	// Find all img tags in content
1175	preg_match_all('/<img[^>]+>/i', $content, $img_tags);
1176
1177	foreach ($img_tags[0] as $img_tag) {
1178	// Extract src attribute
1179	if (preg_match('/src=["\']([^"\']+)["\']/', $img_tag, $src_match)) {
1180	$image_url = $src_match[1];
1181
1182	// Skip if not a valid URL or external image
1183	if (!filter_var($image_url, FILTER_VALIDATE_URL)) {
1184	continue;
1185	}
1186
1187	// Extract title and alt attributes
1188	$title = '';
1189	$alt = '';
1190
1191	if (preg_match('/title=["\']([^"\']*)["\']/', $img_tag, $title_match)) {
1192	$title = $title_match[1];
1193	}
1194
1195	if (preg_match('/alt=["\']([^"\']*)["\']/', $img_tag, $alt_match)) {
1196	$alt = $alt_match[1];
1197	}
1198
1199	$images[] = [
1200	'url' => $image_url,
1201	'title' => $title,
1202	'alt' => $alt
1203	];
1204	}
1205	}
1206
1207	return $images;
1208	}
1209
1210	/**
1211	* Get enabled taxonomies based on settings
1212	*
1213	* @since 1.0.0
1214	* @param array $settings Sitemap settings
1215	* @return array Array of enabled taxonomies
1216	*/
1217	private function get_enabled_taxonomies(array $settings): array {
1218	$taxonomies = [];
1219
1220	// Core taxonomies based on settings
1221	if (!empty($settings['include_categories'])) { // �
1222	Evidence-based field name
1223	$taxonomies[] = 'category';
1224	}
1225
1226	if (!empty($settings['include_tags'])) { // �
1227	Evidence-based field name
1228	$taxonomies[] = 'post_tag';
1229	}
1230
1231	// Auto-detect public custom taxonomies
1232	$custom_taxonomies = get_taxonomies([
1233	'public' => true,
1234	'_builtin' => false
1235	], 'names');
1236
1237	foreach ($custom_taxonomies as $taxonomy) {
1238	if (!$this->should_include_taxonomy($taxonomy)) {
1239	continue;
1240	}
1241
1242	// Same as the post-type walk above: an explicit per-taxonomy flag
1243	// now decides, and an unset flag keeps the previous "included"
1244	// behaviour (#660).
1245	if (\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('taxonomy', $taxonomy, $settings)) {
1246	$taxonomies[] = $taxonomy;
1247	}
1248	}
1249
1250	return array_unique($taxonomies);
1251	}
1252
1253
1254
1255	/**
1256	* Fetch taxonomies using optimized combined query
1257	*
1258	* @since 1.0.0
1259	*
1260	* @param array $taxonomies Array of taxonomy names to fetch
1261	* @param array $settings Sitemap settings
1262	* @return array Grouped terms by taxonomy
1263	*/
1264	private function fetch_taxonomies_optimized(array $taxonomies, array $settings): array {
1265	if (empty($taxonomies)) {
1266	return [];
1267	}
1268
1269	// Parse and validate exclude_terms setting
1270	$exclude_term_ids = [];
1271	if (!empty($settings['exclude_terms'])) {
1272	try {
1273	$exclude_term_ids = $this->validate_exclude_terms($settings['exclude_terms']);
1274	} catch (InvalidArgumentException $e) {
1275	// Continue with empty array on validation failure - error details available in exception
1276	}
1277	}
1278
1279	// Determine hide_empty setting based on taxonomies
1280	$hide_empty = true;
1281	foreach ($taxonomies as $taxonomy) {
1282	// For product categories, don't hide empty categories since they might not have products yet
1283	if ($taxonomy === 'product_cat') {
1284	$hide_empty = false;
1285	break;
1286	}
1287	}
1288
1289	// OPTIMIZED: Single query for multiple taxonomies
1290	$all_terms = get_terms($this->filter_term_query_args([
1291	'taxonomy' => $taxonomies, // �
1292	Multiple taxonomies in single query
1293	'hide_empty' => $hide_empty,
1294	'exclude' => $exclude_term_ids,
1295	'orderby' => 'taxonomy count',
1296	'order' => 'ASC DESC' // Order by taxonomy ASC, then count DESC
1297	]));
1298
1299	if (is_wp_error($all_terms)) {
1300	return [];
1301	}
1302
1303	// Drop terms the user marked noindex. This path feeds the single general
1304	// sitemap while collect_taxonomy_entries_iter() feeds the segmented ones,
1305	// so both need the filter or the two disagree about the same term.
1306	$all_terms = array_values(array_filter(
1307	$all_terms,
1308	fn($term) => !$this->term_is_noindexed((int) $term->term_id)
1309	));
1310
1311	// Group terms by taxonomy
1312	return $this->group_terms_by_taxonomy($all_terms);
1313	}
1314
1315	/**
1316	* Group terms by taxonomy
1317	*
1318	* @since 1.0.0
1319	*
1320	* @param array $terms Array of term objects
1321	* @return array Grouped terms by taxonomy
1322	*/
1323	private function group_terms_by_taxonomy(array $terms): array {
1324	$grouped = [];
1325
1326	foreach ($terms as $term) {
1327	$taxonomy = $term->taxonomy; // �
1328	Evidence-based property name
1329
1330	if (!isset($grouped[$taxonomy])) {
1331	$grouped[$taxonomy] = [];
1332	}
1333
1334	$grouped[$taxonomy][] = $term;
1335	}
1336
1337	return $grouped;
1338	}
1339
1340	/**
1341	* Process taxonomy terms to XML entries
1342	*
1343	* @since 1.0.0
1344	*
1345	* @param array $terms Array of term objects
1346	* @param string $taxonomy Taxonomy name
1347	* @param array $settings Sitemap settings
1348	* @return string XML entries
1349	*/
1350	private function process_taxonomies_to_xml(array $terms, string $taxonomy, array $settings): string {
1351	$xml = '';
1352
1353	foreach ($terms as $term) {
1354	$url = get_term_link($term);
1355	if (!is_wp_error($url)) {
1356	// Omit lastmod for terms (generation time is not a real
1357	// modification time).
1358	$lastmod = '';
1359	$priority = $taxonomy === 'category' ? 0.6 : 0.4;
1360	$changefreq = 'weekly';
1361
1362	$xml .= $this->generate_url_entry($url, $lastmod, $priority, $changefreq);
1363	}
1364	}
1365
1366	return $xml;
1367	}
1368
1369	/**
1370	* Calculate intelligent priority based on content factors
1371	*
1372	* @since 1.0.0
1373	*
1374	* @param \WP_Post $post Post object
1375	* @param string $post_type Post type
1376	* @return float Priority value between 0.1 and 1.0
1377	*/
1378	private function calculate_intelligent_priority(\WP_Post $post, string $post_type): float {
1379	$base_priority = $post_type === 'page' ? 0.9 : 0.8;
1380
1381	// Factors that can adjust priority
1382	$adjustments = 0;
1383
1384	// Recent content gets higher priority
1385	$days_old = (time() - strtotime($post->post_date)) / DAY_IN_SECONDS;
1386	if ($days_old < 30) {
1387	$adjustments += 0.1; // Recent content boost
1388	} elseif ($days_old > 365) {
1389	$adjustments -= 0.1; // Older content penalty
1390	}
1391
1392	// Content length factor
1393	$content_length = strlen(wp_strip_all_tags($post->post_content));
1394	if ($content_length > 2000) {
1395	$adjustments += 0.05; // Comprehensive content boost
1396	} elseif ($content_length < 500) {
1397	$adjustments -= 0.1; // Thin content penalty
1398	}
1399
1400	// Special page types get higher priority
1401	if ($post_type === 'page') {
1402	$page_template = get_page_template_slug($post->ID);
1403	if (in_array($page_template, ['page-home.php', 'front-page.php'], true) \|\|
1404	(int) $post->ID === (int) get_option('page_on_front')) {
1405	$base_priority = 1.0; // Homepage gets maximum priority
1406	} elseif (in_array($page_template, ['page-contact.php', 'page-about.php'], true)) {
1407	$adjustments += 0.05; // Important pages boost
1408	}
1409	}
1410
1411	// Ensure priority stays within valid range
1412	$final_priority = max(0.1, min(1.0, $base_priority + $adjustments));
1413
1414	return round($final_priority, 1);
1415	}
1416
1417	/**
1418	* Calculate change frequency based on content type and age
1419	*
1420	* @since 1.0.0
1421	*
1422	* @param \WP_Post $post Post object
1423	* @param string $post_type Post type
1424	* @return string Change frequency
1425	*/
1426	private function calculate_change_frequency(\WP_Post $post, string $post_type): string {
1427	// Pages typically change less frequently
1428	if ($post_type === 'page') {
1429	$page_template = get_page_template_slug($post->ID);
1430	if ((int) $post->ID === (int) get_option('page_on_front')) {
1431	return 'daily'; // Homepage changes frequently
1432	} elseif (in_array($page_template, ['page-contact.php', 'page-about.php'], true)) {
1433	return 'monthly'; // Static pages change monthly
1434	}
1435	return 'yearly'; // Other pages change rarely
1436	}
1437
1438	// Posts frequency based on age and type
1439	$days_old = (time() - strtotime($post->post_date)) / DAY_IN_SECONDS;
1440
1441	if ($days_old < 7) {
1442	return 'daily'; // Very recent posts
1443	} elseif ($days_old < 30) {
1444	return 'weekly'; // Recent posts
1445	} elseif ($days_old < 365) {
1446	return 'monthly'; // Older posts
1447	}
1448
1449	return 'yearly'; // Very old posts
1450	}
1451
1452	/**
1453	* Determine if content should be included in sitemap
1454	*
1455	* @since 1.0.0
1456	*
1457	* @param \WP_Post $post Post object
1458	* @param array $settings Sitemap settings
1459	* @return bool Whether to include in sitemap
1460	*/
1461	private function should_include_in_sitemap(\WP_Post $post, array $settings): bool {
1462	// The WooCommerce cart, checkout and account pages are transactional,
1463	// never indexable, and generate_default_robots_rules() already emits a
1464	// Disallow for each of them. Listing them here submitted URLs our own
1465	// robots.txt blocks, which Search Console reports as "Submitted URL
1466	// blocked by robots.txt". Yoast and Rank Math exclude the same three.
1467	if (in_array($post->ID, $this->woocommerce_excluded_page_ids(), true)) {
1468	return false;
1469	}
1470
1471	// Respect user setting for password protected content
1472	if (!empty($post->post_password) && !empty($settings['exclude_password_protected'])) {
1473	return false;
1474	}
1475
1476	// Respect user setting for private posts
1477	if ($post->post_status === 'private' && !empty($settings['exclude_private_posts'])) {
1478	return false;
1479	}
1480
1481	// Only published (and, per setting, private) content belongs in the
1482	// sitemap. Content-quality heuristics (length, "demo"/"test"/"sample"
1483	// in the title, "lorem ipsum" text) were intentionally removed: an XML
1484	// sitemap should list every indexable published URL. Filtering by
1485	// description length silently dropped legitimate WooCommerce products
1486	// with short descriptions, and the substring title match excluded real
1487	// pages such as "Demo" or "Product Samples". Indexability is governed
1488	// by noindex directives below, not by heuristics.
1489	if (!in_array($post->post_status, ['publish', 'private'], true)) {
1490	return false;
1491	}
1492
1493	// Check if post overrides robots and sets noindex.
1494	if ((bool) get_post_meta($post->ID, '_thinkrank_robots_meta_enabled', true)) {
1495	$raw = get_post_meta($post->ID, '_thinkrank_robots_meta', true);
1496	if (is_string($raw) && $raw !== '') {
1497	$robots = json_decode($raw, true);
1498	if (is_array($robots) && !empty($robots['noindex'])) {
1499	return false;
1500	}
1501	}
1502	}
1503
1504	return true;
1505	}
1506
1507	/**
1508	* WooCommerce pages that must never reach the sitemap.
1509	*
1510	* Resolved through wc_get_page_id() so a store that moved or renamed its
1511	* cart/checkout/account pages is still matched. Returns an empty list when
1512	* WooCommerce is not active. Memoised — should_include_in_sitemap() runs
1513	* once per post.
1514	*
1515	* @since 2.0.1
1516	*
1517	* @return int[] Page IDs to exclude.
1518	*/
1519	private function woocommerce_excluded_page_ids(): array {
1520	if ($this->woocommerce_excluded_page_ids !== null) {
1521	return $this->woocommerce_excluded_page_ids;
1522	}
1523
1524	$ids = [];
1525
1526	if (function_exists('wc_get_page_id')) {
1527	foreach (['cart', 'checkout', 'myaccount'] as $page) {
1528	$id = (int) wc_get_page_id($page);
1529	// wc_get_page_id() returns -1 when the page is not configured.
1530	if ($id > 0) {
1531	$ids[] = $id;
1532	}
1533	}
1534	}
1535
1536	$this->woocommerce_excluded_page_ids = $ids;
1537
1538	return $ids;
1539	}
1540
1541	/**
1542	* Whether a term carries an explicit noindex override.
1543	*
1544	* Mirrors the post-side check in should_include_post(); terms store the same
1545	* `_thinkrank_robots_meta_enabled` / `_thinkrank_robots_meta` keys, written
1546	* by the update-term-seo ability and by the SEO importer.
1547	*
1548	* @since 1.31.0
1549	*
1550	* @param int $term_id Term to test.
1551	* @return bool True when the term is marked noindex.
1552	*/
1553	private function term_is_noindexed(int $term_id): bool {
1554	if (!(bool) get_term_meta($term_id, '_thinkrank_robots_meta_enabled', true)) {
1555	return false;
1556	}
1557
1558	$raw = get_term_meta($term_id, '_thinkrank_robots_meta', true);
1559	if (!is_string($raw) \|\| $raw === '') {
1560	return false;
1561	}
1562
1563	$robots = json_decode($raw, true);
1564
1565	return is_array($robots) && !empty($robots['noindex']);
1566	}
1567
1568	/**
1569	* Count total URLs in sitemap
1570	*
1571	* @since 1.0.0
1572	*
1573	* @param array $settings Sitemap settings
1574	* @return int Total URL count
1575	*/
1576	public function count_sitemap_urls(array $settings): int {
1577	$count = 1; // Homepage
1578
1579	if (!empty($settings['include_posts'])) {
1580	$count += wp_count_posts('post')->publish;
1581	}
1582
1583	if (!empty($settings['include_pages'])) {
1584	$count += wp_count_posts('page')->publish;
1585	}
1586
1587	if (!empty($settings['include_categories'])) {
1588	$count += wp_count_terms(['taxonomy' => 'category', 'hide_empty' => true]);
1589	}
1590
1591	if (!empty($settings['include_tags'])) {
1592	$count += wp_count_terms(['taxonomy' => 'post_tag', 'hide_empty' => true]);
1593	}
1594
1595	return $count;
1596	}
1597
1598	/**
1599	* Handle content changes for auto-generation
1600	*
1601	* @since 1.0.0
1602	* @param int $post_id Post ID
1603	* @param \WP_Post $post Post object
1604	* @return void
1605	*/
1606	public function handle_content_change(int $post_id, \WP_Post $post): void {
1607	// Skip if auto-generation is disabled
1608	if (!$this->should_auto_generate()) {
1609	return;
1610	}
1611
1612	// Skip autosaves and revisions
1613	if (wp_is_post_autosave($post_id) \|\| wp_is_post_revision($post_id)) {
1614	return;
1615	}
1616
1617	// Only process published content
1618	if ($post->post_status !== 'publish') {
1619	return;
1620	}
1621
1622	// Check if this post type should trigger regeneration
1623	if (!$this->should_include_post_type($post->post_type)) {
1624	return;
1625	}
1626
1627	// Schedule debounced regeneration
1628	$this->schedule_debounced_regeneration();
1629	}
1630
1631	/**
1632	* Handle content deletion for auto-generation
1633	*
1634	* @since 1.0.0
1635	* @param int $post_id Post ID
1636	* @return void
1637	*/
1638	public function handle_content_deletion(int $post_id): void {
1639	// Skip if auto-generation is disabled
1640	if (!$this->should_auto_generate()) {
1641	return;
1642	}
1643
1644	$post = get_post($post_id);
1645	if (!$post) {
1646	return;
1647	}
1648
1649	// Check if this post type should trigger regeneration
1650	if (!$this->should_include_post_type($post->post_type)) {
1651	return;
1652	}
1653
1654	// Schedule debounced regeneration
1655	$this->schedule_debounced_regeneration();
1656	}
1657
1658	/**
1659	* Handle content change by ID (for untrash, etc.)
1660	*
1661	* @since 1.0.0
1662	* @param int $post_id Post ID
1663	* @return void
1664	*/
1665	public function handle_content_change_by_id(int $post_id): void {
1666	$post = get_post($post_id);
1667	if ($post) {
1668	$this->handle_content_change($post_id, $post);
1669	}
1670	}
1671
1672	/**
1673	* Handle taxonomy changes for auto-generation
1674	*
1675	* @since 1.0.0
1676	* @param int $term_id Term ID
1677	* @param int $tt_id Term taxonomy ID
1678	* @param string $taxonomy Taxonomy slug
1679	* @return void
1680	*/
1681	public function handle_taxonomy_change(int $term_id, int $tt_id, string $taxonomy): void {
1682	// Skip if auto-generation is disabled
1683	if (!$this->should_auto_generate()) {
1684	return;
1685	}
1686
1687	// Check if this taxonomy should trigger regeneration
1688	if (!$this->should_include_taxonomy($taxonomy)) {
1689	return;
1690	}
1691
1692	// Schedule debounced regeneration
1693	$this->schedule_debounced_regeneration();
1694	}
1695
1696	/**
1697	* Check if auto-generation is enabled
1698	*
1699	* @since 1.0.0
1700	* @return bool True if auto-generation is enabled
1701	*/
1702	private function should_auto_generate(): bool {
1703	$settings = $this->get_settings('site');
1704
1705	// Check if sitemap is enabled
1706	if (empty($settings['enabled'])) {
1707	return false;
1708	}
1709
1710	// Check if auto-generation is enabled
1711	return !empty($settings['auto_generate']);
1712	}
1713
1714	/**
1715	* Get enabled post types based on settings
1716	*
1717	* @since 1.0.0
1718	* @param array $settings Sitemap settings
1719	* @return array Array of enabled post types
1720	*/
1721	private function get_enabled_post_types(array $settings): array {
1722	$post_types = [];
1723
1724	// Core post types based on settings
1725	if (!empty($settings['include_posts'])) {
1726	$post_types[] = 'post';
1727	}
1728
1729	if (!empty($settings['include_pages'])) {
1730	$post_types[] = 'page';
1731	}
1732
1733	// Auto-detect public custom post types that should be included.
1734	//
1735	// A custom type's `include_<slug>` / `exclude_<slug>` flag is honoured
1736	// here (#660). It was previously stored — additional_setting_keys()
1737	// has always let those keys through — but never read, so a CPT was in
1738	// the sitemap whatever the setting said. Unset still means included, so
1739	// a site that never touched the flag is unaffected.
1740	$custom_post_types = get_post_types([
1741	'public' => true,
1742	'_builtin' => false
1743	], 'names');
1744
1745	foreach ($custom_post_types as $post_type) {
1746	if (!$this->should_include_post_type($post_type)) {
1747	continue;
1748	}
1749
1750	if (\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('post_type', $post_type, $settings)) {
1751	$post_types[] = $post_type;
1752	}
1753	}
1754
1755	return array_unique($post_types);
1756	}
1757
1758	/**
1759	* Check if post type should trigger regeneration
1760	*
1761	* @since 1.0.0
1762	* @param string $post_type Post type
1763	* @return bool True if post type should trigger regeneration
1764	*/
1765	private function should_include_post_type(string $post_type): bool {
1766	// Match Rank Math: only publicly viewable post types belong in the
1767	// sitemap (public && publicly_queryable). Additionally skip post types
1768	// that opt out of front-end search (exclude_from_search => true) — e.g.
1769	// Templately's internal `templately_library` store — which are template
1770	// records, not standalone indexable URLs. BetterDocs `docs` and
1771	// WooCommerce `product` register exclude_from_search => false, so they
1772	// remain included.
1773	// The predicate lives in Content_Type_Settings so the matrix can ask
1774	// the same question before offering a switch for this post type.
1775	return \ThinkRank\SEO\Content_Type_Settings::sitemap_accepts_post_type($post_type);
1776	}
1777
1778	/**
1779	* Check if taxonomy should trigger regeneration
1780	*
1781	* @since 1.0.0
1782	* @param string $taxonomy Taxonomy slug
1783	* @return bool True if taxonomy should trigger regeneration
1784	*/
1785	private function should_include_taxonomy(string $taxonomy): bool {
1786	// Public taxonomies only, and only the ones this generator can actually
1787	// emit — the same predicate the content-type matrix asks before it
1788	// offers a sitemap switch for one (presets still control which
1789	// sitemaps are created).
1790	return \ThinkRank\SEO\Content_Type_Settings::sitemap_accepts_taxonomy($taxonomy);
1791	}
1792
1793	/**
1794	* Schedule debounced sitemap regeneration
1795	*
1796	* @since 1.0.0
1797	* @return void
1798	*/
1799	private function schedule_debounced_regeneration(): void {
1800	$this->mark_regeneration_pending('content');
1801	$this->debounce_event('thinkrank_regenerate_sitemap');
1802	}
1803
1804	/**
1805	* Schedule (or keep) the debounced single event behind a regeneration hook.
1806	*
1807	* An event that is already due is left alone. WP-Cron only runs when a
1808	* request arrives, so on a site with DISABLE_WP_CRON, a blocked loopback or
1809	* little traffic an overdue event can sit in the queue for a long time —
1810	* clearing and re-scheduling it on every save pushed the rebuild
1811	* permanently 30 seconds into the future and the sitemap never updated
1812	* (#629). Debouncing only against an event that has not come due yet keeps
1813	* the bulk-edit coalescing without starving the rebuild.
1814	*
1815	* @since 2.2.1
1816	* @param string $hook Regeneration hook to debounce.
1817	* @return void
1818	*/
1819	private function debounce_event(string $hook): void {
1820	$next = wp_next_scheduled($hook);
1821
1822	if ($next !== false) {
1823	if ($next <= time()) {
1824	return;
1825	}
1826
1827	wp_clear_scheduled_hook($hook);
1828	}
1829
1830	wp_schedule_single_event(time() + self::REGENERATION_DEBOUNCE, $hook);
1831	}
1832
1833	/**
1834	* Record that a rebuild is outstanding, so an overdue one can be taken over
1835	* by a later request and its staleness surfaced in the UI.
1836	*
1837	* `since` is the oldest outstanding change: it is what the takeover grace
1838	* and the admin staleness warning are measured from, so successive edits
1839	* must not push it forward. A settings change outranks a content change —
1840	* it rebuilds regardless of the auto_generate toggle and handles a sitemap
1841	* that has just been disabled — so once one is outstanding it stays the
1842	* recorded source until the rebuild lands.
1843	*
1844	* @since 2.2.1
1845	* @param string $source Either 'content' or 'settings'.
1846	* @return void
1847	*/
1848	private function mark_regeneration_pending(string $source): void {
1849	// Whatever made the static files stale made the rendered ones stale
1850	// too. Invalidating here rather than only on the rebuild keeps the two
1851	// delivery modes reacting to exactly the same triggers, which is the
1852	// only way a dynamic site stays as fresh as a static one (#752).
1853	$this->flush_dynamic_cache();
1854
1855	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
1856	$pending = is_array($pending) ? $pending : [];
1857
1858	$since = !empty($pending['since']) ? (int) $pending['since'] : time();
1859	$current = isset($pending['source']) ? (string) $pending['source'] : '';
1860	$source = ($current === 'settings' \|\| $source === 'settings') ? 'settings' : 'content';
1861
1862	update_option(
1863	self::REGENERATION_PENDING_OPTION,
1864	[
1865	'since' => $since,
1866	'source' => $source,
1867	'attempts' => !empty($pending['attempts']) ? (int) $pending['attempts'] : 0,
1868	'next_attempt' => !empty($pending['next_attempt'])
1869	? (int) $pending['next_attempt']
1870	: time() + self::REGENERATION_TAKEOVER_GRACE,
1871	// Bumped on every change so a rebuild can tell whether the edit
1872	// it started for is still the newest one outstanding.
1873	'revision' => (!empty($pending['revision']) ? (int) $pending['revision'] : 0) + 1,
1874	],
1875	true
1876	);
1877	}
1878
1879	/**
1880	* The revision of the outstanding rebuild, for
1881	* {@see mark_regeneration_complete()} to compare against once it is done.
1882	*
1883	* @since 2.2.1
1884	* @return int Current revision, 0 when nothing is outstanding.
1885	*/
1886	private function current_regeneration_revision(): int {
1887	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
1888
1889	return (is_array($pending) && !empty($pending['revision'])) ? (int) $pending['revision'] : 0;
1890	}
1891
1892	/**
1893	* Clear the outstanding-rebuild marker and any recorded failure.
1894	*
1895	* Public because a manual generation satisfies whatever the automatic path
1896	* was still waiting to write.
1897	*
1898	* @since 2.2.1
1899	* @return void
1900	*/
1901	public function mark_regeneration_complete(?int $revision = null): void {
1902	// The write succeeded, so whatever failure was on record is history.
1903	if (get_option(self::REGENERATION_ERROR_OPTION, null) !== null) {
1904	delete_option(self::REGENERATION_ERROR_OPTION);
1905	}
1906
1907	$pending = get_option(self::REGENERATION_PENDING_OPTION, null);
1908
1909	if ($pending === null) {
1910	return;
1911	}
1912
1913	// A change that landed while this rebuild was running is not covered by
1914	// the files it just wrote, so it has to stay outstanding — otherwise, on
1915	// a site where WP-Cron never fires, clearing the marker would strand it
1916	// exactly the way #629 stranded everything.
1917	if (
1918	$revision !== null
1919	&& is_array($pending)
1920	&& (int) ($pending['revision'] ?? 0) !== $revision
1921	) {
1922	return;
1923	}
1924
1925	delete_option(self::REGENERATION_PENDING_OPTION);
1926	}
1927
1928	/**
1929	* Record a failed regeneration instead of discarding it.
1930	*
1931	* Keeps the pending marker in place so the rebuild is retried, but backs the
1932	* next attempt off exponentially (capped) so a persistently failing
1933	* generation cannot run on every admin request.
1934	*
1935	* @since 2.2.1
1936	* @param string $message Failure detail.
1937	* @param string $source Either 'content' or 'settings'.
1938	* @return void
1939	*/
1940	private function record_regeneration_failure(string $message, string $source): void {
1941	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
1942	$pending = is_array($pending) ? $pending : [];
1943	$attempts = (!empty($pending['attempts']) ? (int) $pending['attempts'] : 0) + 1;
1944
1945	$backoff = min(
1946	self::REGENERATION_TAKEOVER_GRACE * (2 ** min($attempts, 10)),
1947	self::REGENERATION_MAX_BACKOFF
1948	);
1949
1950	// Same precedence mark_regeneration_pending() enforces: a settings
1951	// rebuild outranks a content one and must not be downgraded by a failed
1952	// attempt. Overwriting it routed the retry back through the content
1953	// path, where should_auto_generate() can be false and the completion
1954	// marker then discards the settings rebuild entirely. Only the
1955	// outstanding rebuild is upgraded — the recorded error keeps reporting
1956	// whichever attempt actually failed.
1957	$current = isset($pending['source']) ? (string) $pending['source'] : '';
1958	$pending_source = ($current === 'settings' \|\| $source === 'settings') ? 'settings' : 'content';
1959
1960	update_option(
1961	self::REGENERATION_PENDING_OPTION,
1962	[
1963	'since' => !empty($pending['since']) ? (int) $pending['since'] : time(),
1964	'source' => $pending_source,
1965	'attempts' => $attempts,
1966	'next_attempt' => time() + $backoff,
1967	'revision' => !empty($pending['revision']) ? (int) $pending['revision'] : 0,
1968	],
1969	true
1970	);
1971
1972	update_option(
1973	self::REGENERATION_ERROR_OPTION,
1974	[
1975	'message' => $message,
1976	'source' => $source,
1977	'attempts' => $attempts,
1978	'time' => time(),
1979	],
1980	false
1981	);
1982
1983	if (defined('WP_DEBUG') && WP_DEBUG) {
1984	// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
1985	error_log(sprintf('ThinkRank: sitemap %s regeneration failed — %s', $source, $message));
1986	}
1987	}
1988
1989	/**
1990	* Is a rebuild outstanding and past the point where WP-Cron should have run
1991	* it?
1992	*
1993	* Deliberately cheap — one autoloaded option read — because it is consulted
1994	* on every admin request to decide whether the takeover is needed.
1995	*
1996	* @since 2.2.1
1997	* @return bool True when a request should rebuild the sitemap itself.
1998	*/
1999	public static function has_overdue_regeneration(): bool {
2000	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
2001
2002	if (!is_array($pending) \|\| empty($pending['since'])) {
2003	return false;
2004	}
2005
2006	$due = !empty($pending['next_attempt'])
2007	? (int) $pending['next_attempt']
2008	: (int) $pending['since'] + self::REGENERATION_TAKEOVER_GRACE;
2009
2010	return time() >= $due;
2011	}
2012
2013	/**
2014	* Rebuild the sitemap in-request when WP-Cron has not delivered.
2015	*
2016	* Hooked on `shutdown` for admin, REST and CLI requests only (see
2017	* Plugin::register_sitemap_cron_listeners()), so the work happens after the
2018	* response has been sent and never adds latency to a visitor page view.
2019	*
2020	* @since 2.2.1
2021	* @return void
2022	*/
2023	public function run_overdue_regeneration(): void {
2024	if (!self::has_overdue_regeneration()) {
2025	return;
2026	}
2027
2028	// Cron is running: it is about to do exactly this work.
2029	if (wp_doing_cron()) {
2030	return;
2031	}
2032
2033	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
2034	$source = (is_array($pending) && isset($pending['source'])) ? (string) $pending['source'] : 'content';
2035
2036	if ($source === 'settings') {
2037	$this->regenerate_sitemap_from_settings();
2038	return;
2039	}
2040
2041	$this->auto_regenerate_sitemap();
2042	}
2043
2044	/**
2045	* Acquire the shared generation lock.
2046	*
2047	* @since 2.2.1
2048	* @return bool True when this process may generate.
2049	*/
2050	private function acquire_generation_lock(): bool {
2051	if (get_transient(self::GENERATION_LOCK_TRANSIENT)) {
2052	return false;
2053	}
2054
2055	set_transient(self::GENERATION_LOCK_TRANSIENT, time(), 5 * MINUTE_IN_SECONDS);
2056
2057	return true;
2058	}
2059
2060	/**
2061	* Release the shared generation lock.
2062	*
2063	* @since 2.2.1
2064	* @return void
2065	*/
2066	private function release_generation_lock(): void {
2067	delete_transient(self::GENERATION_LOCK_TRANSIENT);
2068	}
2069
2070	/**
2071	* Report how automatic regeneration is faring, for the admin UI.
2072	*
2073	* The feature used to fail invisibly: `last_generated` simply stopped
2074	* advancing and nothing drew attention to it (#629).
2075	*
2076	* @since 2.2.1
2077	* @return array Health payload.
2078	*/
2079	public function get_regeneration_health(): array {
2080	$settings = $this->get_settings('site');
2081	$pending = get_option(self::REGENERATION_PENDING_OPTION, []);
2082	$pending = is_array($pending) ? $pending : [];
2083	$error = get_option(self::REGENERATION_ERROR_OPTION, []);
2084	$error = is_array($error) ? $error : [];
2085
2086	$since = !empty($pending['since']) ? (int) $pending['since'] : 0;
2087
2088	$next_scheduled = wp_next_scheduled('thinkrank_regenerate_sitemap');
2089	if ($next_scheduled === false) {
2090	$next_scheduled = wp_next_scheduled('thinkrank_regenerate_sitemap_settings');
2091	}
2092
2093	return [
2094	'auto_generate' => !empty($settings['auto_generate']),
2095	'last_generated' => $settings['last_generated'] ?? '',
2096	'pending_since' => $since ? gmdate('c', $since) : null,
2097	'pending_seconds' => $since ? max(0, time() - $since) : 0,
2098	'next_scheduled' => $next_scheduled ? gmdate('c', (int) $next_scheduled) : null,
2099	'cron_disabled' => defined('DISABLE_WP_CRON') && DISABLE_WP_CRON,
2100	'stale' => $this->is_sitemap_stale($settings),
2101	'last_error' => !empty($error['message'])
2102	? [
2103	'message' => (string) $error['message'],
2104	'source' => isset($error['source']) ? (string) $error['source'] : 'content',
2105	'time' => !empty($error['time']) ? gmdate('c', (int) $error['time']) : null,
2106	]
2107	: null,
2108	];
2109	}
2110
2111	/**
2112	* Has published content changed since the served sitemap was last written?
2113	*
2114	* Uses core's cached last-modified lookup, which only considers published
2115	* posts — the same content the sitemap covers.
2116	*
2117	* @since 2.2.1
2118	* @param array $settings Sitemap settings.
2119	* @return bool True when the sitemap is behind the content.
2120	*/
2121	private function is_sitemap_stale(array $settings): bool {
2122	if (empty($settings['enabled']) \|\| empty($settings['last_generated'])) {
2123	// Never generated is already reported separately by the UI.
2124	return false;
2125	}
2126
2127	$generated = strtotime((string) $settings['last_generated']);
2128	if (!$generated) {
2129	return false;
2130	}
2131
2132	$modified = get_lastpostmodified('gmt');
2133	if (!$modified) {
2134	return false;
2135	}
2136
2137	$modified = strtotime($modified . ' UTC');
2138	if (!$modified) {
2139	return false;
2140	}
2141
2142	// A minute of slack keeps a rebuild that ran alongside the edit from
2143	// reporting itself as stale.
2144	return $modified > ($generated + MINUTE_IN_SECONDS);
2145	}
2146
2147	/**
2148	* Public entry point to debounce-rebuild the sitemap after a settings change
2149	* (e.g. toggling inclusion rules via REST or the MCP ability), so the served
2150	* file reflects the new settings instead of going stale until a content edit.
2151	*
2152	* @return void
2153	*/
2154	public function schedule_regeneration(): void {
2155	// Debounce against rapid successive saves, but use the settings-specific
2156	// hook so the rebuild runs regardless of the auto_generate toggle (which
2157	// only governs content-change-triggered regeneration).
2158	$this->mark_regeneration_pending('settings');
2159	$this->debounce_event('thinkrank_regenerate_sitemap_settings');
2160	}
2161
2162	/**
2163	* Rebuild the served sitemap after an explicit settings change.
2164	*
2165	* Unlike {@see auto_regenerate_sitemap()}, this is NOT gated on the
2166	* auto_generate setting: the user deliberately changed inclusion rules and
2167	* expects the served file to reflect them even if content-triggered
2168	* auto-generation is turned off. Still respects the master `enabled` flag.
2169	*
2170	* @return void
2171	*/
2172	public function regenerate_sitemap_from_settings(): void {
2173	if (!$this->acquire_generation_lock()) {
2174	// A manual generation (or another request's takeover) is already
2175	// writing the files; the pending marker survives so this rebuild is
2176	// retried rather than lost.
2177	return;
2178	}
2179
2180	try {
2181	$settings = $this->get_settings('site');
2182	if (empty($settings['enabled'])) {
2183	// The sitemap was disabled: remove the previously generated static
2184	// files so the web server stops serving a stale sitemap that
2185	// crawlers would otherwise keep fetching.
2186	$this->delete_published_sitemaps();
2187	$this->mark_regeneration_complete();
2188	return;
2189	}
2190
2191	$revision = $this->current_regeneration_revision();
2192
2193	if ('dynamic' === $this->resolve_delivery_mode($settings)) {
2194	$this->switch_to_dynamic_delivery($settings, $revision, 'settings');
2195	return;
2196	}
2197
2198	if ($this->generate_and_save($settings)) {
2199	$this->mark_regeneration_complete($revision);
2200	} else {
2201	$this->record_regeneration_failure(
2202	$this->write_failure_message(),
2203	'settings'
2204	);
2205	}
2206	} catch (\Throwable $e) {
2207	$this->record_regeneration_failure($e->getMessage(), 'settings');
2208	} finally {
2209	$this->release_generation_lock();
2210	}
2211	}
2212
2213	/**
2214	* Remove every static sitemap file ThinkRank publishes to the web root.
2215	*
2216	* Called when the sitemap feature is disabled, by the cleanup route, and by
2217	* both removal paths, so /sitemap.xml, /sitemap_index.xml, the segmented
2218	* children (incl. paginated -N pages), and /local-sitemap.xml stop being
2219	* served. Only ThinkRank's own filenames are targeted; WordPress core's
2220	* wp-sitemap.xml and any other plugin's sitemap in the web root are left
2221	* untouched.
2222	*
2223	* @since 1.31.0 Returns the filenames removed, and accepts the settings to
2224	* derive them from, so a caller that already read them (and
2225	* needs to report what went) does not have to re-read or
2226	* re-derive the name list.
2227	* @since 2.1.0 Delegates to thinkrank_webroot_delete_sitemaps(). Uninstall
2228	* needs the same removal but has no autoloader to reach this
2229	* class, so the logic moved to includes/cleanup-webroot.php
2230	* and this stays as the in-plugin entry point.
2231	*
2232	* @param array\|null $settings Optional. Sitemap settings; defaults to the
2233	* saved site settings.
2234	* @return array{deleted: string[], failed: string[]} Basenames removed, and
2235	* those that existed but could not be removed.
2236	*/
2237	public function delete_published_sitemaps(?array $settings = null): array {
2238	return thinkrank_webroot_delete_sitemaps($settings ?? $this->get_settings('site'));
2239	}
2240
2241	/**
2242	* Every child-sitemap filename this site could have published.
2243	*
2244	* @since 1.31.0
2245	* @since 2.1.0 Delegates to thinkrank_webroot_segment_filenames().
2246	*
2247	* @param array $settings Sitemap settings (read for `custom_url_pattern`).
2248	* @return string[] Basenames, e.g. ['sitemap-posts.xml', 'sitemap-pages.xml'].
2249	*/
2250	private function publishable_segment_filenames(array $settings): array {
2251	return thinkrank_webroot_segment_filenames($settings);
2252	}
2253
2254	/**
2255	* Can this web-root file be shown to be a sitemap ThinkRank wrote?
2256	*
2257	* The generator deletes as often as cleanup does — a segment that dropped
2258	* out of the set, a pagination page beyond the new count, the local sitemap
2259	* after the business identity was cleared — and until 2.1.1 it did all
2260	* three by filename alone. That is the #515 bug on a far more frequent
2261	* trigger: our names are the canonical ones, so an ordinary regeneration
2262	* (post save, term change, settings save) destroyed RankMath's
2263	* `sitemap-tags.xml` and `local-sitemap.xml` with no deactivation involved.
2264	*
2265	* Every name the generator derives comes from the current settings — the
2266	* url pattern, the configured `sitemap_urls`, `local-sitemap.xml` — but the
2267	* ownership test is still asked with `$name_derived = false`, which switches
2268	* off the legacy fallback for the whole generator side.
2269	*
2270	* The fallback exists to recover a pre-2.1.1 file written with
2271	* `enable_styling` off, which carries neither marker. That recovery belongs
2272	* to the once-off cleanup paths. Here it can only do harm: this method runs
2273	* on every post save, and everything this version writes carries
2274	* THINKRANK_SITEMAP_MARKER, so after the site's first regeneration an
2275	* unmarked file at one of our names is by definition somebody else's — and
2276	* deleting it on an ordinary regeneration is #515 through the more common
2277	* door. The cost is a stale unmarked segment left on disk until deactivation
2278	* picks it up, which is the safe direction to fail in.
2279	*
2280	* @since 2.1.1
2281	*
2282	* @param string $path Absolute path to a file in the web root.
2283	* @param array $settings Sitemap settings.
2284	* @return bool True when the file may be deleted.
2285	*/
2286	private function webroot_sitemap_is_ours(string $path, array $settings): bool {
2287	return thinkrank_webroot_sitemap_is_ours($path, $settings, false);
2288	}
2289
2290	/**
2291	* Auto-regenerate sitemap (called by scheduled action)
2292	*
2293	* @since 1.0.0
2294	* @return void
2295	*/
2296	public function auto_regenerate_sitemap(): void {
2297	if (!$this->acquire_generation_lock()) {
2298	// A manual generation (or another request's takeover) is already
2299	// writing the files; the pending marker survives so this rebuild is
2300	// retried rather than lost.
2301	return;
2302	}
2303
2304	try {
2305	// Double-check that auto-generation is still enabled
2306	if (!$this->should_auto_generate()) {
2307	// Nothing outstanding can be delivered while the feature is off,
2308	// so drop the marker rather than let the takeover retry forever.
2309	$this->mark_regeneration_complete();
2310	return;
2311	}
2312
2313	$revision = $this->current_regeneration_revision();
2314	$settings = $this->get_settings('site');
2315
2316	// See regenerate_sitemap_from_settings(): nothing to write.
2317	if ('dynamic' === $this->resolve_delivery_mode($settings)) {
2318	$this->switch_to_dynamic_delivery($settings, $revision, 'content');
2319	return;
2320	}
2321
2322	if ($this->generate_and_save($settings)) {
2323	$this->mark_regeneration_complete($revision);
2324	} else {
2325	// Previously this returned quietly and last_generated simply
2326	// stopped advancing, leaving the site owner with no way to learn
2327	// the sitemap had stopped updating (#629).
2328	$this->record_regeneration_failure(
2329	$this->write_failure_message(),
2330	'content'
2331	);
2332	}
2333	} catch (\Throwable $e) {
2334	$this->record_regeneration_failure($e->getMessage(), 'content');
2335	} finally {
2336	$this->release_generation_lock();
2337	}
2338	}
2339
2340	/**
2341	* Build and write the sitemap files for the given settings.
2342	*
2343	* Segmented files plus an index when the settings configure one, a single
2344	* file otherwise, and the standalone local business sitemap either way.
2345	* Records `last_generated` so the UI's "View Generated Sitemaps" links
2346	* unlock, mirroring the manual generate endpoint.
2347	*
2348	* @since 1.17.0
2349	* @param array $settings Sitemap settings.
2350	* @return bool True when the sitemap files were written.
2351	*/
2352	public function generate_and_save(array $settings): bool {
2353	// Dynamic delivery publishes no files, so writing them here would put a
2354	// static copy back in the web root for the server to serve in place of
2355	// the dynamic route. Guarding at each call site left gaps — the
2356	// snapshot migrator's post-import regeneration had none — so the rule
2357	// lives with the writing instead.
2358	//
2359	// `is_collecting()` is the exception that makes dynamic delivery work
2360	// at all: render_document() and collect_documents() reach this same
2361	// method with the writer swapped for a collector, and that is precisely
2362	// the dynamic build. Only a real write is skipped.
2363	if (!$this->is_collecting() && 'dynamic' === $this->resolve_delivery_mode($settings)) {
2364	// Whatever prompted this call changed the sitemap's content, so the
2365	// rendered copies must not outlive it.
2366	$this->flush_dynamic_cache();
2367
2368	return true;
2369	}
2370
2371	// Index mode is driven by the use_sitemap_index toggle (not merely by how
2372	// many sitemap_urls happen to be configured). When the toggle is on but
2373	// no child sitemaps are set up yet, synthesize the per-type segmented set
2374	// so we emit a real <sitemapindex> with paginated children instead of a
2375	// flat urlset misnamed sitemap_index.xml.
2376	$settings = $this->maybe_promote_to_index($settings);
2377
2378	if (!empty($settings['use_sitemap_index']) \|\| count((is_array($settings['sitemap_urls'] ?? null) ? $settings['sitemap_urls'] : [])) > 1) {
2379	$results = $this->generate_multiple_sitemaps($settings);
2380	$written = !empty($results['success']);
2381	} else {
2382	$xml = $this->generate_sitemap($settings);
2383	$primary = $this->get_primary_sitemap_filename($settings);
2384	$written = $this->save_sitemap_to_file($xml, $primary);
2385
2386	// Local business sitemap is a standalone file, regenerated on the
2387	// single-sitemap path too (this is the default mode).
2388	$this->regenerate_local_sitemap($settings);
2389
2390	// Switching out of index mode leaves sitemap_index.xml and every
2391	// child on disk, still served and never refreshed again. The index
2392	// path already prunes what it no longer owns; this path never did,
2393	// so the site kept serving two sitemap trees (#563). Ownership is
2394	// still tested per file, so another plugin's sitemap at one of our
2395	// names is never touched (#515).
2396	$this->prune_orphaned_segments($settings, [['filename' => basename($primary)]]);
2397	}
2398
2399	// last_generated describes what is on disk. A dynamic render publishes
2400	// nothing, so advancing it would report a static publication that never
2401	// happened and would let primary_sitemap_file_exists() callers believe
2402	// there is a file to serve.
2403	if ($written && !$this->is_collecting()) {
2404	$settings['last_generated'] = gmdate('c');
2405	$this->save_settings('site', null, $settings);
2406	}
2407
2408	return $written;
2409	}
2410
2411	/**
2412	* Whether this instance is rendering documents rather than publishing them.
2413	*
2414	* @since 2.9.0
2415	*
2416	* @return bool
2417	*/
2418	private function is_collecting(): bool {
2419	return $this->document_sink !== null;
2420	}
2421
2422	/**
2423	* Complete a regeneration that delivers dynamically, retiring stale files.
2424	*
2425	* Dynamic delivery renders nothing to disk, but that is only half the job.
2426	* A web server hands back an existing `/sitemap.xml` without ever loading
2427	* WordPress, so any file left over from a previous static generation goes on
2428	* being served forever and {@see \ThinkRank\Frontend\SEO_Manager
2429	* ::maybe_serve_sitemap()} is never reached. Switching to dynamic while
2430	* leaving those files in place would therefore appear to do nothing at all.
2431	*
2432	* Both transitions matter and they differ:
2433	*
2434	* - An explicit switch to `dynamic` happens on a site whose root is usually
2435	* still writable, so the files can simply be removed.
2436	* - An `auto` site that becomes read-only cannot remove them, because
2437	* deleting an entry needs write permission on the directory that holds
2438	* it. There the stale sitemap really is stuck in front of us, and the
2439	* honest outcome is a recorded failure naming it rather than a rebuild
2440	* reported as complete (#754 review).
2441	*
2442	* Ownership is tested per file by the shared helper, so another plugin's
2443	* sitemap at one of our names is never deleted (#515).
2444	*
2445	* @since 2.9.0
2446	*
2447	* @param array $settings Sitemap settings.
2448	* @param int $revision Revision this rebuild is completing.
2449	* @param string $source 'settings' or 'content', for the failure record.
2450	* @return void
2451	*/
2452	private function switch_to_dynamic_delivery(array $settings, int $revision, string $source): void {
2453	$this->flush_dynamic_cache();
2454
2455	$removal = $this->delete_published_sitemaps($settings);
2456	$stuck = is_array($removal['failed'] ?? null) ? $removal['failed'] : [];
2457
2458	if (!empty($stuck)) {
2459	$this->record_regeneration_failure(
2460	sprintf(
2461	/* translators: 1: comma-separated file names, 2: absolute path to the WordPress root. */
2462	__('The sitemap is being served from WordPress, but these files are still in the site root and your web server will keep serving them instead: %1$s. They could not be removed because %2$s is not writable. Delete them, or ask your host to make the WordPress root writable.', 'thinkrank'),
2463	implode(', ', $stuck),
2464	untrailingslashit(ABSPATH)
2465	),
2466	$source
2467	);
2468
2469	return;
2470	}
2471
2472	$this->mark_regeneration_complete($revision);
2473	}
2474
2475	/**
2476	* What to tell the site owner when publishing the files failed.
2477	*
2478	* The old wording stated the symptom and stopped there, so the reported
2479	* cause was a guess and this reached support as a plugin fault rather than
2480	* a folder permission (#752, #753). When the root is demonstrably
2481	* unwritable, say that, and say what to do about it.
2482	*
2483	* @since 2.9.0
2484	*
2485	* @return string
2486	*/
2487	private function write_failure_message(): string {
2488	if (!wp_is_writable(ABSPATH)) {
2489	return sprintf(
2490	/* translators: %s: absolute path to the WordPress root. */
2491	__('The sitemap could not be written because the folder %s is not writable by PHP. Ask your host to make the WordPress root writable, or set Sitemap Delivery to Dynamic to serve the sitemap without writing files.', 'thinkrank'),
2492	untrailingslashit(ABSPATH)
2493	);
2494	}
2495
2496	return __('The sitemap files could not be written to the site root.', 'thinkrank');
2497	}
2498
2499	/**
2500	* How this site delivers its sitemap.
2501	*
2502	* `auto` is resolved on whether the web root can be written. That is the
2503	* right signal here (unlike llms.txt, where the question is whether the
2504	* server applies the .htaccess charset block): a site whose root is
2505	* read-only cannot publish a sitemap file at all, and before this existed
2506	* the feature simply failed with "The sitemap files could not be written to
2507	* the site root." and served nothing (#752).
2508	*
2509	* @since 2.9.0
2510	*
2511	* @param array\|null $settings Sitemap settings (falls back to saved ones).
2512	* @return string One of 'static' or 'dynamic'. Never 'auto'.
2513	*/
2514	public function resolve_delivery_mode(?array $settings = null): string {
2515	$settings = $settings ?? $this->get_settings('site');
2516	$mode = (string) ($settings['delivery_mode'] ?? 'auto');
2517
2518	if ('static' === $mode \|\| 'dynamic' === $mode) {
2519	return $mode;
2520	}
2521
2522	return wp_is_writable(ABSPATH) ? 'static' : 'dynamic';
2523	}
2524
2525	/**
2526	* Render one published sitemap document without touching the filesystem.
2527	*
2528	* Runs the ordinary build pipeline with the writer swapped for a collector,
2529	* so the bytes returned here are the bytes the static path would have
2530	* written. `SitemapDeliveryParityTest` asserts that equivalence rather than
2531	* trusting it.
2532	*
2533	* The whole set is built to answer for one file, because the index can only
2534	* be assembled from the children that were actually produced. The result is
2535	* cached per document, so that cost is paid once per change and not once
2536	* per crawler request.
2537	*
2538	* @since 2.9.0
2539	*
2540	* @param string $filename Published file name, e.g. 'sitemap.xml'.
2541	* @param array\|null $settings Sitemap settings (falls back to saved ones).
2542	* @return string\|null XML, or null when this site does not publish that name.
2543	*/
2544	public function render_document(string $filename, ?array $settings = null): ?string {
2545	$filename = basename($filename);
2546	$settings = $settings ?? $this->get_settings('site');
2547
2548	if (empty($settings['enabled'])) {
2549	return null;
2550	}
2551
2552	$cached = get_transient($this->dynamic_cache_key($filename));
2553	if (self::ABSENT_MARKER === $cached) {
2554	return null;
2555	}
2556	if (is_string($cached) && '' !== $cached) {
2557	return $cached;
2558	}
2559
2560	// A miss builds the whole set, because the index can only be assembled
2561	// from the children that were actually produced. Caching only the
2562	// requested document therefore made a crawler walking the index and its
2563	// children rebuild the entire site's sitemap once per file — every post
2564	// and taxonomy query repeated N times on a public endpoint (#754
2565	// review). The set is built once and stored in full.
2566	return $this->stream_documents($settings, $filename);
2567	}
2568
2569	/**
2570	* Build every document, caching each as it is produced, keeping one.
2571	*
2572	* A miss has to build the whole set, because the index can only be
2573	* assembled from the children that were actually produced. It does not have
2574	* to hold the whole set: the static path never keeps more than one page
2575	* in memory, writing each to disk as it goes, and buffering every
2576	* document's XML to return one of them undid that on the request path,
2577	* where a large site's entire sitemap corpus would sit in a single PHP
2578	* process (#754 review).
2579	*
2580	* So the sink writes each document straight to its cache entry and lets it
2581	* go, retaining only the one this request is answering. Peak retention is
2582	* one document, whatever the site's size.
2583	*
2584	* Concurrency: the first request through takes a short lock and does the
2585	* work. One that finds the lock held waits a bounded moment for the winner
2586	* to publish, then builds anyway, because serving a correct sitemap late
2587	* beats serving none.
2588	*
2589	* @since 2.9.0
2590	*
2591	* @param array $settings Sitemap settings.
2592	* @param string $wanted Document this request is answering.
2593	* @return string\|null XML for $wanted, or null when the site does not publish it.
2594	*/
2595	private function stream_documents(array $settings, string $wanted): ?string {
2596	$lock = self::DYNAMIC_CACHE_PREFIX . 'lock';
2597
2598	if (!$this->acquire_render_lock($lock)) {
2599	for ($attempt = 0; $attempt < self::RENDER_LOCK_WAIT_ATTEMPTS; $attempt++) {
2600	usleep(self::RENDER_LOCK_WAIT_MICROSECONDS);
2601
2602	$cached = get_transient($this->dynamic_cache_key($wanted));
2603	if (self::ABSENT_MARKER === $cached) {
2604	return null;
2605	}
2606	if (is_string($cached) && '' !== $cached) {
2607	return $cached;
2608	}
2609	}
2610	}
2611
2612	$kept = null;
2613	// Names only. Keeping the bodies here would be the very retention this
2614	// method exists to avoid.
2615	$produced = [];
2616
2617	$previous = $this->document_sink;
2618	$this->document_sink = function (string $name, string $xml) use (&$kept, &$produced, $wanted): void {
2619	$produced[$name] = true;
2620	set_transient($this->dynamic_cache_key($name), $xml, self::DYNAMIC_CACHE_TTL);
2621
2622	if ($name === $wanted) {
2623	$kept = $xml;
2624	}
2625	};
2626
2627	try {
2628	$this->generate_and_save($settings);
2629
2630	// Names the configuration lists but this build did not produce get
2631	// a negative entry, so asking for one again is a cache hit rather
2632	// than another full rebuild.
2633	$absent = $this->published_document_names($settings);
2634
2635	// Also the exact name this request asked for: a paginated page past
2636	// the end of a stem is a legitimate request shape that the base
2637	// list cannot enumerate, and without an entry it would rebuild on
2638	// every hit.
2639	$absent[] = $wanted;
2640
2641	foreach (array_unique($absent) as $name) {
2642	if (!isset($produced[$name])) {
2643	set_transient($this->dynamic_cache_key($name), self::ABSENT_MARKER, self::DYNAMIC_CACHE_TTL);
2644	}
2645	}
2646	} finally {
2647	$this->document_sink = $previous;
2648	delete_transient($lock);
2649	}
2650
2651	return $kept;
2652	}
2653
2654	/**
2655	* Take the render lock, if it is free.
2656	*
2657	* Not atomic across processes, and deliberately so: the fallback for losing
2658	* a race is duplicated work, never a wrong or missing sitemap, so a
2659	* heavier primitive would buy nothing here.
2660	*
2661	* @since 2.9.0
2662	*
2663	* @param string $lock Lock transient name.
2664	* @return bool True when this request holds the lock.
2665	*/
2666	private function acquire_render_lock(string $lock): bool {
2667	if (false !== get_transient($lock)) {
2668	return false;
2669	}
2670
2671	set_transient($lock, time(), self::RENDER_LOCK_TTL);
2672
2673	return true;
2674	}
2675
2676	/**
2677	* Build every document this site publishes and return them all.
2678	*
2679	* Verification and tooling only. This retains the whole set in memory, so
2680	* it must never be used to answer a request: {@see self::stream_documents()}
2681	* is the serving path and keeps one document at a time regardless of site
2682	* size (#754 review). `SitemapDeliveryParityTest` enforces that separation
2683	* by failing if the request path routes back through here.
2684	*
2685	* @since 2.9.0
2686	*
2687	* @param array $settings Sitemap settings.
2688	* @return array<string,string> Filename => XML.
2689	*/
2690	public function collect_documents(array $settings): array {
2691	$documents = [];
2692
2693	$previous = $this->document_sink;
2694	$this->document_sink = static function (string $name, string $xml) use (&$documents): void {
2695	$documents[$name] = $xml;
2696	};
2697
2698	try {
2699	$this->generate_and_save($settings);
2700	} finally {
2701	$this->document_sink = $previous;
2702	}
2703
2704	return $documents;
2705	}
2706
2707	/**
2708	* The file names this site publishes, without building their contents.
2709	*
2710	* Used by the request router to decide whether a URL is ours before doing
2711	* any work. Cheap: it reads the configured child list rather than querying
2712	* for entries.
2713	*
2714	* @since 2.9.0
2715	*
2716	* @param array\|null $settings Sitemap settings (falls back to saved ones).
2717	* @return string[] File names, including paginated pages that may exist.
2718	*/
2719	public function published_document_names(?array $settings = null): array {
2720	$settings = $settings ?? $this->get_settings('site');
2721	$resolved = $this->maybe_promote_to_index($settings);
2722
2723	$names = [$this->get_primary_sitemap_filename($settings), 'local-sitemap.xml'];
2724
2725	foreach ((array) ($resolved['sitemap_urls'] ?? []) as $child) {
2726	if (!is_array($child) \|\| empty($child['enabled'])) {
2727	continue;
2728	}
2729
2730	$path = (string) wp_parse_url((string) ($child['url'] ?? ''), PHP_URL_PATH);
2731	if ('' !== $path) {
2732	$names[] = basename($path);
2733	}
2734	}
2735
2736	return array_values(array_unique(array_filter($names)));
2737	}
2738
2739	/**
2740	* Does this site publish a document under that name?
2741	*
2742	* Not a plain membership test against {@see self::published_document_names()}:
2743	* that lists the configured children, and a child over the per-file URL cap
2744	* is split into `<stem>-2.xml`, `<stem>-3.xml` and so on, with every page
2745	* listed in the index. Gating the request router on the base list alone
2746	* therefore 404'd exactly the pages the index points at, which is worse than
2747	* not serving them at all.
2748	*
2749	* Page counts are not knowable without building, so the stem is what is
2750	* matched; a page that does not exist is answered by the build finding
2751	* nothing for it, and is then cached as absent.
2752	*
2753	* @since 2.9.0
2754	*
2755	* @param string $name Requested file name.
2756	* @param array\|null $settings Sitemap settings (falls back to saved ones).
2757	* @return bool
2758	*/
2759	public function publishes_document_name(string $name, ?array $settings = null): bool {
2760	$names = $this->published_document_names($settings);
2761
2762	if (in_array($name, $names, true)) {
2763	return true;
2764	}
2765
2766	if (!preg_match('/^(.*)-\d+\.xml$/i', $name, $m)) {
2767	return false;
2768	}
2769
2770	return in_array($m[1] . '.xml', $names, true);
2771	}
2772
2773	/**
2774	* Transient key for a rendered document.
2775	*
2776	* @since 2.9.0
2777	*
2778	* @param string $filename Published file name.
2779	* @return string
2780	*/
2781	private function dynamic_cache_key(string $filename): string {
2782	return self::DYNAMIC_CACHE_PREFIX . md5($filename);
2783	}
2784
2785	/**
2786	* Drop every cached dynamic document.
2787	*
2788	* Called from the same places that mark the static files stale, so the two
2789	* delivery modes invalidate on identical triggers.
2790	*
2791	* @since 2.9.0
2792	*
2793	* @return void
2794	*/
2795	public function flush_dynamic_cache(): void {
2796	foreach ($this->published_document_names() as $name) {
2797	delete_transient($this->dynamic_cache_key($name));
2798	}
2799	}
2800
2801	/**
2802	* Resolve index-vs-single mode, synthesizing child sitemaps when needed.
2803	*
2804	* - When use_sitemap_index is on but no child sitemaps are configured, build
2805	* the per-type segmented set so a real <sitemapindex> is produced (#127).
2806	* - When the toggle is off but a single flat file would exceed the per-file
2807	* URL cap, auto-promote to a paginated index instead of one oversized file
2808	* that can cross Google's 50k-URL/50MB limits (#129).
2809	*
2810	* @param array $settings Sitemap settings.
2811	* @return array Possibly-updated settings.
2812	*/
2813	public function maybe_promote_to_index(array $settings): array {
2814	$saved = $this->get_settings('site');
2815
2816	// Read from the payload, before the merge below folds the saved values
2817	// in: "the caller named this" and "this has a value" are different
2818	// questions, and the mode resolution turns on the former.
2819	$mode_supplied = array_key_exists('use_sitemap_index', $settings);
2820	$urls_supplied = is_array($settings['sitemap_urls'] ?? null);
2821	$has_children = count($urls_supplied ? $settings['sitemap_urls'] : []) > 1;
2822
2823	// Which inclusion flags did the caller actually name? The child list is
2824	// the only thing that reads them, and inheriting a saved one skipped
2825	// that — so on an index-mode site the include_* flags were enforced
2826	// nowhere but in the browser, where SitemapGeneration.js recomputes
2827	// sitemap_urls itself. Every non-UI client, the shipped
2828	// `update-sitemap-settings` ability included, saved the flag and changed
2829	// nothing (#398). Read from the payload for the same reason as above:
2830	// after the merge every saved flag would look like one the caller named.
2831	$named_inclusions = array_intersect(
2832	array_keys(self::INCLUSION_CHILD_TYPES),
2833	array_keys($settings)
2834	);
2835	$inclusions_supplied = (bool) $named_inclusions;
2836
2837	// Inclusion flags may be absent from a partial payload (e.g. the manual
2838	// generate endpoint) — fall back to saved settings so synthesized child
2839	// sitemaps reflect the real include_posts/pages/categories choices.
2840	$inclusions = array_merge($saved, $settings);
2841
2842	// Hand the generators a complete settings array. Only the mode was
2843	// resolved before, so every other unnamed key reached them missing: a
2844	// bare `{}` from a REST/MCP client republished the sitemap with
2845	// enable_styling and include_images read as off, overwriting the live
2846	// files with output that had lost its XSL stylesheet, its image
2847	// namespace and its image entries. Presentation and inclusion settings
2848	// are not something a generate call opts into — they are the site's
2849	// configuration, and only a value actually present in the payload
2850	// overrides them.
2851	$settings = $inclusions;
2852
2853	// The two keys that drive mode keep their own resolution rules below,
2854	// so they must go back to "not specified" when the caller omitted them.
2855	if (!$mode_supplied) {
2856	unset($settings['use_sitemap_index']);
2857	}
2858	if (!$urls_supplied) {
2859	unset($settings['sitemap_urls']);
2860	}
2861
2862	// An absent use_sitemap_index means "not specified", which is not the
2863	// same as "single file". Reading it as the latter meant a partial payload
2864	// — `{}` from a REST/MCP client, or anything short of the full settings
2865	// object the admin bundle sends — republished one flat sitemap.xml on an
2866	// index-mode site and left sitemap_index.xml and its children stale or
2867	// missing. Inherit the saved mode instead; only a value actually present
2868	// in the payload decides the mode.
2869	if (!array_key_exists('use_sitemap_index', $settings)) {
2870	$settings['use_sitemap_index'] = $saved['use_sitemap_index'] ?? '';
2871
2872	// Inheriting the mode means inheriting its children too, unless the
2873	// caller named its own set.
2874	$saved_children = (is_array($saved['sitemap_urls'] ?? null) ? $saved['sitemap_urls'] : []);
2875	if (!empty($settings['use_sitemap_index'])
2876	&& !$urls_supplied
2877	&& count($saved_children) > 1) {
2878	// A named inclusion flag is applied to the inherited list, not
2879	// used to regenerate it. build_segmented_sitemap_urls() also adds
2880	// a child for every public custom post type, so rebuilding here
2881	// would make `{include_pages: false}` — one thing off — silently
2882	// switch on children the saved list never had (an Elementor
2883	// internal CPT, a WooCommerce product feed). Only the flags the
2884	// caller actually named change anything.
2885	$settings['sitemap_urls'] = $inclusions_supplied
2886	? $this->apply_inclusion_flags_to_children($saved_children, $named_inclusions, $inclusions)
2887	: $saved_children;
2888
2889	// The children are resolved either way — including when the
2890	// caller switched the last one off, which leaves a bare index and
2891	// is what they asked for.
2892	$has_children = true;
2893	}
2894	}
2895
2896	if (!empty($settings['use_sitemap_index'])) {
2897	if (!$has_children) {
2898	$settings['sitemap_urls'] = $this->build_segmented_sitemap_urls($inclusions);
2899	}
2900	return $settings;
2901	}
2902
2903	if (!$has_children) {
2904	$limit = $this->get_links_per_sitemap($settings);
2905	if ($limit > 0 && $this->estimate_total_sitemap_urls($inclusions) > $limit) {
2906	$settings['use_sitemap_index'] = true;
2907	$settings['sitemap_urls'] = $this->build_segmented_sitemap_urls($inclusions);
2908	}
2909	}
2910
2911	return $settings;
2912	}
2913
2914	/**
2915	* Rough count of URLs a single-file sitemap would contain, used only to
2916	* decide whether to auto-promote to a paginated index. Cheap COUNT queries;
2917	* intentionally approximate (homepage + published posts of enabled types +
2918	* terms of enabled taxonomies).
2919	*
2920	* @param array $settings Sitemap settings.
2921	* @return int
2922	*/
2923	private function estimate_total_sitemap_urls(array $settings): int {
2924	$total = 1; // homepage
2925
2926	foreach ($this->get_enabled_post_types($settings) as $post_type) {
2927	$counts = wp_count_posts($post_type);
2928	$total += isset($counts->publish) ? (int) $counts->publish : 0;
2929	}
2930
2931	foreach ($this->get_enabled_taxonomies($settings) as $taxonomy) {
2932	$count = wp_count_terms(['taxonomy' => $taxonomy, 'hide_empty' => true]);
2933	if (!is_wp_error($count)) {
2934	$total += (int) $count;
2935	}
2936	}
2937
2938	return $total;
2939	}
2940
2941	/**
2942	* Resolve the sitemap file the site publishes for the given settings.
2943	*
2944	* Index mode serves the index (`sitemap_index.xml`); the default single-file
2945	* mode serves `sitemap.xml`. Callers use this to link to — or check for —
2946	* the file the site actually serves, since ThinkRank's sitemap is a static
2947	* file in the web root rather than a route.
2948	*
2949	* @since 1.17.0
2950	* @param array $settings Sitemap settings.
2951	* @return string Sitemap filename.
2952	*/
2953	public function get_primary_sitemap_filename(array $settings): string {
2954	return thinkrank_webroot_primary_sitemap_filename($settings);
2955	}
2956
2957	/**
2958	* Public URL of the sitemap the site serves.
2959	*
2960	* @since 1.17.0
2961	* @param array\|null $settings Sitemap settings (falls back to saved site settings).
2962	* @return string Absolute sitemap URL.
2963	*/
2964	public function get_primary_sitemap_url(?array $settings = null): string {
2965	$settings = $settings ?? $this->get_settings('site');
2966
2967	return home_url('/' . $this->get_primary_sitemap_filename($settings));
2968	}
2969
2970	/**
2971	* Whether the sitemap file this site publishes exists on disk.
2972	*
2973	* @since 1.17.0
2974	* @param array $settings Sitemap settings.
2975	* @return bool True when the file is present.
2976	*/
2977	public function primary_sitemap_file_exists(array $settings): bool {
2978	return file_exists(ABSPATH . $this->get_primary_sitemap_filename($settings));
2979	}
2980
2981	/**
2982	* Save sitemap XML to file
2983	*
2984	* @since 1.0.0
2985	* @param string $sitemap_xml Sitemap XML content
2986	* @param string $filename Optional. Filename to save (defaults to 'sitemap.xml')
2987	* @return bool True on success, false on failure
2988	*/
2989	private function save_sitemap_to_file(string $sitemap_xml, string $filename = 'sitemap.xml'): bool {
2990	// Validate and sanitize filename for security
2991	try {
2992	$filename = $this->validate_sitemap_filename($filename);
2993	} catch (InvalidArgumentException $e) {
2994	// File validation failed - error details available in exception
2995	return false;
2996	}
2997
2998	// Dynamic delivery: hand the document to the collector instead of the
2999	// filesystem. Reported as published, because for this run it is — the
3000	// caller's success/failure bookkeeping and the index assembly both key
3001	// off this return value.
3002	if ($this->document_sink !== null) {
3003	($this->document_sink)($filename, $sitemap_xml);
3004
3005	return true;
3006	}
3007
3008	$sitemap_path = ABSPATH . $filename;
3009
3010	// Use WordPress filesystem API for better security
3011	global $wp_filesystem;
3012	if (!$wp_filesystem) {
3013	require_once ABSPATH . 'wp-admin/includes/file.php';
3014	WP_Filesystem();
3015	}
3016
3017	if ($wp_filesystem) {
3018	$written = $wp_filesystem->put_contents($sitemap_path, $sitemap_xml, FS_CHMOD_FILE);
3019
3020	if ($written) {
3021	// Every sitemap this version writes carries the ownership
3022	// marker, so once one has been written an unmarked file at one
3023	// of our names cannot be ours. Recording that retires the
3024	// legacy fallback for this install — see
3025	// thinkrank_webroot_sitemap_is_ours().
3026	if (get_option(THINKRANK_SITEMAP_MARKED_WRITE_OPTION) !== '1') {
3027	update_option(THINKRANK_SITEMAP_MARKED_WRITE_OPTION, '1', false);
3028	}
3029	}
3030
3031	return $written;
3032	}
3033
3034	// WP_Filesystem initialization failed
3035	return false;
3036	}
3037
3038	/**
3039	* Build a segmented, index-based sitemap_urls list from inclusion settings.
3040	*
3041	* Produces the index entry plus one child sitemap per enabled content type
3042	* (posts/pages/categories) and one per public custom post type — the shape
3043	* the "complete" preset creates and that generate_multiple_sitemaps() expects.
3044	* Used when enabling the index during import so the index has real children
3045	* instead of being empty.
3046	*
3047	* @since 1.14.0
3048	*
3049	* @param array $inclusions Inclusion flags (include_posts/pages/categories)
3050	* and optionally custom_url_pattern.
3051	* @return array Sitemap URL configs
3052	*/
3053	public function build_segmented_sitemap_urls(array $inclusions): array {
3054	$pattern = $inclusions['custom_url_pattern'] ?? 'sitemap-{type}.xml';
3055
3056	$urls = [$this->sitemap_child_entry('/sitemap_index.xml', 'index')];
3057
3058	foreach (self::INCLUSION_CHILD_TYPES as $flag => $type) {
3059	if (!empty($inclusions[$flag])) {
3060	$urls[] = $this->build_child_sitemap_entry($type, $pattern);
3061	}
3062	}
3063
3064	// Public custom post types each get a child sitemap (parity with the
3065	// "complete" preset and with Rank Math, which lists every public CPT).
3066	foreach (get_post_types(['public' => true, '_builtin' => false], 'names') as $cpt) {
3067	if (!$this->should_include_post_type($cpt)) {
3068	continue;
3069	}
3070
3071	// ...and the per-content-type sitemap switch (#660).
3072	// get_enabled_post_types() already honours it, but this list is what
3073	// index mode builds its children from — so without the same test a
3074	// CPT the user had switched off still got its own child sitemap,
3075	// created and streamed in full. The flags live in $inclusions, which
3076	// is the settings array these children are derived from.
3077	if (!\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('post_type', $cpt, $inclusions)) {
3078	continue;
3079	}
3080
3081	$urls[] = $this->build_child_sitemap_entry($cpt, $pattern);
3082	}
3083
3084	// Public custom taxonomies get the same treatment (#690). Flat mode has
3085	// always walked them through get_enabled_taxonomies(); index mode built
3086	// its children from the list above and never consulted a taxonomy at
3087	// all, so every custom-taxonomy archive silently vanished from the
3088	// sitemap the moment a site switched modes — and the per-taxonomy switch
3089	// the matrix writes had nothing to act on. Same two tests the post-type
3090	// walk applies, in the same order.
3091	$taken = array_column($urls, 'type');
3092
3093	foreach (get_taxonomies(['public' => true, '_builtin' => false], 'names') as $taxonomy) {
3094	if (!$this->should_include_taxonomy($taxonomy)) {
3095	continue;
3096	}
3097
3098	if (!\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('taxonomy', $taxonomy, $inclusions)) {
3099	continue;
3100	}
3101
3102	// Post types and taxonomies are separate registries, so a site can
3103	// hold both a `foo` post type and a `foo` taxonomy. They would
3104	// resolve to one filename, and stream_type_entries() answers post
3105	// types first, so the second child would list the first one's file
3106	// twice in the index rather than adding anything.
3107	if (in_array($taxonomy, $taken, true)) {
3108	continue;
3109	}
3110
3111	$urls[] = $this->build_child_sitemap_entry($taxonomy, $pattern);
3112	}
3113
3114	return $urls;
3115	}
3116
3117	/**
3118	* Apply only the inclusion flags the caller named to an existing child list.
3119	*
3120	* The narrow counterpart to build_segmented_sitemap_urls(): that one
3121	* regenerates the whole set from scratch, which is right when there is no set
3122	* yet and wrong when there is. Rebuilding an existing list would add a child
3123	* for every public custom post type it had never contained, so a payload that
3124	* switches one thing off would switch others on. Here a flag adds or removes
3125	* exactly its own child and leaves every other entry — custom post types,
3126	* hand-added URLs, per-child enabled/status state — untouched (#398).
3127	*
3128	* @since 1.31.0
3129	*
3130	* @param array $children Existing child sitemap entries.
3131	* @param string[] $named_inclusions Inclusion flag keys present in the payload.
3132	* @param array $inclusions Merged settings, for the resolved flag
3133	* values and custom_url_pattern.
3134	* @return array Updated child sitemap entries.
3135	*/
3136	private function apply_inclusion_flags_to_children(
3137	array $children,
3138	array $named_inclusions,
3139	array $inclusions
3140	): array {
3141	$pattern = $inclusions['custom_url_pattern'] ?? 'sitemap-{type}.xml';
3142
3143	foreach ($named_inclusions as $flag) {
3144	$type = self::INCLUSION_CHILD_TYPES[$flag];
3145
3146	$present = false;
3147	foreach ($children as $entry) {
3148	if (($entry['type'] ?? '') === $type) {
3149	$present = true;
3150	break;
3151	}
3152	}
3153
3154	if (empty($inclusions[$flag])) {
3155	if ($present) {
3156	$children = array_values(array_filter(
3157	$children,
3158	static function ($entry) use ($type): bool {
3159	return (is_array($entry) ? ($entry['type'] ?? '') : '') !== $type;
3160	}
3161	));
3162	}
3163	continue;
3164	}
3165
3166	if (!$present) {
3167	$children[] = $this->build_child_sitemap_entry($type, $pattern);
3168	}
3169	}
3170
3171	return $children;
3172	}
3173
3174	/**
3175	* Build one child sitemap entry, resolving its filename from the url pattern.
3176	*
3177	* @since 1.31.0
3178	*
3179	* @param string $type Child sitemap type (posts, pages, a post type name).
3180	* @param string $pattern Filename pattern containing {type}.
3181	* @return array Sitemap URL config.
3182	*/
3183	private function build_child_sitemap_entry(string $type, string $pattern): array {
3184	$file = str_replace('{type}', $type, $pattern);
3185	if (strpos($file, '/') !== 0) {
3186	$file = '/' . $file;
3187	}
3188
3189	return $this->sitemap_child_entry($file, $type);
3190	}
3191
3192	/**
3193	* The shape generate_multiple_sitemaps() expects of a sitemap_urls entry.
3194	*
3195	* @since 1.31.0
3196	*
3197	* @param string $url Sitemap path.
3198	* @param string $type Entry type.
3199	* @return array Sitemap URL config.
3200	*/
3201	private function sitemap_child_entry(string $url, string $type): array {
3202	return [
3203	'url' => $url,
3204	'type' => $type,
3205	'enabled' => true,
3206	'last_checked' => null,
3207	'status' => 'unknown',
3208	];
3209	}
3210
3211	/**
3212	* Generate multiple sitemaps based on settings
3213	*
3214	* @since 1.0.0
3215	* @param array $settings Sitemap settings
3216	* @return array Results of sitemap generation
3217	*/
3218	public function generate_multiple_sitemaps(array $settings): array {
3219	$results = [
3220	'success' => true,
3221	'sitemaps_generated' => [],
3222	'errors' => [],
3223	'total_urls' => 0
3224	];
3225
3226	$sitemap_urls = (is_array($settings['sitemap_urls'] ?? null) ? $settings['sitemap_urls'] : []);
3227
3228	if (empty($sitemap_urls)) {
3229	$results['success'] = false;
3230	$results['errors'][] = 'No sitemap URLs configured';
3231	return $results;
3232	}
3233
3234	$limit = $this->get_links_per_sitemap($settings);
3235
3236	// Defer the index until every child sitemap has been generated, so it can
3237	// list the actual files produced (including pagination pages).
3238	$index_config = null;
3239	$index_children = [];
3240
3241	foreach ($sitemap_urls as $sitemap_config) {
3242	if (empty($sitemap_config['enabled'])) {
3243	continue;
3244	}
3245
3246	$type = $sitemap_config['type'];
3247
3248	if ($type === 'index') {
3249	$index_config = $sitemap_config;
3250	continue;
3251	}
3252
3253	// Skip CPT children that no longer qualify (e.g. an internal store
3254	// like Templately's `templately_library`) even when a previously
3255	// saved config still lists them. Built-in aggregate types ('posts',
3256	// 'pages', 'general', etc.) are not post type names, so this only
3257	// affects real custom post types.
3258	if (post_type_exists($type) && !$this->should_include_post_type($type)) {
3259	continue;
3260	}
3261
3262	// Same for the matrix switch: a child list saved before the user
3263	// excluded this content type still names it, and regenerating from
3264	// that list would rewrite the file they asked not to have. Built-in
3265	// aggregates ('posts', 'pages', ...) are not post type names, so
3266	// post_type_exists() keeps this to real custom post types.
3267	if (post_type_exists($type)
3268	&& !\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('post_type', $type, $settings)) {
3269	continue;
3270	}
3271
3272	// The taxonomy counterpart of the two guards above (#690). A child
3273	// list saved while a taxonomy was still included keeps naming it, so
3274	// without this, excluding one in the matrix would still rewrite and
3275	// re-list the file the user asked not to have. The built-in
3276	// aggregates are named 'categories'/'tags' rather than
3277	// 'category'/'post_tag', so taxonomy_exists() leaves them to the
3278	// inclusion-flag check below.
3279	$child_taxonomy = self::CHILD_TYPE_ALIASES[$type] ?? $type;
3280	if (taxonomy_exists($child_taxonomy)
3281	&& (!$this->should_include_taxonomy($child_taxonomy)
3282	\|\| !\ThinkRank\SEO\Content_Type_Settings::is_included_in_sitemap('taxonomy', $child_taxonomy, $settings))) {
3283	continue;
3284	}
3285
3286	// The built-in aggregates carry their switch in the inclusion flag
3287	// rather than under a post type name, and they are the four most
3288	// people actually use. build_segmented_sitemap_urls() drops a child
3289	// whose flag is empty; regenerating from a list saved while it was
3290	// still on has to make the same decision, or turning Posts, Pages,
3291	// Categories or Tags off in the matrix rewrites and re-lists the
3292	// very file it was asked to remove.
3293	// An absent flag means "not configured", which every other reader
3294	// treats as included; only a flag that is present and off excludes.
3295	$aggregate_flag = array_search($type, self::INCLUSION_CHILD_TYPES, true);
3296	if ($aggregate_flag !== false
3297	&& array_key_exists($aggregate_flag, $settings)
3298	&& empty($settings[$aggregate_flag])) {
3299	continue;
3300	}
3301
3302	try {
3303	// The single "general"/"WordPress" sitemap is one un-paginated file
3304	// (there is no index to reference extra pages); it no longer drops
3305	// overflow URLs.
3306	if ($type === 'general' \|\| $type === 'wordpress') { // phpcs:ignore WordPress.WP.CapitalPDangit.MisspelledInText -- lowercase on purpose: this is the stored type slug.
3307	$xml = $this->generate_sitemap($settings);
3308	$this->write_sitemap_page($sitemap_config['url'], $xml, $type, $this->count_urls_in_xml($xml), $results, $index_children);
3309	continue;
3310	}
3311
3312	$source = $this->stream_type_entries($type, $settings);
3313
3314	// Unknown type — fall back to a single general sitemap file.
3315	if ($source === null) {
3316	$xml = $this->generate_sitemap($settings);
3317	$this->write_sitemap_page($sitemap_config['url'], $xml, $type, $this->count_urls_in_xml($xml), $results, $index_children);
3318	continue;
3319	}
3320
3321	// Stream the entries into files of at most $limit URLs, matching
3322	// Rank Math: page 1 keeps the base filename, pages 2+ get a -N
3323	// suffix, and every page is listed in the index. Buffering only one
3324	// page at a time keeps peak memory bounded to $limit entries rather
3325	// than every URL of the type.
3326	$image_ns = $source['image_ns'];
3327	$buffer = [];
3328	$page = 0;
3329
3330	foreach ($source['entries'] as $entry) {
3331	$buffer[] = $entry;
3332	if (count($buffer) >= $limit) {
3333	$page++;
3334	$this->write_sitemap_page($this->paginate_url($sitemap_config['url'], $page), $this->wrap_urlset($buffer, $settings, $image_ns), $type, count($buffer), $results, $index_children);
3335	$buffer = [];
3336	}
3337	}
3338
3339	// Flush the trailing partial page, or a single empty page when the
3340	// type had no entries at all (parity with the previous behavior of
3341	// always writing at least one page per configured child).
3342	if (!empty($buffer) \|\| $page === 0) {
3343	$page++;
3344	$this->write_sitemap_page($this->paginate_url($sitemap_config['url'], $page), $this->wrap_urlset($buffer, $settings, $image_ns), $type, count($buffer), $results, $index_children);
3345	}
3346
3347	// Remove pages left over from a previous, larger generation.
3348	$this->cleanup_stale_pages($sitemap_config['url'], $page, $settings);
3349
3350	} catch (\Exception $e) {
3351	$results['errors'][] = "Error generating {$type} sitemap: " . $e->getMessage();
3352	$results['success'] = false;
3353	}
3354	}
3355
3356	// Local business sitemap (parity with Rank Math's local-sitemap.xml).
3357	// The physical file is written whenever a business identity is
3358	// configured — independent of segmented vs single mode — and is also
3359	// listed in the sitemap index when one exists.
3360	try {
3361	if ($this->regenerate_local_sitemap($settings) && $index_config !== null) {
3362	$index_children[] = ['url' => '/local-sitemap.xml'];
3363	}
3364	} catch (\Exception $e) {
3365	$results['errors'][] = 'Error generating local sitemap: ' . $e->getMessage();
3366	$results['success'] = false;
3367	}
3368
3369	// Build the index last, from the child files actually generated, plus the
3370	// sitemaps other plugins own: those serve their own URLs and write no
3371	// file here, so they are appended to the index only (#104).
3372	if ($index_config !== null) {
3373	foreach (self::additional_sitemaps() as $extra) {
3374	$index_children[] = ['url' => $extra];
3375	}
3376
3377	try {
3378	$index_xml = $this->generate_sitemap_index($index_children, $settings);
3379	$filename = basename(wp_parse_url($index_config['url'], PHP_URL_PATH));
3380
3381	if ($this->save_sitemap_to_file($index_xml, $filename)) {
3382	$results['sitemaps_generated'][] = [
3383	'url' => $index_config['url'],
3384	'type' => 'index',
3385	'filename' => $filename,
3386	'url_count' => count($index_children),
3387	];
3388	} else {
3389	$results['errors'][] = "Failed to save sitemap: {$filename}";
3390	$results['success'] = false;
3391	}
3392	} catch (\Exception $e) {
3393	$results['errors'][] = 'Error generating index sitemap: ' . $e->getMessage();
3394	$results['success'] = false;
3395	}
3396	}
3397
3398	// Remove segments that are no longer part of the set. Publishing was
3399	// purely additive: a type that dropped out (Categories unticked, a CPT
3400	// that stopped qualifying) simply stopped being overwritten, so its file
3401	// kept serving and — until the index happened to be rebuilt — kept being
3402	// listed in it. The index above is built from the children actually
3403	// generated, so pruning here leaves disk and index agreeing.
3404	$this->prune_orphaned_segments($settings, $results['sitemaps_generated']);
3405
3406	return $results;
3407	}
3408
3409	/**
3410	* Delete published segment files that this run did not write.
3411	*
3412	* Only filenames this site could have published under its own url pattern
3413	* are considered, so another plugin's or core's sitemap in the web root is
3414	* never a candidate — the same reason cleanup does not glob 'sitemap-*.xml'.
3415	*
3416	* @since 1.31.0
3417	*
3418	* @param array $settings Sitemap settings (read for `custom_url_pattern`).
3419	* @param array $generated Entries from $results['sitemaps_generated'].
3420	* @return string[] Basenames removed.
3421	*/
3422	private function prune_orphaned_segments(array $settings, array $generated): array {
3423	// Rendering for a request, not publishing: there is nothing on disk
3424	// this run owns, and a dynamic render must never delete the files a
3425	// site's previous static mode left behind.
3426	if ($this->is_collecting()) {
3427	return [];
3428	}
3429
3430	$kept = [];
3431	foreach ($generated as $entry) {
3432	if (!empty($entry['filename'])) {
3433	$kept[strtolower((string) $entry['filename'])] = true;
3434	}
3435	}
3436
3437	// The current mode's primary and the local business sitemap are written
3438	// by their own paths and are never orphans here.
3439	$primary = strtolower(basename($this->get_primary_sitemap_filename($settings)));
3440	$kept[$primary] = true;
3441	$kept['local-sitemap.xml'] = true;
3442
3443	// The OTHER mode's primary is an orphan the moment the mode changes:
3444	// index mode leaves sitemap.xml behind, flat mode leaves
3445	// sitemap_index.xml and its children. Both used to be kept
3446	// unconditionally, so the site served two sitemap trees and only ever
3447	// refreshed one (#563). The children are already covered by the segment
3448	// sweep below, which now sees them because the index is no longer kept.
3449	$stale_primaries = array_diff(['sitemap.xml', 'sitemap_index.xml'], [$primary]);
3450
3451	$removed = [];
3452
3453	global $wp_filesystem;
3454	if (!$wp_filesystem) {
3455	require_once ABSPATH . 'wp-admin/includes/file.php';
3456	WP_Filesystem();
3457	}
3458	if (!$wp_filesystem) {
3459	return $removed;
3460	}
3461
3462	$candidates = array_merge($this->publishable_segment_filenames($settings), $stale_primaries);
3463
3464	foreach ($candidates as $candidate) {
3465	if (isset($kept[strtolower($candidate)])) {
3466	continue;
3467	}
3468
3469	if (!preg_match('/^(.*)\.xml$/i', $candidate, $m)) {
3470	continue;
3471	}
3472
3473	// The base file plus its numeric pagination pages.
3474	$paths = [ABSPATH . $candidate];
3475	foreach (glob(ABSPATH . $m[1] . '-*.xml') ?: [] as $paged) {
3476	if (preg_match('/^' . preg_quote($m[1], '/') . '-\d+\.xml$/i', basename($paged))) {
3477	$paths[] = $paged;
3478	}
3479	}
3480
3481	foreach ($paths as $path) {
3482	if (!file_exists($path)) {
3483	continue;
3484	}
3485	// A name we could have published is not proof we published
3486	// this file: RankMath and core write at the same paths (#515).
3487	if (!$this->webroot_sitemap_is_ours($path, $settings)) {
3488	continue;
3489	}
3490	if ($wp_filesystem->delete($path)) {
3491	$removed[] = basename($path);
3492	}
3493	}
3494	}
3495
3496	return $removed;
3497	}
3498
3499
3500	/**
3501	* Collect the full (un-paginated) entry list for a content sitemap type.
3502	*
3503	* @since 1.14.0
3504	*
3505	* @param string $type Sitemap config type (posts, pages, categories, …)
3506	* @param array $settings Sitemap settings
3507	* @return array{entries: array<string>, image_ns: bool}\|null Null for an
3508	* unknown type (caller falls back to a general sitemap).
3509	*/
3510	/**
3511	* Write (or remove) the physical local-sitemap.xml file.
3512	*
3513	* Called from every sitemap regeneration path — segmented generation, the
3514	* single-sitemap auto-regeneration, and the manual generate endpoint — so
3515	* the local sitemap works regardless of whether the site uses a sitemap
3516	* index. When no business identity is configured, any stale file is removed.
3517	*
3518	* @since 1.15.x
3519	* @param array\|null $settings Sitemap settings (falls back to saved site settings).
3520	* @return bool True when the file was written, false when nothing was written.
3521	*/
3522	public function regenerate_local_sitemap(?array $settings = null): bool {
3523	$settings = $settings ?? $this->get_settings('site');
3524	$entries = $this->collect_local_entries();
3525
3526	if (empty($entries)) {
3527	// Business identity was cleared — drop the file we left from
3528	// before, but only ours. `local-sitemap.xml` is the name Rank Math
3529	// publishes under too (this method mirrors it deliberately), so on
3530	// a migrated site the file at that path may never have been ours
3531	// to delete (#515).
3532	$path = ABSPATH . 'local-sitemap.xml';
3533	if (!$this->is_collecting() && file_exists($path) && $this->webroot_sitemap_is_ours($path, $settings)) {
3534	wp_delete_file($path);
3535	}
3536	return false;
3537	}
3538
3539	$xml = $this->wrap_urlset($entries, $settings, false);
3540	return $this->save_sitemap_to_file($xml, 'local-sitemap.xml');
3541	}
3542
3543	/**
3544	* Build the local business sitemap entries.
3545	*
3546	* Returns a single URL entry pointing at the on-site page that carries the
3547	* business's LocalBusiness/Organization schema (the configured business URL
3548	* when it's on this site, otherwise the homepage). Gated — like Rank Math's
3549	* `local-sitemap.xml` — on a business (non-person) type being configured
3550	* with an actual location (address or geo coordinates). Returns an empty
3551	* array when no business location is set, so no empty local sitemap is
3552	* written or added to the index.
3553	*
3554	* @since 1.15.x
3555	* @return array Zero or one URL entry
3556	*/
3557	/**
3558	* Does this site publish a local business sitemap right now?
3559	*
3560	* The same gate {@see self::regenerate_local_sitemap()} applies, asked
3561	* without writing anything. Callers that need to know whether the document
3562	* exists must not test the filesystem: under dynamic delivery it is served
3563	* from PHP and there is no file, which is how `local-sitemap.xml` came to be
3564	* dropped from robots.txt on exactly those sites (#752).
3565	*
3566	* @since 2.9.0
3567	*
3568	* @return bool True when the local sitemap has content to publish.
3569	*/
3570	public function publishes_local_sitemap(): bool {
3571	return !empty($this->collect_local_entries());
3572	}
3573
3574	private function collect_local_entries(): array {
3575	if (!class_exists('ThinkRank\\SEO\\Site_Identity_Manager')) {
3576	require_once THINKRANK_PLUGIN_DIR . 'includes/seo/class-site-identity-manager.php';
3577	}
3578
3579	$identity = (new \ThinkRank\SEO\Site_Identity_Manager())->get_settings('site');
3580
3581	// Gate like Rank Math's local sitemap: a business (non-person) identity
3582	// is configured. We only emit a single URL (the location page), so a
3583	// full postal address is NOT required — requiring one wrongly excluded
3584	// migrated sites, since the Rank Math importer carries over business
3585	// type/name/phone but not the address. Personal sites, and sites with no
3586	// business identity at all, get no local sitemap.
3587	$business_type = strtolower((string) ($identity['business_type'] ?? ''));
3588	if ($business_type === 'person') {
3589	return [];
3590	}
3591	if ($business_type === '' && empty($identity['business_name'])) {
3592	return [];
3593	}
3594
3595	// Prefer the configured business URL when it points at this site;
3596	// otherwise fall back to the homepage (which outputs the schema).
3597	$location_url = home_url('/');
3598	if (!empty($identity['business_url'])) {
3599	$candidate = esc_url_raw((string) $identity['business_url']);
3600	if ($candidate && wp_parse_url($candidate, PHP_URL_HOST) === wp_parse_url(home_url(), PHP_URL_HOST)) {
3601	$location_url = $candidate;
3602	}
3603	}
3604
3605	// Omit lastmod — no real modification source for the local business URL.
3606	return [$this->generate_url_entry($location_url, '', 0.8, 'weekly')];
3607	}
3608
3609	/**
3610	* Resolve a streaming entry source for a sitemap type.
3611	*
3612	* Returns an iterable that yields the type's <url> entries one at a time
3613	* (so the paginator never materializes the whole type), the image-namespace
3614	* flag, or null when the type isn't one we build (caller falls back to a
3615	* single general sitemap). Entry order matches the previous array-based
3616	* collect_type_entries() exactly.
3617	*
3618	* @param string $type Sitemap type.
3619	* @param array $settings Sitemap settings.
3620	* @return array{entries: iterable<string>, image_ns: bool}\|null
3621	*/
3622	private function stream_type_entries(string $type, array $settings): ?array {
3623	switch ($type) {
3624	case 'posts':
3625	return ['entries' => $this->collect_post_entries_iter(['post'], $settings), 'image_ns' => true];
3626
3627	case 'pages':
3628	// The homepage lives in the pages sitemap (parity with prior
3629	// output) and is emitted first; collect_post_entries_iter()
3630	// already excludes the static front page, so there's no duplicate.
3631	$entries = (function () use ($settings) {
3632	yield $this->generate_url_entry(home_url('/'), $this->get_homepage_lastmod(), 1.0, 'daily');
3633	yield from $this->collect_post_entries_iter(['page'], $settings);
3634	})();
3635	return ['entries' => $entries, 'image_ns' => true];
3636
3637	case 'categories':
3638	return ['entries' => $this->collect_taxonomy_entries_iter('category', $settings), 'image_ns' => false];
3639
3640	case 'tags':
3641	return ['entries' => $this->collect_taxonomy_entries_iter('post_tag', $settings), 'image_ns' => false];
3642
3643	case 'products':
3644	$entries = post_type_exists('product') ? $this->collect_post_entries_iter(['product'], $settings) : [];
3645	return ['entries' => $entries, 'image_ns' => true];
3646
3647	default:
3648	// Resolve a preset's display name to the object it streams, so
3649	// 'product_categories' is an ordinary taxonomy child rather than
3650	// a case of its own (#690).
3651	$alias = self::CHILD_TYPE_ALIASES[$type] ?? null;
3652	$object = $alias ?? $type;
3653
3654	$custom_post_types = get_post_types(['public' => true, '_builtin' => false], 'names');
3655	if (in_array($object, $custom_post_types, true)) {
3656	return ['entries' => $this->collect_post_entries_iter([$object], $settings), 'image_ns' => true];
3657	}
3658
3659	// Custom taxonomies reach index mode here, streamed through the
3660	// same iterator flat mode uses so the two modes emit identical
3661	// URLs for the same settings.
3662	if (taxonomy_exists($object) && $this->should_include_taxonomy($object)) {
3663	return ['entries' => $this->collect_taxonomy_entries_iter($object, $settings), 'image_ns' => false];
3664	}
3665
3666	// An aliased child whose object is gone (WooCommerce deactivated)
3667	// keeps writing the empty file it always wrote. Returning null
3668	// here would hand it the whole-site fallback instead, dumping
3669	// every URL on the site into a file named for products.
3670	//
3671	// A registered taxonomy this generator will not emit
3672	// (`post_format`, `nav_menu`, a non-public one) needs the same
3673	// answer for the same reason. generate_multiple_sitemaps()
3674	// skips those before they reach here, so nothing takes this
3675	// path today — but it is the one branch where falling through
3676	// to null is silently catastrophic rather than merely wrong,
3677	// and the guard keeping it unreachable lives in another method.
3678	if ($alias !== null \|\| taxonomy_exists($object)) {
3679	return ['entries' => [], 'image_ns' => false];
3680	}
3681
3682	return null;
3683	}
3684	}
3685
3686	/**
3687	* Write one sitemap page file and record it in the results + index child list.
3688	*
3689	* @since 1.14.0
3690	*
3691	* @param string $url Sitemap page URL
3692	* @param string $xml Sitemap XML
3693	* @param string $type Sitemap type (for reporting)
3694	* @param int $url_count Number of URLs in this page
3695	* @param array $results Results accumulator (by reference)
3696	* @param array $index_children Index child list (by reference)
3697	* @return void
3698	*/
3699	private function write_sitemap_page(string $url, string $xml, string $type, int $url_count, array &$results, array &$index_children): void {
3700	$filename = basename(wp_parse_url($url, PHP_URL_PATH));
3701
3702	if ($this->save_sitemap_to_file($xml, $filename)) {
3703	$results['sitemaps_generated'][] = [
3704	'url' => $url,
3705	'type' => $type,
3706	'filename' => $filename,
3707	'url_count' => $url_count,
3708	];
3709	$results['total_urls'] += $url_count;
3710	$index_children[] = ['url' => $url];
3711	} else {
3712	$results['errors'][] = "Failed to save sitemap: {$filename}";
3713	$results['success'] = false;
3714	}
3715	}
3716
3717	/**
3718	* Delete pagination files left over when a type shrinks to fewer pages.
3719	*
3720	* For a base URL like /sitemap-posts.xml, removes sitemap-posts-N.xml files
3721	* whose page number N exceeds the current page count. Page 1 (the base file,
3722	* which has no -N suffix) is never touched.
3723	*
3724	* @since 1.14.0
3725	*
3726	* @since 2.1.1 Each candidate must pass the content ownership test — a
3727	* `-N.xml` page of another plugin's sitemap paginates our
3728	* stem exactly as ours does (#515).
3729	*
3730	* @param string $base_url Base (page 1) sitemap URL
3731	* @param int $current_pages Number of pages generated this run
3732	* @param array $settings Sitemap settings, for the ownership test.
3733	* @return void
3734	*/
3735	private function cleanup_stale_pages(string $base_url, int $current_pages, array $settings): void {
3736	// See prune_orphaned_segments(): a dynamic render deletes nothing.
3737	if ($this->is_collecting()) {
3738	return;
3739	}
3740
3741	$filename = basename(wp_parse_url($base_url, PHP_URL_PATH));
3742	if (!preg_match('/^(.*)\.xml$/i', $filename, $m)) {
3743	return;
3744	}
3745	$stem = $m[1];
3746
3747	global $wp_filesystem;
3748	if (!$wp_filesystem) {
3749	require_once ABSPATH . 'wp-admin/includes/file.php';
3750	WP_Filesystem();
3751	}
3752	if (!$wp_filesystem) {
3753	return;
3754	}
3755
3756	$candidates = glob(ABSPATH . $stem . '-*.xml') ?: [];
3757	foreach ($candidates as $path) {
3758	// Only delete numeric-suffixed pages beyond the current count.
3759	if (preg_match('/-(\d+)\.xml$/', basename($path), $mm)
3760	&& (int) $mm[1] > $current_pages
3761	&& $this->webroot_sitemap_is_ours($path, $settings)) {
3762	$wp_filesystem->delete($path);
3763	}
3764	}
3765	}
3766
3767	/**
3768	* Sitemap URLs contributed by other plugins.
3769	*
3770	* ThinkRank owns the sitemap index and the robots.txt `Sitemap:` lines, so a
3771	* companion plugin that serves its own sitemap — Pro's news and video
3772	* sitemaps, for instance — had no way to be discovered: it appeared in
3773	* neither, leaving manual Search Console submission as the only route in
3774	* (#104). Registering here puts a sitemap in the index when one exists, and
3775	* in robots.txt when it does not.
3776	*
3777	* Callers get root-relative paths. Entries are normalised to a leading
3778	* slash, de-duplicated, and anything that is not a non-empty string is
3779	* dropped, so one badly-behaved callback cannot produce a malformed index.
3780	*
3781	* @since 2.3.1
3782	*
3783	* @return string[] Root-relative sitemap paths, e.g. ['/news-sitemap.xml'].
3784	*/
3785	public static function additional_sitemaps(): array {
3786	/**
3787	* Filters the sitemaps contributed by other plugins.
3788	*
3789	* @since 2.3.1
3790	*
3791	* @param string[] $sitemaps Root-relative sitemap paths.
3792	*/
3793	$sitemaps = apply_filters('thinkrank_additional_sitemaps', []);
3794
3795	if (!is_array($sitemaps)) {
3796	return [];
3797	}
3798
3799	// Both consumers resolve an entry with home_url(), which prefixes the
3800	// install's own directory. Everything below is measured against that so
3801	// an absolute URL is reduced to what home_url() will put back.
3802	$home = wp_parse_url(home_url('/'));
3803	$home_host = strtolower((string) ($home['host'] ?? ''));
3804	$home_path = '/' . trim((string) ($home['path'] ?? ''), '/');
3805
3806	$clean = [];
3807	foreach ($sitemaps as $sitemap) {
3808	if (!is_string($sitemap)) {
3809	continue;
3810	}
3811
3812	$sitemap = trim($sitemap);
3813	if ('' === $sitemap) {
3814	continue;
3815	}
3816
3817	// A full URL on this site is accepted and reduced to the part
3818	// home_url() does not already supply, so a caller that reached for
3819	// home_url() still lands in the right place — including on a
3820	// subdirectory install, where keeping the whole path would repeat
3821	// the directory. A URL on another host is dropped rather than
3822	// rewritten: the sitemaps protocol will not accept a cross-host
3823	// child anyway, and reusing its path would advertise a URL on this
3824	// site that does not exist.
3825	if (preg_match('#^(https?:)?//#i', $sitemap)) {
3826	$parts = wp_parse_url('//' === substr($sitemap, 0, 2) ? 'https:' . $sitemap : $sitemap);
3827	if (!is_array($parts)) {
3828	continue;
3829	}
3830
3831	if (strtolower((string) ($parts['host'] ?? '')) !== $home_host) {
3832	continue;
3833	}
3834
3835	$path = (string) ($parts['path'] ?? '');
3836	if ('' === $path) {
3837	continue;
3838	}
3839
3840	if ('/' !== $home_path && ($path === $home_path \|\| 0 === strpos($path, $home_path . '/'))) {
3841	$path = substr($path, strlen($home_path));
3842	}
3843
3844	// A sitemap served from a query string keeps it; dropping the
3845	// query would point at a different document.
3846	$query = (string) ($parts['query'] ?? '');
3847	$sitemap = $path . ('' !== $query ? '?' . $query : '');
3848	}
3849
3850	$clean[] = '/' . ltrim($sitemap, '/');
3851	}
3852
3853	return array_values(array_unique($clean));
3854	}
3855
3856	/**
3857	* Generate sitemap index XML from the list of child sitemap files produced
3858	* during generation (each already resolved to its final, possibly paginated,
3859	* URL).
3860	*
3861	* @since 1.0.0 (signature updated 1.14.0)
3862	* @param array $children Array of ['url' => string] child sitemap entries
3863	* @param array $settings Sitemap settings
3864	* @return string Sitemap index XML
3865	*/
3866	private function generate_sitemap_index(array $children, array $settings): string {
3867	$xml = $this->xml_prolog($settings, 'index');
3868	$xml .= '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' . "\n";
3869
3870	$site_url = home_url();
3871
3872	foreach ($children as $child) {
3873	$sitemap_url = $child['url'] ?? '';
3874	if ($sitemap_url === '') {
3875	continue;
3876	}
3877	if (!str_starts_with($sitemap_url, 'http')) {
3878	$sitemap_url = $site_url . $sitemap_url;
3879	}
3880
3881	$xml .= " <sitemap>\n";
3882	$xml .= " <loc>" . esc_url(Url_Scheme::apply($sitemap_url)) . "</loc>\n";
3883	$xml .= " <lastmod>" . gmdate('c') . "</lastmod>\n";
3884	$xml .= " </sitemap>\n";
3885	}
3886
3887	$xml .= '</sitemapindex>';
3888
3889	return $xml;
3890	}
3891
3892	/**
3893	* Count URLs in sitemap XML content
3894	*
3895	* @since 1.0.0
3896	* @param string $sitemap_xml Sitemap XML content
3897	* @return int Number of URLs
3898	*/
3899	private function count_urls_in_xml(string $sitemap_xml): int {
3900	return substr_count($sitemap_xml, '<url>');
3901	}
3902
3903	/**
3904	* Validate and sanitize exclude posts input
3905	*
3906	* @since 1.0.0
3907	* @param string $exclude_posts Comma-separated post IDs
3908	* @return array Validated post IDs
3909	* @throws InvalidArgumentException If validation fails
3910	*/
3911	private function validate_exclude_posts(string $exclude_posts): array {
3912	if (empty($exclude_posts)) {
3913	return [];
3914	}
3915
3916	// Limit input length to prevent DoS
3917	if (strlen($exclude_posts) > 1000) {
3918	throw new InvalidArgumentException('Exclude posts list too long (max 1000 characters)');
3919	}
3920
3921	// Validate comma-separated integers only
3922	if (!preg_match('/^[\d,\s]+$/', $exclude_posts)) {
3923	throw new InvalidArgumentException('Exclude posts must contain only numbers and commas');
3924	}
3925
3926	$ids = array_map('intval', array_filter(explode(',', $exclude_posts)));
3927
3928	// Limit number of exclusions to prevent performance issues
3929	if (count($ids) > 100) {
3930	throw new InvalidArgumentException('Too many posts to exclude (max 100)');
3931	}
3932
3933	return array_filter($ids, function($id) {
3934	return $id > 0; // Only positive integers
3935	});
3936	}
3937
3938	/**
3939	* Validate and sanitize exclude terms input
3940	*
3941	* @since 1.0.0
3942	* @param string $exclude_terms Comma-separated term IDs
3943	* @return array Validated term IDs
3944	* @throws InvalidArgumentException If validation fails
3945	*/
3946	private function validate_exclude_terms(string $exclude_terms): array {
3947	if (empty($exclude_terms)) {
3948	return [];
3949	}
3950
3951	// Limit input length to prevent DoS
3952	if (strlen($exclude_terms) > 1000) {
3953	throw new InvalidArgumentException('Exclude terms list too long (max 1000 characters)');
3954	}
3955
3956	// Validate comma-separated integers only
3957	if (!preg_match('/^[\d,\s]+$/', $exclude_terms)) {
3958	throw new InvalidArgumentException('Exclude terms must contain only numbers and commas');
3959	}
3960
3961	$ids = array_map('intval', array_filter(explode(',', $exclude_terms)));
3962
3963	// Limit number of exclusions to prevent performance issues
3964	if (count($ids) > 100) {
3965	throw new InvalidArgumentException('Too many terms to exclude (max 100)');
3966	}
3967
3968	return array_filter($ids, function($id) {
3969	return $id > 0; // Only positive integers
3970	});
3971	}
3972
3973	/**
3974	* Validate and sanitize custom URL pattern
3975	*
3976	* @since 1.0.0
3977	* @param string $pattern Custom URL pattern
3978	* @return string Validated and sanitized pattern
3979	* @throws InvalidArgumentException If validation fails
3980	*/
3981	private function validate_custom_url_pattern(string $pattern): string {
3982	if (empty($pattern)) {
3983	return 'sitemap-{type}.xml';
3984	}
3985
3986	// Remove any HTML/script tags to prevent XSS
3987	$pattern = wp_strip_all_tags($pattern);
3988
3989	// Limit pattern length
3990	if (strlen($pattern) > 100) {
3991	throw new InvalidArgumentException('URL pattern too long (max 100 characters)');
3992	}
3993
3994	// Validate pattern format - only allow safe characters
3995	if (!preg_match('/^[a-zA-Z0-9\-_{}\.]+$/', $pattern)) {
3996	throw new InvalidArgumentException('URL pattern contains invalid characters. Only letters, numbers, hyphens, underscores, dots, and {type} are allowed');
3997	}
3998
3999	// Ensure it contains {type} placeholder
4000	if (strpos($pattern, '{type}') === false) {
4001	throw new InvalidArgumentException('URL pattern must contain {type} placeholder');
4002	}
4003
4004	// Ensure it ends with .xml
4005	if (!str_ends_with($pattern, '.xml')) {
4006	$pattern .= '.xml';
4007	}
4008
4009	return sanitize_file_name($pattern);
4010	}
4011
4012	/**
4013	* Validate sitemap URL
4014	*
4015	* @since 1.0.0
4016	* @param string $url Sitemap URL
4017	* @return string Validated and sanitized URL
4018	* @throws InvalidArgumentException If validation fails
4019	*/
4020	private function validate_sitemap_url(string $url): string {
4021	if (empty($url)) {
4022	throw new InvalidArgumentException('Sitemap URL cannot be empty');
4023	}
4024
4025	// Remove leading/trailing whitespace
4026	$url = trim($url);
4027
4028	// Limit URL length
4029	if (strlen($url) > 200) {
4030	throw new InvalidArgumentException('Sitemap URL too long (max 200 characters)');
4031	}
4032
4033	// Ensure it starts with /
4034	if (!str_starts_with($url, '/')) {
4035	$url = '/' . $url;
4036	}
4037
4038	// Validate URL path format
4039	if (!preg_match('/^\/[a-zA-Z0-9\-_\/\.]+\.xml$/', $url)) {
4040	throw new InvalidArgumentException('Invalid sitemap URL format. Must be a valid path ending with .xml');
4041	}
4042
4043	// Prevent directory traversal
4044	if (strpos($url, '..') !== false) {
4045	throw new InvalidArgumentException('Directory traversal not allowed in sitemap URL');
4046	}
4047
4048	// Prevent multiple slashes
4049	$url = preg_replace('/\/+/', '/', $url);
4050
4051	return sanitize_url($url);
4052	}
4053
4054	/**
4055	* Validate links per sitemap setting
4056	*
4057	* @since 1.0.0
4058	* @param mixed $links_per_sitemap Links per sitemap value
4059	* @return int Validated links per sitemap
4060	* @throws InvalidArgumentException If validation fails
4061	*/
4062	private function validate_links_per_sitemap($links_per_sitemap): int {
4063	$links = intval($links_per_sitemap);
4064
4065	if ($links < 1) {
4066	throw new InvalidArgumentException('Links per sitemap must be at least 1');
4067	}
4068
4069	if ($links > 50000) {
4070	throw new InvalidArgumentException('Links per sitemap cannot exceed 50,000');
4071	}
4072
4073	return $links;
4074	}
4075
4076	/**
4077	* Validate sitemap filename for security
4078	*
4079	* @since 1.0.0
4080	* @param string $filename Filename to validate
4081	* @return string Validated and sanitized filename
4082	* @throws InvalidArgumentException If validation fails
4083	*/
4084	private function validate_sitemap_filename(string $filename): string {
4085	if (empty($filename)) {
4086	return 'sitemap.xml';
4087	}
4088
4089	// Remove any path components to prevent directory traversal
4090	$filename = basename($filename);
4091
4092	// Limit filename length
4093	if (strlen($filename) > 100) {
4094	throw new InvalidArgumentException('Filename too long (max 100 characters)');
4095	}
4096
4097	// Validate filename format - only allow safe characters
4098	if (!preg_match('/^[a-zA-Z0-9\-_\.]+$/', $filename)) {
4099	throw new InvalidArgumentException('Filename contains invalid characters. Only letters, numbers, hyphens, underscores, and dots are allowed');
4100	}
4101
4102	// Prevent directory traversal attempts
4103	if (strpos($filename, '..') !== false) {
4104	throw new InvalidArgumentException('Directory traversal not allowed in filename');
4105	}
4106
4107	// Ensure it ends with .xml
4108	if (!str_ends_with($filename, '.xml')) {
4109	$filename .= '.xml';
4110	}
4111
4112	// Additional sanitization
4113	$filename = sanitize_file_name($filename);
4114
4115	// Final security check - ensure it's still a valid XML filename
4116	if (!preg_match('/^[a-zA-Z0-9\-_]+\.xml$/', $filename)) {
4117	throw new InvalidArgumentException('Invalid XML filename after sanitization');
4118	}
4119
4120	return $filename;
4121	}
4122	}
4123