← All changes | includes/modules/Lazy/LazyModule.php +100 -21 1.2.4 → 1.3.7 View file →

		@@ -38,12 +38,13 @@
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' => __( 'Loads images, videos and embeds only when visitors scroll to them.', 'xspeed' ),
	46	+ 'group' => 'performance',
46	47	// Host page: Lazy Loading (this module) + Image Optimization (Pro)
47	48	// + AI Suggestions (Pro) as tabs — everything a page loads on one
48	49	// page instead of separate rows (FBS-83633). Fonts is NOT here: it
49	50	// has its own Optimization card (#86).
		@@ -55,49 +56,64 @@
55	56	return array(
56	57	'lazy_images' => array(
57	58	'type' => 'bool',
58	59	'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.',
	60	+ 'label' => __( 'Lazy-load images', 'xspeed' ),
	61	+ 'description' => __( 'Images load when the visitor scrolls near them. The first image on the page still loads right away.', 'xspeed' ),
61	62	),
62	63	'lazy_iframes' => array(
63	64	'type' => 'bool',
64	65	'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.',
	66	+ 'label' => __( 'Lazy-load embeds', 'xspeed' ),
	67	+ 'description' => __( 'Embedded content such as YouTube videos and maps loads when the visitor scrolls near it.', 'xspeed' ),
67	68	),
68	69	'video_facade' => array(
69	70	'type' => 'bool',
70	71	'default' => false,
71		- 'label' => 'Click-to-Play Video Facade',
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.',
	72	+ 'label' => __( 'Click-to-play videos', 'xspeed' ),
	73	+ 'description' => __( 'Shows a preview image with a play button in place of YouTube, Vimeo and your own videos that have a poster image. The video loads only when clicked. Autoplaying videos are left alone.', 'xspeed' ),
73	74	),
74	75	'lazy_videos' => array(
75	76	'type' => 'bool',
76	77	'default' => true,
77		- 'label' => 'Lazy-load HTML5 Videos',
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.',
	78	+ 'label' => __( 'Lazy-load your own videos', 'xspeed' ),
	79	+ 'description' => __( 'Videos uploaded to your site download only when played. Autoplaying videos are left alone.', 'xspeed' ),
79	80	),
	81	+ 'lazy_background_images' => array(
	82	+ 'type' => 'bool',
	83	+ 'default' => false,
	84	+ 'label' => __( 'Lazy-load background images', 'xspeed' ),
	85	+ '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' ),
	86	+ ),
80	87	'eager_first_n' => array(
81	88	'type' => 'int',
82	89	'default' => 1,
83	90	'min' => 0,
84	91	'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.',
	92	+ 'label' => __( 'Images to load right away', 'xspeed' ),
	93	+ 'description' => __( 'How many images at the top of the page skip lazy loading. Only the first of them also loads at high priority, and images in hidden or closed sections are not counted. Lazy-loaded background images use the same number. 1 suits most sites; 0 lazy-loads every image.', 'xspeed' ),
	94	+ 'advanced' => true,
	95	+ // Both counters read this number (class-lazy-loader.php), so it
	96	+ // shows while either kind of lazy loading is on.
	97	+ 'dependsOn' => array(
	98	+ 'any' => array(
	99	+ array( 'field' => 'lazy_images' ),
	100	+ array( 'field' => 'lazy_background_images' ),
	101	+ ),
	102	+ ),
87	103	),
88	104	'add_missing_dimensions' => array(
89	105	'type' => 'bool',
90	106	'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.',
	107	+ 'label' => __( 'Add missing image sizes', 'xspeed' ),
	108	+ 'description' => __( 'Adds width and height to images that lack them, using the media library. This stops the page from jumping as images load.', 'xspeed' ),
93	109	),
94	110	'excluded_images' => array(
95	111	'type' => 'list',
96	112	'default' => array(),
97	113	'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.',
	114	+ 'label' => __( 'Excluded images', 'xspeed' ),
	115	+ 'description' => __( 'Images and embeds whose tag contains a line here, such as a class or file name, are never lazy-loaded. Useful for logos and hero images.', 'xspeed' ),
100	116	),
101	117	);
102	118	}
103	119
		@@ -118,8 +134,27 @@
118	134	);
119	135	}
120	136
121	137	public function boot(): void {
	138	+ /*
	139	+ * Deferred to `init`. This module reads its own settings to decide
	140	+ * what to hook, and reading settings builds settings_schema(), whose
	141	+ * labels are declared through __(). boot() runs on `plugins_loaded`,
	142	+ * before `after_setup_theme` — the point WordPress 6.7+ treats as the
	143	+ * earliest safe moment to translate — so doing that here fires
	144	+ * _load_textdomain_just_in_time on every request AND resolves the
	145	+ * labels against a domain that is not loaded yet.
	146	+ *
	147	+ * Everything below hooks actions that fire after `init`, so running
	148	+ * one hook later is equivalent.
	149	+ */
	150	+ add_action( 'init', array( $this, 'boot_on_init' ) );
	151	+ }
	152	+
	153	+ /**
	154	+ * The real boot body — see boot() for why it runs on `init`.
	155	+ */
	156	+ public function boot_on_init(): void {
122	157	// Bail entirely on admin / feed / cron / REST — same scope as
123	158	// Minifier. Lazy-loading rendered HTML only matters on real
124	159	// frontend page renders.
125	160	if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
		@@ -136,8 +171,9 @@
136	171	$any_enabled = ! empty( $opts['lazy_images'] )
137	172	|| ! empty( $opts['lazy_iframes'] )
138	173	|| ! empty( $opts['lazy_videos'] )
139	174	|| ! empty( $opts['video_facade'] )
	175	+ || ! empty( $opts['lazy_background_images'] )
140	176	|| ! empty( $opts['add_missing_dimensions'] );
141	177	if ( ! $any_enabled ) {
142	178	return;
143	179	}
		@@ -166,10 +202,23 @@
166	202	// renders isn't known until the content filter has run — long
167	203	// after wp_head — and a layout rule that arrives in the footer
168	204	// fixes the gap only after the visitor has already seen it.
169	205	add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_facade_style' ) );
	206	+ // Embeds that never touch the HTML: a builder widget builds its
	207	+ // YouTube iframe from script, so the buffer pass has nothing to
	208	+ // rewrite. Head, priority 1, for the same reason as the autoplay
	209	+ // restorer below — it must be listening before the widget's
	210	+ // script sets a src and commits the fetch.
	211	+ add_action( 'wp_head', array( $this, 'print_observer_script' ), 1 );
170	212	}
171	213
	214	+ // Head, because the rule that holds a background back has to apply
	215	+ // before first paint, or the browser has already requested it.
	216	+ if ( ! empty( $opts['lazy_background_images'] ) ) {
	217	+ add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_background_style' ) );
	218	+ add_action( 'wp_head', array( $this, 'print_background_script' ), 1 );
	219	+ }
	220	+
172	221	// Same conditional-footer treatment for the autoplay restorer: it is
173	222	// only printed on a response that actually deferred one.
174	223	if ( ! empty( $opts['lazy_videos'] ) ) {
175	224	/*
		@@ -202,18 +251,48 @@
202	251	wp_enqueue_style( 'xspeed-video-facade' );
203	252	wp_add_inline_style( 'xspeed-video-facade', \XSpeed\Video_Facade::facade_style() );
204	253	}
205	254
	255	+ public function enqueue_background_style(): void {
	256	+ wp_register_style( 'xspeed-lazy-bg', false, array(), XSPEED_VERSION );
	257	+ wp_enqueue_style( 'xspeed-lazy-bg' );
	258	+ wp_add_inline_style( 'xspeed-lazy-bg', Lazy_Loader::background_style() );
	259	+ }
	260	+
206	261	/**
	262	+ * data-xs-nodelay: Delay JS would otherwise hold this back until the
	263	+ * first interaction, and every held background would stay blank.
	264	+ */
	265	+ public function print_background_script(): void {
	266	+ wp_print_inline_script_tag(
	267	+ Lazy_Loader::background_script(),
	268	+ array(
	269	+ 'id' => 'xspeed-lazy-bg',
	270	+ 'data-xs-nodelay' => true,
	271	+ )
	272	+ );
	273	+ }
	274	+
	275	+ /**
207	276	* Emit the click-to-play handler inline. Inline (not enqueued) because
208	277	* it is ~400 bytes — a separate request would cost more than the code.
209	278	*/
210	279	public function print_facade_script(): void {
211		- if ( ! Lazy_Loader::facade_used() ) {
212		- return;
213		- }
	280	+ // No longer gated on facade_used(): the observer script can build a
	281	+ // facade for a JS-injected embed on a page where the server pass
	282	+ // rendered none, and a facade without its click handler is a play
	283	+ // button that plays nothing. ~400 bytes on facade-less pages is the
	284	+ // cost of never shipping that.
	285	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
	286	+ }
214	287
215		- wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
	288	+ /**
	289	+ * Emit the interceptor for JS-injected embeds (see
	290	+ * Video_Facade::observer_script() for the mechanism and why the
	291	+ * footer is too late).
	292	+ */
	293	+ public function print_observer_script(): void {
	294	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::observer_script(), array( 'id' => 'xspeed-video-facade-observer' ) );
216	295	}
217	296
218	297	/**
219	298	* Emit the viewport restorer for deferred AUTOPLAY videos.