From f8fdd6f7325e4d113c87ccd062e994e8c03696f7 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Mon, 26 Aug 2024 09:56:59 -0300
Subject: [PATCH 01/26] =?UTF-8?q?=E2=9C=A8=20New=20WordPress.WP.OptionAuto?=
 =?UTF-8?q?load=20sniff?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This sniff warns users about missing `$autoload` parameter when calling relevant WordPress option functions.

The sniff runs when the following functions are found in the code:
  - add_option( $option, $value = '', $deprecated = '', $autoload = null)
  - update_option( $option, $value, $autoload = null )
  - wp_set_options_autoload( $options, $autoload )
  - wp_set_option_autoload( $option, $autoload )
  - wp_set_option_autoload_values( $options )

For `add_option()` and `update_option()`, if the `$autoload` parameter is not passed, it simply recommends passing it. For the other three functions, the `$autoload` parameter (or `$options` parameter in the case of `wp_set_option_autoload_values()`) is mandatory, so it is not needed to check if the parameter is omitted.

If the `$autoload` parameter is passed and is `true|false|null` for `add_option()` and `update_option()` or `true|false` for `wp_set_options_autoload()`, `wp_set_option_autoload()` and `wp_set_option_autoload_values()`, the sniff stays silent as those are valid values.

If the `$autoload` parameter is passed and is `'yes'|'no'`, the sniff flags as discouraged parameter values and auto-fixes to `true|false`.

For the internal-use only values of the `$autoload` parameter, if the value is `'auto'|'auto-on'|'auto-off'` the sniff flags it as unsupported without auto-fixing. If the value is `'on'|'off'`, the sniff flags it as unsupported and auto-fixes to `true|false`.

Any other value passed is flagged as an unsupported value and a list of supported values is provided.

The sniff ignores the function call when it is not able to determine the value of the `$autoload` parameter. For example, when a variable or a constant is passed.
---
 WordPress-Extra/ruleset.xml                   |   7 +
 WordPress/Docs/WP/OptionAutoloadStandard.xml  | 135 ++++++
 WordPress/Sniffs/WP/OptionAutoloadSniff.php   | 416 ++++++++++++++++++
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc | 214 +++++++++
 .../Tests/WP/OptionAutoloadUnitTest.inc.fixed | 214 +++++++++
 WordPress/Tests/WP/OptionAutoloadUnitTest.php | 116 +++++
 6 files changed, 1102 insertions(+)
 create mode 100644 WordPress/Docs/WP/OptionAutoloadStandard.xml
 create mode 100644 WordPress/Sniffs/WP/OptionAutoloadSniff.php
 create mode 100644 WordPress/Tests/WP/OptionAutoloadUnitTest.inc
 create mode 100644 WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
 create mode 100644 WordPress/Tests/WP/OptionAutoloadUnitTest.php

diff --git a/WordPress-Extra/ruleset.xml b/WordPress-Extra/ruleset.xml
index a939d1eb95..8b9da1a178 100644
--- a/WordPress-Extra/ruleset.xml
+++ b/WordPress-Extra/ruleset.xml
@@ -193,6 +193,13 @@
 		 https://github.com/WordPress/WordPress-Coding-Standards/issues/2459 -->
 	<rule ref="WordPress.WP.GetMetaSingle"/>
 
+	<!-- Flags calls to add_option(), update_option(), wp_set_options_autoload(),
+		 wp_set_option_autoload(), wp_set_option_autoload_values() functions when the
+		 `$autoload` parameter is missing or contain an invalid, internal-only or
+		 deprecated value.
+		 https://github.com/WordPress/WordPress-Coding-Standards/issues/2473 -->
+	<rule ref="WordPress.WP.OptionAutoload"/>
+
 	<!--
 	#############################################################################
 	Code style sniffs for more recent PHP features and syntaxes.
diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
new file mode 100644
index 0000000000..d9d61e8a0d
--- /dev/null
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0"?>
+<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
+    title="Option Autoload"
+    >
+    <standard>
+    <![CDATA[
+    When using `add_option()`, `update_option()`, `wp_set_options_autoload()`,
+    `wp_set_option_autoload()`, or `wp_set_option_autoload_values()`, it is recommended to
+    explicitly set the autoload value to ensure predictable behavior. This value determines whether
+    the option is automatically loaded on every page load, which can impact site performance.
+
+    Check https://felix-arntz.me/blog/autoloading-wordpress-options-efficiently-and-responsibly/ for
+    more information on when to set autoload to `true` or `false`.
+    ]]>
+    </standard>
+    <standard>
+    <![CDATA[
+    Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
+    recommended to always explicitly set it.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Explicitly setting the autoload parameter.">
+        <![CDATA[
+add_option(
+    'my_option',
+    'value',
+    '',
+    <em>true</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Autoload parameter missing.">
+        <![CDATA[
+add_option(
+    'my_option',
+    'value',
+    ''
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    Using 'yes' or 'no' is not recommended. Those values are deprecated. Instead, use
+    `true`|`false`|`null` if using `add_option()` or `update_option()` or `true`|`false` if using
+    `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, or `wp_set_options_autoload()`.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using boolean values.">
+        <![CDATA[
+update_option(
+    'my_option',
+    'value',
+    <em>true</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using deprecated values.">
+        <![CDATA[
+update_option(
+    'my_option',
+    'value',
+    <em>'yes'</em>
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    It is not recommended to use internal-only values ('auto', 'auto-on', 'auto-off', 'on', 'off')
+    in plugin or theme code. Instead, use `true`|`false`|`null` if using `add_option()` or
+    `update_option()` or `true`|`false` if using `wp_set_option_autoload_values()`,
+    `wp_set_option_autoload()`, or `wp_set_options_autoload()`.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using boolean values.">
+        <![CDATA[
+wp_set_option_autoload_values(
+    array(
+        'my_option_1' => <em>true</em>,
+        'my_option_2' => <em>false</em>
+    )
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using internal-only values.">
+        <![CDATA[
+wp_set_option_autoload_values(
+    array(
+        'my_option_1' => <em>'auto-on'</em>,
+        'my_option_2' => <em>'auto-off'</em>
+    )
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
+    Only `true` and `false` are valid values for the autoload parameter, with one exception: `null`
+    is also valid for `add_option()` and `update_option()`.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Using `true`, `false`, or `null`.">
+        <![CDATA[
+wp_set_options_autoload(
+    array( 'my_option_1', 'my_option_2' ),
+    <em>false</em>
+);
+
+wp_set_option_autoload(
+    'my_option',
+    <em>false</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Using invalid values.">
+        <![CDATA[
+wp_set_options_autoload(
+    array( 'my_option_1', 'my_option_2' ),
+    <em>1</em>
+);
+
+wp_set_option_autoload(
+    'my_option',
+    <em>null</em> // `null` is invalid for this function.
+);
+        ]]>
+        </code>
+    </code_comparison>
+</documentation>
diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
new file mode 100644
index 0000000000..b3e0bdc3f1
--- /dev/null
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -0,0 +1,416 @@
+<?php
+/**
+ * WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPressCS\WordPress\Sniffs\WP;
+
+use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Utils\Arrays;
+use PHPCSUtils\Tokens\Collections;
+use PHPCSUtils\Utils\PassedParameters;
+use PHPCSUtils\Utils\TextStrings;
+use WordPressCS\WordPress\AbstractFunctionParameterSniff;
+
+/**
+ * Warns when calls to add_option(), update_option(), wp_set_options_autoload(),
+ * wp_set_option_autoload(), wp_set_option_autoload_values() are missing the `$autoload` param or
+ * contain an invalid, internal or deprecated value.
+ *
+ * @link https://github.com/WordPress/WordPress-Coding-Standards/issues/2473
+ *
+ * @since 3.2.0
+ */
+final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
+
+	/**
+	 * The phrase to use for the metric recorded by this sniff.
+	 *
+	 * @var string
+	 */
+	const METRIC_NAME = 'Value of the `$autoload` parameter in the option functions';
+
+	/**
+	 * List of valid values for the `$autoload` parameter in the add_option() and update_option()
+	 * functions.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $valid_values_add_and_update = array( 'true', 'false', 'null' );
+
+	/**
+	 * List of valid values for the `$autoload` parameter in the wp_set_options_autoload(),
+	 * wp_set_option_autoload(), and wp_set_option_autoload_values() functions.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $valid_values_other_functions = array( 'true', 'false' );
+
+	/**
+	 * List of deprecated values for the `$autoload` parameter.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $deprecated_values = array( 'yes', 'no' );
+
+	/**
+	 * Internal-use only values for `$autoload` that cannot be fixed automatically by the sniff.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $internal_values_non_fixable = array( 'auto', 'auto-on', 'auto-off' );
+
+	/**
+	 * Internal-use only values for `$autoload` that can be fixed automatically by the sniff.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $internal_values_fixable = array( 'on', 'off' );
+
+	/**
+	 * List of replacements for fixable values.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $fixable_values = array(
+		'yes' => 'true',
+		'no'  => 'false',
+		'on'  => 'true',
+		'off' => 'false',
+	);
+
+	/**
+	 * List of functions for which the `$autoload` parameter is optional.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string[]
+	 */
+	protected static $autoload_is_optional = array( 'add_option', 'update_option' );
+
+	/**
+	 * The group name for this group of functions.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var string
+	 */
+	protected $group_name = 'option_autoload';
+
+	/**
+	 * List of functions this sniff should examine.
+	 *
+	 * @link https://developer.wordpress.org/reference/functions/add_option/
+	 * @link https://developer.wordpress.org/reference/functions/update_option/
+	 * @link https://developer.wordpress.org/reference/functions/wp_set_option_autoload/
+	 * @link https://developer.wordpress.org/reference/functions/wp_set_option_autoload_values/
+	 * @link https://developer.wordpress.org/reference/functions/wp_set_options_autoload/
+	 *
+	 * @since 3.2.0
+	 *
+	 * @var array<string, array<string, string|int>> Key is the function name, value is an array
+	 *                                               containing the name and the position of the
+	 *                                               autoload parameter.
+	 */
+	protected $target_functions = array(
+		'add_option'                    => array(
+			'param_name' => 'autoload',
+			'position'   => 4,
+		),
+		'update_option'                 => array(
+			'param_name' => 'autoload',
+			'position'   => 3,
+		),
+		'wp_set_options_autoload'       => array(
+			'param_name' => 'autoload',
+			'position'   => 2,
+		),
+		'wp_set_option_autoload'        => array(
+			'param_name' => 'autoload',
+			'position'   => 2,
+		),
+		// Special case as it takes an array of option names and autoload values as the first param.
+		'wp_set_option_autoload_values' => array(
+			'param_name' => 'options',
+			'position'   => 1,
+		),
+	);
+
+	/**
+	 * Process the parameters of a matched function.
+	 *
+	 * @since 3.2.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 $function_name 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, $function_name, $parameters ) {
+		$function_info = $this->target_functions[ $function_name ];
+
+		$target_param = PassedParameters::getParameterFromStack(
+			$parameters,
+			$function_info['position'],
+			$function_info['param_name']
+		);
+
+		if ( ! is_array( $target_param ) ) {
+			$this->maybe_display_missing_autoload_warning( $stackPtr, $function_name );
+			return;
+		}
+
+		if ( 'wp_set_option_autoload_values' === $function_name ) {
+			$this->handle_wp_set_option_autoload_values( $target_param, $stackPtr );
+			return;
+		}
+
+		$this->check_autoload_value( $target_param, $function_name );
+	}
+
+	/**
+	 * Process the function if no parameters were found.
+	 *
+	 * @since 3.2.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 $function_name The token content (function name) which was matched
+	 *                              in lowercase.
+	 *
+	 * @return void
+	 */
+	public function process_no_parameters( $stackPtr, $group_name, $function_name ) {
+		$this->maybe_display_missing_autoload_warning( $stackPtr, $function_name );
+	}
+
+	/**
+	 * Handle the `wp_set_option_autoload_values()` function. It requires special treatment as it
+	 * takes an array of option names and autoload values instead of the autoload value of a single
+	 * option as a separate parameter.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @param array $options_param Options parameter information.
+	 * @param int   $stackPtr      The position of the current token in the stack.
+	 *
+	 * @return void
+	 */
+	protected function handle_wp_set_option_autoload_values( array $options_param, $stackPtr ) {
+		$array_token = $this->phpcsFile->findNext(
+			Tokens::$emptyTokens,
+			$options_param['start'],
+			$options_param['end'],
+			true
+		);
+
+		if ( false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $array_token ]['code'] ] ) ) {
+			// Bail if the first non-empty token in the parameter is not an array opener as this
+			// means it is not possible to determine the option names and autoload values passed to
+			// wp_set_option_autoload_values().
+			return;
+		}
+
+		$options = PassedParameters::getParameters( $this->phpcsFile, $array_token );
+
+		if ( empty( $options ) ) {
+			// Bail if the array is empty.
+			return;
+		}
+
+		foreach ( $options as $array_item ) {
+			$double_arrow_pointer = Arrays::getDoubleArrowPtr( $this->phpcsFile, $array_item['start'], $array_item['end'] );
+
+			if ( false === $double_arrow_pointer ) {
+				$start = $array_item['start'];
+				$clean = $array_item['clean'];
+			} else {
+				$array_item_parts = explode( '=>', $array_item['clean'] );
+				$start            = $double_arrow_pointer + 1;
+				$clean            = trim( $array_item_parts[1] );
+			}
+
+			$array_value_info = array(
+				'start' => $start,
+				'end'   => $array_item['end'],
+				'clean' => $clean,
+			);
+
+			$this->check_autoload_value( $array_value_info, 'wp_set_option_autoload_values' );
+		}
+	}
+
+	/**
+	 * Adds a PHPCS warning when autoload parameter is missing for the functions where
+	 * this parameter is optional.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @param int    $stackPtr      The position of the current token in the stack.
+	 * @param string $function_name The name of the function being checked.
+	 *
+	 * @return void
+	 */
+	protected function maybe_display_missing_autoload_warning( $stackPtr, $function_name ) {
+		$this->phpcsFile->recordMetric( $stackPtr, self::METRIC_NAME, 'param missing' );
+
+		// Only display a warning for the functions in which the `$autoload` parameter is optional.
+		if ( in_array( $function_name, self::$autoload_is_optional, true ) ) {
+			$this->phpcsFile->addWarning(
+				'It is recommended to always pass the `$autoload` parameter when using %s() function.',
+				$stackPtr,
+				'Missing',
+				array( $this->tokens[ $stackPtr ]['content'] )
+			);
+		}
+	}
+
+	/**
+	 * Check the autoload value for possible violations.
+	 *
+	 * @since 3.2.0
+	 *
+	 * @param array  $autoload_info Information about the autoload value (start and end tokens and
+	 *                              the clean and raw value).
+	 * @param string $function_name The name of the function being checked.
+	 *
+	 * @return void
+	 */
+	protected function check_autoload_value( array $autoload_info, $function_name ) {
+		// Find the first and second param non-empty tokens (the second token might not exist).
+		$param_first_token  = $this->phpcsFile->findNext(
+			Tokens::$emptyTokens,
+			$autoload_info['start'],
+			( $autoload_info['end'] + 1 ),
+			true
+		);
+		$param_second_token = $this->phpcsFile->findNext(
+			Tokens::$emptyTokens,
+			$param_first_token + 1,
+			( $autoload_info['end'] + 1 ),
+			true
+		);
+
+		$normalized_value = strtolower( $autoload_info['clean'] );
+
+		if ( T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code']
+			&& $param_second_token
+			&& in_array( strtolower( $this->tokens[ $param_second_token ]['content'] ), self::$valid_values_add_and_update, true )
+		) {
+			// Ensure the sniff handles correctly `true`, `false` and `null` when they are
+			// namespaced (preceded by a backslash).
+			$param_first_token  = $param_second_token;
+			$param_second_token = false;
+			$normalized_value   = substr( $normalized_value, 1 );
+		}
+
+		if ( in_array( $function_name, self::$autoload_is_optional, true ) ) {
+			$valid_values = self::$valid_values_add_and_update;
+		} else {
+			$valid_values = self::$valid_values_other_functions;
+		}
+
+		if ( in_array( $normalized_value, $valid_values, true ) ) {
+			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, $normalized_value );
+			return;
+		}
+
+		if ( in_array( $this->tokens[ $param_first_token ]['code'], array( T_VARIABLE, T_STRING ), true )
+			&& 'null' !== strtolower( $this->tokens[ $param_first_token ]['content'] )
+		) {
+			// Bail early if the first non-empty token in the parameter is T_VARIABLE or T_STRING as
+			// this means it is not possible to determine the value.
+			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, 'undetermined value' );
+			return;
+		}
+
+		if ( $param_second_token
+			&& ! in_array( $this->tokens[ $param_first_token ]['code'], array( T_ARRAY, T_OPEN_SHORT_ARRAY ), true )
+		) {
+			// Bail early if the parameter has two or more non-empty tokens and the second token is
+			// not an array opener as this means an undetermined param value or a value that is not
+			// easy to determine.
+			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, 'undetermined value' );
+			return;
+		}
+
+		$autoload_value = TextStrings::stripQuotes( $autoload_info['clean'] );
+
+		$known_discouraged_values = array_merge( self::$deprecated_values, self::$internal_values_non_fixable, self::$internal_values_fixable );
+
+		if ( in_array( $autoload_value, $known_discouraged_values, true ) ) {
+			$metric_value = $autoload_value;
+		} else {
+			$metric_value = 'other value';
+		}
+
+		$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, $metric_value );
+
+		if ( in_array( $autoload_value, self::$deprecated_values, true ) ) {
+			$message    = 'The use of `%s` as the value of the `$autoload` parameter is deprecated. Use `%s` instead.';
+			$error_code = 'Deprecated';
+			$data       = array( $autoload_info['clean'], self::$fixable_values[ $autoload_value ] );
+		} elseif ( in_array( $autoload_value, self::$internal_values_fixable, true ) ) {
+			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged. Use `%s` instead.';
+			$error_code = 'InternalUseOnly';
+			$data       = array( $autoload_info['clean'], self::$fixable_values[ $autoload_value ] );
+		} elseif ( in_array( $autoload_value, self::$internal_values_non_fixable, true ) ) {
+			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged.';
+			$error_code = 'InternalUseOnly';
+			$data       = array( $autoload_info['clean'] );
+		} else {
+			$valid_values        = array_map(
+				function ( $value ) {
+					return '`' . $value . '`';
+				},
+				$valid_values
+			);
+			$valid_values_string = implode( ', ', $valid_values );
+			$valid_values_string = substr_replace( $valid_values_string, ' or', strrpos( $valid_values_string, ',' ), 1 );
+			$message             = 'The use of `%s` as the value of the `$autoload` parameter is invalid. Use %s instead.';
+			$error_code          = 'InvalidValue';
+			$data                = array( $autoload_info['clean'], $valid_values_string );
+		}
+
+		if ( in_array( $autoload_value, array_keys( self::$fixable_values ), true ) ) {
+			$fix = $this->phpcsFile->addFixableWarning(
+				$message,
+				$param_first_token,
+				$error_code,
+				$data
+			);
+
+			if ( $fix ) {
+				$this->phpcsFile->fixer->replaceToken( $param_first_token, self::$fixable_values[ $autoload_value ] );
+			}
+
+			return;
+		}
+
+		$this->phpcsFile->addWarning(
+			$message,
+			$param_first_token,
+			$error_code,
+			$data
+		);
+	}
+}
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
new file mode 100644
index 0000000000..e8b8a2cf89
--- /dev/null
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
@@ -0,0 +1,214 @@
+<?php
+
+/*
+ * Not the sniff target.
+ */
+my\ns\add_option($a, $b);
+$this->add_option($a, $b);
+MyClass::add_option($a, $b);
+echo ADD_OPTION;
+add_action('my_action', add_option(...)); // PHP 8.1 first class callable.
+use function add_option;
+
+/*
+ * These should all be okay.
+ */
+$ok = \add_option( 'my_option', 'my_value', '', true );
+$ok = add_option( 'my_option', array('some', 'big', 'array'), '', false );
+$ok = add_option( 'my_option', new stdClass(), '', null );
+$ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
+$ok = add_option( 'my_option', autoload: false );
+$ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
+$ok = \update_option( 'my_option', 'new_value', \true );
+$ok = update_option( 'my_option', 'new_value', \false );
+$ok = update_option( 'my_option', 'new_value', \NULL );
+$ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
+$ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
+$ok = update_option( $option_name, get_option( $option_name ), false );
+$ok = wp_set_options_autoload( array( 'option1', 'option2' ), \false );
+$ok = wp_set_options_autoload( array( 'option1', 'option2' ), \true );
+$ok = wp_set_options_autoload( autoload: false, options: array( 'option1', 'option2' ) );
+$ok = wp_set_option_autoload( 'option1', false );
+$ok = wp_set_option_autoload( 'option1', true );
+$ok = wp_set_option_autoload( autoload: false, option: 'option1' );
+$ok = wp_set_option_autoload_values(
+    array(
+        'option1' => true,
+        'option2' => false,
+    )
+);
+$ok = wp_set_option_autoload_values(
+    options: array(
+        'option1' => true,
+        $option_name => false,
+    )
+);
+
+/*
+ * These should all be ignored by the sniff as the autoload value is undetermined or not easy to
+ * determine.
+ */
+$ignored = add_option( 'my_option', 'my_value', '', $some_variable );
+$ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
+$ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
+$ignored = add_option( 'my_option', 'my_value', '', 'ye' . 's' );
+$ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
+$ignored = add_option( 'my_option', 'new_value', '', yes);
+$ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
+$ignored = wp_set_option_autoload( 'option1', $some_variable );
+$ignored = wp_set_option_autoload_values(
+    array(
+        'option1' => $some_variable,
+        'option2' => $obj->yes,
+        'option3' => $some_variable ? 'yes' : 'no',
+        'option4' => 'ye' . 's',
+        'option5' => (function () { return 'yes'; })(),
+        'option6' => yes,
+        'option7' => \my_function(),
+        'option8' => \SOME_CONSTANT,
+        'option9' => \YES,
+    )
+);
+
+/*
+ * These are ignored because it is not easy to determine the option names and the autoload values or
+ * the `$options` parameter is empty.
+ */
+$ignored = wp_set_option_autoload_values( $options );
+$ignored = wp_set_option_autoload_values( options: $options );
+$ignored = wp_set_option_autoload_values(array());
+$ignored = wp_set_option_autoload_values([]);
+$ignored = wp_set_option_autoload_values(options: array());
+$ignored = wp_set_option_autoload_values(options: []);
+
+/*
+ * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing
+ */
+$ignored = wp_set_option_autoload_values();
+$ignored = wp_set_options_autoload();
+$ignored = wp_set_options_autoload( array( 'option1', 'option2' ) );
+$ignored = wp_set_option_autoload();
+$ignored = wp_set_option_autoload( 'option1' );
+
+/*
+ * These should all be flagged with a warning.
+ */
+$warning = add_option( 'my_option' );
+$warning = \add_option( 'my_option', 'my_value' );
+if ( add_option( 'my_option', 'my_value', true ) ) {}
+$warning = ADD_OPTION( 'my_option', 'my_value', '', 'auto' );
+$warning = add_option( 'my_option', 'my_value', '', 'auto-on' );
+$warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    'auto-off'
+);
+$warning = add_option( 'my_option', 'my_value', '', 'invalid_value' );
+$warning = add_option( 'my_option', 'my_value', '', 'true' );
+$warning = add_option( 'my_option', 'my_value', '', "false" );
+$warning = add_option( 'my_option', 'my_value', '', array('some', 'array') );
+$warning = add_option( 'my_option', 'my_value', '', ['some', 'array'] );
+$warning = add_option( option: 'my_option' );
+$warning = add_option( value: 'my_value', option: 'my_option' );
+$warning = add_option( value: 'my_value', deprecated: '', option: 'my_option' );
+$warning = add_option( value: 'my_value', deprecated: '', autoload: 'auto', option: 'my_option' );
+$warning = add_option( 'my_option', 'my_value', '', 'YES' ); // the uppercase versions of the valid values are not supported.
+$warning = update_option( 'my_option', 'new_value' );
+$warning = update_option( 'my_option', 'new_value', 'auto' );
+$warning = update_option( 'my_option', 'new_value', 'auto-on' );
+$warning = update_option( 'my_option', 'new_value', 'auto-off' );
+$warning = update_option( 'my_option', 'new_value', 'invalid_value' );
+$warning = update_option( value: 'new_value', option: 'my_option' );
+$warning = update_option( value: 'new_value', autoload: 'auto', option: 'my_option' );
+$warning = update_option( $option_name, get_option( $option_name ) );
+$warning = wp_set_options_autoload( array( 'option1', 'option2' ), 'invalid_value' );
+$warning = wp_set_options_autoload( array( 'option1' ), null );
+$warning = wp_set_option_autoload( 'option1', 'invalid_value' );
+$warning = wp_set_option_autoload( 'option1', \NuLL );
+$warning = wp_set_option_autoload_values( ['option1' => null] );
+$warning = wp_set_option_autoload_values(
+    [
+        'option1' => '',
+        'option2' => 'true',
+        'option3' => "false",
+        'option4' => array('some', 'array'),
+        'option5' => ['some', 'array'],
+        'option6' => 'YES',
+        'option7' => 'invalid_value',
+        'option8' => 'auto',
+        'option9' => 'auto-on',
+        'option10' => 'auto-off',
+        'option11',
+        /* some comment */ 'option12' /* some comment */,
+    ]
+);
+
+// Incorrect function calls, should be flagged by the sniff.
+$incorrect_but_warning = add_option();
+$incorrect_but_warning = update_option();
+$incorrect_but_warning = update_option( 'my_option' );
+$incorrect_but_warning = update_option( autoloader: false, value: 'my_value', option: 'my_option' ); // Typo in the autoload parameter.
+$incorrect_but_warning = add_option( autoload: 'yes', 'my_option' );
+$incorrect_but_warning = add_option( autoload: 'no' );
+
+/*
+ * These should all be flagged with a warning and auto-fixed.
+ */
+$autofix_warning = add_option( 'my_option', 'my_value', '', 'yes' );
+$autofix_warning = add_option( 'my_option', 'my_value', '', 'no' );
+$autofix_warning = add_option( 'my_option', 'my_value', '', "yes" );
+$autofix_warning = add_option( 'my_option', 'my_value', '', "no" );
+$autofix_warning = add_option( 'my_option', 'my_value', '', 'on' );
+$autofix_warning = add_option( 'my_option', 'my_value', '', 'off' );
+$autofix_warning = add_option( 'my_option', 'my_value', '', /* weirdly placed comment */ 'off' /* weirdly placed comment */ );
+$autofix_warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    // weirdly placed comment
+    'off'
+);
+$autofix_warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+    'off'
+);
+$autofix_warning = add_option( 'my_option', 'my_value', '','off');
+$autofix_warning = add_option( value: 'my_value', deprecated: '', autoload: 'yes', option: 'my_option' );
+$autofix_warning = update_option( 'my_option', 'new_value', 'yes' );
+$autofix_warning = update_option( 'my_option', 'new_value', 'no' );
+$autofix_warning = update_option( 'my_option', 'new_value', 'on' );
+$autofix_warning = update_option( 'my_option', 'new_value', 'off' );
+$autofix_warning = update_option( value: 'new_value', autoload: 'yes', option: 'my_option' );
+
+$autofix_warning = wp_set_options_autoload( array( 'option1', 'option2' ), 'yes' );
+$autofix_warning = wp_set_options_autoload( array( 'option1', 'option2' ), 'no' );
+$autofix_warning = wp_set_option_autoload( 'option1', 'yes' );
+$autofix_warning = wp_set_option_autoload( 'option1', 'no' );
+$autofix_warning = WP_SET_OPTION_AUTOLOAD_VALUES(
+    array(
+        'option1' => 'yes',
+        'option2' => 'no',
+        'option3' => 'on',
+        'option4' => 'off',
+    )
+);
+$autofix_warning = Wp_Set_Option_Autoload_Values(
+    options: array(
+        'option1' => 'yes',
+    )
+);
+
+$mixed_autoload_values = wp_set_option_autoload_values(
+    array(
+        'option1' => 'yes',
+        'option2' => false,
+        'option3' => 'on',
+        'option4' => true,
+        'option5' => $option_value,
+        'option6' => 'auto',
+    )
+);
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
new file mode 100644
index 0000000000..a563079335
--- /dev/null
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
@@ -0,0 +1,214 @@
+<?php
+
+/*
+ * Not the sniff target.
+ */
+my\ns\add_option($a, $b);
+$this->add_option($a, $b);
+MyClass::add_option($a, $b);
+echo ADD_OPTION;
+add_action('my_action', add_option(...)); // PHP 8.1 first class callable.
+use function add_option;
+
+/*
+ * These should all be okay.
+ */
+$ok = \add_option( 'my_option', 'my_value', '', true );
+$ok = add_option( 'my_option', array('some', 'big', 'array'), '', false );
+$ok = add_option( 'my_option', new stdClass(), '', null );
+$ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
+$ok = add_option( 'my_option', autoload: false );
+$ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
+$ok = \update_option( 'my_option', 'new_value', \true );
+$ok = update_option( 'my_option', 'new_value', \false );
+$ok = update_option( 'my_option', 'new_value', \NULL );
+$ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
+$ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
+$ok = update_option( $option_name, get_option( $option_name ), false );
+$ok = wp_set_options_autoload( array( 'option1', 'option2' ), \false );
+$ok = wp_set_options_autoload( array( 'option1', 'option2' ), \true );
+$ok = wp_set_options_autoload( autoload: false, options: array( 'option1', 'option2' ) );
+$ok = wp_set_option_autoload( 'option1', false );
+$ok = wp_set_option_autoload( 'option1', true );
+$ok = wp_set_option_autoload( autoload: false, option: 'option1' );
+$ok = wp_set_option_autoload_values(
+    array(
+        'option1' => true,
+        'option2' => false,
+    )
+);
+$ok = wp_set_option_autoload_values(
+    options: array(
+        'option1' => true,
+        $option_name => false,
+    )
+);
+
+/*
+ * These should all be ignored by the sniff as the autoload value is undetermined or not easy to
+ * determine.
+ */
+$ignored = add_option( 'my_option', 'my_value', '', $some_variable );
+$ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
+$ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
+$ignored = add_option( 'my_option', 'my_value', '', 'ye' . 's' );
+$ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
+$ignored = add_option( 'my_option', 'new_value', '', yes);
+$ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
+$ignored = wp_set_option_autoload( 'option1', $some_variable );
+$ignored = wp_set_option_autoload_values(
+    array(
+        'option1' => $some_variable,
+        'option2' => $obj->yes,
+        'option3' => $some_variable ? 'yes' : 'no',
+        'option4' => 'ye' . 's',
+        'option5' => (function () { return 'yes'; })(),
+        'option6' => yes,
+        'option7' => \my_function(),
+        'option8' => \SOME_CONSTANT,
+        'option9' => \YES,
+    )
+);
+
+/*
+ * These are ignored because it is not easy to determine the option names and the autoload values or
+ * the `$options` parameter is empty.
+ */
+$ignored = wp_set_option_autoload_values( $options );
+$ignored = wp_set_option_autoload_values( options: $options );
+$ignored = wp_set_option_autoload_values(array());
+$ignored = wp_set_option_autoload_values([]);
+$ignored = wp_set_option_autoload_values(options: array());
+$ignored = wp_set_option_autoload_values(options: []);
+
+/*
+ * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing
+ */
+$ignored = wp_set_option_autoload_values();
+$ignored = wp_set_options_autoload();
+$ignored = wp_set_options_autoload( array( 'option1', 'option2' ) );
+$ignored = wp_set_option_autoload();
+$ignored = wp_set_option_autoload( 'option1' );
+
+/*
+ * These should all be flagged with a warning.
+ */
+$warning = add_option( 'my_option' );
+$warning = \add_option( 'my_option', 'my_value' );
+if ( add_option( 'my_option', 'my_value', true ) ) {}
+$warning = ADD_OPTION( 'my_option', 'my_value', '', 'auto' );
+$warning = add_option( 'my_option', 'my_value', '', 'auto-on' );
+$warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    'auto-off'
+);
+$warning = add_option( 'my_option', 'my_value', '', 'invalid_value' );
+$warning = add_option( 'my_option', 'my_value', '', 'true' );
+$warning = add_option( 'my_option', 'my_value', '', "false" );
+$warning = add_option( 'my_option', 'my_value', '', array('some', 'array') );
+$warning = add_option( 'my_option', 'my_value', '', ['some', 'array'] );
+$warning = add_option( option: 'my_option' );
+$warning = add_option( value: 'my_value', option: 'my_option' );
+$warning = add_option( value: 'my_value', deprecated: '', option: 'my_option' );
+$warning = add_option( value: 'my_value', deprecated: '', autoload: 'auto', option: 'my_option' );
+$warning = add_option( 'my_option', 'my_value', '', 'YES' ); // the uppercase versions of the valid values are not supported.
+$warning = update_option( 'my_option', 'new_value' );
+$warning = update_option( 'my_option', 'new_value', 'auto' );
+$warning = update_option( 'my_option', 'new_value', 'auto-on' );
+$warning = update_option( 'my_option', 'new_value', 'auto-off' );
+$warning = update_option( 'my_option', 'new_value', 'invalid_value' );
+$warning = update_option( value: 'new_value', option: 'my_option' );
+$warning = update_option( value: 'new_value', autoload: 'auto', option: 'my_option' );
+$warning = update_option( $option_name, get_option( $option_name ) );
+$warning = wp_set_options_autoload( array( 'option1', 'option2' ), 'invalid_value' );
+$warning = wp_set_options_autoload( array( 'option1' ), null );
+$warning = wp_set_option_autoload( 'option1', 'invalid_value' );
+$warning = wp_set_option_autoload( 'option1', \NuLL );
+$warning = wp_set_option_autoload_values( ['option1' => null] );
+$warning = wp_set_option_autoload_values(
+    [
+        'option1' => '',
+        'option2' => 'true',
+        'option3' => "false",
+        'option4' => array('some', 'array'),
+        'option5' => ['some', 'array'],
+        'option6' => 'YES',
+        'option7' => 'invalid_value',
+        'option8' => 'auto',
+        'option9' => 'auto-on',
+        'option10' => 'auto-off',
+        'option11',
+        /* some comment */ 'option12' /* some comment */,
+    ]
+);
+
+// Incorrect function calls, should be flagged by the sniff.
+$incorrect_but_warning = add_option();
+$incorrect_but_warning = update_option();
+$incorrect_but_warning = update_option( 'my_option' );
+$incorrect_but_warning = update_option( autoloader: false, value: 'my_value', option: 'my_option' ); // Typo in the autoload parameter.
+$incorrect_but_warning = add_option( autoload: true, 'my_option' );
+$incorrect_but_warning = add_option( autoload: false );
+
+/*
+ * These should all be flagged with a warning and auto-fixed.
+ */
+$autofix_warning = add_option( 'my_option', 'my_value', '', true );
+$autofix_warning = add_option( 'my_option', 'my_value', '', false );
+$autofix_warning = add_option( 'my_option', 'my_value', '', true );
+$autofix_warning = add_option( 'my_option', 'my_value', '', false );
+$autofix_warning = add_option( 'my_option', 'my_value', '', true );
+$autofix_warning = add_option( 'my_option', 'my_value', '', false );
+$autofix_warning = add_option( 'my_option', 'my_value', '', /* weirdly placed comment */ false /* weirdly placed comment */ );
+$autofix_warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    // weirdly placed comment
+    false
+);
+$autofix_warning = add_option(
+    'my_option',
+    'my_value',
+    '',
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+    false
+);
+$autofix_warning = add_option( 'my_option', 'my_value', '',false);
+$autofix_warning = add_option( value: 'my_value', deprecated: '', autoload: true, option: 'my_option' );
+$autofix_warning = update_option( 'my_option', 'new_value', true );
+$autofix_warning = update_option( 'my_option', 'new_value', false );
+$autofix_warning = update_option( 'my_option', 'new_value', true );
+$autofix_warning = update_option( 'my_option', 'new_value', false );
+$autofix_warning = update_option( value: 'new_value', autoload: true, option: 'my_option' );
+
+$autofix_warning = wp_set_options_autoload( array( 'option1', 'option2' ), true );
+$autofix_warning = wp_set_options_autoload( array( 'option1', 'option2' ), false );
+$autofix_warning = wp_set_option_autoload( 'option1', true );
+$autofix_warning = wp_set_option_autoload( 'option1', false );
+$autofix_warning = WP_SET_OPTION_AUTOLOAD_VALUES(
+    array(
+        'option1' => true,
+        'option2' => false,
+        'option3' => true,
+        'option4' => false,
+    )
+);
+$autofix_warning = Wp_Set_Option_Autoload_Values(
+    options: array(
+        'option1' => true,
+    )
+);
+
+$mixed_autoload_values = wp_set_option_autoload_values(
+    array(
+        'option1' => true,
+        'option2' => false,
+        'option3' => true,
+        'option4' => true,
+        'option5' => $option_value,
+        'option6' => 'auto',
+    )
+);
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.php b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
new file mode 100644
index 0000000000..78b31f9b56
--- /dev/null
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
@@ -0,0 +1,116 @@
+<?php
+/**
+ * Unit test class for WordPress Coding Standard.
+ *
+ * @package WPCS\WordPressCodingStandards
+ * @link    https://github.com/WordPress/WordPress-Coding-Standards
+ * @license https://opensource.org/licenses/MIT MIT
+ */
+
+namespace WordPressCS\WordPress\Tests\WP;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Unit test class for the OptionAutoload sniff.
+ *
+ * @since 3.2.0
+ *
+ * @covers \WordPressCS\WordPress\Sniffs\WP\OptionAutoloadSniff
+ */
+final class OptionAutoloadUnitTest extends AbstractSniffUnitTest {
+
+	/**
+	 * Returns the lines where errors should occur.
+	 *
+	 * @return array<int, int> Key is the line number, value is the number of expected errors.
+	 */
+	public function getErrorList() {
+		return array();
+	}
+
+	/**
+	 * Returns the lines where warnings should occur.
+	 *
+	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
+	 */
+	public function getWarningList() {
+		return array(
+			96  => 1,
+			97  => 1,
+			98  => 1,
+			99  => 1,
+			100 => 1,
+			105 => 1,
+			107 => 1,
+			108 => 1,
+			109 => 1,
+			110 => 1,
+			111 => 1,
+			112 => 1,
+			113 => 1,
+			114 => 1,
+			115 => 1,
+			116 => 1,
+			117 => 1,
+			118 => 1,
+			119 => 1,
+			120 => 1,
+			121 => 1,
+			122 => 1,
+			123 => 1,
+			124 => 1,
+			125 => 1,
+			126 => 1,
+			127 => 1,
+			128 => 1,
+			129 => 1,
+			132 => 1,
+			133 => 1,
+			134 => 1,
+			135 => 1,
+			136 => 1,
+			137 => 1,
+			138 => 1,
+			139 => 1,
+			140 => 1,
+			141 => 1,
+			142 => 1,
+			143 => 1,
+			148 => 1,
+			149 => 1,
+			150 => 1,
+			151 => 1,
+			152 => 1,
+			153 => 1,
+			158 => 1,
+			159 => 1,
+			160 => 1,
+			161 => 1,
+			162 => 1,
+			163 => 1,
+			164 => 1,
+			170 => 1,
+			177 => 1,
+			179 => 1,
+			180 => 1,
+			181 => 1,
+			182 => 1,
+			183 => 1,
+			184 => 1,
+			185 => 1,
+			187 => 1,
+			188 => 1,
+			189 => 1,
+			190 => 1,
+			193 => 1,
+			194 => 1,
+			195 => 1,
+			196 => 1,
+			201 => 1,
+			207 => 1,
+			209 => 1,
+			212 => 1,
+		);
+	}
+}

From b47e08aad40a5c204d7cef084da2f95b59447cc2 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 28 Feb 2025 11:22:51 -0300
Subject: [PATCH 02/26] Apply suggestions from code review

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 WordPress/Docs/WP/OptionAutoloadStandard.xml  | 27 ++++----
 WordPress/Sniffs/WP/OptionAutoloadSniff.php   | 65 ++++++++++---------
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc | 10 +--
 .../Tests/WP/OptionAutoloadUnitTest.inc.fixed | 10 +--
 4 files changed, 57 insertions(+), 55 deletions(-)

diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
index d9d61e8a0d..3bc79ed06a 100644
--- a/WordPress/Docs/WP/OptionAutoloadStandard.xml
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -7,11 +7,8 @@
     <![CDATA[
     When using `add_option()`, `update_option()`, `wp_set_options_autoload()`,
     `wp_set_option_autoload()`, or `wp_set_option_autoload_values()`, it is recommended to
-    explicitly set the autoload value to ensure predictable behavior. This value determines whether
+    explicitly set the autoload parameter to ensure predictable behavior. This parameter determines whether
     the option is automatically loaded on every page load, which can impact site performance.
-
-    Check https://felix-arntz.me/blog/autoloading-wordpress-options-efficiently-and-responsibly/ for
-    more information on when to set autoload to `true` or `false`.
     ]]>
     </standard>
     <standard>
@@ -43,13 +40,15 @@ add_option(
     </code_comparison>
     <standard>
     <![CDATA[
-    Using 'yes' or 'no' is not recommended. Those values are deprecated. Instead, use
-    `true`|`false`|`null` if using `add_option()` or `update_option()` or `true`|`false` if using
-    `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, or `wp_set_options_autoload()`.
+    When calling the `add_option()` or `update_option()` functions, use `true`, `false` or `null`
+    as the value for the autoload parameter. For the `wp_set_option_autoload_values()`,
+    `wp_set_option_autoload()`, or `wp_set_options_autoload()` functions, use `true` or `false`.
+
+    Using 'yes' or 'no' as the value for the autoload parameter is deprecated since WordPress 6.6.0.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using boolean values.">
+        <code title="Valid: Using a boolean value.">
         <![CDATA[
 update_option(
     'my_option',
@@ -58,7 +57,7 @@ update_option(
 );
         ]]>
         </code>
-        <code title="Invalid: Using deprecated values.">
+        <code title="Invalid: Using a deprecated value.">
         <![CDATA[
 update_option(
     'my_option',
@@ -70,10 +69,10 @@ update_option(
     </code_comparison>
     <standard>
     <![CDATA[
-    It is not recommended to use internal-only values ('auto', 'auto-on', 'auto-off', 'on', 'off')
-    in plugin or theme code. Instead, use `true`|`false`|`null` if using `add_option()` or
-    `update_option()` or `true`|`false` if using `wp_set_option_autoload_values()`,
-    `wp_set_option_autoload()`, or `wp_set_options_autoload()`.
+    Use `true`|`false`|`null` if using `add_option()` or `update_option()` or `true`|`false` if
+    using `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, or
+    `wp_set_options_autoload()`. It is strongly discouraged to use internal-only values ('auto',
+    'auto-on', 'auto-off', 'on', 'off') in plugin or theme code.
     ]]>
     </standard>
     <code_comparison>
@@ -114,7 +113,7 @@ wp_set_options_autoload(
 
 wp_set_option_autoload(
     'my_option',
-    <em>false</em>
+    <em>true</em>
 );
         ]]>
         </code>
diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index b3e0bdc3f1..f79d1dfd09 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -30,6 +30,8 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	/**
 	 * The phrase to use for the metric recorded by this sniff.
 	 *
+	 * @since 3.2.0
+	 *
 	 * @var string
 	 */
 	const METRIC_NAME = 'Value of the `$autoload` parameter in the option functions';
@@ -42,7 +44,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $valid_values_add_and_update = array( 'true', 'false', 'null' );
+	private $valid_values_add_and_update = array( 'true', 'false', 'null' );
 
 	/**
 	 * List of valid values for the `$autoload` parameter in the wp_set_options_autoload(),
@@ -52,7 +54,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $valid_values_other_functions = array( 'true', 'false' );
+	private $valid_values_other_functions = array( 'true', 'false' );
 
 	/**
 	 * List of deprecated values for the `$autoload` parameter.
@@ -61,7 +63,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $deprecated_values = array( 'yes', 'no' );
+	private $deprecated_values = array( 'yes', 'no' );
 
 	/**
 	 * Internal-use only values for `$autoload` that cannot be fixed automatically by the sniff.
@@ -70,7 +72,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $internal_values_non_fixable = array( 'auto', 'auto-on', 'auto-off' );
+	private $internal_values_non_fixable = array( 'auto', 'auto-on', 'auto-off' );
 
 	/**
 	 * Internal-use only values for `$autoload` that can be fixed automatically by the sniff.
@@ -79,16 +81,16 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $internal_values_fixable = array( 'on', 'off' );
+	private $internal_values_fixable = array( 'on', 'off' );
 
 	/**
 	 * List of replacements for fixable values.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, string>
 	 */
-	protected static $fixable_values = array(
+	private $fixable_values = array(
 		'yes' => 'true',
 		'no'  => 'false',
 		'on'  => 'true',
@@ -102,7 +104,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var string[]
 	 */
-	protected static $autoload_is_optional = array( 'add_option', 'update_option' );
+	private $autoload_is_optional = array( 'add_option', 'update_option' );
 
 	/**
 	 * The group name for this group of functions.
@@ -215,7 +217,7 @@ public function process_no_parameters( $stackPtr, $group_name, $function_name )
 	 *
 	 * @return void
 	 */
-	protected function handle_wp_set_option_autoload_values( array $options_param, $stackPtr ) {
+	private function handle_wp_set_option_autoload_values( array $options_param, $stackPtr ) {
 		$array_token = $this->phpcsFile->findNext(
 			Tokens::$emptyTokens,
 			$options_param['start'],
@@ -266,15 +268,16 @@ protected function handle_wp_set_option_autoload_values( array $options_param, $
 	 * @since 3.2.0
 	 *
 	 * @param int    $stackPtr      The position of the current token in the stack.
-	 * @param string $function_name The name of the function being checked.
+	 * @param string $function_name The token content (function name) which was matched
+	 *                              in lowercase.
 	 *
 	 * @return void
 	 */
-	protected function maybe_display_missing_autoload_warning( $stackPtr, $function_name ) {
+	private function maybe_display_missing_autoload_warning( $stackPtr, $function_name ) {
 		$this->phpcsFile->recordMetric( $stackPtr, self::METRIC_NAME, 'param missing' );
 
 		// Only display a warning for the functions in which the `$autoload` parameter is optional.
-		if ( in_array( $function_name, self::$autoload_is_optional, true ) ) {
+		if ( in_array( $function_name, $this->autoload_is_optional, true ) ) {
 			$this->phpcsFile->addWarning(
 				'It is recommended to always pass the `$autoload` parameter when using %s() function.',
 				$stackPtr,
@@ -290,13 +293,13 @@ protected function maybe_display_missing_autoload_warning( $stackPtr, $function_
 	 * @since 3.2.0
 	 *
 	 * @param array  $autoload_info Information about the autoload value (start and end tokens and
-	 *                              the clean and raw value).
-	 * @param string $function_name The name of the function being checked.
+	 *                              the clean value).
+	 * @param string $function_name The token content (function name) which was matched
+	 *                              in lowercase.
 	 *
 	 * @return void
 	 */
-	protected function check_autoload_value( array $autoload_info, $function_name ) {
-		// Find the first and second param non-empty tokens (the second token might not exist).
+	private function check_autoload_value( array $autoload_info, $function_name ) {
 		$param_first_token  = $this->phpcsFile->findNext(
 			Tokens::$emptyTokens,
 			$autoload_info['start'],
@@ -312,9 +315,9 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 
 		$normalized_value = strtolower( $autoload_info['clean'] );
 
-		if ( T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code']
+		if ( \T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code']
 			&& $param_second_token
-			&& in_array( strtolower( $this->tokens[ $param_second_token ]['content'] ), self::$valid_values_add_and_update, true )
+			&& in_array( strtolower( $this->tokens[ $param_second_token ]['content'] ), $this->valid_values_add_and_update, true )
 		) {
 			// Ensure the sniff handles correctly `true`, `false` and `null` when they are
 			// namespaced (preceded by a backslash).
@@ -323,10 +326,10 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 			$normalized_value   = substr( $normalized_value, 1 );
 		}
 
-		if ( in_array( $function_name, self::$autoload_is_optional, true ) ) {
-			$valid_values = self::$valid_values_add_and_update;
+		if ( in_array( $function_name, $this->autoload_is_optional, true ) ) {
+			$valid_values = $this->valid_values_add_and_update;
 		} else {
-			$valid_values = self::$valid_values_other_functions;
+			$valid_values = $this->valid_values_other_functions;
 		}
 
 		if ( in_array( $normalized_value, $valid_values, true ) ) {
@@ -334,7 +337,7 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 			return;
 		}
 
-		if ( in_array( $this->tokens[ $param_first_token ]['code'], array( T_VARIABLE, T_STRING ), true )
+		if ( in_array( $this->tokens[ $param_first_token ]['code'], array( \T_VARIABLE, \T_STRING ), true )
 			&& 'null' !== strtolower( $this->tokens[ $param_first_token ]['content'] )
 		) {
 			// Bail early if the first non-empty token in the parameter is T_VARIABLE or T_STRING as
@@ -344,7 +347,7 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 		}
 
 		if ( $param_second_token
-			&& ! in_array( $this->tokens[ $param_first_token ]['code'], array( T_ARRAY, T_OPEN_SHORT_ARRAY ), true )
+			&& ! isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $param_first_token ]['code'] ] )
 		) {
 			// Bail early if the parameter has two or more non-empty tokens and the second token is
 			// not an array opener as this means an undetermined param value or a value that is not
@@ -355,7 +358,7 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 
 		$autoload_value = TextStrings::stripQuotes( $autoload_info['clean'] );
 
-		$known_discouraged_values = array_merge( self::$deprecated_values, self::$internal_values_non_fixable, self::$internal_values_fixable );
+		$known_discouraged_values = array_merge( $this->deprecated_values, $this->internal_values_non_fixable, $this->internal_values_fixable );
 
 		if ( in_array( $autoload_value, $known_discouraged_values, true ) ) {
 			$metric_value = $autoload_value;
@@ -365,15 +368,15 @@ protected function check_autoload_value( array $autoload_info, $function_name )
 
 		$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, $metric_value );
 
-		if ( in_array( $autoload_value, self::$deprecated_values, true ) ) {
+		if ( in_array( $autoload_value, $this->deprecated_values, true ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is deprecated. Use `%s` instead.';
 			$error_code = 'Deprecated';
-			$data       = array( $autoload_info['clean'], self::$fixable_values[ $autoload_value ] );
-		} elseif ( in_array( $autoload_value, self::$internal_values_fixable, true ) ) {
+			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
+		} elseif ( in_array( $autoload_value, $this->internal_values_fixable, true ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged. Use `%s` instead.';
 			$error_code = 'InternalUseOnly';
-			$data       = array( $autoload_info['clean'], self::$fixable_values[ $autoload_value ] );
-		} elseif ( in_array( $autoload_value, self::$internal_values_non_fixable, true ) ) {
+			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
+		} elseif ( in_array( $autoload_value, $this->internal_values_non_fixable, true ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged.';
 			$error_code = 'InternalUseOnly';
 			$data       = array( $autoload_info['clean'] );
@@ -391,7 +394,7 @@ function ( $value ) {
 			$data                = array( $autoload_info['clean'], $valid_values_string );
 		}
 
-		if ( in_array( $autoload_value, array_keys( self::$fixable_values ), true ) ) {
+		if ( in_array( $autoload_value, array_keys( $this->fixable_values ), true ) ) {
 			$fix = $this->phpcsFile->addFixableWarning(
 				$message,
 				$param_first_token,
@@ -400,7 +403,7 @@ function ( $value ) {
 			);
 
 			if ( $fix ) {
-				$this->phpcsFile->fixer->replaceToken( $param_first_token, self::$fixable_values[ $autoload_value ] );
+				$this->phpcsFile->fixer->replaceToken( $param_first_token, $this->fixable_values[ $autoload_value ] );
 			}
 
 			return;
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
index e8b8a2cf89..1215a8726d 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
@@ -45,8 +45,8 @@ $ok = wp_set_option_autoload_values(
 );
 
 /*
- * These should all be ignored by the sniff as the autoload value is undetermined or not easy to
- * determine.
+ * These should all be ignored by the sniff as the autoload value can't be reliably
+ * determined.
  */
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable );
 $ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
@@ -71,8 +71,8 @@ $ignored = wp_set_option_autoload_values(
 );
 
 /*
- * These are ignored because it is not easy to determine the option names and the autoload values or
- * the `$options` parameter is empty.
+ * These are ignored because the option names and the autoload values can't be reliably determined
+ * or the `$options` parameter is empty.
  */
 $ignored = wp_set_option_autoload_values( $options );
 $ignored = wp_set_option_autoload_values( options: $options );
@@ -82,7 +82,7 @@ $ignored = wp_set_option_autoload_values(options: array());
 $ignored = wp_set_option_autoload_values(options: []);
 
 /*
- * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing
+ * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing.
  */
 $ignored = wp_set_option_autoload_values();
 $ignored = wp_set_options_autoload();
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
index a563079335..a4f33a42f9 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
@@ -45,8 +45,8 @@ $ok = wp_set_option_autoload_values(
 );
 
 /*
- * These should all be ignored by the sniff as the autoload value is undetermined or not easy to
- * determine.
+ * These should all be ignored by the sniff as the autoload value can't be reliably
+ * determined.
  */
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable );
 $ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
@@ -71,8 +71,8 @@ $ignored = wp_set_option_autoload_values(
 );
 
 /*
- * These are ignored because it is not easy to determine the option names and the autoload values or
- * the `$options` parameter is empty.
+ * These are ignored because the option names and the autoload values can't be reliably determined
+ * or the `$options` parameter is empty.
  */
 $ignored = wp_set_option_autoload_values( $options );
 $ignored = wp_set_option_autoload_values( options: $options );
@@ -82,7 +82,7 @@ $ignored = wp_set_option_autoload_values(options: array());
 $ignored = wp_set_option_autoload_values(options: []);
 
 /*
- * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing
+ * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing.
  */
 $ignored = wp_set_option_autoload_values();
 $ignored = wp_set_options_autoload();

From 715b43ae58e58b10bcec4dba509befde6370adbb Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 28 Feb 2025 17:18:22 -0300
Subject: [PATCH 03/26] Attemp to improve the XML documentation by combining
 standards

---
 WordPress/Docs/WP/OptionAutoloadStandard.xml | 114 +++++++------------
 1 file changed, 41 insertions(+), 73 deletions(-)

diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
index 3bc79ed06a..b2520ae144 100644
--- a/WordPress/Docs/WP/OptionAutoloadStandard.xml
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -7,18 +7,28 @@
     <![CDATA[
     When using `add_option()`, `update_option()`, `wp_set_options_autoload()`,
     `wp_set_option_autoload()`, or `wp_set_option_autoload_values()`, it is recommended to
-    explicitly set the autoload parameter to ensure predictable behavior. This parameter determines whether
-    the option is automatically loaded on every page load, which can impact site performance.
+    explicitly set the autoload parameter to ensure predictable behavior. This parameter determines
+    whether the option is automatically loaded on every page load, which can impact site performance.
     ]]>
     </standard>
     <standard>
     <![CDATA[
-    Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
-    recommended to always explicitly set it.
+    The following values should be used when setting the autoload parameter depending on the function:
+
+    - For `add_option()` and `update_option()`: `true`, `false`, or `null`.
+    - For `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, and
+    `wp_set_options_autoload()`: `true` or `false`.
+
+    Using 'yes' or 'no' is deprecated since WordPress 6.6.0. Using 'auto', 'auto-on', 'auto-off',
+    'on', or 'off' in plugin/theme code is strongly discouraged as those values are meant for
+    internal-use only.
+
+    Any other values, including `null` for functions other than `add_option()` and `update_option()`
+    are invalid.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Explicitly setting the autoload parameter.">
+        <code title="Valid: Using a boolean value or `null`">
         <![CDATA[
 add_option(
     'my_option',
@@ -26,107 +36,65 @@ add_option(
     '',
     <em>true</em>
 );
-        ]]>
-        </code>
-        <code title="Invalid: Autoload parameter missing.">
-        <![CDATA[
-add_option(
-    'my_option',
-    'value',
-    ''
-);
-        ]]>
-        </code>
-    </code_comparison>
-    <standard>
-    <![CDATA[
-    When calling the `add_option()` or `update_option()` functions, use `true`, `false` or `null`
-    as the value for the autoload parameter. For the `wp_set_option_autoload_values()`,
-    `wp_set_option_autoload()`, or `wp_set_options_autoload()` functions, use `true` or `false`.
 
-    Using 'yes' or 'no' as the value for the autoload parameter is deprecated since WordPress 6.6.0.
-    ]]>
-    </standard>
-    <code_comparison>
-        <code title="Valid: Using a boolean value.">
-        <![CDATA[
 update_option(
     'my_option',
     'value',
-    <em>true</em>
+    <em>null</em>
 );
         ]]>
         </code>
-        <code title="Invalid: Using a deprecated value.">
+        <code title="Invalid: Using deprecated, internal-only, or invalid values">
         <![CDATA[
-update_option(
+add_option(
     'my_option',
     'value',
+    '',
     <em>'yes'</em>
 );
-        ]]>
-        </code>
-    </code_comparison>
-    <standard>
-    <![CDATA[
-    Use `true`|`false`|`null` if using `add_option()` or `update_option()` or `true`|`false` if
-    using `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, or
-    `wp_set_options_autoload()`. It is strongly discouraged to use internal-only values ('auto',
-    'auto-on', 'auto-off', 'on', 'off') in plugin or theme code.
-    ]]>
-    </standard>
-    <code_comparison>
-        <code title="Valid: Using boolean values.">
-        <![CDATA[
-wp_set_option_autoload_values(
-    array(
-        'my_option_1' => <em>true</em>,
-        'my_option_2' => <em>false</em>
-    )
+
+wp_set_option_autoload(
+    'my_option',
+    <em>null</em>
 );
-        ]]>
-        </code>
-        <code title="Invalid: Using internal-only values.">
-        <![CDATA[
+
 wp_set_option_autoload_values(
     array(
-        'my_option_1' => <em>'auto-on'</em>,
-        'my_option_2' => <em>'auto-off'</em>
+        'option1' => <em>'auto-on'</em>,
+        'option2' => <em>'off'</em>
     )
 );
+
+wp_set_options_autoload(
+    array('option1', 'option2'),
+    <em>1</em>
+);
         ]]>
         </code>
     </code_comparison>
     <standard>
     <![CDATA[
-    Only `true` and `false` are valid values for the autoload parameter, with one exception: `null`
-    is also valid for `add_option()` and `update_option()`.
+    Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
+    recommended to always explicitly set it.
     ]]>
     </standard>
     <code_comparison>
-        <code title="Valid: Using `true`, `false`, or `null`.">
+        <code title="Valid: Explicitly setting the autoload parameter.">
         <![CDATA[
-wp_set_options_autoload(
-    array( 'my_option_1', 'my_option_2' ),
-    <em>false</em>
-);
-
-wp_set_option_autoload(
+add_option(
     'my_option',
+    'value',
+    '',
     <em>true</em>
 );
         ]]>
         </code>
-        <code title="Invalid: Using invalid values.">
+        <code title="Invalid: Autoload parameter missing.">
         <![CDATA[
-wp_set_options_autoload(
-    array( 'my_option_1', 'my_option_2' ),
-    <em>1</em>
-);
-
-wp_set_option_autoload(
+add_option(
     'my_option',
-    <em>null</em> // `null` is invalid for this function.
+    'value',
+    ''
 );
         ]]>
         </code>

From 4cf89cf864d14e5a0cc18a01b2b000ac52acec92 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 11 Mar 2025 13:57:10 -0300
Subject: [PATCH 04/26] Fix unintentional coding standard violation in a test
 case

---
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc       | 2 +-
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
index 1215a8726d..cd94cbf520 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
@@ -176,7 +176,7 @@ $autofix_warning = add_option(
     // phpcs:ignore Standard.Category.Sniff -- For test reasons.
     'off'
 );
-$autofix_warning = add_option( 'my_option', 'my_value', '','off');
+$autofix_warning = add_option( 'my_option', 'my_value', '', 'off' );
 $autofix_warning = add_option( value: 'my_value', deprecated: '', autoload: 'yes', option: 'my_option' );
 $autofix_warning = update_option( 'my_option', 'new_value', 'yes' );
 $autofix_warning = update_option( 'my_option', 'new_value', 'no' );
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
index a4f33a42f9..8ba435c046 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
@@ -176,7 +176,7 @@ $autofix_warning = add_option(
     // phpcs:ignore Standard.Category.Sniff -- For test reasons.
     false
 );
-$autofix_warning = add_option( 'my_option', 'my_value', '',false);
+$autofix_warning = add_option( 'my_option', 'my_value', '', false );
 $autofix_warning = add_option( value: 'my_value', deprecated: '', autoload: true, option: 'my_option' );
 $autofix_warning = update_option( 'my_option', 'new_value', true );
 $autofix_warning = update_option( 'my_option', 'new_value', false );

From 3ca5d1fc831a37d6aab95ab5ef49a88900b48bdc Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 12 Mar 2025 10:46:55 -0300
Subject: [PATCH 05/26] Update some tests to have more function name case
 variations

---
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc      | 14 +++++++-------
 .../Tests/WP/OptionAutoloadUnitTest.inc.fixed      | 14 +++++++-------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
index cd94cbf520..b7ed143e45 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
@@ -15,16 +15,16 @@ use function add_option;
  */
 $ok = \add_option( 'my_option', 'my_value', '', true );
 $ok = add_option( 'my_option', array('some', 'big', 'array'), '', false );
-$ok = add_option( 'my_option', new stdClass(), '', null );
+$ok = ADD_OPTION( 'my_option', new stdClass(), '', null );
 $ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
 $ok = add_option( 'my_option', autoload: false );
 $ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
 $ok = \update_option( 'my_option', 'new_value', \true );
 $ok = update_option( 'my_option', 'new_value', \false );
-$ok = update_option( 'my_option', 'new_value', \NULL );
+$ok = Update_Option( 'my_option', 'new_value', \NULL );
 $ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
 $ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
-$ok = update_option( $option_name, get_option( $option_name ), false );
+$ok = update_OPTION( $option_name, get_option( $option_name ), false );
 $ok = wp_set_options_autoload( array( 'option1', 'option2' ), \false );
 $ok = wp_set_options_autoload( array( 'option1', 'option2' ), \true );
 $ok = wp_set_options_autoload( autoload: false, options: array( 'option1', 'option2' ) );
@@ -49,13 +49,13 @@ $ok = wp_set_option_autoload_values(
  * determined.
  */
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable );
-$ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
+$ignored = ADD_OPTION( 'my_option', 'my_value', '', $obj->yes );
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
-$ignored = add_option( 'my_option', 'my_value', '', 'ye' . 's' );
+$ignored = Add_Option( 'my_option', 'my_value', '', 'ye' . 's' );
 $ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
 $ignored = add_option( 'my_option', 'new_value', '', yes);
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
-$ignored = wp_set_option_autoload( 'option1', $some_variable );
+$ignored = wp_set_OPTION_autoload( 'option1', $some_variable );
 $ignored = wp_set_option_autoload_values(
     array(
         'option1' => $some_variable,
@@ -146,7 +146,7 @@ $warning = wp_set_option_autoload_values(
 
 // Incorrect function calls, should be flagged by the sniff.
 $incorrect_but_warning = add_option();
-$incorrect_but_warning = update_option();
+$incorrect_but_warning = update_OPTION();
 $incorrect_but_warning = update_option( 'my_option' );
 $incorrect_but_warning = update_option( autoloader: false, value: 'my_value', option: 'my_option' ); // Typo in the autoload parameter.
 $incorrect_but_warning = add_option( autoload: 'yes', 'my_option' );
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
index 8ba435c046..35d941af3e 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
@@ -15,16 +15,16 @@ use function add_option;
  */
 $ok = \add_option( 'my_option', 'my_value', '', true );
 $ok = add_option( 'my_option', array('some', 'big', 'array'), '', false );
-$ok = add_option( 'my_option', new stdClass(), '', null );
+$ok = ADD_OPTION( 'my_option', new stdClass(), '', null );
 $ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
 $ok = add_option( 'my_option', autoload: false );
 $ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
 $ok = \update_option( 'my_option', 'new_value', \true );
 $ok = update_option( 'my_option', 'new_value', \false );
-$ok = update_option( 'my_option', 'new_value', \NULL );
+$ok = Update_Option( 'my_option', 'new_value', \NULL );
 $ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
 $ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
-$ok = update_option( $option_name, get_option( $option_name ), false );
+$ok = update_OPTION( $option_name, get_option( $option_name ), false );
 $ok = wp_set_options_autoload( array( 'option1', 'option2' ), \false );
 $ok = wp_set_options_autoload( array( 'option1', 'option2' ), \true );
 $ok = wp_set_options_autoload( autoload: false, options: array( 'option1', 'option2' ) );
@@ -49,13 +49,13 @@ $ok = wp_set_option_autoload_values(
  * determined.
  */
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable );
-$ignored = add_option( 'my_option', 'my_value', '', $obj->yes );
+$ignored = ADD_OPTION( 'my_option', 'my_value', '', $obj->yes );
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
-$ignored = add_option( 'my_option', 'my_value', '', 'ye' . 's' );
+$ignored = Add_Option( 'my_option', 'my_value', '', 'ye' . 's' );
 $ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
 $ignored = add_option( 'my_option', 'new_value', '', yes);
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
-$ignored = wp_set_option_autoload( 'option1', $some_variable );
+$ignored = wp_set_OPTION_autoload( 'option1', $some_variable );
 $ignored = wp_set_option_autoload_values(
     array(
         'option1' => $some_variable,
@@ -146,7 +146,7 @@ $warning = wp_set_option_autoload_values(
 
 // Incorrect function calls, should be flagged by the sniff.
 $incorrect_but_warning = add_option();
-$incorrect_but_warning = update_option();
+$incorrect_but_warning = update_OPTION();
 $incorrect_but_warning = update_option( 'my_option' );
 $incorrect_but_warning = update_option( autoloader: false, value: 'my_value', option: 'my_option' ); // Typo in the autoload parameter.
 $incorrect_but_warning = add_option( autoload: true, 'my_option' );

From 5571c8e73b6d74fec03307f296bced1942da98e4 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 12 Mar 2025 11:51:40 -0300
Subject: [PATCH 06/26] Update some tests to have more whitespaces, comments
 and annotations

---
 WordPress/Tests/WP/OptionAutoloadUnitTest.inc | 29 ++++++---
 .../Tests/WP/OptionAutoloadUnitTest.inc.fixed | 29 ++++++---
 WordPress/Tests/WP/OptionAutoloadUnitTest.php | 62 +++++++++----------
 3 files changed, 75 insertions(+), 45 deletions(-)

diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
index b7ed143e45..a7917d4103 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc
@@ -19,8 +19,13 @@ $ok = ADD_OPTION( 'my_option', new stdClass(), '', null );
 $ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
 $ok = add_option( 'my_option', autoload: false );
 $ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
-$ok = \update_option( 'my_option', 'new_value', \true );
-$ok = update_option( 'my_option', 'new_value', \false );
+$ok = \update_option(    'my_option'    ,    'new_value'    ,    \true    );
+$ok = update_option(
+    'my_option',
+    'new_value',
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+    /* comment */ \false /* comment */
+);
 $ok = Update_Option( 'my_option', 'new_value', \NULL );
 $ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
 $ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
@@ -53,7 +58,12 @@ $ignored = ADD_OPTION( 'my_option', 'my_value', '', $obj->yes );
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
 $ignored = Add_Option( 'my_option', 'my_value', '', 'ye' . 's' );
 $ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
-$ignored = add_option( 'my_option', 'new_value', '', yes);
+$ignored = add_option(
+    'my_option',
+    'new_value',
+    '',
+    /* comment */ yes /* comment */
+);
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
 $ignored = wp_set_OPTION_autoload( 'option1', $some_variable );
 $ignored = wp_set_option_autoload_values(
@@ -85,7 +95,7 @@ $ignored = wp_set_option_autoload_values(options: []);
  * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing.
  */
 $ignored = wp_set_option_autoload_values();
-$ignored = wp_set_options_autoload();
+$ignored = wp_set_options_autoload( /* some comment */ );
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ) );
 $ignored = wp_set_option_autoload();
 $ignored = wp_set_option_autoload( 'option1' );
@@ -108,7 +118,7 @@ $warning = add_option( 'my_option', 'my_value', '', 'invalid_value' );
 $warning = add_option( 'my_option', 'my_value', '', 'true' );
 $warning = add_option( 'my_option', 'my_value', '', "false" );
 $warning = add_option( 'my_option', 'my_value', '', array('some', 'array') );
-$warning = add_option( 'my_option', 'my_value', '', ['some', 'array'] );
+$warning = /* comment */ add_option /* comment */ ( 'my_option', 'my_value', '', ['some', 'array'] );
 $warning = add_option( option: 'my_option' );
 $warning = add_option( value: 'my_value', option: 'my_option' );
 $warning = add_option( value: 'my_value', deprecated: '', option: 'my_option' );
@@ -117,7 +127,11 @@ $warning = add_option( 'my_option', 'my_value', '', 'YES' ); // the uppercase ve
 $warning = update_option( 'my_option', 'new_value' );
 $warning = update_option( 'my_option', 'new_value', 'auto' );
 $warning = update_option( 'my_option', 'new_value', 'auto-on' );
-$warning = update_option( 'my_option', 'new_value', 'auto-off' );
+$warning = update_option(
+    /* option name */ 'my_option',
+    'new_value' /* option value */,
+    /* autoload value */ 'auto-off' // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+);
 $warning = update_option( 'my_option', 'new_value', 'invalid_value' );
 $warning = update_option( value: 'new_value', option: 'my_option' );
 $warning = update_option( value: 'new_value', autoload: 'auto', option: 'my_option' );
@@ -128,6 +142,7 @@ $warning = wp_set_option_autoload( 'option1', 'invalid_value' );
 $warning = wp_set_option_autoload( 'option1', \NuLL );
 $warning = wp_set_option_autoload_values( ['option1' => null] );
 $warning = wp_set_option_autoload_values(
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
     [
         'option1' => '',
         'option2' => 'true',
@@ -137,7 +152,7 @@ $warning = wp_set_option_autoload_values(
         'option6' => 'YES',
         'option7' => 'invalid_value',
         'option8' => 'auto',
-        'option9' => 'auto-on',
+        'option9' /* some comment */ => /* some comment */ 'auto-on',
         'option10' => 'auto-off',
         'option11',
         /* some comment */ 'option12' /* some comment */,
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
index 35d941af3e..accac21b5a 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
@@ -19,8 +19,13 @@ $ok = ADD_OPTION( 'my_option', new stdClass(), '', null );
 $ok = add_option( 'my_option', autoload: FALSE, value: 'my_value' );
 $ok = add_option( 'my_option', autoload: false );
 $ok = add_option( autoload: false, deprecated: '', value: 'my_value', option: 'my_option' );
-$ok = \update_option( 'my_option', 'new_value', \true );
-$ok = update_option( 'my_option', 'new_value', \false );
+$ok = \update_option(    'my_option'    ,    'new_value'    ,    \true    );
+$ok = update_option(
+    'my_option',
+    'new_value',
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+    /* comment */ \false /* comment */
+);
 $ok = Update_Option( 'my_option', 'new_value', \NULL );
 $ok = update_option( 'my_option', autoload: TrUe, value: 'new_value' );
 $ok = update_option( autoload: false, value: 'my_value', option: 'my_option' );
@@ -53,7 +58,12 @@ $ignored = ADD_OPTION( 'my_option', 'my_value', '', $obj->yes );
 $ignored = add_option( 'my_option', 'my_value', '', $some_variable ? 'yes' : 'no' );
 $ignored = Add_Option( 'my_option', 'my_value', '', 'ye' . 's' );
 $ignored = add_option( 'my_option', 'my_value', '', (function () { return 'yes'; })() );
-$ignored = add_option( 'my_option', 'new_value', '', yes);
+$ignored = add_option(
+    'my_option',
+    'new_value',
+    '',
+    /* comment */ yes /* comment */
+);
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ), $some_variable );
 $ignored = wp_set_OPTION_autoload( 'option1', $some_variable );
 $ignored = wp_set_option_autoload_values(
@@ -85,7 +95,7 @@ $ignored = wp_set_option_autoload_values(options: []);
  * Invalid function calls that are ignored by the sniff as a mandatory parameter is missing.
  */
 $ignored = wp_set_option_autoload_values();
-$ignored = wp_set_options_autoload();
+$ignored = wp_set_options_autoload( /* some comment */ );
 $ignored = wp_set_options_autoload( array( 'option1', 'option2' ) );
 $ignored = wp_set_option_autoload();
 $ignored = wp_set_option_autoload( 'option1' );
@@ -108,7 +118,7 @@ $warning = add_option( 'my_option', 'my_value', '', 'invalid_value' );
 $warning = add_option( 'my_option', 'my_value', '', 'true' );
 $warning = add_option( 'my_option', 'my_value', '', "false" );
 $warning = add_option( 'my_option', 'my_value', '', array('some', 'array') );
-$warning = add_option( 'my_option', 'my_value', '', ['some', 'array'] );
+$warning = /* comment */ add_option /* comment */ ( 'my_option', 'my_value', '', ['some', 'array'] );
 $warning = add_option( option: 'my_option' );
 $warning = add_option( value: 'my_value', option: 'my_option' );
 $warning = add_option( value: 'my_value', deprecated: '', option: 'my_option' );
@@ -117,7 +127,11 @@ $warning = add_option( 'my_option', 'my_value', '', 'YES' ); // the uppercase ve
 $warning = update_option( 'my_option', 'new_value' );
 $warning = update_option( 'my_option', 'new_value', 'auto' );
 $warning = update_option( 'my_option', 'new_value', 'auto-on' );
-$warning = update_option( 'my_option', 'new_value', 'auto-off' );
+$warning = update_option(
+    /* option name */ 'my_option',
+    'new_value' /* option value */,
+    /* autoload value */ 'auto-off' // phpcs:ignore Standard.Category.Sniff -- For test reasons.
+);
 $warning = update_option( 'my_option', 'new_value', 'invalid_value' );
 $warning = update_option( value: 'new_value', option: 'my_option' );
 $warning = update_option( value: 'new_value', autoload: 'auto', option: 'my_option' );
@@ -128,6 +142,7 @@ $warning = wp_set_option_autoload( 'option1', 'invalid_value' );
 $warning = wp_set_option_autoload( 'option1', \NuLL );
 $warning = wp_set_option_autoload_values( ['option1' => null] );
 $warning = wp_set_option_autoload_values(
+    // phpcs:ignore Standard.Category.Sniff -- For test reasons.
     [
         'option1' => '',
         'option2' => 'true',
@@ -137,7 +152,7 @@ $warning = wp_set_option_autoload_values(
         'option6' => 'YES',
         'option7' => 'invalid_value',
         'option8' => 'auto',
-        'option9' => 'auto-on',
+        'option9' /* some comment */ => /* some comment */ 'auto-on',
         'option10' => 'auto-off',
         'option11',
         /* some comment */ 'option12' /* some comment */,
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.php b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
index 78b31f9b56..9cc076676a 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.php
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
@@ -36,22 +36,12 @@ public function getErrorList() {
 	 */
 	public function getWarningList() {
 		return array(
-			96  => 1,
-			97  => 1,
-			98  => 1,
-			99  => 1,
-			100 => 1,
-			105 => 1,
+			106 => 1,
 			107 => 1,
 			108 => 1,
 			109 => 1,
 			110 => 1,
-			111 => 1,
-			112 => 1,
-			113 => 1,
-			114 => 1,
 			115 => 1,
-			116 => 1,
 			117 => 1,
 			118 => 1,
 			119 => 1,
@@ -65,9 +55,7 @@ public function getWarningList() {
 			127 => 1,
 			128 => 1,
 			129 => 1,
-			132 => 1,
 			133 => 1,
-			134 => 1,
 			135 => 1,
 			136 => 1,
 			137 => 1,
@@ -77,40 +65,52 @@ public function getWarningList() {
 			141 => 1,
 			142 => 1,
 			143 => 1,
+			147 => 1,
 			148 => 1,
 			149 => 1,
 			150 => 1,
 			151 => 1,
 			152 => 1,
 			153 => 1,
+			154 => 1,
+			155 => 1,
+			156 => 1,
+			157 => 1,
 			158 => 1,
-			159 => 1,
-			160 => 1,
-			161 => 1,
-			162 => 1,
 			163 => 1,
 			164 => 1,
-			170 => 1,
+			165 => 1,
+			166 => 1,
+			167 => 1,
+			168 => 1,
+			173 => 1,
+			174 => 1,
+			175 => 1,
+			176 => 1,
 			177 => 1,
+			178 => 1,
 			179 => 1,
-			180 => 1,
-			181 => 1,
-			182 => 1,
-			183 => 1,
-			184 => 1,
 			185 => 1,
-			187 => 1,
-			188 => 1,
-			189 => 1,
-			190 => 1,
-			193 => 1,
+			192 => 1,
 			194 => 1,
 			195 => 1,
 			196 => 1,
-			201 => 1,
-			207 => 1,
+			197 => 1,
+			198 => 1,
+			199 => 1,
+			200 => 1,
+			202 => 1,
+			203 => 1,
+			204 => 1,
+			205 => 1,
+			208 => 1,
 			209 => 1,
-			212 => 1,
+			210 => 1,
+			211 => 1,
+			216 => 1,
+			222 => 1,
+			224 => 1,
+			227 => 1,
 		);
 	}
 }

From b11700f85ed8920c24e023c0380677c14d38e427 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 12 Mar 2025 14:58:53 -0300
Subject: [PATCH 07/26] Use `false === isset()` instead of `! isset()` for
 consistency with the rest of the sniff code

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index f79d1dfd09..cd85f53a05 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -347,7 +347,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 		}
 
 		if ( $param_second_token
-			&& ! isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $param_first_token ]['code'] ] )
+			&& false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $param_first_token ]['code'] ] )
 		) {
 			// Bail early if the parameter has two or more non-empty tokens and the second token is
 			// not an array opener as this means an undetermined param value or a value that is not

From d86b3416d29199f8c98415accfe1229ba53c5618 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 12 Mar 2025 14:21:59 -0300
Subject: [PATCH 08/26] Improve sniff performance by changing the format of
 some properties

This allows to use isset() instead of in_array()
---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 90 +++++++++++++--------
 1 file changed, 55 insertions(+), 35 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index cd85f53a05..647fcaa4e3 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -37,54 +37,70 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	const METRIC_NAME = 'Value of the `$autoload` parameter in the option functions';
 
 	/**
-	 * List of valid values for the `$autoload` parameter in the add_option() and update_option()
-	 * functions.
+	 * Valid values for the `$autoload` parameter in the add_option() and update_option() functions.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, string>
 	 */
-	private $valid_values_add_and_update = array( 'true', 'false', 'null' );
+	private $valid_values_add_and_update = array(
+		'true'  => 'true',
+		'false' => 'false',
+		'null'  => 'null',
+	);
 
 	/**
-	 * List of valid values for the `$autoload` parameter in the wp_set_options_autoload(),
+	 * Valid values for the `$autoload` parameter in the wp_set_options_autoload(),
 	 * wp_set_option_autoload(), and wp_set_option_autoload_values() functions.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, string>
 	 */
-	private $valid_values_other_functions = array( 'true', 'false' );
+	private $valid_values_other_functions = array(
+		'true'  => 'true',
+		'false' => 'false',
+	);
 
 	/**
-	 * List of deprecated values for the `$autoload` parameter.
+	 * Deprecated values for the `$autoload` parameter.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, true>
 	 */
-	private $deprecated_values = array( 'yes', 'no' );
+	private $deprecated_values = array(
+		'yes' => true,
+		'no'  => true,
+	);
 
 	/**
 	 * Internal-use only values for `$autoload` that cannot be fixed automatically by the sniff.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, true>
 	 */
-	private $internal_values_non_fixable = array( 'auto', 'auto-on', 'auto-off' );
+	private $internal_values_non_fixable = array(
+		'auto'     => true,
+		'auto-on'  => true,
+		'auto-off' => true,
+	);
 
 	/**
 	 * Internal-use only values for `$autoload` that can be fixed automatically by the sniff.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, true>
 	 */
-	private $internal_values_fixable = array( 'on', 'off' );
+	private $internal_values_fixable = array(
+		'on'  => true,
+		'off' => true,
+	);
 
 	/**
-	 * List of replacements for fixable values.
+	 * Replacements for fixable values.
 	 *
 	 * @since 3.2.0
 	 *
@@ -98,13 +114,16 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	);
 
 	/**
-	 * List of functions for which the `$autoload` parameter is optional.
+	 * Functions for which the `$autoload` parameter is optional.
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var string[]
+	 * @var array<string, true>
 	 */
-	private $autoload_is_optional = array( 'add_option', 'update_option' );
+	private $autoload_is_optional = array(
+		'add_option'    => true,
+		'update_option' => true,
+	);
 
 	/**
 	 * The group name for this group of functions.
@@ -277,7 +296,7 @@ private function maybe_display_missing_autoload_warning( $stackPtr, $function_na
 		$this->phpcsFile->recordMetric( $stackPtr, self::METRIC_NAME, 'param missing' );
 
 		// Only display a warning for the functions in which the `$autoload` parameter is optional.
-		if ( in_array( $function_name, $this->autoload_is_optional, true ) ) {
+		if ( isset( $this->autoload_is_optional[ $function_name ] ) ) {
 			$this->phpcsFile->addWarning(
 				'It is recommended to always pass the `$autoload` parameter when using %s() function.',
 				$stackPtr,
@@ -315,24 +334,25 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 
 		$normalized_value = strtolower( $autoload_info['clean'] );
 
-		if ( \T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code']
-			&& $param_second_token
-			&& in_array( strtolower( $this->tokens[ $param_second_token ]['content'] ), $this->valid_values_add_and_update, true )
-		) {
-			// Ensure the sniff handles correctly `true`, `false` and `null` when they are
-			// namespaced (preceded by a backslash).
-			$param_first_token  = $param_second_token;
-			$param_second_token = false;
-			$normalized_value   = substr( $normalized_value, 1 );
+		if ( \T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code'] && $param_second_token ) {
+			$token_content_lowercase = strtolower( $this->tokens[ $param_second_token ]['content'] );
+
+			if ( isset( $this->valid_values_add_and_update[ $token_content_lowercase ] ) ) {
+				// Ensure the sniff handles correctly `true`, `false` and `null` when they are
+				// namespaced (preceded by a backslash).
+				$param_first_token  = $param_second_token;
+				$param_second_token = false;
+				$normalized_value   = substr( $normalized_value, 1 );
+			}
 		}
 
-		if ( in_array( $function_name, $this->autoload_is_optional, true ) ) {
+		if ( isset( $this->autoload_is_optional[ $function_name ] ) ) {
 			$valid_values = $this->valid_values_add_and_update;
 		} else {
 			$valid_values = $this->valid_values_other_functions;
 		}
 
-		if ( in_array( $normalized_value, $valid_values, true ) ) {
+		if ( isset( $valid_values[ $normalized_value ] ) ) {
 			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, $normalized_value );
 			return;
 		}
@@ -360,7 +380,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 
 		$known_discouraged_values = array_merge( $this->deprecated_values, $this->internal_values_non_fixable, $this->internal_values_fixable );
 
-		if ( in_array( $autoload_value, $known_discouraged_values, true ) ) {
+		if ( isset( $known_discouraged_values[ $autoload_value ] ) ) {
 			$metric_value = $autoload_value;
 		} else {
 			$metric_value = 'other value';
@@ -368,15 +388,15 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 
 		$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, $metric_value );
 
-		if ( in_array( $autoload_value, $this->deprecated_values, true ) ) {
+		if ( isset( $this->deprecated_values[ $autoload_value ] ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is deprecated. Use `%s` instead.';
 			$error_code = 'Deprecated';
 			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
-		} elseif ( in_array( $autoload_value, $this->internal_values_fixable, true ) ) {
+		} elseif ( isset( $this->internal_values_fixable[ $autoload_value ] ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged. Use `%s` instead.';
 			$error_code = 'InternalUseOnly';
 			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
-		} elseif ( in_array( $autoload_value, $this->internal_values_non_fixable, true ) ) {
+		} elseif ( isset( $this->internal_values_non_fixable [ $autoload_value ] ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged.';
 			$error_code = 'InternalUseOnly';
 			$data       = array( $autoload_info['clean'] );
@@ -394,7 +414,7 @@ function ( $value ) {
 			$data                = array( $autoload_info['clean'], $valid_values_string );
 		}
 
-		if ( in_array( $autoload_value, array_keys( $this->fixable_values ), true ) ) {
+		if ( isset( $this->fixable_values[ $autoload_value ] ) ) {
 			$fix = $this->phpcsFile->addFixableWarning(
 				$message,
 				$param_first_token,

From 5ca80758df5ba59c94122baf7f5753b305dfbd34 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:32:54 -0300
Subject: [PATCH 09/26] Apply suggestions from code review

Co-authored-by: Juliette <663378+jrfnl@users.noreply.github.com>
---
 WordPress/Docs/WP/OptionAutoloadStandard.xml |  9 +++++----
 WordPress/Sniffs/WP/OptionAutoloadSniff.php  | 18 ++++++------------
 2 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
index b2520ae144..82f575b05a 100644
--- a/WordPress/Docs/WP/OptionAutoloadStandard.xml
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -7,8 +7,9 @@
     <![CDATA[
     When using `add_option()`, `update_option()`, `wp_set_options_autoload()`,
     `wp_set_option_autoload()`, or `wp_set_option_autoload_values()`, it is recommended to
-    explicitly set the autoload parameter to ensure predictable behavior. This parameter determines
-    whether the option is automatically loaded on every page load, which can impact site performance.
+    explicitly set the autoload parameter to ensure predictable behavior.
+    The autoload flag determines whether the option is automatically loaded on every page load,
+    which can impact site performance.
     ]]>
     </standard>
     <standard>
@@ -23,7 +24,7 @@
     'on', or 'off' in plugin/theme code is strongly discouraged as those values are meant for
     internal-use only.
 
-    Any other values, including `null` for functions other than `add_option()` and `update_option()`
+    Any other values, including `null` for functions other than `add_option()` and `update_option()`,
     are invalid.
     ]]>
     </standard>
@@ -75,7 +76,7 @@ wp_set_options_autoload(
     <standard>
     <![CDATA[
     Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
-    recommended to always explicitly set it.
+    strongly recommended to always explicitly set it.
     ]]>
     </standard>
     <code_comparison>
diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 647fcaa4e3..4a9af78b9f 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -240,7 +240,7 @@ private function handle_wp_set_option_autoload_values( array $options_param, $st
 		$array_token = $this->phpcsFile->findNext(
 			Tokens::$emptyTokens,
 			$options_param['start'],
-			$options_param['end'],
+			( $options_param['end'] + 1 ),
 			true
 		);
 
@@ -311,8 +311,8 @@ private function maybe_display_missing_autoload_warning( $stackPtr, $function_na
 	 *
 	 * @since 3.2.0
 	 *
-	 * @param array  $autoload_info Information about the autoload value (start and end tokens and
-	 *                              the clean value).
+	 * @param array  $autoload_info Information about the autoload value (start and end tokens,
+	 *                              the clean value and potentially the "raw" value - which isn't used).
 	 * @param string $function_name The token content (function name) which was matched
 	 *                              in lowercase.
 	 *
@@ -369,7 +369,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 		if ( $param_second_token
 			&& false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $param_first_token ]['code'] ] )
 		) {
-			// Bail early if the parameter has two or more non-empty tokens and the second token is
+			// Bail early if the parameter has two or more non-empty tokens and the first token is
 			// not an array opener as this means an undetermined param value or a value that is not
 			// easy to determine.
 			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, 'undetermined value' );
@@ -401,13 +401,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 			$error_code = 'InternalUseOnly';
 			$data       = array( $autoload_info['clean'] );
 		} else {
-			$valid_values        = array_map(
-				function ( $value ) {
-					return '`' . $value . '`';
-				},
-				$valid_values
-			);
-			$valid_values_string = implode( ', ', $valid_values );
+			$valid_values_string = '`' . implode( '`, `', $valid_values ) . '`';
 			$valid_values_string = substr_replace( $valid_values_string, ' or', strrpos( $valid_values_string, ',' ), 1 );
 			$message             = 'The use of `%s` as the value of the `$autoload` parameter is invalid. Use %s instead.';
 			$error_code          = 'InvalidValue';
@@ -422,7 +416,7 @@ function ( $value ) {
 				$data
 			);
 
-			if ( $fix ) {
+			if ( true === $fix ) {
 				$this->phpcsFile->fixer->replaceToken( $param_first_token, $this->fixable_values[ $autoload_value ] );
 			}
 

From 86740fb0151b5141cb486f8264148c1bf370410b Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:34:12 -0300
Subject: [PATCH 10/26] Remove unused parameter

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 4a9af78b9f..0d745be914 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -201,7 +201,7 @@ public function process_parameters( $stackPtr, $group_name, $function_name, $par
 		}
 
 		if ( 'wp_set_option_autoload_values' === $function_name ) {
-			$this->handle_wp_set_option_autoload_values( $target_param, $stackPtr );
+			$this->handle_wp_set_option_autoload_values( $target_param );
 			return;
 		}
 
@@ -232,11 +232,10 @@ public function process_no_parameters( $stackPtr, $group_name, $function_name )
 	 * @since 3.2.0
 	 *
 	 * @param array $options_param Options parameter information.
-	 * @param int   $stackPtr      The position of the current token in the stack.
 	 *
 	 * @return void
 	 */
-	private function handle_wp_set_option_autoload_values( array $options_param, $stackPtr ) {
+	private function handle_wp_set_option_autoload_values( array $options_param ) {
 		$array_token = $this->phpcsFile->findNext(
 			Tokens::$emptyTokens,
 			$options_param['start'],

From a9a3e8a62d352cdce1695d3af1716be0eb314d81 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:37:57 -0300
Subject: [PATCH 11/26] Rename test case file to be able to add more test case
 files with syntax errors

---
 ...tTest.inc => OptionAutoloadUnitTest.1.inc} |   0
 ...xed => OptionAutoloadUnitTest.1.inc.fixed} |   0
 WordPress/Tests/WP/OptionAutoloadUnitTest.php | 164 +++++++++---------
 3 files changed, 86 insertions(+), 78 deletions(-)
 rename WordPress/Tests/WP/{OptionAutoloadUnitTest.inc => OptionAutoloadUnitTest.1.inc} (100%)
 rename WordPress/Tests/WP/{OptionAutoloadUnitTest.inc.fixed => OptionAutoloadUnitTest.1.inc.fixed} (100%)

diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc
similarity index 100%
rename from WordPress/Tests/WP/OptionAutoloadUnitTest.inc
rename to WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed
similarity index 100%
rename from WordPress/Tests/WP/OptionAutoloadUnitTest.inc.fixed
rename to WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.php b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
index 9cc076676a..77cdc0eb44 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.php
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
@@ -32,85 +32,93 @@ public function getErrorList() {
 	/**
 	 * Returns the lines where warnings should occur.
 	 *
+	 * @param string $testFile The name of the file being tested.
+	 *
 	 * @return array<int, int> Key is the line number, value is the number of expected warnings.
 	 */
-	public function getWarningList() {
-		return array(
-			106 => 1,
-			107 => 1,
-			108 => 1,
-			109 => 1,
-			110 => 1,
-			115 => 1,
-			117 => 1,
-			118 => 1,
-			119 => 1,
-			120 => 1,
-			121 => 1,
-			122 => 1,
-			123 => 1,
-			124 => 1,
-			125 => 1,
-			126 => 1,
-			127 => 1,
-			128 => 1,
-			129 => 1,
-			133 => 1,
-			135 => 1,
-			136 => 1,
-			137 => 1,
-			138 => 1,
-			139 => 1,
-			140 => 1,
-			141 => 1,
-			142 => 1,
-			143 => 1,
-			147 => 1,
-			148 => 1,
-			149 => 1,
-			150 => 1,
-			151 => 1,
-			152 => 1,
-			153 => 1,
-			154 => 1,
-			155 => 1,
-			156 => 1,
-			157 => 1,
-			158 => 1,
-			163 => 1,
-			164 => 1,
-			165 => 1,
-			166 => 1,
-			167 => 1,
-			168 => 1,
-			173 => 1,
-			174 => 1,
-			175 => 1,
-			176 => 1,
-			177 => 1,
-			178 => 1,
-			179 => 1,
-			185 => 1,
-			192 => 1,
-			194 => 1,
-			195 => 1,
-			196 => 1,
-			197 => 1,
-			198 => 1,
-			199 => 1,
-			200 => 1,
-			202 => 1,
-			203 => 1,
-			204 => 1,
-			205 => 1,
-			208 => 1,
-			209 => 1,
-			210 => 1,
-			211 => 1,
-			216 => 1,
-			222 => 1,
-			224 => 1,
-			227 => 1,
-		);
+	public function getWarningList( $testFile = '' ) {
+		switch ( $testFile ) {
+			case 'OptionAutoloadUnitTest.1.inc':
+				return array(
+					106 => 1,
+					107 => 1,
+					108 => 1,
+					109 => 1,
+					110 => 1,
+					115 => 1,
+					117 => 1,
+					118 => 1,
+					119 => 1,
+					120 => 1,
+					121 => 1,
+					122 => 1,
+					123 => 1,
+					124 => 1,
+					125 => 1,
+					126 => 1,
+					127 => 1,
+					128 => 1,
+					129 => 1,
+					133 => 1,
+					135 => 1,
+					136 => 1,
+					137 => 1,
+					138 => 1,
+					139 => 1,
+					140 => 1,
+					141 => 1,
+					142 => 1,
+					143 => 1,
+					147 => 1,
+					148 => 1,
+					149 => 1,
+					150 => 1,
+					151 => 1,
+					152 => 1,
+					153 => 1,
+					154 => 1,
+					155 => 1,
+					156 => 1,
+					157 => 1,
+					158 => 1,
+					163 => 1,
+					164 => 1,
+					165 => 1,
+					166 => 1,
+					167 => 1,
+					168 => 1,
+					173 => 1,
+					174 => 1,
+					175 => 1,
+					176 => 1,
+					177 => 1,
+					178 => 1,
+					179 => 1,
+					185 => 1,
+					192 => 1,
+					194 => 1,
+					195 => 1,
+					196 => 1,
+					197 => 1,
+					198 => 1,
+					199 => 1,
+					200 => 1,
+					202 => 1,
+					203 => 1,
+					204 => 1,
+					205 => 1,
+					208 => 1,
+					209 => 1,
+					210 => 1,
+					211 => 1,
+					216 => 1,
+					222 => 1,
+					224 => 1,
+					227 => 1,
+				);
+
+			default:
+				return array();
+		}
 	}
 }

From 69cf0660328c5c70795f57fd4a1793d73948043b Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:41:59 -0300
Subject: [PATCH 12/26] Handle case when $array_token is false + add a test for
 it

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php     | 2 +-
 WordPress/Tests/WP/OptionAutoloadUnitTest.2.inc | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 WordPress/Tests/WP/OptionAutoloadUnitTest.2.inc

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 0d745be914..cf850c5bb6 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -243,7 +243,7 @@ private function handle_wp_set_option_autoload_values( array $options_param ) {
 			true
 		);
 
-		if ( false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $array_token ]['code'] ] ) ) {
+		if ( false === $array_token || false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $array_token ]['code'] ] ) ) {
 			// Bail if the first non-empty token in the parameter is not an array opener as this
 			// means it is not possible to determine the option names and autoload values passed to
 			// wp_set_option_autoload_values().
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.2.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.2.inc
new file mode 100644
index 0000000000..2d8b8fba02
--- /dev/null
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.2.inc
@@ -0,0 +1,8 @@
+<?php
+
+/*
+ * Intentional parse error (missing parameter value after parameter name).
+ * This should be the only test in this file.
+ */
+
+wp_set_option_autoload_values(options:);

From a07dbf3cce2df9ffb89b00f1a91e06e7eede4112 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:52:20 -0300
Subject: [PATCH 13/26] Improve sniff XML doc following suggestions from code
 review

---
 WordPress/Docs/WP/OptionAutoloadStandard.xml | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
index 82f575b05a..eb26bc2fab 100644
--- a/WordPress/Docs/WP/OptionAutoloadStandard.xml
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -20,9 +20,8 @@
     - For `wp_set_option_autoload_values()`, `wp_set_option_autoload()`, and
     `wp_set_options_autoload()`: `true` or `false`.
 
-    Using 'yes' or 'no' is deprecated since WordPress 6.6.0. Using 'auto', 'auto-on', 'auto-off',
-    'on', or 'off' in plugin/theme code is strongly discouraged as those values are meant for
-    internal-use only.
+    Using 'yes' or 'no' is deprecated since WordPress 6.6.0. Plugin/theme code should also not use
+    values for the parameter which are for WP core internal use only.
 
     Any other values, including `null` for functions other than `add_option()` and `update_option()`,
     are invalid.
@@ -31,10 +30,8 @@
     <code_comparison>
         <code title="Valid: Using a boolean value or `null`">
         <![CDATA[
-add_option(
-    'my_option',
-    'value',
-    '',
+wp_set_options_autoload(
+    array('option1', 'option2'),
     <em>true</em>
 );
 

From 06b2551fdac461729d04d53064fb2a0fa82a60d7 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 17:59:25 -0300
Subject: [PATCH 14/26] Add link to external blog post about when to use the
 autoload flag

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 1 +
 1 file changed, 1 insertion(+)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index cf850c5bb6..bc3c1b8a52 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -22,6 +22,7 @@
  * contain an invalid, internal or deprecated value.
  *
  * @link https://github.com/WordPress/WordPress-Coding-Standards/issues/2473
+ * @link https://felix-arntz.me/blog/autoloading-wordpress-options-efficiently-and-responsibly/ For more information on how to use the autoload flag.
  *
  * @since 3.2.0
  */

From 86c88b83436d8510c4af8578afedb509c997fcea Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 18:01:53 -0300
Subject: [PATCH 15/26] Add backticks to all function calls in the docblocks

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index bc3c1b8a52..805837c552 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -17,8 +17,8 @@
 use WordPressCS\WordPress\AbstractFunctionParameterSniff;
 
 /**
- * Warns when calls to add_option(), update_option(), wp_set_options_autoload(),
- * wp_set_option_autoload(), wp_set_option_autoload_values() are missing the `$autoload` param or
+ * Warns when calls to `add_option()`, `update_option()`, `wp_set_options_autoload()`,
+ * `wp_set_option_autoload()`, `wp_set_option_autoload_values()` are missing the `$autoload` param or
  * contain an invalid, internal or deprecated value.
  *
  * @link https://github.com/WordPress/WordPress-Coding-Standards/issues/2473
@@ -38,7 +38,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	const METRIC_NAME = 'Value of the `$autoload` parameter in the option functions';
 
 	/**
-	 * Valid values for the `$autoload` parameter in the add_option() and update_option() functions.
+	 * Valid values for the `$autoload` parameter in the `add_option()` and `update_option()` functions.
 	 *
 	 * @since 3.2.0
 	 *
@@ -51,8 +51,8 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	);
 
 	/**
-	 * Valid values for the `$autoload` parameter in the wp_set_options_autoload(),
-	 * wp_set_option_autoload(), and wp_set_option_autoload_values() functions.
+	 * Valid values for the `$autoload` parameter in the `wp_set_options_autoload()`,
+	 * `wp_set_option_autoload()`, and `wp_set_option_autoload_values()` functions.
 	 *
 	 * @since 3.2.0
 	 *

From b882b8e41dde052a9ec6a134fd44d89cd271dcdd Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 18:03:22 -0300
Subject: [PATCH 16/26] Rename property `valid_values_other_functions` to
 `valid_values_wp_set_option_functions`

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 805837c552..b5ec417318 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -58,7 +58,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @var array<string, string>
 	 */
-	private $valid_values_other_functions = array(
+	private $valid_values_wp_set_option_functions = array(
 		'true'  => 'true',
 		'false' => 'false',
 	);
@@ -349,7 +349,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 		if ( isset( $this->autoload_is_optional[ $function_name ] ) ) {
 			$valid_values = $this->valid_values_add_and_update;
 		} else {
-			$valid_values = $this->valid_values_other_functions;
+			$valid_values = $this->valid_values_wp_set_option_functions;
 		}
 
 		if ( isset( $valid_values[ $normalized_value ] ) ) {

From 088a6459ec665027a32e14bb480cfec21ebb7cc4 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 18:12:27 -0300
Subject: [PATCH 17/26] Explain in the docblock the array properties where all
 values are `true`

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index b5ec417318..5d22b3c5ed 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -68,7 +68,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var array<string, true>
+	 * @var array<string, true> The key is the name of the deprecated value. The array value is irrelevant.
 	 */
 	private $deprecated_values = array(
 		'yes' => true,
@@ -80,7 +80,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var array<string, true>
+	 * @var array<string, true> The key is the non-fixable value. The array value is irrelevant.
 	 */
 	private $internal_values_non_fixable = array(
 		'auto'     => true,
@@ -93,7 +93,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var array<string, true>
+	 * @var array<string, true> The key is the fixable value. The array value is irrelevant.
 	 */
 	private $internal_values_fixable = array(
 		'on'  => true,
@@ -119,7 +119,7 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @var array<string, true>
+	 * @var array<string, true> The key is the function name. The value is irrelevant.
 	 */
 	private $autoload_is_optional = array(
 		'add_option'    => true,

From 198677d46e6ec62e24598313d7a66f16beec5b84 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 18:21:20 -0300
Subject: [PATCH 18/26] Ensure all `@param array` tags explain the structure of
 the array

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 5d22b3c5ed..b22f1d1ff2 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -179,11 +179,11 @@ final class OptionAutoloadSniff extends AbstractFunctionParameterSniff {
 	 *
 	 * @since 3.2.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 $function_name The token content (function name) which was matched
-	 *                              in lowercase.
-	 * @param array  $parameters    Array with information about the parameters.
+	 * @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                                $function_name The token content (function name) which was matched
+	 *                                                             in lowercase.
+	 * @param array<int, array<string, int|string>> $parameters    Array with information about the parameters.
 	 *
 	 * @return void
 	 */
@@ -232,7 +232,7 @@ public function process_no_parameters( $stackPtr, $group_name, $function_name )
 	 *
 	 * @since 3.2.0
 	 *
-	 * @param array $options_param Options parameter information.
+	 * @param array<string, int|string> $options_param Options parameter information.
 	 *
 	 * @return void
 	 */
@@ -311,10 +311,10 @@ private function maybe_display_missing_autoload_warning( $stackPtr, $function_na
 	 *
 	 * @since 3.2.0
 	 *
-	 * @param array  $autoload_info Information about the autoload value (start and end tokens,
-	 *                              the clean value and potentially the "raw" value - which isn't used).
-	 * @param string $function_name The token content (function name) which was matched
-	 *                              in lowercase.
+	 * @param array<string, int|string> $autoload_info Information about the autoload value (start and end tokens, the
+	 *                                                 clean value and potentially the "raw" value - which isn't used).
+	 * @param string                    $function_name The token content (function name) which was matched
+	 *                                                 in lowercase.
 	 *
 	 * @return void
 	 */

From 6e18b203c02d0b833c907dc7368033860d074217 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Fri, 4 Jul 2025 18:23:02 -0300
Subject: [PATCH 19/26] Only record `param missing` metric when the autoload
 parameter is optional

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index b22f1d1ff2..c855c9d51b 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -293,10 +293,10 @@ private function handle_wp_set_option_autoload_values( array $options_param ) {
 	 * @return void
 	 */
 	private function maybe_display_missing_autoload_warning( $stackPtr, $function_name ) {
-		$this->phpcsFile->recordMetric( $stackPtr, self::METRIC_NAME, 'param missing' );
-
 		// Only display a warning for the functions in which the `$autoload` parameter is optional.
 		if ( isset( $this->autoload_is_optional[ $function_name ] ) ) {
+			$this->phpcsFile->recordMetric( $stackPtr, self::METRIC_NAME, 'param missing' );
+
 			$this->phpcsFile->addWarning(
 				'It is recommended to always pass the `$autoload` parameter when using %s() function.',
 				$stackPtr,

From 2752fffcbb17c061caf8e7a94349553de1fcca68 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 11:25:38 -0300
Subject: [PATCH 20/26] Use array union instead of `array_merge()` to create
 the list of known discouraged values

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index c855c9d51b..895e68b0ca 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -378,7 +378,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 
 		$autoload_value = TextStrings::stripQuotes( $autoload_info['clean'] );
 
-		$known_discouraged_values = array_merge( $this->deprecated_values, $this->internal_values_non_fixable, $this->internal_values_fixable );
+		$known_discouraged_values = $this->deprecated_values + $this->internal_values_non_fixable + $this->internal_values_fixable;
 
 		if ( isset( $known_discouraged_values[ $autoload_value ] ) ) {
 			$metric_value = $autoload_value;

From 1465df03bee010631cf1cab37f75847bbc56f80f Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 11:28:52 -0300
Subject: [PATCH 21/26] Use one error code for fixable internal values and
 another for non-fixable internal values

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 895e68b0ca..de0fcd4187 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -394,11 +394,11 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
 		} elseif ( isset( $this->internal_values_fixable[ $autoload_value ] ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged. Use `%s` instead.';
-			$error_code = 'InternalUseOnly';
+			$error_code = 'InternalUseOnlyOnOff';
 			$data       = array( $autoload_info['clean'], $this->fixable_values[ $autoload_value ] );
 		} elseif ( isset( $this->internal_values_non_fixable [ $autoload_value ] ) ) {
 			$message    = 'The use of `%s` as the value of the `$autoload` parameter is discouraged.';
-			$error_code = 'InternalUseOnly';
+			$error_code = 'InternalUseOnlyAuto';
 			$data       = array( $autoload_info['clean'] );
 		} else {
 			$valid_values_string = '`' . implode( '`, `', $valid_values ) . '`';

From 1975fcc0c19424e3d64fffa777b704f02dd0232d Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 11:51:09 -0300
Subject: [PATCH 22/26] Update if condition to explicitly check what is
 expected and add a test to reach that condition

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php     | 2 +-
 WordPress/Tests/WP/OptionAutoloadUnitTest.3.inc | 8 ++++++++
 WordPress/Tests/WP/OptionAutoloadUnitTest.php   | 5 +++++
 3 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 WordPress/Tests/WP/OptionAutoloadUnitTest.3.inc

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index de0fcd4187..a1b6858642 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -334,7 +334,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 
 		$normalized_value = strtolower( $autoload_info['clean'] );
 
-		if ( \T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code'] && $param_second_token ) {
+		if ( \T_NS_SEPARATOR === $this->tokens[ $param_first_token ]['code'] && is_int( $param_second_token ) ) {
 			$token_content_lowercase = strtolower( $this->tokens[ $param_second_token ]['content'] );
 
 			if ( isset( $this->valid_values_add_and_update[ $token_content_lowercase ] ) ) {
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.3.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.3.inc
new file mode 100644
index 0000000000..9e7f9a7145
--- /dev/null
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.3.inc
@@ -0,0 +1,8 @@
+<?php
+
+/*
+ * Intentional parse error (just a namespace separator as the third parameter).
+ * This should be the only test in this file.
+ */
+
+update_option('my_option', 'new_value', \);
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.php b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
index 77cdc0eb44..988dbab5ac 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.php
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
@@ -117,6 +117,11 @@ public function getWarningList( $testFile = '' ) {
 					227 => 1,
 				);
 
+			case 'OptionAutoloadUnitTest.3.inc':
+				return array(
+					8 => 1,
+				);
+
 			default:
 				return array();
 		}

From 3f728aa62528ceee12a2dbd540ee51d15edae4f6 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 13:49:45 -0300
Subject: [PATCH 23/26] Add another test without whitespaces surrounding the
 parameter to test the condition on OptionAutoloadSniff.php:247 correctly

---
 .../Tests/WP/OptionAutoloadUnitTest.1.inc     |  1 +
 .../WP/OptionAutoloadUnitTest.1.inc.fixed     |  1 +
 WordPress/Tests/WP/OptionAutoloadUnitTest.php | 34 +++++++++----------
 3 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc
index a7917d4103..7cbe4e9281 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc
@@ -84,6 +84,7 @@ $ignored = wp_set_option_autoload_values(
  * These are ignored because the option names and the autoload values can't be reliably determined
  * or the `$options` parameter is empty.
  */
+$ignored = wp_set_option_autoload_values($options);
 $ignored = wp_set_option_autoload_values( $options );
 $ignored = wp_set_option_autoload_values( options: $options );
 $ignored = wp_set_option_autoload_values(array());
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed
index accac21b5a..f5ee9e161e 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.1.inc.fixed
@@ -84,6 +84,7 @@ $ignored = wp_set_option_autoload_values(
  * These are ignored because the option names and the autoload values can't be reliably determined
  * or the `$options` parameter is empty.
  */
+$ignored = wp_set_option_autoload_values($options);
 $ignored = wp_set_option_autoload_values( $options );
 $ignored = wp_set_option_autoload_values( options: $options );
 $ignored = wp_set_option_autoload_values(array());
diff --git a/WordPress/Tests/WP/OptionAutoloadUnitTest.php b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
index 988dbab5ac..30f6208b0f 100644
--- a/WordPress/Tests/WP/OptionAutoloadUnitTest.php
+++ b/WordPress/Tests/WP/OptionAutoloadUnitTest.php
@@ -40,13 +40,12 @@ public function getWarningList( $testFile = '' ) {
 		switch ( $testFile ) {
 			case 'OptionAutoloadUnitTest.1.inc':
 				return array(
-					106 => 1,
 					107 => 1,
 					108 => 1,
 					109 => 1,
 					110 => 1,
-					115 => 1,
-					117 => 1,
+					111 => 1,
+					116 => 1,
 					118 => 1,
 					119 => 1,
 					120 => 1,
@@ -59,8 +58,8 @@ public function getWarningList( $testFile = '' ) {
 					127 => 1,
 					128 => 1,
 					129 => 1,
-					133 => 1,
-					135 => 1,
+					130 => 1,
+					134 => 1,
 					136 => 1,
 					137 => 1,
 					138 => 1,
@@ -69,7 +68,7 @@ public function getWarningList( $testFile = '' ) {
 					141 => 1,
 					142 => 1,
 					143 => 1,
-					147 => 1,
+					144 => 1,
 					148 => 1,
 					149 => 1,
 					150 => 1,
@@ -81,40 +80,41 @@ public function getWarningList( $testFile = '' ) {
 					156 => 1,
 					157 => 1,
 					158 => 1,
-					163 => 1,
+					159 => 1,
 					164 => 1,
 					165 => 1,
 					166 => 1,
 					167 => 1,
 					168 => 1,
-					173 => 1,
+					169 => 1,
 					174 => 1,
 					175 => 1,
 					176 => 1,
 					177 => 1,
 					178 => 1,
 					179 => 1,
-					185 => 1,
-					192 => 1,
-					194 => 1,
+					180 => 1,
+					186 => 1,
+					193 => 1,
 					195 => 1,
 					196 => 1,
 					197 => 1,
 					198 => 1,
 					199 => 1,
 					200 => 1,
-					202 => 1,
+					201 => 1,
 					203 => 1,
 					204 => 1,
 					205 => 1,
-					208 => 1,
+					206 => 1,
 					209 => 1,
 					210 => 1,
 					211 => 1,
-					216 => 1,
-					222 => 1,
-					224 => 1,
-					227 => 1,
+					212 => 1,
+					217 => 1,
+					223 => 1,
+					225 => 1,
+					228 => 1,
 				);
 
 			case 'OptionAutoloadUnitTest.3.inc':

From 57237b08dca838883a012eee405468201d6d5459 Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 14:18:31 -0300
Subject: [PATCH 24/26] Add a comment explaining why `null` needs special
 treatment on line 361

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index a1b6858642..701dbd2332 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -360,8 +360,17 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 		if ( in_array( $this->tokens[ $param_first_token ]['code'], array( \T_VARIABLE, \T_STRING ), true )
 			&& 'null' !== strtolower( $this->tokens[ $param_first_token ]['content'] )
 		) {
-			// Bail early if the first non-empty token in the parameter is T_VARIABLE or T_STRING as
-			// this means it is not possible to determine the value.
+			/*
+			 * Bail early if the first non-empty token in the parameter is T_VARIABLE or T_STRING as
+			 * this means it is not possible to determine the value.
+			 *
+			 * Exception for `null`: when FQN `\null` is used, PHPCS tokenizes it as T_STRING. Since
+			 * `null` is a known invalid value for the `$autoload` parameter in some functions (not
+			 * an undetermined value), we shouldn't bail in this case.
+			 *
+			 * Similar special treatment for FQN `\true` and `\false` is not needed as these values
+			 * are always valid and already handled in the condition above.
+			 */
 			$this->phpcsFile->recordMetric( $param_first_token, self::METRIC_NAME, 'undetermined value' );
 			return;
 		}

From c7bd6136cf1479fb1c4e8e25310893a1f41ee95e Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Tue, 15 Jul 2025 14:22:14 -0300
Subject: [PATCH 25/26] Explicitly check if $param_second_token is an integer

---
 WordPress/Sniffs/WP/OptionAutoloadSniff.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/WordPress/Sniffs/WP/OptionAutoloadSniff.php b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
index 701dbd2332..aa127f8926 100644
--- a/WordPress/Sniffs/WP/OptionAutoloadSniff.php
+++ b/WordPress/Sniffs/WP/OptionAutoloadSniff.php
@@ -375,7 +375,7 @@ private function check_autoload_value( array $autoload_info, $function_name ) {
 			return;
 		}
 
-		if ( $param_second_token
+		if ( is_int( $param_second_token )
 			&& false === isset( Collections::arrayOpenTokensBC()[ $this->tokens[ $param_first_token ]['code'] ] )
 		) {
 			// Bail early if the parameter has two or more non-empty tokens and the first token is

From b8f7cf69af5954173ba77f4633b2954688e420bd Mon Sep 17 00:00:00 2001
From: Rodrigo Primo <rodrigosprimo@gmail.com>
Date: Wed, 16 Jul 2025 09:52:11 -0300
Subject: [PATCH 26/26] Move the third block of the documentation up as
 suggestion during code review

---
 WordPress/Docs/WP/OptionAutoloadStandard.xml | 54 ++++++++++----------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/WordPress/Docs/WP/OptionAutoloadStandard.xml b/WordPress/Docs/WP/OptionAutoloadStandard.xml
index eb26bc2fab..4297afecb5 100644
--- a/WordPress/Docs/WP/OptionAutoloadStandard.xml
+++ b/WordPress/Docs/WP/OptionAutoloadStandard.xml
@@ -14,6 +14,33 @@
     </standard>
     <standard>
     <![CDATA[
+    Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
+    strongly recommended to always explicitly set it.
+    ]]>
+    </standard>
+    <code_comparison>
+        <code title="Valid: Explicitly setting the autoload parameter.">
+        <![CDATA[
+add_option(
+    'my_option',
+    'value',
+    '',
+    <em>true</em>
+);
+        ]]>
+        </code>
+        <code title="Invalid: Autoload parameter missing.">
+        <![CDATA[
+add_option(
+    'my_option',
+    'value',
+    ''
+);
+        ]]>
+        </code>
+    </code_comparison>
+    <standard>
+    <![CDATA[
     The following values should be used when setting the autoload parameter depending on the function:
 
     - For `add_option()` and `update_option()`: `true`, `false`, or `null`.
@@ -66,33 +93,6 @@ wp_set_option_autoload_values(
 wp_set_options_autoload(
     array('option1', 'option2'),
     <em>1</em>
-);
-        ]]>
-        </code>
-    </code_comparison>
-    <standard>
-    <![CDATA[
-    Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
-    strongly recommended to always explicitly set it.
-    ]]>
-    </standard>
-    <code_comparison>
-        <code title="Valid: Explicitly setting the autoload parameter.">
-        <![CDATA[
-add_option(
-    'my_option',
-    'value',
-    '',
-    <em>true</em>
-);
-        ]]>
-        </code>
-        <code title="Invalid: Autoload parameter missing.">
-        <![CDATA[
-add_option(
-    'my_option',
-    'value',
-    ''
 );
         ]]>
         </code>