# xspeed/1.0.7/includes/class-preloader.php

xSpeed Cache: AI-Powered Performance Hub with MCP, Caching & CDN, version 1.0.7. 367 lines.

- Page: https://pluginprobe.com/plugins/xspeed/1.0.7/code/includes/class-preloader.php
- Raw: https://pluginprobe.com/plugins/xspeed/1.0.7/raw/includes/class-preloader.php
- Modified: 2026-06-01T17:33:22+00:00

Line numbers below start at 1. Link to a line or a range by appending a fragment to the
page URL, for example `https://pluginprobe.com/plugins/xspeed/1.0.7/code/includes/class-preloader.php#L10-L20`.

```php
<?php
/**
 * Preloader — sitemap-driven cache warmer.
 *
 * On `start()`:
 *   1. Fetches the configured sitemap (or auto-detects /wp-sitemap.xml).
 *   2. Recursively follows nested sitemap indexes.
 *   3. Filters URLs against the Cache module's excluded_urls list.
 *   4. Queues the result in a transient.
 *   5. Schedules the next WP-Cron tick.
 *
 * Each `tick()` processes up to `batch_size` URLs from the queue via
 * `wp_remote_get()` (short timeout, sslverify off for local dev tolerance,
 * a UA that flags itself so site owners can spot crawler traffic in
 * access logs). Cache::should_cache() picks up the GET → writes the cache
 * file on miss. The next visitor sees a HIT.
 *
 * State (transient `xspeed_preloader_state`):
 *   { running, started_at, finished_at, queue, processed, total,
 *     last_url, errors[] }
 *
 * Configuration comes from PreloaderModule's per-module option
 * (xspeed_module_preloader) via Settings_Manager.
 *
 * @package XSpeed
 */

declare(strict_types=1);

namespace XSpeed;

defined( 'ABSPATH' ) || exit;

final class Preloader {

	public const STATE_KEY      = 'xspeed_preloader_state';
	public const STATE_TTL      = 86400; // 24h — long enough for slow crawls.
	public const CRON_HOOK      = 'xspeed_preloader_tick';
	public const USER_AGENT     = 'xSpeed-Preloader/1.0 (+cache warmer; admin-initiated)';
	public const REQUEST_TIMEOUT = 8;

	/**
	 * Kick off a fresh crawl. Returns the initial state.
	 */
	public static function start(): array {
		$opts = Settings_Manager::get( 'preloader' );
		$urls = self::resolve_queue( $opts );

		$state = array(
			'running'     => ! empty( $urls ),
			'started_at'  => time(),
			'finished_at' => 0,
			'queue'       => array_values( $urls ),
			'processed'   => 0,
			'total'       => count( $urls ),
			'last_url'    => '',
			'errors'      => array(),
		);
		set_transient( self::STATE_KEY, $state, self::STATE_TTL );

		Activity_Log::record(
			'preloader_started',
			sprintf( 'Preloader queued %d URL%s for warming.', $state['total'], 1 === $state['total'] ? '' : 's' ),
			$state['total'] > 0 ? Activity_Log::INFO : Activity_Log::WARN
		);

		// Schedule the first tick ~5 seconds out so the kick-off REST call
		// returns instantly; wp_schedule_single_event covers the
		// "process the queue ASAP" path without a heavy synchronous loop.
		if ( $state['running'] ) {
			wp_schedule_single_event( time() + 5, self::CRON_HOOK );
		}

		return $state;
	}

	/**
	 * Cancel an in-flight crawl. Idempotent.
	 */
	public static function stop(): array {
		$state = self::status();
		if ( $state['running'] ) {
			Activity_Log::record(
				'preloader_stopped',
				sprintf( 'Preloader stopped (%d/%d URLs warmed).', $state['processed'], $state['total'] ),
				Activity_Log::INFO
			);
		}

		// Clear scheduled ticks.
		wp_clear_scheduled_hook( self::CRON_HOOK );

		$state['running']     = false;
		$state['finished_at'] = time();
		$state['queue']       = array();
		set_transient( self::STATE_KEY, $state, self::STATE_TTL );
		return $state;
	}

	public static function status(): array {
		$raw = get_transient( self::STATE_KEY );
		if ( ! is_array( $raw ) ) {
			return self::empty_state();
		}
		return wp_parse_args( $raw, self::empty_state() );
	}

	private static function empty_state(): array {
		return array(
			'running'     => false,
			'started_at'  => 0,
			'finished_at' => 0,
			'queue'       => array(),
			'processed'   => 0,
			'total'       => 0,
			'last_url'    => '',
			'errors'      => array(),
		);
	}

	/**
	 * Tick handler — pulls up to batch_size URLs off the queue, warms
	 * each, persists state, and reschedules itself until the queue is
	 * empty. Called via the xspeed_preloader_tick action.
	 */
	public static function tick(): void {
		$state = self::status();
		if ( ! $state['running'] || empty( $state['queue'] ) ) {
			if ( $state['running'] ) {
				self::mark_complete( $state );
			}
			return;
		}

		$opts  = Settings_Manager::get( 'preloader' );
		$batch = max( 1, min( 50, (int) ( $opts['batch_size'] ?? 5 ) ) );

		$processed_this_tick = 0;
		while ( $processed_this_tick < $batch && ! empty( $state['queue'] ) ) {
			$url = array_shift( $state['queue'] );
			self::warm_url( $url, $state );
			$state['processed']++;
			$state['last_url'] = $url;
			$processed_this_tick++;
		}

		if ( empty( $state['queue'] ) ) {
			self::mark_complete( $state );
			return;
		}

		// More to do — persist + reschedule. Slight delay to avoid
		// hammering the origin with parallel batches.
		set_transient( self::STATE_KEY, $state, self::STATE_TTL );
		wp_schedule_single_event( time() + 10, self::CRON_HOOK );
	}

	/**
	 * Fire a single warm request for one URL with no queue / no cron
	 * (the "content warmer" path: new post published → warm its URL
	 * immediately). Records an activity event so the user can see in
	 * the Health log that warming happened.
	 *
	 * Best-effort and non-blocking-feeling — uses a short timeout so a
	 * dead origin can't hang the calling request. Returns true if the
	 * fetch completed with a non-error status, false otherwise.
	 */
	public static function warm_one( string $url, string $cause = 'manual' ): bool {
		if ( '' === $url ) {
			return false;
		}
		$response = wp_remote_get(
			$url,
			array(
				'timeout'    => self::REQUEST_TIMEOUT,
				'sslverify'  => false,
				'user-agent' => self::USER_AGENT,
				'blocking'   => true,
			)
		);
		if ( is_wp_error( $response ) ) {
			Activity_Log::record(
				'preloader_warm_failed',
				sprintf( 'Warm %s failed (%s): %s', $cause, $url, $response->get_error_message() ),
				Activity_Log::WARN
			);
			return false;
		}
		$code = (int) wp_remote_retrieve_response_code( $response );
		if ( $code >= 400 ) {
			Activity_Log::record(
				'preloader_warm_failed',
				sprintf( 'Warm %s failed (%s): HTTP %d', $cause, $url, $code ),
				Activity_Log::WARN
			);
			return false;
		}
		Activity_Log::record(
			'preloader_warmed_one',
			sprintf( 'Warmed %s (%s)', $url, $cause ),
			Activity_Log::INFO
		);
		return true;
	}

	private static function warm_url( string $url, array &$state ): void {
		$response = wp_remote_get(
			$url,
			array(
				'timeout'    => self::REQUEST_TIMEOUT,
				'sslverify'  => false,
				'user-agent' => self::USER_AGENT,
				'headers'    => array(
					'Accept' => 'text/html,application/xhtml+xml',
				),
				'blocking'   => true,
			)
		);
		if ( is_wp_error( $response ) ) {
			$state['errors'][] = array(
				'url'   => $url,
				'error' => $response->get_error_message(),
				'ts'    => time(),
			);
			// Cap retained errors so a broken sitemap doesn't blow the
			// transient size.
			$state['errors'] = array_slice( $state['errors'], -20 );
			return;
		}
		$code = (int) wp_remote_retrieve_response_code( $response );
		if ( $code >= 400 ) {
			$state['errors'][] = array(
				'url'   => $url,
				'error' => sprintf( 'HTTP %d', $code ),
				'ts'    => time(),
			);
			$state['errors'] = array_slice( $state['errors'], -20 );
		}
	}

	private static function mark_complete( array $state ): void {
		$state['running']     = false;
		$state['finished_at'] = time();
		$state['queue']       = array();
		set_transient( self::STATE_KEY, $state, self::STATE_TTL );

		Activity_Log::record(
			'preloader_completed',
			sprintf(
				'Preloader finished — %d/%d URLs warmed, %d error%s.',
				$state['processed'],
				$state['total'],
				count( $state['errors'] ),
				1 === count( $state['errors'] ) ? '' : 's'
			),
			empty( $state['errors'] ) ? Activity_Log::SUCCESS : Activity_Log::WARN
		);
	}

	/**
	 * Build the URL queue for a fresh crawl: parse the sitemap, follow
	 * nested indexes, drop excluded paths.
	 *
	 * @return string[]
	 */
	private static function resolve_queue( array $opts ): array {
		$sitemap = trim( (string) ( $opts['sitemap_url'] ?? '' ) );
		if ( '' === $sitemap ) {
			$sitemap = home_url( '/wp-sitemap.xml' );
		}

		$urls = self::fetch_sitemap_urls( $sitemap, 0 );

		$cache_opts = Settings_Manager::get( 'cache' );
		$excluded   = is_array( $cache_opts['excluded_urls'] ?? null ) ? $cache_opts['excluded_urls'] : array();
		if ( ! empty( $excluded ) ) {
			$urls = array_filter(
				$urls,
				static function ( $u ) use ( $excluded ) {
					$path = (string) wp_parse_url( $u, PHP_URL_PATH );
					foreach ( $excluded as $needle ) {
						if ( '' !== $needle && false !== strpos( $path, (string) $needle ) ) {
							return false;
						}
					}
					return true;
				}
			);
		}

		// Dedup + cap at 5000 to bound the transient size on huge sites.
		$urls = array_values( array_unique( $urls ) );
		return array_slice( $urls, 0, 5000 );
	}

	/**
	 * Recursive sitemap parser. Depth-limited to 3 so a maliciously
	 * deep index can't stack-overflow.
	 */
	private static function fetch_sitemap_urls( string $sitemap_url, int $depth ): array {
		if ( $depth > 3 ) {
			return array();
		}
		$res = wp_remote_get(
			$sitemap_url,
			array(
				'timeout'    => self::REQUEST_TIMEOUT,
				'sslverify'  => false,
				'user-agent' => self::USER_AGENT,
			)
		);
		if ( is_wp_error( $res ) || (int) wp_remote_retrieve_response_code( $res ) >= 400 ) {
			return array();
		}
		$body = (string) wp_remote_retrieve_body( $res );
		if ( '' === $body ) {
			return array();
		}

		$urls = array();
		// Sitemap index → recurse.
		if ( false !== strpos( $body, '<sitemapindex' ) ) {
			if ( preg_match_all( '#<loc>([^<]+)</loc>#i', $body, $matches ) ) {
				foreach ( $matches[1] as $child ) {
					$urls = array_merge( $urls, self::fetch_sitemap_urls( trim( $child ), $depth + 1 ) );
				}
			}
			return $urls;
		}
		// URL set → collect.
		if ( preg_match_all( '#<loc>([^<]+)</loc>#i', $body, $matches ) ) {
			foreach ( $matches[1] as $u ) {
				$u = trim( $u );
				if ( '' !== $u && false !== filter_var( $u, FILTER_VALIDATE_URL ) ) {
					$urls[] = $u;
				}
			}
		}
		return $urls;
	}

	/**
	 * Apply the user's schedule choice. Called on settings change.
	 * Manual = no cron schedule (user must hit "Start now" to crawl).
	 */
	public static function apply_schedule( string $schedule ): void {
		wp_clear_scheduled_hook( 'xspeed_preloader_recurring' );
		if ( in_array( $schedule, array( 'hourly', 'daily', 'weekly' ), true ) ) {
			if ( ! wp_next_scheduled( 'xspeed_preloader_recurring' ) ) {
				wp_schedule_event( time() + 60, $schedule, 'xspeed_preloader_recurring' );
			}
		}
	}

	/**
	 * Recurring schedule hook handler — fires per the user's chosen
	 * cadence and kicks off a fresh crawl unless one is already running.
	 */
	public static function recurring_kickoff(): void {
		$state = self::status();
		if ( $state['running'] ) {
			return;
		}
		self::start();
	}
}

```