xspeed / includes / modules / Lazy / LazyModule.php

LazyModule.php in xSpeed Cache: AI-Powered Performance Hub with MCP, Caching & CDN 1.2.4, at includes/modules/Lazy/LazyModule.php

276 lines 11.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Lazy module — defers img / iframe / video loading via native browser
4	* lazy-load attributes. Also auto-fills missing image dimensions to
5	* prevent CLS.
6	*
7	* What WordPress core does already (since 5.5):
8	* - Adds loading="lazy" to the_content images.
9	*
10	* What this module adds:
11	* - First N images get loading="eager" so the LCP isn't deferred.
12	* - Adds decoding="async" (core doesn't).
13	* - Lazy-loads iframes (core's iframe lazy was reverted).
14	* - preload="none" on <video> (closest thing to native video lazy).
15	* - Auto-fills missing width / height attributes (best CLS win).
16	* - Excludes by substring patterns (src or class match) — useful for
17	* hero banner classes, logo files, etc.
18	*
19	* Tier: Free per FEATURES.md "Images" §1-6 (LiteSpeed parity — all
20	* Free in LS Cache).
21	*
22	* @package XSpeed
23	*/
24
25	declare(strict_types=1);
26
27	namespace XSpeed\Modules\Lazy;
28
29	defined( 'ABSPATH' ) \|\| exit;
30
31	use XSpeed\Lazy_Loader;
32	use XSpeed\Module;
33
34	final class LazyModule extends Module {
35
36	public const SLUG = 'lazy';
37	public const TIER = self::TIER_FREE;
38	public const VERSION = '1.0.0';
39
40	public function ui_metadata(): array {
41	return array(
42	'label' => 'Media Optimization',
43	'tab_label' => 'Lazy Loading', // its own tab on the Media Optimization page
44	'icon' => 'Image',
45	'description' => 'Control how images, iframes, and videos load — lazy-loading, missing dimensions, and format optimization.',
46	// Host page: Lazy Loading (this module) + Image Optimization (Pro)
47	// + AI Suggestions (Pro) as tabs — everything a page loads on one
48	// page instead of separate rows (FBS-83633). Fonts is NOT here: it
49	// has its own Optimization card (#86).
50	'custom_panel' => 'MediaPanel',
51	);
52	}
53
54	public function settings_schema(): array {
55	return array(
56	'lazy_images' => array(
57	'type' => 'bool',
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.',
61	),
62	'lazy_iframes' => array(
63	'type' => 'bool',
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.',
67	),
68	'video_facade' => array(
69	'type' => 'bool',
70	'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.',
73	),
74	'lazy_videos' => array(
75	'type' => 'bool',
76	'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.',
79	),
80	'eager_first_n' => array(
81	'type' => 'int',
82	'default' => 1,
83	'min' => 0,
84	'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.',
87	),
88	'add_missing_dimensions' => array(
89	'type' => 'bool',
90	'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.',
93	),
94	'excluded_images' => array(
95	'type' => 'list',
96	'default' => array(),
97	'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.',
100	),
101	);
102	}
103
104	public function conflicts(): array {
105	return array(
106	array(
107	'plugin' => 'wp-smushit/wp-smush.php',
108	'feature' => 'images.lazyload',
109	'strategy' => \XSpeed\Conflict_Registry::STRATEGY_WARN,
110	'reason' => 'Smush also offers lazy-loading; running both can cause double-rewriting.',
111	),
112	array(
113	'plugin' => 'a3-lazy-load/a3-lazy-load.php',
114	'feature' => 'images.lazyload',
115	'strategy' => \XSpeed\Conflict_Registry::STRATEGY_REFUSE,
116	'reason' => 'a3 Lazy Load is a dedicated lazy-load plugin; disable it before enabling xSpeed lazy-load.',
117	),
118	);
119	}
120
121	public function boot(): void {
122	// Bail entirely on admin / feed / cron / REST — same scope as
123	// Minifier. Lazy-loading rendered HTML only matters on real
124	// frontend page renders.
125	if ( is_admin() \|\| ( defined( 'DOING_AJAX' ) && DOING_AJAX ) \|\| ( defined( 'DOING_CRON' ) && DOING_CRON ) \|\| ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
126	return;
127	}
128
129	// Never lazy-load inside a builder editor: the builder measures and
130	// positions elements it expects to be loaded. (#281)
131	if ( \XSpeed\Builder_Editor::is_active() ) {
132	return;
133	}
134
135	$opts = $this->get_settings();
136	$any_enabled = ! empty( $opts['lazy_images'] )
137	\|\| ! empty( $opts['lazy_iframes'] )
138	\|\| ! empty( $opts['lazy_videos'] )
139	\|\| ! empty( $opts['video_facade'] )
140	\|\| ! empty( $opts['add_missing_dimensions'] );
141	if ( ! $any_enabled ) {
142	return;
143	}
144
145	// Reset the eager-load budget once per page render, before any
146	// content filter runs, so the "first N images eager" budget is
147	// shared across the featured image + content + avatars rather than
148	// restarting on every filter pass. (FBS-82172 Bug 1)
149	add_action( 'template_redirect', array( Lazy_Loader::class, 'reset_state' ) );
150
151	// Late priority so the_content runs after every other filter
152	// (shortcodes, do_blocks, embeds). Avoids rewriting tags that
153	// haven't been generated yet.
154	add_filter( 'the_content', array( Lazy_Loader::class, 'process_html' ), 999 );
155	add_filter( 'post_thumbnail_html', array( Lazy_Loader::class, 'process_html' ), 999 );
156	add_filter( 'get_avatar', array( Lazy_Loader::class, 'process_html' ), 999 );
157	add_filter( 'widget_text_content', array( Lazy_Loader::class, 'process_html' ), 999 );
158
159	// The facade's click handler is printed only on pages that actually
160	// rendered a facade — a page with no embeds should not carry the
161	// script that reveals them.
162	if ( ! empty( $opts['video_facade'] ) ) {
163	add_action( 'wp_footer', array( $this, 'print_facade_script' ), 99 );
164	// The layout rule goes in the HEAD, unconditionally, while the
165	// handler stays conditional in the footer. Whether a facade
166	// renders isn't known until the content filter has run — long
167	// after wp_head — and a layout rule that arrives in the footer
168	// fixes the gap only after the visitor has already seen it.
169	add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_facade_style' ) );
170	}
171
172	// Same conditional-footer treatment for the autoplay restorer: it is
173	// only printed on a response that actually deferred one.
174	if ( ! empty( $opts['lazy_videos'] ) ) {
175	/*
176	* HEAD, not footer — and as early as anything can run.
177	*
178	* A page-builder video block creates its <video> from its own
179	* script. Ours has to be listening BEFORE that happens: printed
180	* in the footer it loaded after the block's script had already
181	* built the player and started the fetch, so the bytes were
182	* committed before we could defer them. Measured on a live page,
183	* our restorer sat ~17KB after the first block script in the
184	* document, and the videos still downloaded on load.
185	*
186	* It costs ~1KB inline and installs only observers, so running it
187	* early is cheap; a MutationObserver on documentElement catches
188	* every <video> the moment it is inserted, whichever script did
189	* the inserting.
190	*/
191	add_action( 'wp_head', array( $this, 'print_autoplay_script' ), 1 );
192	}
193	}
194
195	/**
196	* Register the facade's layout rule as an inline style on a
197	* dependency-free handle — ~150 bytes, so a separate file would cost
198	* more than the CSS.
199	*/
200	public function enqueue_facade_style(): void {
201	wp_register_style( 'xspeed-video-facade', false, array(), XSPEED_VERSION );
202	wp_enqueue_style( 'xspeed-video-facade' );
203	wp_add_inline_style( 'xspeed-video-facade', \XSpeed\Video_Facade::facade_style() );
204	}
205
206	/**
207	* Emit the click-to-play handler inline. Inline (not enqueued) because
208	* it is ~400 bytes — a separate request would cost more than the code.
209	*/
210	public function print_facade_script(): void {
211	if ( ! Lazy_Loader::facade_used() ) {
212	return;
213	}
214
215	wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
216	}
217
218	/**
219	* Emit the viewport restorer for deferred AUTOPLAY videos.
220	*
221	* Separate from the facade script because the two are independent: a
222	* page can defer an autoplay hero without any click-to-play facade on
223	* it, and vice versa. Both are gated on having actually rewritten
224	* something, so a page with no video ships neither.
225	*/
226	public function print_autoplay_script(): void {
227	/*
228	* Deliberately NOT gated on needs_autoplay_script().
229	*
230	* That flag is only meaningful after the content filter has run, and
231	* this prints in wp_head — long before. The facade script above can
232	* afford to be conditional because it only has to be present by the
233	* time a human clicks; this one has to be listening before another
234	* plugin's script builds a <video> and starts fetching it, which
235	* happens well before wp_footer.
236	*
237	* The cost of being unconditional is ~1KB inline on pages with no
238	* video, and the script installs observers only — it does no work
239	* and touches nothing when it finds no autoplay video. That is a
240	* better trade than missing the one case the feature exists for.
241	*/
242	wp_print_inline_script_tag( Lazy_Loader::autoplay_script(), array( 'id' => 'xspeed-lazy-autoplay' ) );
243	}
244
245	public function cli_commands(): array {
246	return array(
247	array(
248	'name' => 'xspeed lazy',
249	'callback' => array( $this, 'cli_handler' ),
250	'shortdesc' => 'Show which lazy-load toggles are active.',
251	'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.',
252	'synopsis' => array(),
253	),
254	);
255	}
256
257	public function cli_handler( array $args, array $assoc ): void {
258	$opts = $this->get_settings();
259	foreach ( $opts as $key => $value ) {
260	$display = is_array( $value ) ? implode( ',', $value ) : ( $value ? 'on' : ( is_numeric( $value ) ? (string) $value : 'off' ) );
261	if ( is_int( $value ) ) {
262	$display = (string) $value;
263	}
264	\WP_CLI::log( sprintf( '%-30s %s', $key, $display ) );
265	}
266	}
267
268	/**
269	* Lazy has no master switch -- it is on when any of lazy_images /
270	* lazy_iframes / video_facade / lazy_videos is set. (#363)
271	*/
272	public function is_active(): ?bool {
273	return $this->any_bool_flag_on();
274	}
275	}
276