← All changes | includes/modules/Lazy/LazyModule.php +154 -21 1.1.4 → 1.3.6 View file →

		@@ -38,12 +38,12 @@
38	38	public const VERSION = '1.0.0';
39	39
40	40	public function ui_metadata(): array {
41	41	return array(
42		- 'label' => 'Media Optimization',
43		- 'tab_label' => 'Lazy Loading', // its own tab on the Media Optimization page
	42	+ 'label' => __( 'Media Optimization', 'xspeed' ),
	43	+ 'tab_label' => __( 'Lazy Loading', 'xspeed' ), // its own tab on the Media Optimization page
44	44	'icon' => 'Image',
45		- 'description' => 'Control how images, iframes, and videos load — lazy-loading, missing dimensions, and format optimization.',
	45	+ 'description' => __( 'Control how images, iframes, and videos load — lazy-loading, missing dimensions, and format optimization.', 'xspeed' ),
46	46	// Host page: Lazy Loading (this module) + Image Optimization (Pro)
47	47	// + AI Suggestions (Pro) as tabs — everything a page loads on one
48	48	// page instead of separate rows (FBS-83633). Fonts is NOT here: it
49	49	// has its own Optimization card (#86).
		@@ -55,49 +55,55 @@
55	55	return array(
56	56	'lazy_images' => array(
57	57	'type' => 'bool',
58	58	'default' => true,
59		- 'label' => 'Lazy-load Images',
60		- 'description' => 'Add loading="lazy" + decoding="async" to <img> tags in post content. The first images on the page get loading="eager" so the LCP image is not deferred.',
	59	+ 'label' => __( 'Lazy-load Images', 'xspeed' ),
	60	+ 'description' => __( 'Add loading="lazy" + decoding="async" to <img> tags in post content. The first images on the page get loading="eager" so the LCP image is not deferred.', 'xspeed' ),
61	61	),
62	62	'lazy_iframes' => array(
63	63	'type' => 'bool',
64	64	'default' => true,
65		- 'label' => 'Lazy-load Iframes',
66		- 'description' => 'Add loading="lazy" to <iframe> tags. Useful for YouTube / Vimeo embeds + map widgets that pull a lot of bytes.',
	65	+ 'label' => __( 'Lazy-load Iframes', 'xspeed' ),
	66	+ 'description' => __( 'Add loading="lazy" to <iframe> tags. Useful for YouTube / Vimeo embeds + map widgets that pull a lot of bytes.', 'xspeed' ),
67	67	),
68	68	'video_facade' => array(
69	69	'type' => 'bool',
70	70	'default' => false,
71		- 'label' => 'Click-to-Play Video Facade',
72		- 'description' => 'Replace YouTube and Vimeo embeds with a poster image and a play button. The player only loads when a visitor clicks it, so a page with embeds no longer pays ~1MB of third-party JavaScript that most visitors never use. Falls back to the normal embed when JavaScript is off.',
	71	+ 'label' => __( 'Click-to-Play Video Facade', 'xspeed' ),
	72	+ 'description' => __( 'Replace YouTube and Vimeo embeds — and self-hosted <video> tags that have a poster — with the poster image and a play button. The video only loads when a visitor clicks it, so a page with embeds no longer pays ~1MB of third-party JavaScript, or the full weight of a hosted video file, for visitors who never press play. Autoplaying videos are left alone. Falls back to the normal embed when JavaScript is off.', 'xspeed' ),
73	73	),
74	74	'lazy_videos' => array(
75	75	'type' => 'bool',
76	76	'default' => true,
77		- 'label' => 'Lazy-load HTML5 Videos',
78		- 'description' => 'Set preload="none" on self-hosted <video> tags. Browsers do not yet support loading="lazy" on video; preload="none" is the closest equivalent.',
	77	+ 'label' => __( 'Lazy-load HTML5 Videos', 'xspeed' ),
	78	+ 'description' => __( 'Set preload="none" on self-hosted <video> tags, overriding a player\'s own preload="auto"/"metadata". Autoplaying videos are left alone — they need their bytes regardless. Browsers do not yet support loading="lazy" on video; preload="none" is the closest equivalent.', 'xspeed' ),
79	79	),
	80	+ 'lazy_background_images' => array(
	81	+ 'type' => 'bool',
	82	+ 'default' => false,
	83	+ 'label' => __( 'Lazy-load Background Images', 'xspeed' ),
	84	+ 'description' => __( 'Hold back background images set in an element\'s inline style (a Cover or Group block, a page-builder section) until the element is near the screen. Uses a small script; visitors without JavaScript get every background as usual. The first N backgrounds on the page load straight away, like images. Backgrounds set in a stylesheet are not affected.', 'xspeed' ),
	85	+ ),
80	86	'eager_first_n' => array(
81	87	'type' => 'int',
82	88	'default' => 1,
83	89	'min' => 0,
84	90	'max' => 10,
85		- 'label' => 'Eager-load First N Images',
86		- 'description' => 'How many images at the top of the post get loading="eager". 1 is usually right (the LCP hero image). 0 to lazy-load everything.',
	91	+ 'label' => __( 'Eager-load First N Images', 'xspeed' ),
	92	+ 'description' => __( 'How many images at the top of the post get loading="eager". 1 is usually right (the LCP hero image). 0 to lazy-load everything. Lazy-loaded background images use the same number.', 'xspeed' ),
87	93	),
88	94	'add_missing_dimensions' => array(
89	95	'type' => 'bool',
90	96	'default' => true,
91		- 'label' => 'Add Missing Image Dimensions',
92		- 'description' => 'When an <img class="wp-image-N"> has no width/height, look the values up from the media library and inject them. Prevents the page-layout shift that hurts CLS scores.',
	97	+ 'label' => __( 'Add Missing Image Dimensions', 'xspeed' ),
	98	+ 'description' => __( 'When an <img class="wp-image-N"> has no width/height, look the values up from the media library and inject them. Prevents the page-layout shift that hurts CLS scores.', 'xspeed' ),
93	99	),
94	100	'excluded_images' => array(
95	101	'type' => 'list',
96	102	'default' => array(),
97	103	'item_type' => 'string',
98		- 'label' => 'Excluded Images',
99		- 'description' => 'Substring patterns that, if found anywhere in the <img> / <iframe> tag (typically a class or filename), exempt that element from lazy-loading. Useful for hero / logo / sprite images. Or add data-skip-lazy to the tag directly.',
	104	+ 'label' => __( 'Excluded Images', 'xspeed' ),
	105	+ 'description' => __( 'Substring patterns that, if found anywhere in the <img> / <iframe> tag (typically a class or filename), exempt that element from lazy-loading. Useful for hero / logo / sprite images. Or add data-skip-lazy to the tag directly.', 'xspeed' ),
100	106	),
101	107	);
102	108	}
103	109
		@@ -118,8 +124,27 @@
118	124	);
119	125	}
120	126
121	127	public function boot(): void {
	128	+ /*
	129	+ * Deferred to `init`. This module reads its own settings to decide
	130	+ * what to hook, and reading settings builds settings_schema(), whose
	131	+ * labels are declared through __(). boot() runs on `plugins_loaded`,
	132	+ * before `after_setup_theme` — the point WordPress 6.7+ treats as the
	133	+ * earliest safe moment to translate — so doing that here fires
	134	+ * _load_textdomain_just_in_time on every request AND resolves the
	135	+ * labels against a domain that is not loaded yet.
	136	+ *
	137	+ * Everything below hooks actions that fire after `init`, so running
	138	+ * one hook later is equivalent.
	139	+ */
	140	+ add_action( 'init', array( $this, 'boot_on_init' ) );
	141	+ }
	142	+
	143	+ /**
	144	+ * The real boot body — see boot() for why it runs on `init`.
	145	+ */
	146	+ public function boot_on_init(): void {
122	147	// Bail entirely on admin / feed / cron / REST — same scope as
123	148	// Minifier. Lazy-loading rendered HTML only matters on real
124	149	// frontend page renders.
125	150	if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
		@@ -125,13 +150,20 @@
125	150	if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
126	151	return;
127	152	}
128	153
	154	+ // Never lazy-load inside a builder editor: the builder measures and
	155	+ // positions elements it expects to be loaded. (#281)
	156	+ if ( \XSpeed\Builder_Editor::is_active() ) {
	157	+ return;
	158	+ }
	159	+
129	160	$opts = $this->get_settings();
130	161	$any_enabled = ! empty( $opts['lazy_images'] )
131	162	|| ! empty( $opts['lazy_iframes'] )
132	163	|| ! empty( $opts['lazy_videos'] )
133	164	|| ! empty( $opts['video_facade'] )
	165	+ || ! empty( $opts['lazy_background_images'] )
134	166	|| ! empty( $opts['add_missing_dimensions'] );
135	167	if ( ! $any_enabled ) {
136	168	return;
137	169	}
		@@ -160,9 +192,44 @@
160	192	// renders isn't known until the content filter has run — long
161	193	// after wp_head — and a layout rule that arrives in the footer
162	194	// fixes the gap only after the visitor has already seen it.
163	195	add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_facade_style' ) );
	196	+ // Embeds that never touch the HTML: a builder widget builds its
	197	+ // YouTube iframe from script, so the buffer pass has nothing to
	198	+ // rewrite. Head, priority 1, for the same reason as the autoplay
	199	+ // restorer below — it must be listening before the widget's
	200	+ // script sets a src and commits the fetch.
	201	+ add_action( 'wp_head', array( $this, 'print_observer_script' ), 1 );
164	202	}
	203	+
	204	+ // Head, because the rule that holds a background back has to apply
	205	+ // before first paint, or the browser has already requested it.
	206	+ if ( ! empty( $opts['lazy_background_images'] ) ) {
	207	+ add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_background_style' ) );
	208	+ add_action( 'wp_head', array( $this, 'print_background_script' ), 1 );
	209	+ }
	210	+
	211	+ // Same conditional-footer treatment for the autoplay restorer: it is
	212	+ // only printed on a response that actually deferred one.
	213	+ if ( ! empty( $opts['lazy_videos'] ) ) {
	214	+ /*
	215	+ * HEAD, not footer — and as early as anything can run.
	216	+ *
	217	+ * A page-builder video block creates its <video> from its own
	218	+ * script. Ours has to be listening BEFORE that happens: printed
	219	+ * in the footer it loaded after the block's script had already
	220	+ * built the player and started the fetch, so the bytes were
	221	+ * committed before we could defer them. Measured on a live page,
	222	+ * our restorer sat ~17KB after the first block script in the
	223	+ * document, and the videos still downloaded on load.
	224	+ *
	225	+ * It costs ~1KB inline and installs only observers, so running it
	226	+ * early is cheap; a MutationObserver on documentElement catches
	227	+ * every <video> the moment it is inserted, whichever script did
	228	+ * the inserting.
	229	+ */
	230	+ add_action( 'wp_head', array( $this, 'print_autoplay_script' ), 1 );
	231	+ }
165	232	}
166	233
167	234	/**
168	235	* Register the facade's layout rule as an inline style on a
		@@ -174,20 +241,77 @@
174	241	wp_enqueue_style( 'xspeed-video-facade' );
175	242	wp_add_inline_style( 'xspeed-video-facade', \XSpeed\Video_Facade::facade_style() );
176	243	}
177	244
	245	+ public function enqueue_background_style(): void {
	246	+ wp_register_style( 'xspeed-lazy-bg', false, array(), XSPEED_VERSION );
	247	+ wp_enqueue_style( 'xspeed-lazy-bg' );
	248	+ wp_add_inline_style( 'xspeed-lazy-bg', Lazy_Loader::background_style() );
	249	+ }
	250	+
178	251	/**
	252	+ * data-xs-nodelay: Delay JS would otherwise hold this back until the
	253	+ * first interaction, and every held background would stay blank.
	254	+ */
	255	+ public function print_background_script(): void {
	256	+ wp_print_inline_script_tag(
	257	+ Lazy_Loader::background_script(),
	258	+ array(
	259	+ 'id' => 'xspeed-lazy-bg',
	260	+ 'data-xs-nodelay' => true,
	261	+ )
	262	+ );
	263	+ }
	264	+
	265	+ /**
179	266	* Emit the click-to-play handler inline. Inline (not enqueued) because
180	267	* it is ~400 bytes — a separate request would cost more than the code.
181	268	*/
182	269	public function print_facade_script(): void {
183		- if ( ! Lazy_Loader::facade_used() ) {
184		- return;
185		- }
	270	+ // No longer gated on facade_used(): the observer script can build a
	271	+ // facade for a JS-injected embed on a page where the server pass
	272	+ // rendered none, and a facade without its click handler is a play
	273	+ // button that plays nothing. ~400 bytes on facade-less pages is the
	274	+ // cost of never shipping that.
	275	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
	276	+ }
186	277
187		- wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
	278	+ /**
	279	+ * Emit the interceptor for JS-injected embeds (see
	280	+ * Video_Facade::observer_script() for the mechanism and why the
	281	+ * footer is too late).
	282	+ */
	283	+ public function print_observer_script(): void {
	284	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::observer_script(), array( 'id' => 'xspeed-video-facade-observer' ) );
188	285	}
189	286
	287	+ /**
	288	+ * Emit the viewport restorer for deferred AUTOPLAY videos.
	289	+ *
	290	+ * Separate from the facade script because the two are independent: a
	291	+ * page can defer an autoplay hero without any click-to-play facade on
	292	+ * it, and vice versa. Both are gated on having actually rewritten
	293	+ * something, so a page with no video ships neither.
	294	+ */
	295	+ public function print_autoplay_script(): void {
	296	+ /*
	297	+ * Deliberately NOT gated on needs_autoplay_script().
	298	+ *
	299	+ * That flag is only meaningful after the content filter has run, and
	300	+ * this prints in wp_head — long before. The facade script above can
	301	+ * afford to be conditional because it only has to be present by the
	302	+ * time a human clicks; this one has to be listening before another
	303	+ * plugin's script builds a <video> and starts fetching it, which
	304	+ * happens well before wp_footer.
	305	+ *
	306	+ * The cost of being unconditional is ~1KB inline on pages with no
	307	+ * video, and the script installs observers only — it does no work
	308	+ * and touches nothing when it finds no autoplay video. That is a
	309	+ * better trade than missing the one case the feature exists for.
	310	+ */
	311	+ wp_print_inline_script_tag( Lazy_Loader::autoplay_script(), array( 'id' => 'xspeed-lazy-autoplay' ) );
	312	+ }
	313	+
190	314	public function cli_commands(): array {
191	315	return array(
192	316	array(
193	317	'name' => 'xspeed lazy',
		@@ -192,8 +316,9 @@
192	316	array(
193	317	'name' => 'xspeed lazy',
194	318	'callback' => array( $this, 'cli_handler' ),
195	319	'shortdesc' => 'Show which lazy-load toggles are active.',
	320	+ 'ai_hint' => 'Which lazy-loading and image optimizations are on (images, iframes, missing width/height)? Use for questions about images loading too early, layout shift (CLS), or offscreen images flagged by PageSpeed.',
196	321	'synopsis' => array(),
197	322	),
198	323	);
199	324	}
		@@ -206,6 +331,14 @@
206	331	$display = (string) $value;
207	332	}
208	333	\WP_CLI::log( sprintf( '%-30s %s', $key, $display ) );
209	334	}
	335	+ }
	336	+
	337	+ /**
	338	+ * Lazy has no master switch -- it is on when any of lazy_images /
	339	+ * lazy_iframes / video_facade / lazy_videos is set. (#363)
	340	+ */
	341	+ public function is_active(): ?bool {
	342	+ return $this->any_bool_flag_on();
210	343	}
211	344	}