includes/Images/class-lcp-preload.php
LCP/hero-preload service — LCP resolution, preload emission, and dedup/slot state.
Class Lcp_Preload
Class Lcp_Preload
final class Lcp_PreloadConstants
| Constant | Visibility | Value | Line |
|---|---|---|---|
MAX_PRELOAD_WIDTH | private | 1478 | 106 |
MAX_LCP_PRELOADS | private | 2 | 117 |
Properties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$owner | private | Image_Optimisation | — | 89 |
$preload_emitted | private static | array | array() | 135 |
$preload_emitted_urls | private static | array | array() | 151 |
$heuristic_lcp_memo | private static | array<string, | array() | 164 |
$responsive_lcp_preload_emitted | private static | bool | false | 177 |
$lcp_priority_applied | private | bool | false | 191 |
public __construct()
public function __construct(Image_Optimisation $owner)Constructor. Parameter Type Default Description $ownerImage_Optimisation— Image_Optimisation instance (options + memo + collaborator owner).
publicstatic clear_lcp_preload_caches()
public static function clear_lcp_preload_caches(): voidClear the per-request LCP/preload static caches.
Return: void.
publicstatic clear_heuristic_lcp_memo()
public static function clear_heuristic_lcp_memo(): voidClear the heuristic LCP memo only.
Return: void.
privatestatic heuristic_memo_key()
private static function heuristic_memo_key(string $buffer): stringBlog-scoped key for the heuristic LCP memo. Parameter Type Default Description $bufferstring— HTML buffer.
Return: string — Memo key.
publicstatic has_emitted_preload()
public static function has_emitted_preload(string $url, string=\'\' $media): boolWhether a preload hint was already emitted for a URL this request. Parameter Type Default Description $urlstring— The raw preload URL. $mediastring=\'\'— The preload media attribute.
Return: bool — True when the URL + media pair already emitted.
publicstatic mark_preload_emitted()
public static function mark_preload_emitted(string $url, string=\'\' $media): voidRecord a preload hint as emitted for this request. Parameter Type Default Description $urlstring— The raw preload URL. $mediastring=\'\'— The preload media attribute.
Return: void.
publicstatic record_direct_preload_url()
public static function record_direct_preload_url(string $url): voidRecord a directly-emitted hero URL for same-response lazy exclusion. Parameter Type Default Description $urlstring— The raw preload URL.
Return: void.
publicstatic get_direct_preload_normalized_urls()
public static function get_direct_preload_normalized_urls(): arrayNormalized forms of the directly-emitted preload URLs.
Return: string[] — Normalized direct-preload URLs.
publicstatic build_preload_dedup_key()
public static function build_preload_dedup_key(string $url, string $media): stringBuild the dedup key for a preload item (normalized URL + query + media). Parameter Type Default Description $urlstring— The raw preload URL. $mediastring— The preload media attribute.
Return: string — The dedup key.
publicstatic is_hero_preload_claimed()
public static function is_hero_preload_claimed(string $url): boolWhether any preload was already claimed for a hero URL, any media. Parameter Type Default Description $urlstring— The raw hero URL.
Return: bool — True when the URL already emitted with any media.
public claim_hero_preload_slot()
public function claim_hero_preload_slot(string $url, string=\'\' $media, ?string=null $buffer): boolClaim the single hero preload slot for a URL. Parameter Type Default Description $urlstring— The raw hero URL. $mediastring=\'\'— The preload media attribute (\’\’ for buffer companions). $buffer?string=null— Optional HTML buffer to scan for an existing hint.
Return: bool — True when the caller may emit (slot claimed), false to skip.
publicstatic release_hero_preload_slot()
public static function release_hero_preload_slot(string $url, string=\'\' $media): voidRelease a previously claimed hero preload slot. Parameter Type Default Description $urlstring— The raw hero URL. $mediastring=\'\'— The preload media attribute (\’\’ for buffer companions).
Return: void.
public is_cdn_preload_url()
public function is_cdn_preload_url(string $url): boolWhether a preload candidate lives on the configured CDN. Parameter Type Default Description $urlstring— The candidate URL.
Return: bool — True when the URL host matches a configured CDN host.
public is_allowed_hero_preload_url()
public function is_allowed_hero_preload_url(string $url): boolWhether a hero URL may be preloaded (same-origin or configured CDN). Parameter Type Default Description $urlstring— The candidate URL.
Return: bool — True when the URL may be preloaded.
public is_html_api_available()
public function is_html_api_available(): boolWhether the WP HTML API may be used for hero scanning.
Return: bool — True when the HTML API may be used.
public get_computed_css_hero_url()
public function get_computed_css_hero_url(?string=null $buffer): stringServer-side computed CSS-hero URL passed via filter. Parameter Type Default Description $buffer?string=null— Optional HTML buffer passed to the filter for context.
Return: string — The computed hero URL, or empty string.
public sweep_lazy_high_conflicts()
public function sweep_lazy_high_conflicts(string $buffer): stringForce eager on any element already marked fetchpriority high. Parameter Type Default Description $bufferstring— The HTML buffer.
Return: string — The buffer with high-priority nodes forced eager.
public is_occlusion_fetchpriority_low_enabled()
public function is_occlusion_fetchpriority_low_enabled(): boolWhether occlusion-aware fetchpriority=low demotion is enabled.
Return: bool — True when occluded nodes should be demoted to low.
public get_occluded_image_urls_for_request()
public function get_occluded_image_urls_for_request(): arrayResolve OD-occluded image URLs for the current request.
Return: string[] — Occluded image URLs (may be empty).
public apply_occlusion_fetchpriority_low()
public function apply_occlusion_fetchpriority_low(string $buffer, array $occluded_urls, ?string=null $lcp_url): stringDemote OD-occluded in-viewport images to fetchpriority=low. Parameter Type Default Description $bufferstring— The HTML buffer. $occluded_urlsarray— Raw occluded image URLs. $lcp_url?string=null— Optional true-LCP URL to protect.
Return: string — The buffer with occluded nodes demoted to low.
public preload_images()
public function preload_images()Preloads images for optimization.
public get_all_preload_data()
public function get_all_preload_data(): arrayRetrieves all preloading data from front-page, post meta, and post types.
Return: array — List of preload data items.
public is_image_lcp_url()
public function is_image_lcp_url(string $url): boolWhether a candidate URL is a plausible LCP image (text-LCP guard). Parameter Type Default Description $urlstring— The candidate URL.
Return: bool — True when the URL may be preloaded as an image.
public get_manual_lcp_url()
public function get_manual_lcp_url(): stringRead the manual per-post LCP URL picker value (`_wppo_lcp_preload_url`).
Return: string — The manual LCP image URL, or empty string.
public is_same_origin_preload_url()
public function is_same_origin_preload_url(string $url): boolWhether a preload candidate URL is same-origin with this site. Parameter Type Default Description $urlstring— The candidate URL.
Return: bool — True when the URL may be preloaded.
public is_core_loading_optimization_available()
public function is_core_loading_optimization_available(): boolWhether core\’s loading-optimization API is available.
Return: bool — True when core may be consulted for a node verdict.
public get_core_loading_verdict_for_tag()
public function get_core_loading_verdict_for_tag($tags): ?arrayAsk core for its loading-optimization verdict on the current tag. Parameter Type Default Description $tagsmixed— Tag processor positioned on an `<img>` node.
Return: array{decoding?:string}|null — Core\’s verdict, or null.
public is_auto_lcp_disabled_for_post()
public function is_auto_lcp_disabled_for_post(): boolWhether automatic (signal-driven) LCP preload is disabled for the current post.
Return: bool — True when auto-LCP must be skipped for this post.
public get_stable_signal_lcp_url()
public function get_stable_signal_lcp_url(): stringResolve the stable signal-only LCP image URL for the current page.
Return: string — The stable signal LCP image URL, or empty string.
public resolve_od_only_lcp_url()
public function resolve_od_only_lcp_url(): stringResolve the OD-only LCP image URL (manual picker + OD real-visit data).
Return: string — The OD-only LCP image URL, or empty string.
public resolve_auto_lcp_url()
public function resolve_auto_lcp_url(?string=null $buffer): stringResolve the single auto-detected LCP image URL for the current page. Parameter Type Default Description $buffer?string=null— Optional HTML buffer for the heuristic fallback.
Return: string — The LCP image URL, or empty string when none resolves.
publicstatic get_lcp_responsive_data_for_url()
public static function get_lcp_responsive_data_for_url(string $lcp_url): arrayResolve responsive srcset/sizes for an LCP URL via the media library. Parameter Type Default Description $lcp_urlstring— The resolved LCP image URL.
Return: array{srcset: — string, sizes: string} Responsive data (empty strings when unavailable).
public get_lcp_srcset_for_url()
public function get_lcp_srcset_for_url(string $lcp_url, ?string=null $buffer): stringFind the responsive srcset for an LCP URL inside an HTML buffer. Parameter Type Default Description $lcp_urlstring— The resolved LCP image URL. $buffer?string=null— Optional HTML buffer to scan.
Return: string — The srcset value, or empty string.
public get_lcp_sizes_for_url()
public function get_lcp_sizes_for_url(string $lcp_url, ?string=null $buffer): stringFind the responsive sizes value for an LCP URL inside an HTML buffer. Parameter Type Default Description $lcp_urlstring— The resolved LCP image URL. $buffer?string=null— Optional HTML buffer to scan.
Return: string — The sizes value, or empty string.
public emit_responsive_lcp_preload()
public function emit_responsive_lcp_preload(?string=null $buffer): stringEmit a breakpoint-specific responsive LCP preload. Parameter Type Default Description $buffer?string=null— Optional HTML buffer for responsive fallback scans.
Return: string — The preload `<link>` tag, or empty string when skipped.
public get_responsive_lcp_candidate()
public function get_responsive_lcp_candidate(?string=null $buffer): arrayResolve the responsive LCP candidate (OD breakpoints → RUM field). Parameter Type Default Description $buffer?string=null— Optional HTML buffer for fallback scans.
Return: array{url: — string, srcset: string, sizes: string, type: string, media: string}|array Empty when unresolved.
public pick_breakpoint_winner()
public function pick_breakpoint_winner(array $entries, ?string=null $buffer): arrayPick the breakpoint winner from OD per-viewport entries. Parameter Type Default Description $entriesarray— OD breakpoint entries. $buffer?string=null— Optional HTML buffer for gap-fill.
Return: array{url: — string, srcset: string, sizes: string, type: string, media: string}|array Winner or empty.
public resolve_rum_fallback_candidate()
public function resolve_rum_fallback_candidate(?string=null $buffer): arrayResolve the RUM field-LCP fallback candidate. Parameter Type Default Description $buffer?string=null— Optional HTML buffer for gap-fill.
Return: array{url: — string, srcset: string, sizes: string, type: string, media: string}|array Candidate or empty.
public response_already_has_high_preload()
public function response_already_has_high_preload(?string=null $buffer): boolWhether the response already carries a fetchpriority-high hint. Parameter Type Default Description $buffer?string=null— Optional HTML buffer to inspect.
Return: bool — True when a high hint already exists.
public get_manual_lcp_preload_data()
public function get_manual_lcp_preload_data(): arrayRetrieves the manual per-post LCP image preload item.
Return: array — List of preload items (zero or one item).
public get_auto_lcp_preload_data()
public function get_auto_lcp_preload_data(): arrayRetrieves the single auto-detected LCP image preload item.
Return: array — List of preload items (zero or one item).
public get_breakpoint_srcset_for_url()
public function get_breakpoint_srcset_for_url(string $lcp_url, ?string=null $buffer): arrayLook up breakpoint srcset/sizes for a resolved LCP URL. Parameter Type Default Description $lcp_urlstring— The resolved LCP image URL. $buffer?string=null— Optional HTML buffer for gap-fill.
Return: array{srcset: — string, sizes: string} Responsive pair.
public is_auto_lcp_rum_satisfied()
public function is_auto_lcp_rum_satisfied(): boolWhether the RUM gate for the additive auto-LCP toggle is satisfied.
Return: bool — True when RUM gating passes.
public get_current_lcp_url()
public function get_current_lcp_url(): stringResolves the currently-detected LCP image URL for the current page.
Return: string — The LCP image URL, or empty string when none is stored.
public get_lcp_memo_key()
public function get_lcp_memo_key(): stringCurrent-URL key for the per-instance LCP memos (issue #1216).
Return: string — Memo key (possibly empty).
public get_heuristic_lcp_url()
public function get_heuristic_lcp_url(string $buffer): stringP2 DOM-first heuristic LCP URL, memoized per buffer hash (issue #1216). Parameter Type Default Description $bufferstring— HTML buffer to scan.
Return: string — Heuristic LCP URL, or empty string.
public get_lazy_lcp_exclusion_url()
public function get_lazy_lcp_exclusion_url(array $image_optimisation, ?string=null $buffer): stringResolve the LCP-candidate URL excluded from lazy load (memoized per instance). Parameter Type Default Description $image_optimisationarray— Image optimisation settings. $buffer?string=null— Optional HTML buffer for the heuristic tier.
Return: string — The candidate URL, or empty string when none applies.
public get_effective_exclude_first_images_count()
public function get_effective_exclude_first_images_count(array $image_optimisation): intGet the effective excludeFirstImages count, preferring OD measured data. Parameter Type Default Description $image_optimisationarray— Image optimisation settings.
Return: int — Exclude count.
public get_front_page_preload_data()
public function get_front_page_preload_data(array $image_optimisation): arrayRetrieves front page preload data if enabled. Parameter Type Default Description $image_optimisationarray— Image optimization configuration.
Return: array — List of preload items for the front page.
public get_meta_preload_data()
public function get_meta_preload_data(): arrayRetrieves preload data from post meta.
Return: array — List of preload items from meta.
public get_post_type_preload_data()
public function get_post_type_preload_data(array $image_optimisation): arrayRetrieves preload data for specific post types. Parameter Type Default Description $image_optimisationarray— Image optimization configuration.
Return: array — List of preload items for the post type.
public get_image_url_by_post_type()
public function get_image_url_by_post_type(int $thumbnail_id): stringRetrieves the URL of the featured image for the current post type. Parameter Type Default Description $thumbnail_idint— The ID of the thumbnail image.
Return: string — The URL of the image.
public should_exclude_image()
public function should_exclude_image(string $image_url, array $exclude_img_urls): boolCheck if an image should be excluded from preloading or optimization. Parameter Type Default Description $image_urlstring— The URL of the image. $exclude_img_urlsarray— Array of URLs to exclude.
Return: bool — True if the image should be excluded, false otherwise.
public parse_srcset_data()
public function parse_srcset_data($srcset, $image_optimisation): arrayParse srcset data from an image tag. Parameter Type Default Description $srcsetstring— The srcset string from the image tag. $image_optimisationarray— Image optimization configuration array.
Return: array — Array of parsed sources: array( \’url\’ => string, \’width\’ => int ).
public get_srcset_preload_items()
public function get_srcset_preload_items($srcset, $default_image, $image_optimisation): arrayRetrieves preload data items from an image\’s srcset. Parameter Type Default Description $srcsetstring— The srcset string from the image tag. $default_imagestring— The fallback image URL. $image_optimisationarray— Image optimization configuration array.
Return: array — List of preload items.
public prepare_preload_item()
public function prepare_preload_item(string $img_url, string=\'\' $imagesrcset, string=\'\' $imagesizes): arrayPrepares a URL for preloading, handling specific prefixes and resolving relative paths. Parameter Type Default Description $img_urlstring— The original URL to prepare. $imagesrcsetstring=\'\'— Optional responsive srcset for the preload link. $imagesizesstring=\'\'— Optional sizes for the preload link.
Return: array — Structured preload item.
public generate_img_preload()
public function generate_img_preload(=\'\' $img_url)Generates a preload link for a given image URL. Parameter Type Default Description $img_url=\'\'— The URL of the image to preload. Empty resolves the stable signal candidate.
Return: void.
public prioritize_lcp_in_buffer()
public function prioritize_lcp_in_buffer($filtered_output, =\'\' $output)Post-render LCP image prioritization (optional enhancement). Parameter Type Default Description $filtered_outputstring— The filtered output from previous callbacks. $output=\'\'— The raw output buffer content (unused; present for parity with the 6.9 filter signature and safe when used as an ob_start callback).
Return: string — The processed buffer.
public wppo_add_fetchpriority()
public function wppo_add_fetchpriority($attr, =null $attachment, =null $size)Stamp fetchpriority=\”high\” on the LCP attachment at render time. Parameter Type Default Description $attrmixed— Image attributes (expected array). $attachment=null— Attachment post object, ID, or array with ID. $size=null— Requested image size.
Return: mixed — The (possibly stamped) attributes, unchanged on miss.
public resolve_fetchpriority_lcp_url()
public function resolve_fetchpriority_lcp_url(): stringResolve the LCP candidate for the render-time fetchpriority filter, memoized per page.
Return: string — The validated LCP image URL, or empty string.
public fetchpriority_candidate_matches()
public function fetchpriority_candidate_matches(string $candidate, string $normalized_lcp, string $exact_lcp, bool $size_is_full): boolSize-aware LCP candidate comparison for the fetchpriority filter. Parameter Type Default Description $candidatestring— The rendered file URL to test. $normalized_lcpstring— Normalized LCP URL (size suffix stripped). $exact_lcpstring— Normalized LCP URL (size suffix preserved). $size_is_fullbool— Whether the requested image size is \’full\’.
Return: bool — True when the candidate corresponds to the LCP image.
public prioritize_lcp_image()
public function prioritize_lcp_image(string $buffer, ?string=null $lcp_url): stringSet fetchpriority=\”high\” on the detected LCP image. Parameter Type Default Description $bufferstring— The HTML buffer. $lcp_url?string=null— Optional pre-resolved LCP URL. When null the URL is resolved via resolve_auto_lcp_url() (same-origin guarded OD/stored/heuristic chain; the stored tier internally reads get_current_lcp_url()).
Return: string — The buffer with fetchpriority=\”high\” on the LCP image.
public maybe_preload_hero_image()
public function maybe_preload_hero_image(string $buffer, array $image_optimisation, ?string=null $lcp_url): stringHero fallback: ensure the first-viewport image preloads with fetchpriority=high and is never lazy. Parameter Type Default Description $bufferstring— The HTML buffer. $image_optimisationarray— Image optimisation settings. $lcp_url?string=null— Optional pre-resolved LCP URL. When null the URL is resolved via resolve_auto_lcp_url().
Return: string — The buffer with hero preload link injected.
public get_first_image_src_in_buffer()
public function get_first_image_src_in_buffer(string $buffer): stringGet the first <img src> URL in the buffer (hero fallback). Parameter Type Default Description $bufferstring— The HTML buffer.
Return: string — First image src, or empty string when none found.
public is_trivial_heuristic_image()
public function is_trivial_heuristic_image($tags, string $src): boolWhether a heuristic `<img>` candidate is trivial (pixel/hidden/tiny). Parameter Type Default Description $tags\\WP_HTML_Tag_Processor— The tag processor on the candidate `<img>`. $srcstring— The candidate src URL.
Return: bool — True when the candidate should be skipped.
public buffer_has_image_preload()
public function buffer_has_image_preload(string $buffer, string $url): boolWhether the buffer already contains a preload link for the image URL. Parameter Type Default Description $bufferstring— The HTML buffer. $urlstring— The image URL to look for.
Return: bool — True when a matching preload link exists.
public buffer_has_image_preload_with_tag_processor()
public function buffer_has_image_preload_with_tag_processor(string $buffer, string $needle, string $needle_exact, bool $needle_has_sizes, string $needle_query): ?boolTag Processor scan for an existing image preload link (WP 6.2+). Parameter Type Default Description $bufferstring— The HTML buffer. $needlestring— Normalized target URL. $needle_exactstring— Normalized target URL without size-suffix collapsing. $needle_has_sizesbool— Whether the target itself carries a size suffix. $needle_querystring— Raw query string of the target URL.
Return: bool|null — True/false on success, null on failure (fallback).
public get_url_query()
public function get_url_query(string $url): stringGet the raw query string of a URL for preload-dedup comparison. Parameter Type Default Description $urlstring— The URL to inspect.
Return: string — The query string without the leading `?`, or empty.
public tag_matches_lcp_url()
public function tag_matches_lcp_url($tags, string $lcp_url): boolWhether the matched image tag references the given LCP URL. Parameter Type Default Description $tags\\WP_HTML_Tag_Processor— The tag processor matched on an <img>. $lcp_urlstring— The detected LCP image URL.
Return: bool — True if the image references the LCP URL.
public normalize_image_url()
public function normalize_image_url(string $url, bool=true $strip_size_suffix): stringNormalize an image URL for LCP matching. Parameter Type Default Description $urlstring— The raw URL to normalize. $strip_size_suffixbool=true— Whether to strip WordPress size suffixes. Default true.
Return: string — Normalized host + path, or an empty string when unparseable.
publicstatic normalize_image_url_static()
public static function normalize_image_url_static(string $url, bool=true $strip_size_suffix): stringStatic normalization behind normalize_image_url(). Parameter Type Default Description $urlstring— The image URL to normalize. $strip_size_suffixbool=true— Whether to strip WP size suffixes.
Return: string — Normalized host + path, or empty string.
public get_preload_dedup_key()
public function get_preload_dedup_key(string $url, string $media): stringBuild the dedup key for a preload item (normalized URL + query + media). Parameter Type Default Description $urlstring— The raw preload URL. $mediastring— The preload media attribute.
Return: string — The dedup key.
public buffer_has_matching_img()
public function buffer_has_matching_img(string $buffer, string $lcp_url): boolWhether any img element in the buffer references the given LCP URL. Parameter Type Default Description $bufferstring— The HTML buffer. $lcp_urlstring— The detected LCP image URL.
Return: bool — True when an img matches the LCP URL.
public maybe_inject_css_hero_preload()
public function maybe_inject_css_hero_preload(string $buffer, ?string=null $lcp_url): stringInject exactly one CSS-hero preload link into the buffer head. Parameter Type Default Description $bufferstring— The HTML buffer. $lcp_url?string=null— Optional pre-resolved LCP URL. When null the URL is resolved via resolve_auto_lcp_url() (same-origin guarded OD/stored/heuristic chain), matching every other emission path.
Return: string — The buffer with at most one added preload link.
Hooks
Hooks referenced in includes/Images/class-lcp-preload.php: Hook Type Line Notes wppo_computed_css_hero_urlfilter 655 — wppo_occlusion_fetchpriority_low_enabledfilter 769 @param ×1 wppo_occlusion_fetchpriority_low_urlsfilter 839 @param ×2 wppo_lcp_first_nfilter 2742 — wppo_debug_logaction 3308 —