From efbc5c70441b0e0300ec74f3f1c59d8ebf07c654 Mon Sep 17 00:00:00 2001
From: reverb256 <reverb256@users.noreply.github.com>
Date: Wed, 8 Apr 2026 11:07:44 -0500
Subject: [PATCH 1/2] fix: add explanation notice for modern image format
 settings

Users frequently open support topics confused about why their uploads
aren't generating AVIF/WebP files. The plugin discards converted files
that are larger than the original (default behavior).

This adds an informational notice to the Modern Image Formats settings
section that explains this behavior and links to the plugin FAQ.

Uses existing notice notice-info inline pattern from other callbacks.

Fixes #2442
---
 plugins/webp-uploads/settings.php | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/plugins/webp-uploads/settings.php b/plugins/webp-uploads/settings.php
index 78cccb2140..7304ea7fa7 100644
--- a/plugins/webp-uploads/settings.php
+++ b/plugins/webp-uploads/settings.php
@@ -79,7 +79,7 @@ function webp_uploads_add_media_settings_fields(): void {
 	add_settings_section(
 		'perflab_modern_image_format_settings',
 		_x( 'Modern Image Formats', 'settings page section name', 'webp-uploads' ),
-		'__return_empty_string',
+		'webp_uploads_render_settings_section_info',
 		'media',
 		array(
 			'before_section' => '<div id="modern-image-formats">',
@@ -139,6 +139,33 @@ function webp_uploads_add_media_settings_fields(): void {
  *
  * @since 2.0.0
  */
+/**
+ * Render informational notice for the Modern Image Formats settings section.
+ *
+ * Explains why modern format images may not always be generated after upload.
+ */
+function webp_uploads_render_settings_section_info(): void {
+	?>
+	<div class="notice notice-info inline" style="margin:0;padding:10px 14px;">
+		<p>
+			<?php
+			echo wp_kses(
+				__( 'Modern image formats (e.g. WebP, AVIF) are only generated when they result in a smaller file than the original. If a converted image would be larger, the original is kept instead. For more details, see the <a href="https://wordpress.org/plugins/webp-uploads/#faq">FAQ</a>.', 'webp-uploads' ),
+				array(
+					'a' => array(
+						'href' => array(),
+					),
+				)
+			);
+			?>
+		</p>
+	</div>
+	<?php
+}
+
+/**
+ * Callback for rendering the AVIF/WebP output format setting.
+ */
 function webp_uploads_generate_avif_webp_setting_callback(): void {
 
 	$selected       = webp_uploads_get_image_output_format();

From adf158f4d2cab017ec7b73e315db381636c24f8d Mon Sep 17 00:00:00 2001
From: reverb256 <reverb256@users.noreply.github.com>
Date: Wed, 8 Apr 2026 12:02:25 -0500
Subject: [PATCH 2/2] test: add test for modern image formats settings section
 info notice

Covers webp_uploads_render_settings_section_info() which was flagged
by Codecov as 0% patch coverage.

Test asserts the info notice contains:
- notice-info CSS class
- Explanation about modern format generation
- Link to the plugin FAQ
---
 plugins/webp-uploads/tests/test-settings.php | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/plugins/webp-uploads/tests/test-settings.php b/plugins/webp-uploads/tests/test-settings.php
index 0d167b1d09..eefb9fe50d 100644
--- a/plugins/webp-uploads/tests/test-settings.php
+++ b/plugins/webp-uploads/tests/test-settings.php
@@ -7,6 +7,18 @@
 
 class Test_WebP_Uploads_Settings extends WP_UnitTestCase {
 
+	/**
+	 * @covers ::webp_uploads_render_settings_section_info
+	 */
+	public function test_webp_uploads_render_settings_section_info_contains_notice(): void {
+		$output = get_echo( 'webp_uploads_render_settings_section_info' );
+
+		$this->assertStringContainsString( 'notice notice-info inline', $output );
+		$this->assertStringContainsString( 'Modern image formats', $output );
+		$this->assertStringContainsString( 'https://wordpress.org/plugins/webp-uploads/#faq', $output );
+		$this->assertStringContainsString( 'smaller file than the original', $output );
+	}
+
 	/**
 	 * @covers ::webp_uploads_add_settings_action_link
 	 */