From 9b3ea19f294c39e4cf74ab34e9c62b5b153e8b93 Mon Sep 17 00:00:00 2001
From: Faisal Ahammad <faisalahammad24@gmail.com>
Date: Sun, 26 Jul 2026 08:34:15 +0600
Subject: [PATCH 1/3] Add Autoloaded_Options_Check for missing $autoload
 parameter

Warns when add_option() or update_option() is called without
explicitly setting the $autoload parameter. The option then
defaults to autoloading on every page request, which bloats
the alloptions row and slows down every request.

The check runs a new PluginCheck.CodeAnalysis.AutoLoadedOptions
sniff that flags calls where $autoload is not passed. Calls
with an explicit boolean are left alone.
---
 docs/checks.md                                |   1 +
 .../Performance/Autoloaded_Options_Check.php  |  78 ++++++++++++++
 includes/Checker/Default_Check_Repository.php |   1 +
 .../CodeAnalysis/AutoLoadedOptionsSniff.php   | 101 ++++++++++++++++++
 .../AutoLoadedOptionsUnitTest.inc             |  28 +++++
 .../AutoLoadedOptionsUnitTest.php             |  61 +++++++++++
 phpcs-sniffs/PluginCheck/ruleset.xml          |   1 +
 .../load.php                                  |  28 +++++
 .../load.php                                  |  28 +++++
 .../Checks/Autoloaded_Options_Check_Tests.php |  57 ++++++++++
 10 files changed, 384 insertions(+)
 create mode 100644 includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
 create mode 100644 phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
 create mode 100644 phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc
 create mode 100644 phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php
 create mode 100644 tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php
 create mode 100644 tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php
 create mode 100644 tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php

diff --git a/docs/checks.md b/docs/checks.md
index f7ffd0e72..4d01edc62 100644
--- a/docs/checks.md
+++ b/docs/checks.md
@@ -36,4 +36,5 @@
 | enqueued_styles_scope | performance | Checks whether any stylesheets are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | enqueued_scripts_scope | performance | Checks whether any scripts are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | non_blocking_scripts | performance | Checks whether scripts and styles are enqueued using a recommended loading strategy. | [Learn more](https://developer.wordpress.org/plugins/) |
+| autoloaded_options | performance | Warns when <code>add_option()</code> or <code>update_option()</code> are called without explicitly setting the <code>$autoload</code> parameter. | [Learn more](https://developer.wordpress.org/reference/functions/add_option/) |
 | ai_provider | general | Recommends the WordPress AI Client when a plugin integrates directly with a third-party AI provider. | [Learn more](https://developer.wordpress.org/plugins/) |
diff --git a/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php b/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
new file mode 100644
index 000000000..b738abd0b
--- /dev/null
+++ b/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
@@ -0,0 +1,78 @@
+<?php
+/**
+ * Class Autoloaded_Options_Check.
+ *
+ * @package plugin-check
+ */
+
+namespace WordPress\Plugin_Check\Checker\Checks\Performance;
+
+use WordPress\Plugin_Check\Checker\Check_Categories;
+use WordPress\Plugin_Check\Checker\Check_Result;
+use WordPress\Plugin_Check\Checker\Checks\Abstract_PHP_CodeSniffer_Check;
+use WordPress\Plugin_Check\Traits\Stable_Check;
+
+/**
+ * Check to detect missing $autoload parameter on add_option() / update_option().
+ *
+ * @since 2.1.0
+ */
+class Autoloaded_Options_Check extends Abstract_PHP_CodeSniffer_Check {
+
+	use Stable_Check;
+
+	/**
+	 * Gets the categories for the check.
+	 *
+	 * Every check must have at least one category.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return array The categories for the check.
+	 */
+	public function get_categories() {
+		return array( Check_Categories::CATEGORY_PERFORMANCE );
+	}
+
+	/**
+	 * Returns an associative array of arguments to pass to PHPCS.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param Check_Result $result The check result to amend, including the plugin context to check.
+	 * @return array An associative array of PHPCS CLI arguments.
+	 */
+	protected function get_args( Check_Result $result ) {
+		return array(
+			'extensions' => 'php',
+			'standard'   => 'PluginCheck',
+			'sniffs'     => 'PluginCheck.CodeAnalysis.AutoLoadedOptions',
+		);
+	}
+
+	/**
+	 * Gets the description for the check.
+	 *
+	 * Every check must have a short description explaining what the check does.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return string Description.
+	 */
+	public function get_description(): string {
+		return __( 'Warns when add_option() or update_option() are called without explicitly setting the $autoload parameter.', 'plugin-check' );
+	}
+
+	/**
+	 * Gets the documentation URL for the check.
+	 *
+	 * Every check must have a URL with further information about the check.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return string The documentation URL.
+	 */
+	public function get_documentation_url(): string {
+		return __( 'https://developer.wordpress.org/reference/functions/add_option/', 'plugin-check' );
+	}
+}
diff --git a/includes/Checker/Default_Check_Repository.php b/includes/Checker/Default_Check_Repository.php
index d4d5c548d..b86528fe5 100644
--- a/includes/Checker/Default_Check_Repository.php
+++ b/includes/Checker/Default_Check_Repository.php
@@ -104,6 +104,7 @@ private function register_default_checks() {
 				'direct_file_access'         => new Checks\Plugin_Repo\Direct_File_Access_Check(),
 				'external_admin_menu_links'  => new Checks\Plugin_Repo\External_Admin_Menu_Links_Check(),
 				'wp_functions_compatibility' => new Checks\Plugin_Repo\WP_Functions_Compatibility_Check(),
+				'autoloaded_options'         => new Checks\Performance\Autoloaded_Options_Check(),
 				'ai_provider'                => new Checks\General\AI_Provider_Check(),
 			)
 		);
diff --git a/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
new file mode 100644
index 000000000..e015f4bb0
--- /dev/null
+++ b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
@@ -0,0 +1,101 @@
+<?php
+/**
+ * AutoLoadedOptionsSniff
+ *
+ * Based on code from {@link https://github.com/WordPress/WordPress-Coding-Standards}
+ * which is licensed under {@link https://opensource.org/licenses/MIT}.
+ *
+ * @package PluginCheck
+ */
+
+namespace PluginCheckCS\PluginCheck\Sniffs\CodeAnalysis;
+
+use PHPCSUtils\Utils\MessageHelper;
+use PHPCSUtils\Utils\PassedParameters;
+use WordPressCS\WordPress\AbstractFunctionParameterSniff;
+
+/**
+ * Warns when add_option() / update_option() are called without explicitly
+ * setting the $autoload parameter.
+ *
+ * The default value of $autoload is true, which loads the option on every
+ * page request. Plugins that accumulate autoloaded options slow down every
+ * request. Letting the author choose explicitly is the goal.
+ *
+ * @link https://developer.wordpress.org/reference/functions/add_option/
+ * @link https://developer.wordpress.org/reference/functions/update_option/
+ *
+ * @since 2.1.0
+ */
+final class AutoLoadedOptionsSniff extends AbstractFunctionParameterSniff {
+
+	/**
+	 * Position of the $autoload parameter for each target function.
+	 *
+	 * add_option() is `add_option( $option, $value, $deprecated, $autoload )`
+	 * update_option() is `update_option( $option, $value, $autoload )`.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @var array<string, int>
+	 */
+	protected $autoload_positions = array(
+		'add_option'    => 4,
+		'update_option' => 3,
+	);
+
+	/**
+	 * List of functions to examine.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @var array<string, true>
+	 */
+	protected $target_functions = array(
+		'add_option'    => true,
+		'update_option' => true,
+	);
+
+	/**
+	 * Processes this test, when one of its tokens is encountered.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 * @return int|void Integer stack pointer to skip forward or void to continue normal file processing.
+	 */
+	public function process_token( $stackPtr ) {
+		if ( isset( $this->target_functions[ strtolower( $this->tokens[ $stackPtr ]['content'] ) ] ) ) {
+			$this->exclude = array();
+
+			return parent::process_token( $stackPtr );
+		}
+	}
+
+	/**
+	 * Process the parameters of a matched function call.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param int    $stackPtr        The position of the current token in the stack.
+	 * @param string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched in lowercase.
+	 * @param array  $parameters      Array with information about the parameters.
+	 * @return void
+	 */
+	public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
+		$position = $this->autoload_positions[ $matched_content ];
+		$found    = PassedParameters::getParameterFromStack( $parameters, $position, 'autoload' );
+
+		if ( false === $found ) {
+			$error_code = MessageHelper::stringToErrorcode( $matched_content . '_autoload', true );
+
+			$this->phpcsFile->addWarning(
+				'The $autoload parameter for %s() is not explicitly set; the option will default to autoloading on every page request. Pass an explicit boolean (true or false) to make the performance trade-off intentional.',
+				$stackPtr,
+				$error_code . 'Missing',
+				array( $matched_content )
+			);
+		}
+	}
+}
diff --git a/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc b/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc
new file mode 100644
index 000000000..8d8ac81b0
--- /dev/null
+++ b/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc
@@ -0,0 +1,28 @@
+<?php
+
+// Bad: add_option() with no $autoload.
+add_option( 'no_autoload_a' ); // Warning.
+
+// Bad: add_option() with only $value set.
+add_option( 'no_autoload_b', 'value' ); // Warning.
+
+// Bad: add_option() with only $deprecated set.
+add_option( 'no_autoload_c', 'value', '' ); // Warning.
+
+// Bad: update_option() with no $autoload.
+update_option( 'no_autoload_d' ); // Warning.
+
+// Bad: update_option() with only $value set.
+update_option( 'no_autoload_e', 'value' ); // Warning.
+
+// Good: add_option() with explicit autoload = false.
+add_option( 'autoload_false_a', 'value', '', false );
+
+// Good: add_option() with explicit autoload = true.
+add_option( 'autoload_true_a', 'value', '', true );
+
+// Good: update_option() with explicit autoload = false.
+update_option( 'autoload_false_b', 'value', false );
+
+// Good: update_option() with explicit autoload = true.
+update_option( 'autoload_true_b', 'value', true );
diff --git a/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php b/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php
new file mode 100644
index 000000000..4d3b4b91b
--- /dev/null
+++ b/phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php
@@ -0,0 +1,61 @@
+<?php
+/**
+ * Unit tests for AutoLoadedOptionsSniff.
+ *
+ * @package PluginCheck
+ */
+
+namespace PluginCheckCS\PluginCheck\Tests\CodeAnalysis;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PluginCheckCS\PluginCheck\Sniffs\CodeAnalysis\AutoLoadedOptionsSniff;
+use PluginCheckCS\PluginCheck\Tests\AbstractSniffUnitTest;
+
+/**
+ * Unit tests for AutoLoadedOptionsSniff.
+ */
+final class AutoLoadedOptionsUnitTest extends AbstractSniffUnitTest {
+
+	/**
+	 * Returns the lines where errors should occur.
+	 *
+	 * @return array <int line number> => <int number of errors>
+	 */
+	public function getErrorList() {
+		return array();
+	}
+
+	/**
+	 * Returns the lines where warnings should occur.
+	 *
+	 * @return array <int line number> => <int number of warnings>
+	 */
+	public function getWarningList() {
+		return array(
+			4  => 1,
+			7  => 1,
+			10 => 1,
+			13 => 1,
+			16 => 1,
+		);
+	}
+
+	/**
+	 * Returns the fully qualified class name (FQCN) of the sniff.
+	 *
+	 * @return string The fully qualified class name of the sniff.
+	 */
+	protected function get_sniff_fqcn() {
+		return AutoLoadedOptionsSniff::class;
+	}
+
+	/**
+	 * Sets the parameters for the sniff.
+	 *
+	 * @throws \RuntimeException If unable to set the ruleset parameters required for the test.
+	 *
+	 * @param Sniff $sniff The sniff being tested.
+	 */
+	public function set_sniff_parameters( Sniff $sniff ) {
+	}
+}
diff --git a/phpcs-sniffs/PluginCheck/ruleset.xml b/phpcs-sniffs/PluginCheck/ruleset.xml
index 3c5b50d2d..c19f5fa80 100644
--- a/phpcs-sniffs/PluginCheck/ruleset.xml
+++ b/phpcs-sniffs/PluginCheck/ruleset.xml
@@ -4,6 +4,7 @@
 	<description>Plugin Check Sniffs</description>
 
 	<rule ref="PluginCheck.CodeAnalysis.AIProvider" />
+	<rule ref="PluginCheck.CodeAnalysis.AutoLoadedOptions" />
 	<rule ref="PluginCheck.CodeAnalysis.DiscouragedFunctions" />
 	<rule ref="PluginCheck.CodeAnalysis.EnqueuedResourceOffloading" />
 	<rule ref="PluginCheck.CodeAnalysis.Heredoc" />
diff --git a/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php b/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php
new file mode 100644
index 000000000..119270473
--- /dev/null
+++ b/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * Plugin Name: Test Plugin Autoloaded Options check with errors
+ * Plugin URI: https://github.com/WordPress/plugin-check
+ * Description: Test plugin for the Autoloaded Options check.
+ * Requires at least: 6.0
+ * Requires PHP: 5.6
+ * Version: 1.0.0
+ * Author: WordPress Performance Team
+ * Author URI: https://make.wordpress.org/performance/
+ * License: GPLv2 or later
+ * License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * Text Domain: test-plugin-autoloaded-options-check-with-errors
+ *
+ * @package test-plugin-autoloaded-options-check-with-errors
+ */
+
+// add_option without $autoload.
+add_option( 'autoloaded_with_errors_a' );
+
+// add_option with $value but no $autoload.
+add_option( 'autoloaded_with_errors_b', 'value' );
+
+// update_option without $autoload.
+update_option( 'autoloaded_with_errors_c' );
+
+// update_option with $value but no $autoload.
+update_option( 'autoloaded_with_errors_d', 'value' );
diff --git a/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php b/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php
new file mode 100644
index 000000000..b0c9e3e6c
--- /dev/null
+++ b/tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * Plugin Name: Test Plugin Autoloaded Options check without errors
+ * Plugin URI: https://github.com/WordPress/plugin-check
+ * Description: Test plugin for the Autoloaded Options check (clean fixture).
+ * Requires at least: 6.0
+ * Requires PHP: 5.6
+ * Version: 1.0.0
+ * Author: WordPress Performance Team
+ * Author URI: https://make.wordpress.org/performance/
+ * License: GPLv2 or later
+ * License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * Text Domain: test-plugin-autoloaded-options-check-without-errors
+ *
+ * @package test-plugin-autoloaded-options-check-without-errors
+ */
+
+// add_option with explicit autoload = false.
+add_option( 'autoloaded_without_errors_a', 'value', '', false );
+
+// add_option with explicit autoload = true.
+add_option( 'autoloaded_without_errors_b', 'value', '', true );
+
+// update_option with explicit autoload = false.
+update_option( 'autoloaded_without_errors_c', 'value', false );
+
+// update_option with explicit autoload = true.
+update_option( 'autoloaded_without_errors_d', 'value', true );
diff --git a/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php b/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php
new file mode 100644
index 000000000..5bc634fd6
--- /dev/null
+++ b/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php
@@ -0,0 +1,57 @@
+<?php
+/**
+ * Tests for the Autoloaded_Options_Check class.
+ *
+ * @package plugin-check
+ */
+
+use WordPress\Plugin_Check\Checker\Check_Context;
+use WordPress\Plugin_Check\Checker\Check_Result;
+use WordPress\Plugin_Check\Checker\Checks\Performance\Autoloaded_Options_Check;
+
+class Autoloaded_Options_Check_Tests extends WP_UnitTestCase {
+
+	public function test_run_with_errors() {
+		$check         = new Autoloaded_Options_Check();
+		$check_context = new Check_Context( UNIT_TESTS_PLUGIN_DIR . 'test-plugin-autoloaded-options-check-with-errors/load.php' );
+		$check_result  = new Check_Result( $check_context );
+
+		$check->run( $check_result );
+
+		$warnings = $check_result->get_warnings();
+
+		$this->assertNotEmpty( $warnings );
+		$this->assertArrayHasKey( 'load.php', $warnings );
+
+		// Both add_option calls without $autoload must produce warnings.
+		$this->assertSame(
+			'PluginCheck.CodeAnalysis.AutoLoadedOptions.add_option_autoloadMissing',
+			$warnings['load.php'][19][1][0]['code']
+		);
+		$this->assertSame(
+			'PluginCheck.CodeAnalysis.AutoLoadedOptions.add_option_autoloadMissing',
+			$warnings['load.php'][22][1][0]['code']
+		);
+
+		// Both update_option calls without $autoload must produce warnings.
+		$this->assertSame(
+			'PluginCheck.CodeAnalysis.AutoLoadedOptions.update_option_autoloadMissing',
+			$warnings['load.php'][25][1][0]['code']
+		);
+		$this->assertSame(
+			'PluginCheck.CodeAnalysis.AutoLoadedOptions.update_option_autoloadMissing',
+			$warnings['load.php'][28][1][0]['code']
+		);
+	}
+
+	public function test_run_without_errors() {
+		$check         = new Autoloaded_Options_Check();
+		$check_context = new Check_Context( UNIT_TESTS_PLUGIN_DIR . 'test-plugin-autoloaded-options-check-without-errors/load.php' );
+		$check_result  = new Check_Result( $check_context );
+
+		$check->run( $check_result );
+
+		$this->assertEmpty( $check_result->get_errors() );
+		$this->assertEmpty( $check_result->get_warnings() );
+	}
+}

From c28b6ea29c18486e3a6c106727d7338ea3eecc45 Mon Sep 17 00:00:00 2001
From: Faisal Ahammad <faisalahammad24@gmail.com>
Date: Sun, 26 Jul 2026 09:04:22 +0600
Subject: [PATCH 2/3] fix(sniffs): capitalize long description in
 AutoLoadedOptionsSniff

- Capitalize first letter of two long-description lines that started
  with a function name. Generic.Commenting.DocComment.LongNotCapital
  requires the long description in a doc comment to start uppercase.

Refs #1413
---
 .../Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php            | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
index e015f4bb0..e6b47a5a2 100644
--- a/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
+++ b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
@@ -32,8 +32,8 @@ final class AutoLoadedOptionsSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * Position of the $autoload parameter for each target function.
 	 *
-	 * add_option() is `add_option( $option, $value, $deprecated, $autoload )`
-	 * update_option() is `update_option( $option, $value, $autoload )`.
+	 * Add_option() is `add_option( $option, $value, $deprecated, $autoload )`.
+	 * Update_option() is `update_option( $option, $value, $autoload )`.
 	 *
 	 * @since 2.1.0
 	 *

From 73e6f50c3bb83746368a0f37c3cd4965e9959c28 Mon Sep 17 00:00:00 2001
From: Faisal Ahammad <faisalahammad24@gmail.com>
Date: Mon, 21 Sep 2026 23:05:00 +0600
Subject: [PATCH 3/3] Correct autoload option warning wording

- Reword sniff docblock and warning message so they no longer imply that an omitted $autoload always autoloads. The value is left to WordPress and depends on whether the option already exists and on the WordPress version.
- Update check description and docs/checks.md row with the same wording, and link to update_option() docs.
- Harden the check test: assert empty errors, warning count 4, and read warning codes with dynamic column keys.

Addresses PR feedback.
Refs #1413
---
 docs/checks.md                                |  2 +-
 .../Performance/Autoloaded_Options_Check.php  |  4 ++--
 .../CodeAnalysis/AutoLoadedOptionsSniff.php   | 21 +++++++++++--------
 .../Checks/Autoloaded_Options_Check_Tests.php | 13 ++++++++----
 4 files changed, 24 insertions(+), 16 deletions(-)

diff --git a/docs/checks.md b/docs/checks.md
index 4d01edc62..aeb4a8d3b 100644
--- a/docs/checks.md
+++ b/docs/checks.md
@@ -36,5 +36,5 @@
 | enqueued_styles_scope | performance | Checks whether any stylesheets are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | enqueued_scripts_scope | performance | Checks whether any scripts are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | non_blocking_scripts | performance | Checks whether scripts and styles are enqueued using a recommended loading strategy. | [Learn more](https://developer.wordpress.org/plugins/) |
-| autoloaded_options | performance | Warns when <code>add_option()</code> or <code>update_option()</code> are called without explicitly setting the <code>$autoload</code> parameter. | [Learn more](https://developer.wordpress.org/reference/functions/add_option/) |
+| autoloaded_options | performance | Warns when <code>add_option()</code> or <code>update_option()</code> are called without explicitly setting the <code>$autoload</code> parameter, leaving the autoload value implicit and dependent on WordPress behavior. | [Learn more](https://developer.wordpress.org/reference/functions/update_option/) |
 | ai_provider | general | Recommends the WordPress AI Client when a plugin integrates directly with a third-party AI provider. | [Learn more](https://developer.wordpress.org/plugins/) |
diff --git a/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php b/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
index b738abd0b..e10ba1559 100644
--- a/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
+++ b/includes/Checker/Checks/Performance/Autoloaded_Options_Check.php
@@ -60,7 +60,7 @@ protected function get_args( Check_Result $result ) {
 	 * @return string Description.
 	 */
 	public function get_description(): string {
-		return __( 'Warns when add_option() or update_option() are called without explicitly setting the $autoload parameter.', 'plugin-check' );
+		return __( 'Warns when add_option() or update_option() are called without explicitly setting the $autoload parameter, leaving the autoload value implicit and dependent on WordPress behavior.', 'plugin-check' );
 	}
 
 	/**
@@ -73,6 +73,6 @@ public function get_description(): string {
 	 * @return string The documentation URL.
 	 */
 	public function get_documentation_url(): string {
-		return __( 'https://developer.wordpress.org/reference/functions/add_option/', 'plugin-check' );
+		return __( 'https://developer.wordpress.org/reference/functions/update_option/', 'plugin-check' );
 	}
 }
diff --git a/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
index e6b47a5a2..f3445a123 100644
--- a/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
+++ b/phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php
@@ -18,9 +18,11 @@
  * Warns when add_option() / update_option() are called without explicitly
  * setting the $autoload parameter.
  *
- * The default value of $autoload is true, which loads the option on every
- * page request. Plugins that accumulate autoloaded options slow down every
- * request. Letting the author choose explicitly is the goal.
+ * When omitted, the autoload value is left to WordPress and depends on
+ * whether the option already exists and on the WordPress version: on 6.6+
+ * WordPress decides from the option size, update_option() on an existing
+ * option keeps its current value, and older versions autoload it. Deciding
+ * explicitly with a boolean keeps the performance trade-off intentional.
  *
  * @link https://developer.wordpress.org/reference/functions/add_option/
  * @link https://developer.wordpress.org/reference/functions/update_option/
@@ -90,12 +92,13 @@ public function process_parameters( $stackPtr, $group_name, $matched_content, $p
 		if ( false === $found ) {
 			$error_code = MessageHelper::stringToErrorcode( $matched_content . '_autoload', true );
 
-			$this->phpcsFile->addWarning(
-				'The $autoload parameter for %s() is not explicitly set; the option will default to autoloading on every page request. Pass an explicit boolean (true or false) to make the performance trade-off intentional.',
-				$stackPtr,
-				$error_code . 'Missing',
-				array( $matched_content )
-			);
+				$this->phpcsFile->addWarning(
+					'The $autoload parameter for %s() is not explicitly set, so the autoload value is left to WordPress and depends on whether the option already exists and on the WordPress version. Pass an explicit boolean (true or false) to make the performance trade-off intentional.',
+					$stackPtr,
+					$error_code . 'Missing',
+					array( $matched_content )
+				);
+
 		}
 	}
 }
diff --git a/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php b/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php
index 5bc634fd6..94cd103cb 100644
--- a/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php
+++ b/tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php
@@ -18,29 +18,34 @@ public function test_run_with_errors() {
 
 		$check->run( $check_result );
 
+		$errors   = $check_result->get_errors();
 		$warnings = $check_result->get_warnings();
 
+		$this->assertEmpty( $errors );
 		$this->assertNotEmpty( $warnings );
 		$this->assertArrayHasKey( 'load.php', $warnings );
+		$this->assertSame( 4, $check_result->get_warning_count() );
 
 		// Both add_option calls without $autoload must produce warnings.
+		$add_option_column = key( $warnings['load.php'][19] );
 		$this->assertSame(
 			'PluginCheck.CodeAnalysis.AutoLoadedOptions.add_option_autoloadMissing',
-			$warnings['load.php'][19][1][0]['code']
+			$warnings['load.php'][19][ $add_option_column ][0]['code']
 		);
 		$this->assertSame(
 			'PluginCheck.CodeAnalysis.AutoLoadedOptions.add_option_autoloadMissing',
-			$warnings['load.php'][22][1][0]['code']
+			$warnings['load.php'][22][ $add_option_column ][0]['code']
 		);
 
 		// Both update_option calls without $autoload must produce warnings.
+		$update_option_column = key( $warnings['load.php'][25] );
 		$this->assertSame(
 			'PluginCheck.CodeAnalysis.AutoLoadedOptions.update_option_autoloadMissing',
-			$warnings['load.php'][25][1][0]['code']
+			$warnings['load.php'][25][ $update_option_column ][0]['code']
 		);
 		$this->assertSame(
 			'PluginCheck.CodeAnalysis.AutoLoadedOptions.update_option_autoloadMissing',
-			$warnings['load.php'][28][1][0]['code']
+			$warnings['load.php'][28][ $update_option_column ][0]['code']
 		);
 	}