includes/Support/class-url.php
URL boundary — construction, comparison, normalization, and exclusion.
Class Url
Class Url
final class UrlProperties
| Property | Visibility | Type | Default | Line |
|---|---|---|---|---|
$home_url_cache | private static | array | array() | 56 |
$canonical_host_cache | private static | array | array() | 64 |
$same_site_home_host | private static | array | array() | 72 |
$exclusion_rule_cache | private static | array | array() | 86 |
$content_url_cache | private static | array | array() | 94 |
publicstatic reset_cached_home_urls()
public static function reset_cached_home_urls(): voidResets the home_url static cache for testing isolation.
Return: void.
publicstatic process_urls()
public static function process_urls($urls)Normalize and deduplicate a list of URLs. Parameter Type Default Description $urlsstring|array— Raw URLs as a newline-delimited string or an array of strings.
Return: array — Cleaned list of unique, trimmed URLs with empty values removed and numeric keys reindexed.
publicstatic coerce_string_list()
public static function coerce_string_list($raw): arrayCoerce an untrusted string list (e.g. filter output) to a clean list. Parameter Type Default Description $rawmixed— Untrusted list value.
Return: string[] — Clean list.
publicstatic is_url_excluded()
public static function is_url_excluded(string $url, array $exclude_urls): boolCheck whether a URL matches any of the exclusion rules. Parameter Type Default Description $urlstring— The URL to check. $exclude_urlsarray— List of exclusion rules.
Return: bool — True when the URL matches any exclusion rule, false otherwise.
publicstatic get_current_url()
public static function get_current_url(): stringGet the current front-end URL including scheme and host.
Return: string — Current URL.
publicstatic normalize_rum_path()
public static function normalize_rum_path(string $path): stringNormalize a RUM page path for storage and lookup. Parameter Type Default Description $pathstring— Raw page path.
Return: string — Normalized path (e.g. \’/hero-page\’, \’/\’).
publicstatic normalize_url()
public static function normalize_url(string $url): stringNormalize a URL for LCP matching. Parameter Type Default Description $urlstring— The raw URL to normalize.
Return: string — Normalized host + path, or empty string when unparseable.
publicstatic normalize_site_url()
public static function normalize_site_url(string $url): stringResolve a site URL to an absolute https URL. Parameter Type Default Description $urlstring— Raw URL.
Return: string — Absolute URL or \’\’ when empty/data:.
publicstatic normalize_image_key()
public static function normalize_image_key(string $url): stringNormalize a URL to a stable image/cache key (host + path). Parameter Type Default Description $urlstring— Raw URL.
Return: string — Normalized key or \’\’.
publicstatic cached_content_url()
public static function cached_content_url($path)Get a content URL, cached per site per request. Parameter Type Default Description $pathstring— Path relative to the content directory.
Return: string — The content URL for the given path.
privatestatic pin_url_scheme()
private static function pin_url_scheme(string $url): stringRewrite a URL\’s scheme to the site\’s canonical scheme. Parameter Type Default Description $urlstring— URL to normalize.
Return: string — URL carrying the canonical scheme.
publicstatic canonical_scheme()
public static function canonical_scheme(): stringThe site\’s canonical URL scheme, independent of the current request.
Return: string — Either \’http\’ or \’https\’.
publicstatic cached_home_url()
public static function cached_home_url(string=\'\' $path): stringGet the home URL, cached per site per request. Parameter Type Default Description $pathstring=\'\'— Optional. Path relative to the home URL. Default empty.
Return: string — The untrailingslashed home URL, with path appended if provided.
publicstatic is_same_site_host()
public static function is_same_site_host(string $url): boolWhether a URL\’s host matches the home host (case-insensitive). Parameter Type Default Description $urlstring— URL to check.
Return: bool — True when hosts match and home host is known.
privatestatic normalize_host_for_compare()
private static function normalize_host_for_compare(string $host): stringNormalize a host for case-insensitive same-site comparison. Parameter Type Default Description $hoststring— Raw host value.
Return: string — Normalized host.
publicstatic is_same_site_url()
public static function is_same_site_url(string $url): boolWhether a URL is same-site and safe for server-side fetching. Parameter Type Default Description $urlstring— URL to check.
Return: bool — True when safe.
privatestatic is_allowed_same_site_port()
private static function is_allowed_same_site_port(array $parsed): boolWhether a parsed URL\’s port is allowed by the same-site policy. Parameter Type Default Description $parsedarray— —
Return: bool — True when the port leg passes.
privatestatic home_effective_port()
private static function home_effective_port(): ?intEffective port of the home URL (explicit port or scheme default).
Return: int|null — Effective home port, or null when indeterminable (fail closed).
publicstatic same_site_url_or_home()
public static function same_site_url_or_home(string $url, string $fallback): stringValidate a caller-supplied URL as same-site, else the fallback. Parameter Type Default Description $urlstring— Caller URL (already esc_url_raw\’d by caller). $fallbackstring— Fallback (home URL, or \’\’ to fail closed).
Return: string — Same-site URL or the fallback.
publicstatic resolve_same_host_redirect()
public static function resolve_same_host_redirect(string $location, string $current_url): string|falseResolve a redirect Location against the current URL and validate it. Parameter Type Default Description $locationstring— Raw Location header value. $current_urlstring— URL of the response that sent the Location.
Return: string|false — Absolute validated URL, or false when the hop is not allowed.
privatestatic normalize_redirect_target()
private static function normalize_redirect_target(string $target): stringNormalize a redirect target (path + optional ?query/#fragment). Parameter Type Default Description $targetstring— Path with optional query/fragment suffix.
Return: string — Normalized target.
privatestatic remove_dot_segments()
private static function remove_dot_segments(string $path): stringRemove RFC 3986 section 5.2.4 dot segments from a URL path. Parameter Type Default Description $pathstring— URL path to normalize.
Return: string — Normalized path (always starting with \’/\’).
publicstatic get_canonical_host()
public static function get_canonical_host(): stringResolve the canonical host for cache keying from home_url().
Return: string — Canonical lowercase host, or \’\’ when it cannot be resolved.
privatestatic resolve_canonical_host()
private static function resolve_canonical_host(): stringUncached canonical-host resolution backing get_canonical_host().
Return: string — Canonical lowercase host, or \’\’ when unresolvable.