# xspeed/1.3.3/includes/class-resource-hints-processor.php
xSpeed Cache: AI-Powered Performance Hub with MCP, Caching & CDN, version 1.3.3. 930 lines.
- Page: https://pluginprobe.com/plugins/xspeed/1.3.3/code/includes/class-resource-hints-processor.php
- Raw: https://pluginprobe.com/plugins/xspeed/1.3.3/raw/includes/class-resource-hints-processor.php
- Modified: 2026-09-13T15:30:04+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.3.3/code/includes/class-resource-hints-processor.php#L10-L20`.
```php
by the largest declared size it can read —
* width×height attributes, else the widest srcset candidate — boosted by
* the author's own priority signals (fetchpriority="high", an explicit
* loading="eager") and lightly weighted by document position, and emits
* a //, images the theme
* explicitly lazy-loads, and tiny images never compete (FBS-84576).
* 2. Emits $opts Preload module settings.
* @return string Rewritten HTML (unchanged when disabled or no match).
*/
public static function process( string $html, array $opts ): string {
if ( empty( $opts['enabled'] ) ) {
return $html;
}
// Only touch real HTML documents. A JSON/XML/feed body that happens
// to reach here should pass through untouched.
if ( false === stripos( $html, ' with none of
// the width/height/fetchpriority signals the scorer reads. On the site
// that surfaced this, 3.3s of a 5.3s mobile LCP was pure discovery
// delay for exactly such an image. (FBS-84578)
$manual = array_filter( array_map( 'strval', (array) ( $opts['preload_images'] ?? array() ) ) );
if ( ! empty( $manual ) ) {
$hints .= self::build_manual_image_preloads( $manual, $hints );
}
// Full-page eager promotion for Lazy-excluded heroes (FBS-83553 H2). The
// Lazy module only filters the_content/thumbnail/avatar/widget, so a
// theme/builder hero printed OUTSIDE those keeps WP core's
// loading="lazy". This pass runs over the whole document, so it can reach
// those heroes: for any $urls The configured list.
* @param string $existing_hints Hints already built this request.
*/
private static function build_manual_image_preloads( array $urls, string $existing_hints ): string {
/**
* Filter the manual image-preload list before it is emitted.
*
* @param array $urls Configured URLs, in panel order.
*/
$urls = (array) apply_filters( 'xspeed_preload_images', $urls );
$out = '';
$seen = array();
foreach ( $urls as $url ) {
$url = trim( (string) $url );
if ( '' === $url ) {
continue;
}
// A full URL or a site-relative path; nothing else is guessable.
$is_absolute = (bool) preg_match( '#^https?://#i', $url );
$is_relative = '' !== $url && '/' === $url[0] && ( strlen( $url ) < 2 || '/' !== $url[1] );
if ( ! $is_absolute && ! $is_relative ) {
continue;
}
$href = esc_url( $url );
if ( '' === $href || isset( $seen[ $href ] ) || false !== strpos( $existing_hints, 'href="' . $href . '"' ) ) {
continue;
}
$seen[ $href ] = true;
$out .= '"\'])*>#i',
static function ( array $m ) use ( $exclusions ) {
$tag = $m[0];
foreach ( $exclusions as $needle ) {
if ( '' !== $needle && false !== stripos( $tag, $needle ) ) {
$tag = (string) preg_replace( '#\s*\bloading=(["\'])\s*lazy\s*\1#i', '', $tag );
$tag = self::set_fetchpriority( $tag );
if ( ! preg_match( '#\bdecoding=#i', $tag ) ) {
$tag = (string) preg_replace( '#s for detected font hosts + user hosts.
* Deduped and idempotent (skips hosts already preconnected in $html).
*
* @param string $html Page HTML (scanned for font stylesheets).
* @param string[] $user_hosts Extra hosts to always preconnect.
* @param bool $auto_fonts Whether to auto-add font hosts.
* @return string preconnect ]*>#i', $html, $matches, PREG_OFFSET_CAPTURE ) ) {
foreach ( $matches[0] as $index => $match ) {
[ $tag, $offset ] = $match;
// Skip anything the user excluded.
$excluded = false;
foreach ( $exclusions as $needle ) {
if ( '' !== $needle && false !== stripos( $tag, $needle ) ) {
$excluded = true;
break;
}
}
if ( $excluded ) {
continue;
}
// An image inside // is site chrome by
// construction — a footer brand strip or FAQ illustration can
// never be the LCP element, whatever size it declares. On the
// FBS-84576 repro these decoys outranked the real hero three
// times on one layout.
if ( self::offset_in_ranges( $offset, $skip_ranges ) ) {
continue;
}
// An image the theme explicitly lazy-loads is never the
// intended LCP — the author has already said "this can wait".
// Preloading it would contradict the markup and steal
// bandwidth from the image that matters. (FBS-84576)
if ( 'lazy' === strtolower( self::attr( $tag, 'loading' ) ) ) {
continue;
}
// Resolve the EFFECTIVE image URL. Page builders + JS lazy
// loaders park a placeholder (a data: URI or a 1px spacer) in
// `src` and the real URL in `data-src`, so the hero the browser
// actually paints is behind data-src. (FBS-83553 H1)
[ $src, $srcset, $sizes ] = self::effective_image_src( $tag );
if ( '' === $src ) {
continue; // no real URL (pure data-URI spacer, no data-src).
}
// Chrome markers / explicit opt-out / obviously-tiny images
// never compete. (FBS-83553 H1 "logo before hero".)
if ( self::looks_too_small( $tag ) ) {
continue;
}
$candidates[] = array(
'tag' => $tag,
'src' => $src,
'srcset' => $srcset,
'sizes' => $sizes,
'score' => self::weighted_score( self::lcp_score( $tag, $srcset ), $tag, $index ),
'order' => $index,
);
}
}
// PASS 1b — the same for CSS background images.
//
// On a page builder the hero is usually a background-image on the
// section, not an ]*>#i',
static function ( array $m ) use ( &$seen, $chosen ) {
++$seen;
if ( ! isset( $chosen[ $seen ] ) ) {
return $m[0];
}
// Add fetchpriority="high" AND remove any loading="lazy" the
// theme / WP core left on the LCP image. fetchpriority="high"
// with loading="lazy" is contradictory — the browser can still
// defer a lazy image, so preloading it while it stays lazy wins
// nothing. Stripping lazy is what actually lets the preload land.
return self::promote_lcp_img( $m[0] );
},
$html
);
return array( (string) $html, $preload );
}
/**
* Collect CSS `background-image` heroes as LCP candidates.
*
* Only INLINE `style` attributes are read. A background declared in an
* external stylesheet is invisible here by design: resolving it would mean
* fetching and parsing CSS from inside an output-buffer pass, and the URL a
* selector resolves to depends on cascade order we cannot evaluate from
* markup. Builders that put the hero in a generated per-post stylesheet are
* therefore still unserved — worth doing, but not at this cost. (#247)
*
* Scores are the element's declared pixel area so a background competes
* against an $skip_ranges Byte ranges of chrome containers.
* @return array
*/
private static function background_candidates( string $html, array $exclusions, array $skip_ranges ): array {
if ( ! preg_match_all( '#<(?:div|section|header|figure|a|span|li|main|article|aside)\b[^>]*\sstyle\s*=\s*(["\']).*?\1[^>]*>#is', $html, $matches, PREG_OFFSET_CAPTURE ) ) {
return array();
}
$found = array();
foreach ( $matches[0] as $index => $match ) {
[ $tag, $offset ] = $match;
// The same chrome-container gate as // is never the hero. (FBS-84576)
if ( self::offset_in_ranges( $offset, $skip_ranges ) ) {
continue;
}
$style = self::attr( $tag, 'style' );
if ( '' === $style || false === stripos( $style, 'background' ) ) {
continue;
}
$src = self::background_url( $style );
if ( '' === $src ) {
continue;
}
foreach ( $exclusions as $needle ) {
if ( '' !== $needle && false !== stripos( $tag, $needle ) ) {
continue 2;
}
}
// Same chrome/opt-out gates as // regions. Nesting-aware per tag
* name (a nav inside a nav extends the range); an unclosed open tag
* poisons through to the end of the document, which errs on the side of
* not preloading — the safe direction, since a wrong preload is worse
* than none. (FBS-84576)
*
* @return array [start, end] byte offsets.
*/
private static function chrome_container_ranges( string $html ): array {
$ranges = array();
foreach ( array( 'footer', 'nav', 'aside' ) as $name ) {
// (?=[\s/>]) rather than \b: a word boundary sits before the `-`
// of a custom element, so ``.
if ( ! preg_match_all( '#<(/?)' . $name . '(?=[\s/>])[^>]*>#i', $html, $m, PREG_OFFSET_CAPTURE ) ) {
continue;
}
$depth = 0;
$start = 0;
foreach ( $m[0] as $i => $match ) {
$closing = '' !== $m[1][ $i ][0];
if ( ! $closing ) {
if ( 0 === $depth ) {
$start = $match[1];
}
++$depth;
} elseif ( $depth > 0 ) {
--$depth;
if ( 0 === $depth ) {
$ranges[] = array( $start, $match[1] );
}
}
}
if ( $depth > 0 ) {
$ranges[] = array( $start, strlen( $html ) );
}
}
return $ranges;
}
/** Does a byte offset fall inside any of the given [start, end] ranges? */
private static function offset_in_ranges( int $offset, array $ranges ): bool {
foreach ( $ranges as $range ) {
if ( $offset > $range[0] && $offset < $range[1] ) {
return true;
}
}
return false;
}
/**
* Score for an image whose size we can't read at all.
*
* Deliberately non-zero: an unmeasurable image must still beat nothing and
* still be preloadable on a page where no image declares its size. But it
* sits below a 200×200 declared area (40 000), so anything we CAN measure
* as a plausible hero outranks a guess.
*/
private const UNKNOWN_SIZE_SCORE = 1;
/**
* Height-to-width ratio assumed when only a `w` descriptor is readable.
*
* 9/16 — the commonest hero/banner shape, and close enough that a
* width-only candidate is compared against a declared w×h area on the
* same scale rather than being systematically inflated.
*/
private const ASSUMED_ASPECT_RATIO = 9 / 16;
/**
* Largest `w` descriptor in a srcset, or 0 when there isn't one.
*
* Only `w` descriptors are read. An `x` descriptor (`hero.jpg 2x`)
* describes pixel density, not layout width, so it says nothing about
* rendered area.
*/
private static function widest_srcset_width( string $srcset ): int {
if ( '' === $srcset ) {
return 0;
}
$widest = 0;
foreach ( explode( ',', $srcset ) as $candidate ) {
if ( preg_match( '#(\d+)w\s*$#', trim( $candidate ), $m ) ) {
$widest = max( $widest, (int) $m[1] );
}
}
return $widest;
}
/**
* Assemble one with a WebP/AVIF , so the browser paints e.g.
* hero.png.webp, NOT the hero.png this preload would otherwise point at —
* making the high-priority preload a wasted download while the real LCP
* resource goes un-preloaded). By filtering the URL, a webp/avif layer can
* redirect the preload to the format it will actually serve, WITHOUT Free
* knowing that layer exists. (FBS-83553 H3)
*/
private static function preload_link( string $src, string $srcset, string $sizes ): string {
// Resolve the `type` from the ORIGINAL image URL (before rewriting), so a
// negotiating layer can key off the source .jpg/.png — after rewriting,
// the URL is already a .webp and the derivation would no-op.
$original = $src;
/**
* Filter an explicit `type` for the preload link (e.g. "image/webp").
* Empty = omit. A typed image preload is only fetched by browsers that
* accept that type, so pairing a webp href with type="image/webp" is safe
* even though the markup is baked into a shared cache file.
*
* @param string $type Defaults to '' (no type attribute).
* @param string $src The ORIGINAL (pre-rewrite) preload URL.
*/
$type = (string) apply_filters( 'xspeed_lcp_preload_type', '', $original );
/**
* Filter the LCP preload href. Return a modern-format sibling (webp/avif)
* when one will actually be served for this image.
*
* @param string $src The original image URL chosen for preload.
*/
$src = (string) apply_filters( 'xspeed_lcp_preload_url', $src );
if ( '' !== $srcset ) {
/** @param string $srcset The original srcset chosen for preload. */
$srcset = (string) apply_filters( 'xspeed_lcp_preload_srcset', $srcset );
}
$attrs = sprintf( 'href="%s"', esc_url( $src ) );
if ( '' !== $srcset ) {
// Preserve the responsive candidate set so the browser preloads
// the same file it would have chosen from the . Prefers to land right
* before the first stylesheet so the preloads are discovered before the
* render-blocking CSS. Falls back to after , then prepend.
*/
private static function inject_into_head( string $html, string $hints ): string {
// Before the first ]*rel=["\']stylesheet["\'][^>]*>#i', $html, $m, PREG_OFFSET_CAPTURE ) ) {
$pos = $m[0][1];
return substr( $html, 0, $pos ) . $hints . substr( $html, $pos );
}
// Otherwise right after the opening .
if ( preg_match( '#]*>#i', $html, $m, PREG_OFFSET_CAPTURE ) ) {
$pos = $m[0][1] + strlen( $m[0][0] );
return substr( $html, 0, $pos ) . "\n" . $hints . substr( $html, $pos );
}
// No head at all — prepend (degenerate documents).
return $hints . $html;
}
}
```