Add Autoloaded_Options_Check for missing $autoload parameter

docs/checks.md

@@ -36,4 +36,5 @@
 | enqueued_styles_scope | performance | Checks whether any stylesheets are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | enqueued_scripts_scope | performance | Checks whether any scripts are loaded on all pages, which is usually not desirable and can lead to performance issues. | [Learn more](https://developer.wordpress.org/plugins/) |
 | non_blocking_scripts | performance | Checks whether scripts and styles are enqueued using a recommended loading strategy. | [Learn more](https://developer.wordpress.org/plugins/) |
+| autoloaded_options | performance | Warns when <code>add_option()</code> or <code>update_option()</code> are called without explicitly setting the <code>$autoload</code> parameter. | [Learn more](https://developer.wordpress.org/reference/functions/add_option/) |
 | ai_provider | general | Recommends the WordPress AI Client when a plugin integrates directly with a third-party AI provider. | [Learn more](https://developer.wordpress.org/plugins/) |

includes/Checker/Checks/Performance/Autoloaded_Options_Check.php

@@ -0,0 +1,78 @@
+<?php
+/**
+ * Class Autoloaded_Options_Check.
+ *
+ * @package plugin-check
+ */
+
+namespace WordPress\Plugin_Check\Checker\Checks\Performance;
+
+use WordPress\Plugin_Check\Checker\Check_Categories;
+use WordPress\Plugin_Check\Checker\Check_Result;
+use WordPress\Plugin_Check\Checker\Checks\Abstract_PHP_CodeSniffer_Check;
+use WordPress\Plugin_Check\Traits\Stable_Check;
+
+/**
+ * Check to detect missing $autoload parameter on add_option() / update_option().
+ *
+ * @since 2.1.0
+ */
+class Autoloaded_Options_Check extends Abstract_PHP_CodeSniffer_Check {
+
+	use Stable_Check;
+
+	/**
+	 * Gets the categories for the check.
+	 *
+	 * Every check must have at least one category.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return array The categories for the check.
+	 */
+	public function get_categories() {
+		return array( Check_Categories::CATEGORY_PERFORMANCE );
+	}
+
+	/**
+	 * Returns an associative array of arguments to pass to PHPCS.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param Check_Result $result The check result to amend, including the plugin context to check.
+	 * @return array An associative array of PHPCS CLI arguments.
+	 */
+	protected function get_args( Check_Result $result ) {
+		return array(
+			'extensions' => 'php',
+			'standard'   => 'PluginCheck',
+			'sniffs'     => 'PluginCheck.CodeAnalysis.AutoLoadedOptions',
+		);
+	}
+
+	/**
+	 * Gets the description for the check.
+	 *
+	 * Every check must have a short description explaining what the check does.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return string Description.
+	 */
+	public function get_description(): string {
+		return __( 'Warns when add_option() or update_option() are called without explicitly setting the $autoload parameter.', 'plugin-check' );
+	}
+
+	/**
+	 * Gets the documentation URL for the check.
+	 *
+	 * Every check must have a URL with further information about the check.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @return string The documentation URL.
+	 */
+	public function get_documentation_url(): string {
+		return __( 'https://developer.wordpress.org/reference/functions/add_option/', 'plugin-check' );
+	}
+}

includes/Checker/Default_Check_Repository.php

@@ -104,6 +104,7 @@ private function register_default_checks() {
 				'direct_file_access'         => new Checks\Plugin_Repo\Direct_File_Access_Check(),
 				'external_admin_menu_links'  => new Checks\Plugin_Repo\External_Admin_Menu_Links_Check(),
 				'wp_functions_compatibility' => new Checks\Plugin_Repo\WP_Functions_Compatibility_Check(),
+				'autoloaded_options'         => new Checks\Performance\Autoloaded_Options_Check(),
 				'ai_provider'                => new Checks\General\AI_Provider_Check(),
 			)
 		);

phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php

@@ -0,0 +1,101 @@
+<?php
+/**
+ * AutoLoadedOptionsSniff
+ *
+ * Based on code from {@link https://github.com/WordPress/WordPress-Coding-Standards}
+ * which is licensed under {@link https://opensource.org/licenses/MIT}.
+ *
+ * @package PluginCheck
+ */
+
+namespace PluginCheckCS\PluginCheck\Sniffs\CodeAnalysis;
+
+use PHPCSUtils\Utils\MessageHelper;
+use PHPCSUtils\Utils\PassedParameters;
+use WordPressCS\WordPress\AbstractFunctionParameterSniff;
+
+/**
+ * Warns when add_option() / update_option() are called without explicitly
+ * setting the $autoload parameter.
+ *
+ * The default value of $autoload is true, which loads the option on every
+ * page request. Plugins that accumulate autoloaded options slow down every
+ * request. Letting the author choose explicitly is the goal.
+ *
+ * @link https://developer.wordpress.org/reference/functions/add_option/
+ * @link https://developer.wordpress.org/reference/functions/update_option/
+ *
+ * @since 2.1.0
+ */
+final class AutoLoadedOptionsSniff extends AbstractFunctionParameterSniff {
+
+	/**
+	 * Position of the $autoload parameter for each target function.
+	 *
+	 * Add_option() is `add_option( $option, $value, $deprecated, $autoload )`.
+	 * Update_option() is `update_option( $option, $value, $autoload )`.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @var array<string, int>
+	 */
+	protected $autoload_positions = array(
+		'add_option'    => 4,
+		'update_option' => 3,
+	);
+
+	/**
+	 * List of functions to examine.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @var array<string, true>
+	 */
+	protected $target_functions = array(
+		'add_option'    => true,
+		'update_option' => true,
+	);
+
+	/**
+	 * Processes this test, when one of its tokens is encountered.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param int $stackPtr The position of the current token in the stack.
+	 * @return int|void Integer stack pointer to skip forward or void to continue normal file processing.
+	 */
+	public function process_token( $stackPtr ) {
+		if ( isset( $this->target_functions[ strtolower( $this->tokens[ $stackPtr ]['content'] ) ] ) ) {
+			$this->exclude = array();
+
+			return parent::process_token( $stackPtr );
+		}
+	}
+
+	/**
+	 * Process the parameters of a matched function call.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param int    $stackPtr        The position of the current token in the stack.
+	 * @param string $group_name      The name of the group which was matched.
+	 * @param string $matched_content The token content (function name) which was matched in lowercase.
+	 * @param array  $parameters      Array with information about the parameters.
+	 * @return void
+	 */
+	public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
+		$position = $this->autoload_positions[ $matched_content ];
+		$found    = PassedParameters::getParameterFromStack( $parameters, $position, 'autoload' );
+
+		if ( false === $found ) {
+			$error_code = MessageHelper::stringToErrorcode( $matched_content . '_autoload', true );
+
+			$this->phpcsFile->addWarning(
+				'The $autoload parameter for %s() is not explicitly set; the option will default to autoloading on every page request. Pass an explicit boolean (true or false) to make the performance trade-off intentional.',
+				$stackPtr,
+				$error_code . 'Missing',
+				array( $matched_content )
+			);
+		}
+	}
+}

phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc

@@ -0,0 +1,28 @@
+<?php
+
+// Bad: add_option() with no $autoload.
+add_option( 'no_autoload_a' ); // Warning.
+
+// Bad: add_option() with only $value set.
+add_option( 'no_autoload_b', 'value' ); // Warning.
+
+// Bad: add_option() with only $deprecated set.
+add_option( 'no_autoload_c', 'value', '' ); // Warning.
+
+// Bad: update_option() with no $autoload.
+update_option( 'no_autoload_d' ); // Warning.
+
+// Bad: update_option() with only $value set.
+update_option( 'no_autoload_e', 'value' ); // Warning.
+
+// Good: add_option() with explicit autoload = false.
+add_option( 'autoload_false_a', 'value', '', false );
+
+// Good: add_option() with explicit autoload = true.
+add_option( 'autoload_true_a', 'value', '', true );
+
+// Good: update_option() with explicit autoload = false.
+update_option( 'autoload_false_b', 'value', false );
+
+// Good: update_option() with explicit autoload = true.
+update_option( 'autoload_true_b', 'value', true );

phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php

@@ -0,0 +1,61 @@
+<?php
+/**
+ * Unit tests for AutoLoadedOptionsSniff.
+ *
+ * @package PluginCheck
+ */
+
+namespace PluginCheckCS\PluginCheck\Tests\CodeAnalysis;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PluginCheckCS\PluginCheck\Sniffs\CodeAnalysis\AutoLoadedOptionsSniff;
+use PluginCheckCS\PluginCheck\Tests\AbstractSniffUnitTest;
+
+/**
+ * Unit tests for AutoLoadedOptionsSniff.
+ */
+final class AutoLoadedOptionsUnitTest extends AbstractSniffUnitTest {
+
+	/**
+	 * Returns the lines where errors should occur.
+	 *
+	 * @return array <int line number> => <int number of errors>
+	 */
+	public function getErrorList() {
+		return array();
+	}
+
+	/**
+	 * Returns the lines where warnings should occur.
+	 *
+	 * @return array <int line number> => <int number of warnings>
+	 */
+	public function getWarningList() {
+		return array(
+			4  => 1,
+			7  => 1,
+			10 => 1,
+			13 => 1,
+			16 => 1,
+		);
+	}
+
+	/**
+	 * Returns the fully qualified class name (FQCN) of the sniff.
+	 *
+	 * @return string The fully qualified class name of the sniff.
+	 */
+	protected function get_sniff_fqcn() {
+		return AutoLoadedOptionsSniff::class;
+	}
+
+	/**
+	 * Sets the parameters for the sniff.
+	 *
+	 * @throws \RuntimeException If unable to set the ruleset parameters required for the test.
+	 *
+	 * @param Sniff $sniff The sniff being tested.
+	 */
+	public function set_sniff_parameters( Sniff $sniff ) {
+	}
+}

phpcs-sniffs/PluginCheck/ruleset.xml

@@ -4,6 +4,7 @@
 	<description>Plugin Check Sniffs</description>
 
 	<rule ref="PluginCheck.CodeAnalysis.AIProvider" />
+	<rule ref="PluginCheck.CodeAnalysis.AutoLoadedOptions" />
 	<rule ref="PluginCheck.CodeAnalysis.DiscouragedFunctions" />
 	<rule ref="PluginCheck.CodeAnalysis.EnqueuedResourceOffloading" />
 	<rule ref="PluginCheck.CodeAnalysis.Heredoc" />

tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Plugin Name: Test Plugin Autoloaded Options check with errors
+ * Plugin URI: https://github.com/WordPress/plugin-check
+ * Description: Test plugin for the Autoloaded Options check.
+ * Requires at least: 6.0
+ * Requires PHP: 5.6
+ * Version: 1.0.0
+ * Author: WordPress Performance Team
+ * Author URI: https://make.wordpress.org/performance/
+ * License: GPLv2 or later
+ * License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * Text Domain: test-plugin-autoloaded-options-check-with-errors
+ *
+ * @package test-plugin-autoloaded-options-check-with-errors
+ */
+
+// add_option without $autoload.
+add_option( 'autoloaded_with_errors_a' );
+
+// add_option with $value but no $autoload.
+add_option( 'autoloaded_with_errors_b', 'value' );
+
+// update_option without $autoload.
+update_option( 'autoloaded_with_errors_c' );
+
+// update_option with $value but no $autoload.
+update_option( 'autoloaded_with_errors_d', 'value' );

tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php

@@ -0,0 +1,28 @@
+<?php
+/**
+ * Plugin Name: Test Plugin Autoloaded Options check without errors
+ * Plugin URI: https://github.com/WordPress/plugin-check
+ * Description: Test plugin for the Autoloaded Options check (clean fixture).
+ * Requires at least: 6.0
+ * Requires PHP: 5.6
+ * Version: 1.0.0
+ * Author: WordPress Performance Team
+ * Author URI: https://make.wordpress.org/performance/
+ * License: GPLv2 or later
+ * License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html
+ * Text Domain: test-plugin-autoloaded-options-check-without-errors
+ *
+ * @package test-plugin-autoloaded-options-check-without-errors
+ */
+
+// add_option with explicit autoload = false.
+add_option( 'autoloaded_without_errors_a', 'value', '', false );
+
+// add_option with explicit autoload = true.
+add_option( 'autoloaded_without_errors_b', 'value', '', true );
+
+// update_option with explicit autoload = false.
+update_option( 'autoloaded_without_errors_c', 'value', false );
+
+// update_option with explicit autoload = true.
+update_option( 'autoloaded_without_errors_d', 'value', true );