includes/CSS/class-critical-css.php
Critical CSS Generation for above-the-fold optimization.
Class Critical_CSS
Class Critical_CSS
class Critical_CSSConstants
| Constant | Visibility | Value | Line |
|---|---|---|---|
ABOVE_FOLD_SELECTORS | private | array( \'html\', \'body\', \'header\', \'.header\', \'#header\', \'.site-header\', \'#masthead\', \'nav\', \'.nav\', \'#nav\', \'.menu\', \'.primary-menu\', \'.main-navigation\', \'h1\', \'h2\', \'h3\', \'.hero\', \'.banner\', \'.page-title\', \'.entry-title\', \'.page-header\', \'.entry-header\', \'.logo\', \'.site-logo\', \'.site-branding\', \'img\', \'.wp-block-image\', \'figure\', \'main\', \'.main\', \'.content\', \'.site-content\', \'.container\', \'.wrapper\', \'.row\', \'.section\', \'.top-bar\', \'.topbar\', \'.skip-link\', \'.screen-reader-text\', \':root\', \'p\', \'a\', \'ul\', \'li\', \'button\', \'.btn\', \'.button\', ) | 61 |
SKIP_DEFER_HANDLES | private | array( \'wppo-combine-css\', \'dashicons\', \'admin-bar\', \'wp-block-library\', \'wc-block-style\', ) | 118 |
MAX_IMPORT_DEPTH | private | 3 | 132 |
DEFAULT_CCSS_MAX_SIZE | private | 20480 | 144 |
DEFAULT_CCSS_QUEUE_CAP | private | 5 | 156 |
MAX_CCSS_QUEUE_CAP | private | 100 | 164 |
DEFAULT_CCSS_GEN_TIMEOUT | private | 25 | 179 |
MAX_CCSS_GEN_TIMEOUT | private | 120 | 190 |
DEFAULT_CCSS_INLINE_BUDGET_BYTES | private | 14336 | 204 |
MIN_CCSS_INLINE_BUDGET_BYTES | private | 1024 | 212 |
MAX_CCSS_INLINE_BUDGET_BYTES | private | 102400 | 223 |
MAX_CCSS_SOURCE_BYTES | private | 2097152 | 236 |
MAX_CCSS_FETCHES | private | 30 | 249 |
MAX_CCSS_FILE_BYTES | private | 524288 | 257 |
DEFAULT_EXCLUDED_POST_TYPES | private | array( \'fl-builder-template\', \'elementor_library\' ) | 269 |
LAST_FULL_REGEN_OPTION | public | \'wppo_ccss_last_full_regen\' | 282 |
FULL_REGEN_COOLDOWN_SECONDS | private | 18000 | 293 |
TARGETED_REGEN_CAP | private | 20 | 305 |
TARGETED_REGEN_OPTION | public | \'wppo_ccss_last_targeted_regen\' | 319 |
TARGETED_REGEN_COOLDOWN_SECONDS | private | 3600 | 331 |
VIEWPORT_VARIANTS | public | array( \'mobile\', \'desktop\' ) | 409 |
MIN_INLINE_SIZE | private | 500 | 420 |
Properties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$lcp_preload_emitted | private static | array | array() | 38 |
$ccss_defer_blocked | private static | array | array() | 51 |
$has_microtime | private static | ?bool | null | 339 |
$excluded_memo | private static | ?array | null | 354 |
$gzip_size_memo | private static | array | array() | 368 |
$commerce_context_memo | private static | ?bool | null | 380 |
$commerce_excluded_context_memo | private static | ?bool | null | 392 |
$stale_probe_memo | private static | array | array() | 2656 |
$above_fold_matcher | private static | ?array | null | 4871 |
$ccss_presets_memo | private static | ?array | null | 4884 |
privatestatic get_ccss_dir()
private static function get_ccss_dir(): stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_dir}.
Return: string — Result (see Ccss_Store).
privatestatic get_ccss_url()
private static function get_ccss_url(): stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_url}.
Return: string — Result (see Ccss_Store).
publicstatic get_template_hash()
public static function get_template_hash(string=\'\' $template): stringGenerate a unique template hash for a template slug + stylesheet. Parameter Type Default Description $templatestring=\'\'— Optional template slug. Defaults to current template via get_current_template_slug().
Return: string — MD5 hash.
privatestatic get_current_template_slug()
private static function get_current_template_slug(): stringGet the current WordPress template slug based on conditional tags.
Return: string — Template slug: \’home\’, \’single\’, \’page\’, \’archive\’, or \’index\’.
privatestatic get_ccss_file()
private static function get_ccss_file(string $template_hash): stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_file}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: string — Result (see Ccss_Store).
privatestatic is_ccss_path_contained()
private static function is_ccss_path_contained(string $path): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::is_ccss_path_contained}. Parameter Type Default Description $pathstring— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
publicstatic stage_ccss_for_template()
public static function stage_ccss_for_template(string $template_hash, string $css): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::stage_ccss_for_template}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store). $cssstring— Parameter (see Ccss_Store).
Return: array — Result (see Ccss_Store).
publicstatic promote_staged_ccss()
public static function promote_staged_ccss(string $template_hash): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::promote_staged_ccss}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
publicstatic rollback_ccss_to_fallback()
public static function rollback_ccss_to_fallback(string $template_hash, string=\'manual\' $reason): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::rollback_ccss_to_fallback}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store). $reasonstring=\'manual\'— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
publicstatic get_ccss_rollout_status()
public static function get_ccss_rollout_status(string $template_hash): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_rollout_status}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: array — Result (see Ccss_Store).
publicstatic verify_ccss_health()
public static function verify_ccss_health(string $template_hash): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::verify_ccss_health}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: array — Result (see Ccss_Store).
publicstatic generate_preview_for_template()
public static function generate_preview_for_template(string $template): arrayDry-run critical-CSS generation with staged preview (issue #1348). Parameter Type Default Description $templatestring— Template identifier.
Return: array{staged: — bool, reason: string, bytes: int, checksum: string, live_bytes: int, live_checksum: string, changed: bool, template: string} Preview metadata.
publicstatic get_ccss_max_size()
public static function get_ccss_max_size(): intRead the configured CCSS inline size cap in bytes.
Return: int — Cap in bytes.
publicstatic truncate_to_cap()
public static function truncate_to_cap(string $css, int $cap): stringTruncate CSS to the cap without breaking a rule. Parameter Type Default Description $cssstring— CSS content. $capint— Maximum bytes.
Return: string — Truncated CSS, or \’\’ when nothing fits.
publicstatic get_full_regen_cooldown()
public static function get_full_regen_cooldown(): intEffective full-regen cooldown in seconds (issue #1462).
Return: int — Cooldown in seconds.
publicstatic get_ccss_inline_budget_bytes()
public static function get_ccss_inline_budget_bytes(): intRead the configured gzipped inline budget in bytes (issue #1388).
Return: int — Budget in bytes, clamped to MIN..MAX_CCSS_INLINE_BUDGET_BYTES.
publicstatic is_full_regen_cooled_down()
public static function is_full_regen_cooled_down(): boolWhether a non-forced full regeneration is inside the cooldown window (issue #1462).
Return: bool — True when the last full regen is newer than the cooldown.
publicstatic mark_full_regen()
public static function mark_full_regen(): voidRecord a completed full-regeneration scan (issue #1462).
Return: void.
publicstatic get_targeted_regen_cooldown()
public static function get_targeted_regen_cooldown(): intEffective targeted-regeneration cooldown in seconds (issue #1462).
Return: int — Cooldown in seconds (>= 0).
publicstatic is_targeted_regen_cooled_down()
public static function is_targeted_regen_cooled_down(): boolWhether a targeted regeneration is inside the throttle window (issue #1462).
Return: bool — True when the last targeted regen is newer than the cooldown.
publicstatic mark_targeted_regen()
public static function mark_targeted_regen(): voidRecord a targeted-regeneration pass (issue #1462).
Return: void.
publicstatic estimate_committed_inline_bytes()
public static function estimate_committed_inline_bytes(): intBytes already committed to inline output on this request (issue #1462).
Return: int — Committed inline bytes (>= 0).
publicstatic get_effective_ccss_budget()
public static function get_effective_ccss_budget(int=0 $already_inlined): intEffective inline budget for critical CSS after prior commits (issue #1462). Parameter Type Default Description $already_inlinedint=0— Bytes already committed to inline output.
Return: int — Effective budget in bytes (>= 0).
publicstatic coordinate_inline_budgets()
public static function coordinate_inline_budgets(string $ccss, string|int=\'\' $used_css): arrayCoordinate used CSS and critical CSS within one inline budget (issue #1462). Parameter Type Default Description $ccssstring— Critical CSS content for the current template. $used_cssstring|int=\'\'— Used-CSS content already committed inline (\’\’ when file-delivered), or a byte count to avoid materialising a stub string.
Return: array{inline: — string, deferred: string} Budget-aware CCSS split.
publicstatic request_targeted_regen()
public static function request_targeted_regen(string=\'\' $reason, int=20 $cap): intQueue a bounded targeted regen after builder/theme updates (issue #1462). Parameter Type Default Description $reasonstring=\'\'— Short reason for logging (e.g. \’builder-update\’). $capint=20— Maximum templates to requeue in this pass (0 = empty pass, no work; negatives clamp to 0).
Return: int — Number of jobs queued.
publicstatic gzipped_size()
public static function gzipped_size(string $css): intMeasure the gzipped transfer size of CSS output (issue #1388). Parameter Type Default Description $cssstring— CSS content.
Return: int — Gzipped size in bytes, or raw size without zlib.
publicstatic is_over_inline_budget()
public static function is_over_inline_budget(string $css): boolWhether CSS output exceeds the gzipped inline budget (issue #1388). Parameter Type Default Description $cssstring— CSS content.
Return: bool — True when the gzipped size exceeds the inline budget.
publicstatic is_commerce_excluded()
public static function is_commerce_excluded(): boolWhether cart/checkout inline critical CSS is excluded (issue #1388).
Return: bool — True when commerce exclusion is active.
publicstatic is_commerce_context()
public static function is_commerce_context(): boolWhether the current request is a cart/checkout context (issue #1388).
Return: bool — True on cart/checkout pages.
privatestatic is_commerce_excluded_context()
private static function is_commerce_excluded_context(): boolWhether commerce exclusion applies to the current request (issue #1388 review).
Return: bool — True when inline/deferral must yield to normal stylesheets.
publicstatic get_ccss_inline_budget_label()
public static function get_ccss_inline_budget_label(): stringHuman-readable label for the configured gzipped inline budget (issue #1388 review).
Return: string — e.g. \”14 KB\” or \”2.5 KB\”.
publicstatic is_checksum_regen_enabled()
public static function is_checksum_regen_enabled(): boolWhether checksum-triggered CCSS regen on save is enabled (issue #1388).
Return: bool — True when checksum regen is active.
publicstatic get_css_queue_cap()
public static function get_css_queue_cap(): intRead the configured per-run CCSS queue cap (issue #1164).
Return: int — Per-run cap, or PHP_INT_MAX when uncapped.
publicstatic get_ccss_queue_cap()
public static function get_ccss_queue_cap(): intCanonical double-`s` spelling of the per-run CCSS queue cap (issue #1235).
Return: int — Per-run cap, or PHP_INT_MAX when uncapped.
publicstatic get_ccss_gen_timeout()
public static function get_ccss_gen_timeout(): intRead the configured wall-clock budget in seconds for one CCSS generation run (issue #1235).
Return: int — Budget in seconds, clamped to 1..MAX_CCSS_GEN_TIMEOUT.
publicstatic parse_excluded_slugs()
public static function parse_excluded_slugs($raw): arrayNormalize raw exclusion slugs (setting lines or filter output). Parameter Type Default Description $rawstring|string[]|mixed— Raw slugs.
Return: string[] — Validated lowercase slugs.
publicstatic get_excluded_post_types()
public static function get_excluded_post_types(): arrayBuilder-template post types excluded from CSS generation (issue #1274).
Return: string[] — Excluded post type slugs.
publicstatic reset_excluded_post_types_memo()
public static function reset_excluded_post_types_memo(): voidReset the request-lifetime exclusion memo (unit tests).
Return: void.
publicstatic resolve_template_slug()
public static function resolve_template_slug(string $template, ?array=null $templates): stringResolve a template slug or hash to its canonical slug (issue #1274). Parameter Type Default Description $templatestring— Template slug or template hash. $templates?array=null— Optional pre-enumerated template map (reuses the caller\’s scan).
Return: string — Canonical slug, or \’\’ when unknown.
publicstatic is_known_template()
public static function is_known_template(string $template, ?array=null $templates): boolWhether a template slug or hash is a known template (issue #1274 review). Parameter Type Default Description $templatestring— Template slug or template hash. $templates?array=null— Optional pre-enumerated template map (reuses the caller\’s scan).
Return: bool — True when the slug or hash resolves to a template.
publicstatic is_post_type_excluded()
public static function is_post_type_excluded(string $post_type): boolWhether a post type is excluded from CSS generation (issue #1274). Parameter Type Default Description $post_typestring— Post type slug.
Return: bool — True when excluded.
publicstatic is_excluded_post()
public static function is_excluded_post(int $post_id): boolWhether a post ID belongs to an excluded builder-template type (issue #1274). Parameter Type Default Description $post_idint— Post ID.
Return: bool — True when the post should be skipped.
publicstatic get_ccss_max_retries()
public static function get_ccss_max_retries(): intBounded-retry cap for generic generation failures (issue #1274).
Return: int — Retry cap, 0..5.
privatestatic generation_now()
private static function generation_now(): floatCurrent wall-clock time in seconds with fractions.
Return: float — Now.
privatestatic generation_deadline()
private static function generation_deadline(int $budget): floatAbsolute deadline for a generation budget starting now. Parameter Type Default Description $budgetint— Budget in seconds.
Return: float — Unix timestamp (fractions) when the budget expires.
privatestatic generation_expired()
private static function generation_expired(?float $deadline): boolWhether a generation deadline has expired. Parameter Type Default Description $deadline?float— Absolute deadline, or null when uncapped.
Return: bool — True when the budget is exhausted.
privatestatic request_timeout_for_deadline()
private static function request_timeout_for_deadline(?float $deadline, int $fallback): intPer-request HTTP timeout bounded by the remaining budget. Parameter Type Default Description $deadline?float— Absolute deadline, or null for the default. $fallbackint— Historical per-request timeout in seconds.
Return: int — Timeout in seconds, 0 when exhausted, otherwise 1..$fallback.
privatestatic is_valid_template_hash()
private static function is_valid_template_hash($hash): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::is_valid_template_hash}. Parameter Type Default Description $hashmixed— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
privatestatic resolve_generation_budget()
private static function resolve_generation_budget(?float=null $deadline): arrayResolve one generation budget + deadline pair (issue #1235 review). Parameter Type Default Description $deadline?float=null— Optional caller-supplied deadline.
Return: array{0:int,1:float|null} — Budget and absolute deadline.
publicstatic generate_guarded()
public static function generate_guarded(string $template_hash, string $template, ?bool&=null $timed_out, bool=false $stage_only): boolGuarded CCSS generation wrapper with a wall-clock timeout (issue #1235). Parameter Type Default Description $template_hashstring— Template hash to generate. $templatestring— Template identifier for the sample URL. $timed_out?bool&=null— Out-param: true when the run hit the timeout budget. $stage_onlybool=false— When true (issue #1348 dry-run), the output lands on the staged sibling instead of going live.
Return: bool — True on success, false on failure or timeout.
publicstatic is_viewport_variants_enabled()
public static function is_viewport_variants_enabled(): boolWhether viewport-split CCSS variants are enabled (issue #1164).
Return: bool — True when split variants should be emitted/served.
publicstatic get_ccss_variant_file()
public static function get_ccss_variant_file(string $template_hash, string $variant): stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_variant_file}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store). $variantstring— Parameter (see Ccss_Store).
Return: string — Result (see Ccss_Store).
publicstatic get_ccss_variant_content()
public static function get_ccss_variant_content(string $template_hash, string $variant): ?stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_variant_content}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store). $variantstring— Parameter (see Ccss_Store).
Return: ?string — Result (see Ccss_Store).
publicstatic is_variant_stale()
public static function is_variant_stale(string $template_hash, string $variant): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::is_variant_stale}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store). $variantstring— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
publicstatic invalidate_stale_variants()
public static function invalidate_stale_variants(string $template_hash): voidFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::invalidate_stale_variants}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: void.
publicstatic is_block_library_defer_exempt()
public static function is_block_library_defer_exempt(string $handle, string=\'\' $href): boolWhether a stylesheet handle is exempt from CCSS deferral (issue #1164). Parameter Type Default Description $handlestring— Stylesheet handle. $hrefstring=\'\'— Stylesheet URL (optional, substring match).
Return: bool — True when the handle must load normally.
publicstatic is_elementor_context()
public static function is_elementor_context(?int=null $post_id): boolWhether the current request is an Elementor context (issue #1164). Parameter Type Default Description $post_id?int=null— Optional post ID to inspect.
Return: bool — True when Elementor handling applies.
publicstatic passes_elementor_smoke()
public static function passes_elementor_smoke(string $html, string $purged_css): boolElementor smoke check: purged CSS must still cover builder markers (issue #1164). Parameter Type Default Description $htmlstring— Page HTML. $purged_cssstring— Purged/used CSS candidate.
Return: bool — True when it is safe to serve the purged CSS.
publicstatic get_ccss_safelist_presets()
public static function get_ccss_safelist_presets(): arrayBuilt-in Critical CSS safelist presets (issue #1102).
Return: string[].
publicstatic get_ccss_safelist()
public static function get_ccss_safelist(): arrayUser safelist of selectors always kept in Critical CSS (issue #1038).
Return: string[] — Safelisted selectors, trimmed and de-duplicated.
publicstatic matches_ccss_safelist()
public static function matches_ccss_safelist(string $selector, ?array=null $safelist): boolWhether a selector matches the Critical CSS user safelist. Parameter Type Default Description $selectorstring— CSS selector string (may be a group). $safelist?array=null— Optional pre-fetched safelist; callers walking many rules pass the list in so settings are read once, not per rule.
Return: bool — True when safelisted.
publicstatic get_ccss_effective_safelist()
public static function get_ccss_effective_safelist(): arrayEffective Critical CSS safelist: built-in presets + user entries.
Return: string[] — Merged safelisted selectors.
publicstatic compute_css_checksum()
public static function compute_css_checksum(string $css): stringStable content hash of CSS source (issue #1038). Parameter Type Default Description $cssstring— CSS content.
Return: string — SHA-256 checksum, or \’\’ for empty input.
privatestatic get_source_checksum_key()
private static function get_source_checksum_key(string $template_hash): stringMultisite-aware transient key for a template\’s source checksum. Parameter Type Default Description $template_hashstring— Template hash.
Return: string — Transient key.
privatestatic get_source_urls_key()
private static function get_source_urls_key(string $template_hash): stringMultisite-aware transient key for a template\’s canonical source URL list. Parameter Type Default Description $template_hashstring— Template hash.
Return: string — Transient key.
privatestatic get_source_checksum_ttl()
private static function get_source_checksum_ttl(): intTTL for the per-template source baseline transients.
Return: int — TTL in seconds.
publicstatic store_source_urls()
public static function store_source_urls(string $template_hash, array $source_urls): voidPersist the canonical document-ordered source URL list after generation. Parameter Type Default Description $template_hashstring— Template hash. $source_urlsarray— Document-ordered stylesheet URLs.
Return: void.
privatestatic get_stored_source_urls()
private static function get_stored_source_urls(string $template_hash): arrayRead the persisted canonical source URL list. Parameter Type Default Description $template_hashstring— Template hash.
Return: string[] — Persisted URLs, or array() when none.
publicstatic is_source_checksum_stale()
public static function is_source_checksum_stale(string $template_hash, string $source_css): boolWhether stored source checksum differs (stale CCSS, issue #1038). Parameter Type Default Description $template_hashstring— Template hash. $source_cssstring— Locally-available source CSS content.
Return: bool — True when the source changed since generation.
publicstatic store_source_checksum()
public static function store_source_checksum(string $template_hash, string $source_css): voidPersist the source checksum after a successful generation. Parameter Type Default Description $template_hashstring— Template hash. $source_cssstring— Source CSS content that was generated from.
Return: void.
publicstatic maybe_refresh_from_local_css()
public static function maybe_refresh_from_local_css(string $template_hash, string $source_css): boolChecksum-triggered refresh from locally-available CSS (issue #1038). Parameter Type Default Description $template_hashstring— Template hash. $source_cssstring— Locally-available source CSS content.
Return: bool — True when the stored variant was dropped as stale.
privatestatic build_local_source_css()
private static function build_local_source_css(array $urls, ?float=null $deadline): stringBuild the canonical local-source CSS string from ordered URLs. Parameter Type Default Description $urlsarray— Ordered stylesheet URLs (document/queue order). $deadline?float=null— Optional absolute wall-clock deadline; the file loop breaks early when expired (issue #1235 review).
Return: string — Concatenated source CSS, or \’\’ when none resolve locally.
privatestatic is_skipped_source_url()
private static function is_skipped_source_url(string $url): boolWhether a stylesheet URL is excluded from the CCSS source set. Parameter Type Default Description $urlstring— Stylesheet URL or handle-like fragment.
Return: bool — True when skipped.
privatestatic get_core_inlined_handles()
private static function get_core_inlined_handles(): arrayHandles core\’s `wp_maybe_inline_styles()` will print inline.
Return: string[] — Handles that core will inline (queue order).
privatestatic get_local_source_css()
private static function get_local_source_css(): stringAggregate locally-available source CSS from the queued stylesheets.
Return: string — Concatenated local source CSS, or \’\’ when unavailable.
publicstatic maybe_check_stale_on_enqueue()
public static function maybe_check_stale_on_enqueue(): voidChecksum freshness probe wired into the production path (issue #1038).
Return: void.
publicstatic maybe_check_stale_and_requeue()
public static function maybe_check_stale_and_requeue(string $template_hash): boolChecksum freshness probe (issue #1038). Parameter Type Default Description $template_hashstring— Template hash.
Return: bool — True when the stored variant was dropped as stale.
publicstatic maybe_regen_on_save()
public static function maybe_regen_on_save($post_id, =null $post): boolChecksum-gated CCSS regen on post save (issue #1388). Parameter Type Default Description $post_idint— Post ID. $post=null— Post object or null.
Return: bool — True when at least one stale template was requeued.
privatestatic get_styles_inline_limit()
private static function get_styles_inline_limit(): intRead core\’s `styles_inline_size_limit` budget.
Return: int — The inline size limit in bytes.
privatestatic is_inline_allowed()
private static function is_inline_allowed(): boolWhether CCSS may be inlined on this request.
Return: bool — True when inlining is allowed.
publicstatic is_deferral_suspended_by_js()
public static function is_deferral_suspended_by_js(): boolWhether stylesheet deferral is suspended by deferred/delayed JS.
Return: bool — True when deferJS or delayJS is enabled.
publicstatic is_ccss_effective()
public static function is_ccss_effective(): boolWhether critical CSS is effective on this request.
Return: bool — True when CCSS emission and deferral should run.
privatestatic loadcss_loader_tag()
private static function loadcss_loader_tag(): stringAsync loadCSS fallback snippet as a script tag (audit #1392).
Return: string — Inline loader script tag.
privatestatic has_strict_csp()
private static function has_strict_csp(): boolWhether a strict Content-Security-Policy blocks raw inline scripts.
Return: bool — True when inline scripts would be blocked.
privatestatic get_ccss_file_url()
private static function get_ccss_file_url(string $template_hash): stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_file_url}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: string — Result (see Ccss_Store).
publicstatic get_ccss_meta()
public static function get_ccss_meta(string $template_hash): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_meta}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: array — Result (see Ccss_Store).
publicstatic reset_ccss_memo()
public static function reset_ccss_memo(): voidReset the per-request CCSS memos (facade, FUT-001).
Return: void.
privatestatic invalidate_ccss_memo()
private static function invalidate_ccss_memo(string $template_hash): voidFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::invalidate_ccss_memo}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: void.
publicstatic ccss_exists()
public static function ccss_exists(string $template_hash): boolFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::ccss_exists}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: bool — Result (see Ccss_Store).
privatestatic get_ccss_content()
private static function get_ccss_content(string $template_hash): ?stringFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_ccss_content}. Parameter Type Default Description $template_hashstring— Parameter (see Ccss_Store).
Return: ?string — Result (see Ccss_Store).
publicstatic get_status_all()
public static function get_status_all(): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_status_all}.
Return: array — Result (see Ccss_Store).
privatestatic get_templates()
private static function get_templates(): arrayFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_templates}.
Return: array — Result (see Ccss_Store).
privatestatic get_sample_url()
private static function get_sample_url(string $template): string|falseFacade proxy (FUT-001): canonical owner is {@see \\PerformanceOptimise\\Inc\\Ccss_Store::get_sample_url}. Parameter Type Default Description $templatestring— Parameter (see Ccss_Store).
Return: string|false — Result (see Ccss_Store).
publicstatic get_field_lcp_preload_url()
public static function get_field_lcp_preload_url(?string=null $url): stringField-measured LCP image preload target for a page URL (issue #1255). Parameter Type Default Description $url?string=null— Page URL. Null resolves the current request path. Only the path is used.
Return: string — Same-origin LCP image URL, or \’\’ when none resolves.
privatestatic is_image_preload_url()
private static function is_image_preload_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.
privatestatic is_image_pipeline_lcp_preload_active()
private static function is_image_pipeline_lcp_preload_active(): boolWhether the image pipeline owns LCP preloading on this request.
Return: bool — True when the image pipeline will preload the LCP hero.
privatestatic is_ccss_field_lcp_preload_allowed()
private static function is_ccss_field_lcp_preload_allowed(): boolWhether the CCSS-path field-LCP preload may fire on this request.
Return: bool — True when the CCSS-path preload may emit.
privatestatic maybe_emit_field_lcp_preload()
private static function maybe_emit_field_lcp_preload(): voidEmit the field-measured LCP image preload for the current page.
Return: void.
privatestatic extract_css_sources_with_processor()
private static function extract_css_sources_with_processor(string $html, ?float $deadline): ?arrayExtract inline `<style>` bodies and stylesheet hrefs via the HTML API. Parameter Type Default Description $htmlstring— Page HTML (already byte-capped by the caller). $deadline?float— Absolute deadline, or null when uncapped.
Return: array{inline_css: — string, source_urls: string[]}|null Inline CSS plus document-ordered hrefs, or null to take the DOM path.
publicstatic generate()
public static function generate(string $url, ?string&=null $source_css, ?array&=null $resolved_urls, ?float=null $deadline)Generate critical CSS for a given URL. Parameter Type Default Description $urlstring— The page URL to generate CCSS for. $source_css?string&=null— Out-param: canonical local-source CSS (locally-resolvable external stylesheets, document order) used for the freshness checksum (issue #1038). $resolved_urls?array&=null— Out-param: the exact document-ordered `//link[@rel=stylesheet]` href list the fetch saw, persisted so the runtime probe re-hashes the same list (audit #9). Pass a non-null array to receive it; null opts out and receives nothing. $deadline?float=null— Optional absolute wall-clock deadline (see generation_deadline()). Trusted callers only: external deadlines clamp to now + MAX_CCSS_GEN_TIMEOUT so a caller can never smuggle an unbounded budget. When null a fresh get_ccss_gen_timeout() budget applies; expired runs abort fail-open (issue #1235).
Return: string|false — The critical CSS content, or false on failure.
privatestatic fetch_stylesheet_with_imports()
private static function fetch_stylesheet_with_imports(string $url, int=0 $depth, ?float=null $deadline, array&=array() $seen, int&=0 $fetches): stringFetch a stylesheet and recursively resolve @import directives. Parameter Type Default Description $urlstring— The stylesheet URL. $depthint=0— Current recursion depth. $deadline?float=null— Optional absolute wall-clock deadline. $seenarray&=array()— By-ref case-insensitive visited-URL set shared across the whole generation run (cycle dedupe). $fetchesint&=0— By-ref total-fetch counter shared across the whole run, bounded by MAX_CCSS_FETCHES.
Return: string — The combined CSS content with @imports inlined, or empty string on failure or expiry.
privatestatic resolve_import_url()
private static function resolve_import_url(string $import_url, string $base_url): stringResolve a potentially relative @import URL against a base stylesheet URL. Parameter Type Default Description $import_urlstring— The URL from the @import statement. $base_urlstring— The base stylesheet URL.
Return: string — The absolute resolved URL, or empty string if unresolvable.
privatestatic is_same_site_host()
private static function is_same_site_host(string $url): boolWhether the URL points at this WordPress site\’s own host. Parameter Type Default Description $urlstring— The URL to inspect.
Return: bool — True when the URL host matches home_url().
privatestatic is_safe_stylesheet_url()
private static function is_safe_stylesheet_url(string $url): boolWhether a stylesheet URL is safe to request server-side. Parameter Type Default Description $urlstring— The stylesheet URL.
Return: bool — True when safe to fetch.
privatestatic decode_css_entities()
private static function decode_css_entities(string $css): stringDecode numeric/hex HTML entities so encoded payloads cannot smuggle `<` past the encoder (e.g. Parameter Type Default Description $cssstring— Raw critical CSS.
Return: string — Entity-decoded CSS.
privatestatic contains_unsafe_css_tokens()
private static function contains_unsafe_css_tokens(string $css): boolWhether decoded CSS contains tokens that could break out of a `<style>` element or execute script when inlined. Parameter Type Default Description $cssstring— Raw critical CSS.
Return: bool — True when hostile tokens are present.
privatestatic sanitize_inline_css_tokens()
private static function sanitize_inline_css_tokens(string $css): stringSanitize generated critical CSS for safe output inside a <style> tag. Parameter Type Default Description $cssstring— Raw critical CSS.
Return: string — Sanitized critical CSS.
privatestatic sanitize_inline_css()
private static function sanitize_inline_css(string $css): stringSanitize generated critical CSS for safe output inside a <style> tag. Parameter Type Default Description $cssstring— Raw critical CSS.
Return: string — Sanitized critical CSS.
privatestatic extract_above_fold_css()
private static function extract_above_fold_css(string $css, ?float=null $deadline): stringExtract above-fold CSS rules using heuristic selector matching. Parameter Type Default Description $cssstring— Full CSS content. $deadline?float=null— Optional absolute wall-clock deadline; the scan stops early when it expires (issue #1235).
Return: string — Extracted critical CSS.
privatestatic parse_regular_rules()
private static function parse_regular_rules(string $css, array& $critical_parts, ?array=null $safelist, ?float=null $deadline): voidParse regular (non-at-rule) CSS rules using brace-depth tracking. Parameter Type Default Description $cssstring— Full CSS content. $critical_partsarray&— Reference to array of extracted critical CSS parts. $safelist?array=null— Pre-fetched safelist (null = fetch once here). $deadline?float=null— Optional absolute wall-clock deadline; the scan stops early when it expires (issue #1235).
Return: void.
privatestatic filter_media_query_rules()
private static function filter_media_query_rules(string $media_query, ?array=null $safelist, ?float=null $deadline): stringFilter rules inside a media query to keep only above-fold selectors. Parameter Type Default Description $media_querystring— Full media query block. $safelist?array=null— Pre-fetched safelist (null = fetch once here). $deadline?float=null— Optional absolute wall-clock deadline; the per-rule loop aborts early when expired (issue #1235).
Return: string — Filtered media query or empty string.
privatestatic matches_above_fold()
private static function matches_above_fold(string $selector, ?array=null $safelist): boolCheck if a CSS selector matches above-fold selectors. Parameter Type Default Description $selectorstring— The CSS selector string (may contain multiple selectors separated by commas). $safelist?array=null— Pre-fetched safelist (null = fetch once here).
Return: bool — True if any individual selector should be included in critical CSS.
privatestatic matches_above_fold_single()
private static function matches_above_fold_single(string $selector, ?array=null $safelist): boolCheck if a single CSS selector matches above-fold selectors using token-based matching. Parameter Type Default Description $selectorstring— A single trimmed CSS selector. $safelist?array=null— Pre-fetched safelist (null = fetch once here).
Return: bool — True if the selector matches.
privatestatic get_above_fold_matcher()
private static function get_above_fold_matcher(): arrayBuild the precompiled above-fold matcher (exact hash sets + one alternation).
Return: array{exact: — array<string, bool>, regex: string}.
privatestatic token_match()
private static function token_match(string $selector_part, string $above): boolToken-based selector matching that prevents substring false positives. Parameter Type Default Description $selector_partstring— A single selector fragment (e.g., \’.container\’, \’#header\’, \’h1\’). $abovestring— The above-fold selector pattern to match against.
Return: bool — True if the selector part matches the pattern.
privatestatic token_match_precompiled()
private static function token_match_precompiled(string $selector_part): boolFast token match using the precompiled above-fold matcher. Parameter Type Default Description $selector_partstring— Single selector fragment (last descendant part).
Return: bool — True on match.
privatestatic generate_and_store()
private static function generate_and_store(string $template_hash, string $template, ?float=null $deadline, ?int=null $budget, bool=false $stage_only): boolGenerate critical CSS for a template and store it atomically. Parameter Type Default Description $template_hashstring— Template hash. $templatestring— Template identifier for the sample URL. $deadline?float=null— Optional absolute wall-clock deadline. $budget?int=null— Optional already-resolved budget for logging (avoids a second settings read). $stage_onlybool=false— When true (issue #1348 dry-run), commit to the staged sibling: no variant mirrors, no source-checksum baselining, live file untouched.
Return: bool — True on success, false on failure or timeout.
publicstatic inline_ccss()
public static function inline_ccss(): voidInline critical CSS in the <head> for non-logged-in visitors.
Return: void.
publicstatic defer_stylesheets()
public static function defer_stylesheets(string $tag, string $handle, string $href): stringDefer full stylesheets by adding media=\”print\” onload=\”this.media=\’all\’\”. Parameter Type Default Description $tagstring— The link tag HTML. $handlestring— The stylesheet handle. $hrefstring— The stylesheet URL.
Return: string — Modified link tag.
privatestatic purge_template_artifacts()
private static function purge_template_artifacts(string $template_hash): voidPurge every stored artifact for a template hash (issue #1347). Parameter Type Default Description $template_hashstring— Template hash.
Return: void.
publicstatic background_generate()
public static function background_generate(array $args): voidBackground generation callback for Action Scheduler. Parameter Type Default Description $argsarray— Arguments containing \’template_hash\’.
Return: void.
publicstatic order_templates_by_rum_priority()
public static function order_templates_by_rum_priority(array $templates): arrayOrder templates worst-p75 LCP first for CCSS queue prioritization. Parameter Type Default Description $templatesarray— —
Return: array<string, — string> Ordered templates (same entries).
publicstatic regenerate_all()
public static function regenerate_all(bool=false $force): intRegenerate all template CCSS files via Action Scheduler. Parameter Type Default Description $forcebool=false— Bypass the cooldown (explicit operator paths: builder purge after a wipe, manual triggers).
Return: int — Number of jobs queued.
publicstatic regenerate_single()
public static function regenerate_single(string $template, ?array=null $templates): intRegenerate critical CSS for a single template (issue #1274). Parameter Type Default Description $templatestring— Template slug or template hash. $templates?array=null— Optional pre-enumerated template map (reuses the caller\’s scan).
Return: int — 1 when queued, 0 for legit skip/unknown, -1 when the scheduler is unavailable (infra failure, not a benign skip).
publicstatic clear_all()
public static function clear_all(?array=null $templates): voidClear all CCSS files and status transients. Parameter Type Default Description $templates?array=null— —
Return: void.
publicstatic get_status_cache_for_store()
public static function get_status_cache_for_store(string $hash)Read the generation-status cache through the canonical owner. Parameter Type Default Description $hashstring— Template hash.
Return: string|false — Status string, or false when unset.
Hooks
Hooks referenced in includes/CSS/class-critical-css.php: Hook Type Line Notes wppo_ccss_regen_cooldownfilter 699 — wppo_ccss_inline_budgetfilter 736 — wppo_ccss_targeted_cooldownfilter 824 @param ×1 wppo_committed_inline_bytesfilter 910 — wppo_ccss_queue_capfilter 1395 — wppo_ccss_generation_timeoutfilter 1452 — wppo_ccss_excluded_post_typesfilter 1543 — wppo_is_elementor_pagefilter 2128 — wppo_ccss_safelist_presetsfilter 2253 @param ×1 wppo_ccss_safelistfilter 2289 @param ×1 wppo_ccss_checksum_ttlfilter 2462 @param ×1 wppo_inline_combined_cssfilter 3120 — wppo_critical_css_strict_cspfilter 3196 @param ×1 wppo_ccss_field_lcp_preloadfilter 3539 — wppo_ccss_allowed_stylesheet_hostfilter 4315 @param ×2 wppo_ccss_sanitize_inlinefilter 4515 @param ×1