| @@ -19,8 +19,10 @@ | ||
| 19 | 19 | declare(strict_types=1); |
| 20 | 20 | |
| 21 | 21 | namespace XSpeed\Modules\Fonts; |
| 22 | 22 | |
| 23 | +defined( 'ABSPATH' ) || exit; | |
| 24 | + | |
| 23 | 25 | use XSpeed\Module; |
| 24 | 26 | |
| 25 | 27 | final class FontsModule extends Module { |
| 26 | 28 | |
| @@ -29,11 +31,12 @@ | ||
| 29 | 31 | public const VERSION = '1.0.0'; |
| 30 | 32 | |
| 31 | 33 | public function ui_metadata(): array { |
| 32 | 34 | return array( |
| 33 | - 'label' => 'Fonts', | |
| 35 | + 'label' => __( 'Fonts', 'xspeed' ), | |
| 34 | 36 | 'icon' => 'Type', |
| 35 | - 'description' => 'Stop web fonts from blocking text. Adds display=swap to Google Fonts and preloads the fonts you mark critical.', | |
| 37 | + 'description' => __( 'Shows text right away while web fonts load, and preloads key fonts.', 'xspeed' ), | |
| 38 | + 'group' => 'performance', | |
| 36 | 39 | ); |
| 37 | 40 | } |
| 38 | 41 | |
| 39 | 42 | public function settings_schema(): array { |
| @@ -40,22 +43,41 @@ | ||
| 40 | 43 | return array( |
| 41 | 44 | 'font_display_swap' => array( |
| 42 | 45 | 'type' => 'bool', |
| 43 | 46 | 'default' => true, |
| 44 | - 'label' => 'Add font-display: swap', | |
| 45 | - 'description' => 'Append display=swap to Google Fonts URLs so text renders immediately in a fallback face while the web font loads. No effect on URLs that already declare a display value.', | |
| 47 | + 'label' => __( 'Show text while fonts load', 'xspeed' ), | |
| 48 | + 'description' => __( 'Text in Google Fonts, and in fonts added to WordPress itself, shows at once in a standard font, then switches when the web font arrives.', 'xspeed' ), | |
| 46 | 49 | ), |
| 47 | 50 | 'preload_fonts' => array( |
| 48 | 51 | 'type' => 'list', |
| 49 | 52 | 'default' => array(), |
| 50 | 53 | 'item_type' => 'url', |
| 51 | - 'label' => 'Preload Font URLs', | |
| 52 | - 'description' => 'One absolute font URL per line (woff2/woff/ttf/otf). Each becomes a <link rel="preload" as="font" crossorigin> in the head so the browser starts downloading before the CSS parses. Use only for fonts that render above the fold.', | |
| 54 | + 'label' => __( 'Fonts to preload', 'xspeed' ), | |
| 55 | + 'description' => __( 'One full font file URL per line (woff2, woff, ttf or otf). The browser fetches these first, so list only fonts used at the top of the page.', 'xspeed' ), | |
| 53 | 56 | ), |
| 54 | 57 | ); |
| 55 | 58 | } |
| 56 | 59 | |
| 57 | 60 | public function boot(): void { |
| 61 | + /* | |
| 62 | + * Deferred to `init`. This module reads its own settings to decide | |
| 63 | + * what to hook, and reading settings builds settings_schema(), whose | |
| 64 | + * labels are declared through __(). boot() runs on `plugins_loaded`, | |
| 65 | + * before `after_setup_theme` — the point WordPress 6.7+ treats as the | |
| 66 | + * earliest safe moment to translate — so doing that here fires | |
| 67 | + * _load_textdomain_just_in_time on every request AND resolves the | |
| 68 | + * labels against a domain that is not loaded yet. | |
| 69 | + * | |
| 70 | + * Everything below hooks actions that fire after `init`, so running | |
| 71 | + * one hook later is equivalent. | |
| 72 | + */ | |
| 73 | + add_action( 'init', array( $this, 'boot_on_init' ) ); | |
| 74 | + } | |
| 75 | + | |
| 76 | + /** | |
| 77 | + * The real boot body — see boot() for why it runs on `init`. | |
| 78 | + */ | |
| 79 | + public function boot_on_init(): void { | |
| 58 | 80 | // Frontend-only rewriting. Admin / cron / AJAX / REST never |
| 59 | 81 | // render <link rel="stylesheet"> tags we should touch. |
| 60 | 82 | if ( is_admin() |
| 61 | 83 | || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) |
| @@ -60,8 +82,12 @@ | ||
| 60 | 82 | if ( is_admin() |
| 61 | 83 | || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) |
| 62 | 84 | || ( defined( 'DOING_CRON' ) && DOING_CRON ) |
| 63 | 85 | || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) |
| 86 | + // A builder editing screen is a front-end URL none of the above | |
| 87 | + // catch; swapping font-display under it changes what the editor | |
| 88 | + // measures. (#281) | |
| 89 | + || \XSpeed\Builder_Editor::is_active() | |
| 64 | 90 | ) { |
| 65 | 91 | return; |
| 66 | 92 | } |
| 67 | 93 | |
| @@ -68,8 +94,27 @@ | ||
| 68 | 94 | $opts = $this->get_settings(); |
| 69 | 95 | |
| 70 | 96 | if ( ! empty( $opts['font_display_swap'] ) ) { |
| 71 | 97 | add_filter( 'style_loader_tag', array( __CLASS__, 'inject_display_swap' ), 10, 2 ); |
| 98 | + | |
| 99 | + // Fonts added through the Font Library or theme.json are printed | |
| 100 | + // by core with font-display: fallback, and core offers no filter | |
| 101 | + // for it. Fallback hides the text for up to 100ms while the font | |
| 102 | + // loads; when that text is the LCP, the hero paints after the | |
| 103 | + // font instead of at first paint. Measured on a live text hero: | |
| 104 | + // LCP landed ~85ms after FCP with fallback and on FCP with swap, | |
| 105 | + // CLS unchanged, and PageSpeed mobile moved between 81 and 90 | |
| 106 | + // depending on which side of that window the font fell. So core's | |
| 107 | + // own printer runs with swap as the default. Only an exact | |
| 108 | + // priority-50 hook is replaced: anything that already moved or | |
| 109 | + // removed it is left alone. | |
| 110 | + if ( function_exists( 'wp_print_font_faces' ) | |
| 111 | + && class_exists( '\WP_Font_Face_Resolver' ) | |
| 112 | + && 50 === has_action( 'wp_head', 'wp_print_font_faces' ) | |
| 113 | + ) { | |
| 114 | + remove_action( 'wp_head', 'wp_print_font_faces', 50 ); | |
| 115 | + add_action( 'wp_head', array( __CLASS__, 'print_font_faces_swap' ), 50 ); | |
| 116 | + } | |
| 72 | 117 | } |
| 73 | 118 | |
| 74 | 119 | if ( ! empty( $opts['preload_fonts'] ) ) { |
| 75 | 120 | add_action( |
| @@ -103,15 +148,36 @@ | ||
| 103 | 148 | } |
| 104 | 149 | |
| 105 | 150 | $href = $m[2]; |
| 106 | 151 | |
| 107 | - // Already has a display param — leave it alone (respect the | |
| 108 | - // theme / plugin that set it). | |
| 109 | - if ( preg_match( '/[?&]display=/i', $href ) ) { | |
| 152 | + // A display param the theme set is respected ONLY when it is one of | |
| 153 | + // the non-blocking choices (swap / fallback / optional) — someone | |
| 154 | + // picked those deliberately and each is a defensible trade. `auto` | |
| 155 | + // and `block` are the values this setting exists to remove: `auto` | |
| 156 | + // IS block behavior in every engine, and it is almost never a | |
| 157 | + // choice — it is the default a theme's enqueue happened to emit. | |
| 158 | + // "Respecting" it turned the switch into a no-op on exactly the | |
| 159 | + // sites that need it: a live text-LCP measured a 5.5s render delay | |
| 160 | + // behind flatsome's `display=auto` Poppins URL while this option | |
| 161 | + // was on and its label promised the opposite. WP Rocket and | |
| 162 | + // LiteSpeed rewrite these too. The href here has been through | |
| 163 | + // esc_url(), which encodes "&" as "&" — decode before | |
| 164 | + // matching, rewrite on the ORIGINAL encoded href so str_replace | |
| 165 | + // finds it in the tag verbatim. (FBS-82161) | |
| 166 | + $href_decoded = html_entity_decode( $href, ENT_QUOTES | ENT_HTML5 ); | |
| 167 | + if ( preg_match( '/([?&])display=(auto|block)(&|$)/i', $href_decoded ) ) { | |
| 168 | + $new_href = preg_replace( '/((?:[?&]|�*38;|&#[xX]0*26;|&)display=)(?:auto|block)(?=&|$)/i', '$1swap', $href ); | |
| 169 | + | |
| 170 | + return str_replace( $href, $new_href, $tag ); | |
| 171 | + } | |
| 172 | + if ( preg_match( '/[?&]display=/i', $href_decoded ) ) { | |
| 110 | 173 | return $tag; |
| 111 | 174 | } |
| 112 | 175 | |
| 113 | - $separator = ( false === strpos( $href, '?' ) ) ? '?' : '&'; | |
| 176 | + // Pick the separator from the DECODED url (so a "?" hidden behind an | |
| 177 | + // entity is still recognised), but append to the ORIGINAL (encoded) | |
| 178 | + // href so the str_replace below matches the tag verbatim. | |
| 179 | + $separator = ( false === strpos( $href_decoded, '?' ) ) ? '?' : '&'; | |
| 114 | 180 | $new_href = $href . $separator . 'display=swap'; |
| 115 | 181 | |
| 116 | 182 | return str_replace( $href, $new_href, $tag ); |
| 117 | 183 | } |
| @@ -116,8 +182,46 @@ | ||
| 116 | 182 | return str_replace( $href, $new_href, $tag ); |
| 117 | 183 | } |
| 118 | 184 | |
| 119 | 185 | /** |
| 186 | + * Print core's font faces as wp_print_font_faces() does, with swap as | |
| 187 | + * the font-display default. | |
| 188 | + */ | |
| 189 | + public static function print_font_faces_swap(): void { | |
| 190 | + $fonts = \WP_Font_Face_Resolver::get_fonts_from_theme_json(); | |
| 191 | + if ( empty( $fonts ) ) { | |
| 192 | + return; | |
| 193 | + } | |
| 194 | + // WordPress 6.4+. Only hooked when the function exists (see | |
| 195 | + // boot_on_init()), called by name so a 6.0 floor stays compatible. | |
| 196 | + call_user_func( 'wp_print_font_faces', self::default_display_swap( $fonts ) ); | |
| 197 | + } | |
| 198 | + | |
| 199 | + /** | |
| 200 | + * Give every font face without its own font-display a swap one. | |
| 201 | + * | |
| 202 | + * The resolver only sets font-display when a theme.json fontFace | |
| 203 | + * declares fontDisplay, so a face that has one was chosen on purpose | |
| 204 | + * and keeps it. Public + static so the test suite can drive it. | |
| 205 | + * | |
| 206 | + * @param array<int|string,mixed> $fonts Font families, each a list of faces. | |
| 207 | + * @return array<int|string,mixed> | |
| 208 | + */ | |
| 209 | + public static function default_display_swap( array $fonts ): array { | |
| 210 | + foreach ( $fonts as $family => $faces ) { | |
| 211 | + if ( ! is_array( $faces ) ) { | |
| 212 | + continue; | |
| 213 | + } | |
| 214 | + foreach ( $faces as $i => $face ) { | |
| 215 | + if ( is_array( $face ) && ! isset( $face['font-display'] ) ) { | |
| 216 | + $fonts[ $family ][ $i ]['font-display'] = 'swap'; | |
| 217 | + } | |
| 218 | + } | |
| 219 | + } | |
| 220 | + return $fonts; | |
| 221 | + } | |
| 222 | + | |
| 223 | + /** | |
| 120 | 224 | * Render the preload <link> markup for a list of font URLs. |
| 121 | 225 | * |
| 122 | 226 | * Pulled out as a static so tests can assert the markup directly |
| 123 | 227 | * without buffering wp_head output. |
| @@ -150,18 +254,24 @@ | ||
| 150 | 254 | $path = strtolower( wp_parse_url( $url, PHP_URL_PATH ) ?? '' ); |
| 151 | 255 | if ( '' === $path ) { |
| 152 | 256 | $path = strtolower( $url ); |
| 153 | 257 | } |
| 154 | - if ( str_ends_with( $path, '.woff2' ) ) { | |
| 258 | + // Plugin floor is PHP 7.4 — str_ends_with() is 8.0+. Use a | |
| 259 | + // substr() compare instead so the matrix's 7.4 leg passes. | |
| 260 | + $ends_with = static function ( string $haystack, string $needle ): bool { | |
| 261 | + $len = strlen( $needle ); | |
| 262 | + return 0 !== $len && substr( $haystack, -$len ) === $needle; | |
| 263 | + }; | |
| 264 | + if ( $ends_with( $path, '.woff2' ) ) { | |
| 155 | 265 | return 'font/woff2'; |
| 156 | 266 | } |
| 157 | - if ( str_ends_with( $path, '.woff' ) ) { | |
| 267 | + if ( $ends_with( $path, '.woff' ) ) { | |
| 158 | 268 | return 'font/woff'; |
| 159 | 269 | } |
| 160 | - if ( str_ends_with( $path, '.ttf' ) ) { | |
| 270 | + if ( $ends_with( $path, '.ttf' ) ) { | |
| 161 | 271 | return 'font/ttf'; |
| 162 | 272 | } |
| 163 | - if ( str_ends_with( $path, '.otf' ) ) { | |
| 273 | + if ( $ends_with( $path, '.otf' ) ) { | |
| 164 | 274 | return 'font/otf'; |
| 165 | 275 | } |
| 166 | 276 | return 'font/woff2'; |
| 167 | 277 | } |
| @@ -171,8 +281,9 @@ | ||
| 171 | 281 | array( |
| 172 | 282 | 'name' => 'xspeed fonts', |
| 173 | 283 | 'callback' => array( $this, 'cli_handler' ), |
| 174 | 284 | 'shortdesc' => 'Show font-optimization settings.', |
| 285 | + 'ai_hint' => 'How are web fonts being optimized (font-display swap, preloading, local hosting)? Use for questions about invisible text while loading (FOIT/FOUT) or render-blocking fonts.', | |
| 175 | 286 | 'synopsis' => array(), |
| 176 | 287 | ), |
| 177 | 288 | ); |
| 178 | 289 | } |
