← All changes | includes/modules/Lazy/LazyModule.php +231 -15 1.0.8 → 1.4.0 View file →

		@@ -38,11 +38,18 @@
38	38	public const VERSION = '1.0.0';
39	39
40	40	public function ui_metadata(): array {
41	41	return array(
42		- 'label' => 'Lazy Load',
43		- 'icon' => 'Image',
44		- 'description' => 'Defer images / iframes / videos until they scroll into view, and auto-add missing dimensions to prevent CLS.',
	42	+ 'label' => __( 'Media Optimization', 'xspeed' ),
	43	+ 'tab_label' => __( 'Lazy Loading', 'xspeed' ), // its own tab on the Media Optimization page
	44	+ 'icon' => 'Image',
	45	+ 'description' => __( 'Loads images, videos and embeds only when visitors scroll to them.', 'xspeed' ),
	46	+ 'group' => 'performance',
	47	+ // Host page: Lazy Loading (this module) + Image Optimization (Pro)
	48	+ // + AI Suggestions (Pro) as tabs — everything a page loads on one
	49	+ // page instead of separate rows (FBS-83633). Fonts is NOT here: it
	50	+ // has its own Optimization card (#86).
	51	+ 'custom_panel' => 'MediaPanel',
45	52	);
46	53	}
47	54
48	55	public function settings_schema(): array {
		@@ -49,43 +56,71 @@
49	56	return array(
50	57	'lazy_images' => array(
51	58	'type' => 'bool',
52	59	'default' => true,
53		- 'label' => 'Lazy-load Images',
54		- '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' ),
55	62	),
56	63	'lazy_iframes' => array(
57	64	'type' => 'bool',
58	65	'default' => true,
59		- 'label' => 'Lazy-load Iframes',
60		- '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' ),
61	68	),
	69	+ 'video_facade' => array(
	70	+ 'type' => 'bool',
	71	+ 'default' => false,
	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' ),
	74	+ ),
62	75	'lazy_videos' => array(
63	76	'type' => 'bool',
64	77	'default' => true,
65		- 'label' => 'Lazy-load HTML5 Videos',
66		- 'description' => 'Set preload="none" on self-hosted <video> tags. 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. An autoplaying video still plays by itself, but its file waits until the video is near the screen. Add data-skip-lazy to a video to leave it alone.', 'xspeed' ),
67	80	),
	81	+ 'video_after_load' => array(
	82	+ 'type' => 'bool',
	83	+ 'default' => false,
	84	+ 'label' => __( 'Start autoplay videos after page load', 'xspeed' ),
	85	+ 'description' => __( 'An autoplaying video, such as a hero background, waits until the page has finished loading, even when it is on screen from the start. Visitors see the poster first, and the video no longer competes with the page\'s images, styles and scripts. Needs "Lazy-load your own videos".', 'xspeed' ),
	86	+ 'dependsOn' => array( 'field' => 'lazy_videos' ),
	87	+ ),
	88	+ 'lazy_background_images' => array(
	89	+ 'type' => 'bool',
	90	+ 'default' => false,
	91	+ 'label' => __( 'Lazy-load background images', 'xspeed' ),
	92	+ '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' ),
	93	+ ),
68	94	'eager_first_n' => array(
69	95	'type' => 'int',
70	96	'default' => 1,
71	97	'min' => 0,
72	98	'max' => 10,
73		- 'label' => 'Eager-load First N Images',
74		- '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.',
	99	+ 'label' => __( 'Images to load right away', 'xspeed' ),
	100	+ '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' ),
	101	+ 'advanced' => true,
	102	+ // Both counters read this number (class-lazy-loader.php), so it
	103	+ // shows while either kind of lazy loading is on.
	104	+ 'dependsOn' => array(
	105	+ 'any' => array(
	106	+ array( 'field' => 'lazy_images' ),
	107	+ array( 'field' => 'lazy_background_images' ),
	108	+ ),
	109	+ ),
75	110	),
76	111	'add_missing_dimensions' => array(
77	112	'type' => 'bool',
78	113	'default' => true,
79		- 'label' => 'Add Missing Image Dimensions',
80		- '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.',
	114	+ 'label' => __( 'Add missing image sizes', 'xspeed' ),
	115	+ 'description' => __( 'Adds width and height to images that lack them, using the media library. This stops the page from jumping as images load.', 'xspeed' ),
81	116	),
82	117	'excluded_images' => array(
83	118	'type' => 'list',
84	119	'default' => array(),
85	120	'item_type' => 'string',
86		- 'label' => 'Excluded Images',
87		- '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.',
	121	+ 'label' => __( 'Excluded images', 'xspeed' ),
	122	+ 'description' => __( 'Images, videos 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' ),
88	123	),
89	124	);
90	125	}
91	126
		@@ -106,8 +141,27 @@
106	141	);
107	142	}
108	143
109	144	public function boot(): void {
	145	+ /*
	146	+ * Deferred to `init`. This module reads its own settings to decide
	147	+ * what to hook, and reading settings builds settings_schema(), whose
	148	+ * labels are declared through __(). boot() runs on `plugins_loaded`,
	149	+ * before `after_setup_theme` — the point WordPress 6.7+ treats as the
	150	+ * earliest safe moment to translate — so doing that here fires
	151	+ * _load_textdomain_just_in_time on every request AND resolves the
	152	+ * labels against a domain that is not loaded yet.
	153	+ *
	154	+ * Everything below hooks actions that fire after `init`, so running
	155	+ * one hook later is equivalent.
	156	+ */
	157	+ add_action( 'init', array( $this, 'boot_on_init' ) );
	158	+ }
	159	+
	160	+ /**
	161	+ * The real boot body — see boot() for why it runs on `init`.
	162	+ */
	163	+ public function boot_on_init(): void {
110	164	// Bail entirely on admin / feed / cron / REST — same scope as
111	165	// Minifier. Lazy-loading rendered HTML only matters on real
112	166	// frontend page renders.
113	167	if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
		@@ -113,12 +167,20 @@
113	167	if ( is_admin() || ( defined( 'DOING_AJAX' ) && DOING_AJAX ) || ( defined( 'DOING_CRON' ) && DOING_CRON ) || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
114	168	return;
115	169	}
116	170
	171	+ // Never lazy-load inside a builder editor: the builder measures and
	172	+ // positions elements it expects to be loaded. (#281)
	173	+ if ( \XSpeed\Builder_Editor::is_active() ) {
	174	+ return;
	175	+ }
	176	+
117	177	$opts = $this->get_settings();
118	178	$any_enabled = ! empty( $opts['lazy_images'] )
119	179	|| ! empty( $opts['lazy_iframes'] )
120	180	|| ! empty( $opts['lazy_videos'] )
	181	+ || ! empty( $opts['video_facade'] )
	182	+ || ! empty( $opts['lazy_background_images'] )
121	183	|| ! empty( $opts['add_missing_dimensions'] );
122	184	if ( ! $any_enabled ) {
123	185	return;
124	186	}
		@@ -135,10 +197,155 @@
135	197	add_filter( 'the_content', array( Lazy_Loader::class, 'process_html' ), 999 );
136	198	add_filter( 'post_thumbnail_html', array( Lazy_Loader::class, 'process_html' ), 999 );
137	199	add_filter( 'get_avatar', array( Lazy_Loader::class, 'process_html' ), 999 );
138	200	add_filter( 'widget_text_content', array( Lazy_Loader::class, 'process_html' ), 999 );
	201	+
	202	+ /**
	203	+ * Whether media-library images printed in the footer get srcset
	204	+ * with sizes="auto" and loading="lazy". Core never filters that
	205	+ * markup, so a footer popup ships its images at full size.
	206	+ *
	207	+ * @param bool $enabled Default true while lazy-loading images is on.
	208	+ */
	209	+ if ( ! empty( $opts['lazy_images'] ) && apply_filters( 'xspeed_lazy_footer_images', true ) ) {
	210	+ add_action( 'template_redirect', array( \XSpeed\Footer_Images::class, 'reset_state' ) );
	211	+ add_action( 'get_footer', array( \XSpeed\Footer_Images::class, 'start' ), PHP_INT_MAX, 0 );
	212	+ add_action( 'wp_footer', array( \XSpeed\Footer_Images::class, 'start' ), PHP_INT_MIN, 0 );
	213	+ add_action( 'wp_footer', array( \XSpeed\Footer_Images::class, 'finish' ), PHP_INT_MAX, 0 );
	214	+ }
	215	+
	216	+ // The facade's click handler is printed only on pages that actually
	217	+ // rendered a facade — a page with no embeds should not carry the
	218	+ // script that reveals them.
	219	+ if ( ! empty( $opts['video_facade'] ) ) {
	220	+ add_action( 'wp_footer', array( $this, 'print_facade_script' ), 99 );
	221	+ // The layout rule goes in the HEAD, unconditionally, while the
	222	+ // handler stays conditional in the footer. Whether a facade
	223	+ // renders isn't known until the content filter has run — long
	224	+ // after wp_head — and a layout rule that arrives in the footer
	225	+ // fixes the gap only after the visitor has already seen it.
	226	+ add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_facade_style' ) );
	227	+ // Embeds that never touch the HTML: a builder widget builds its
	228	+ // YouTube iframe from script, so the buffer pass has nothing to
	229	+ // rewrite. Head, priority 1, for the same reason as the autoplay
	230	+ // restorer below — it must be listening before the widget's
	231	+ // script sets a src and commits the fetch.
	232	+ add_action( 'wp_head', array( $this, 'print_observer_script' ), 1 );
	233	+ }
	234	+
	235	+ // Head, because the rule that holds a background back has to apply
	236	+ // before first paint, or the browser has already requested it.
	237	+ if ( ! empty( $opts['lazy_background_images'] ) ) {
	238	+ add_action( 'wp_enqueue_scripts', array( $this, 'enqueue_background_style' ) );
	239	+ add_action( 'wp_head', array( $this, 'print_background_script' ), 1 );
	240	+ }
	241	+
	242	+ // Same conditional-footer treatment for the autoplay restorer: it is
	243	+ // only printed on a response that actually deferred one.
	244	+ if ( ! empty( $opts['lazy_videos'] ) ) {
	245	+ /*
	246	+ * HEAD, not footer — and as early as anything can run.
	247	+ *
	248	+ * A page-builder video block creates its <video> from its own
	249	+ * script. Ours has to be listening BEFORE that happens: printed
	250	+ * in the footer it loaded after the block's script had already
	251	+ * built the player and started the fetch, so the bytes were
	252	+ * committed before we could defer them. Measured on a live page,
	253	+ * our restorer sat ~17KB after the first block script in the
	254	+ * document, and the videos still downloaded on load.
	255	+ *
	256	+ * It costs ~1KB inline and installs only observers, so running it
	257	+ * early is cheap; a MutationObserver on documentElement catches
	258	+ * every <video> the moment it is inserted, whichever script did
	259	+ * the inserting.
	260	+ */
	261	+ add_action( 'wp_head', array( $this, 'print_autoplay_script' ), 1 );
	262	+ }
139	263	}
140	264
	265	+ /**
	266	+ * Register the facade's layout rule as an inline style on a
	267	+ * dependency-free handle — ~150 bytes, so a separate file would cost
	268	+ * more than the CSS.
	269	+ */
	270	+ public function enqueue_facade_style(): void {
	271	+ wp_register_style( 'xspeed-video-facade', false, array(), XSPEED_VERSION );
	272	+ wp_enqueue_style( 'xspeed-video-facade' );
	273	+ wp_add_inline_style( 'xspeed-video-facade', \XSpeed\Video_Facade::facade_style() );
	274	+ }
	275	+
	276	+ public function enqueue_background_style(): void {
	277	+ wp_register_style( 'xspeed-lazy-bg', false, array(), XSPEED_VERSION );
	278	+ wp_enqueue_style( 'xspeed-lazy-bg' );
	279	+ wp_add_inline_style( 'xspeed-lazy-bg', Lazy_Loader::background_style() );
	280	+ }
	281	+
	282	+ /**
	283	+ * data-xs-nodelay: Delay JS would otherwise hold this back until the
	284	+ * first interaction, and every held background would stay blank.
	285	+ */
	286	+ public function print_background_script(): void {
	287	+ wp_print_inline_script_tag(
	288	+ Lazy_Loader::background_script(),
	289	+ array(
	290	+ 'id' => 'xspeed-lazy-bg',
	291	+ 'data-xs-nodelay' => true,
	292	+ )
	293	+ );
	294	+ }
	295	+
	296	+ /**
	297	+ * Emit the click-to-play handler inline. Inline (not enqueued) because
	298	+ * it is ~400 bytes — a separate request would cost more than the code.
	299	+ */
	300	+ public function print_facade_script(): void {
	301	+ // No longer gated on facade_used(): the observer script can build a
	302	+ // facade for a JS-injected embed on a page where the server pass
	303	+ // rendered none, and a facade without its click handler is a play
	304	+ // button that plays nothing. ~400 bytes on facade-less pages is the
	305	+ // cost of never shipping that.
	306	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::facade_script(), array( 'id' => 'xspeed-video-facade' ) );
	307	+ }
	308	+
	309	+ /**
	310	+ * Emit the interceptor for JS-injected embeds (see
	311	+ * Video_Facade::observer_script() for the mechanism and why the
	312	+ * footer is too late).
	313	+ */
	314	+ public function print_observer_script(): void {
	315	+ wp_print_inline_script_tag( \XSpeed\Video_Facade::observer_script(), array( 'id' => 'xspeed-video-facade-observer' ) );
	316	+ }
	317	+
	318	+ /**
	319	+ * Emit the viewport restorer for deferred AUTOPLAY videos.
	320	+ *
	321	+ * Separate from the facade script because the two are independent: a
	322	+ * page can defer an autoplay hero without any click-to-play facade on
	323	+ * it, and vice versa. Both are gated on having actually rewritten
	324	+ * something, so a page with no video ships neither.
	325	+ */
	326	+ public function print_autoplay_script(): void {
	327	+ /*
	328	+ * Deliberately NOT gated on needs_autoplay_script().
	329	+ *
	330	+ * That flag is only meaningful after the content filter has run, and
	331	+ * this prints in wp_head — long before. The facade script above can
	332	+ * afford to be conditional because it only has to be present by the
	333	+ * time a human clicks; this one has to be listening before another
	334	+ * plugin's script builds a <video> and starts fetching it, which
	335	+ * happens well before wp_footer.
	336	+ *
	337	+ * The cost of being unconditional is ~1KB inline on pages with no
	338	+ * video, and the script installs observers only — it does no work
	339	+ * and touches nothing when it finds no autoplay video. That is a
	340	+ * better trade than missing the one case the feature exists for.
	341	+ */
	342	+ $settings = $this->get_settings();
	343	+ $after_load = ! empty( $settings['video_after_load'] );
	344	+ $excluded = is_array( $settings['excluded_images'] ?? null ) ? $settings['excluded_images'] : array();
	345	+ wp_print_inline_script_tag( Lazy_Loader::autoplay_script( $after_load, $excluded ), array( 'id' => 'xspeed-lazy-autoplay' ) );
	346	+ }
	347	+
141	348	public function cli_commands(): array {
142	349	return array(
143	350	array(
144	351	'name' => 'xspeed lazy',
		@@ -143,8 +350,9 @@
143	350	array(
144	351	'name' => 'xspeed lazy',
145	352	'callback' => array( $this, 'cli_handler' ),
146	353	'shortdesc' => 'Show which lazy-load toggles are active.',
	354	+ '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.',
147	355	'synopsis' => array(),
148	356	),
149	357	);
150	358	}
		@@ -157,6 +365,14 @@
157	365	$display = (string) $value;
158	366	}
159	367	\WP_CLI::log( sprintf( '%-30s %s', $key, $display ) );
160	368	}
	369	+ }
	370	+
	371	+ /**
	372	+ * Lazy has no master switch -- it is on when any of lazy_images /
	373	+ * lazy_iframes / video_facade / lazy_videos is set. (#363)
	374	+ */
	375	+ public function is_active(): ?bool {
	376	+ return $this->any_bool_flag_on();
161	377	}
162	378	}