Add Autoloaded_Options_Check for missing $autoload parameter by faisalahammad · Pull Request #1413 · WordPress/plugin-check

faisalahammad · 2026-07-26T02:34:54Z

What?

Closes #28

Adds a new check, autoloaded_options, that warns plugin authors when add_option() or update_option() is called without explicitly setting the $autoload parameter.

Why?

When the $autoload parameter is omitted, WordPress determines the value based on the WordPress version and whether the option already exists. This implicit decision can lead to options being loaded on every page request, which can bloat the alloptions row and slow down requests. Letting the author choose explicitly makes the performance trade-off intentional.

How?

Custom PHPCS sniff PluginCheck.CodeAnalysis.AutoLoadedOptions that wraps AbstractFunctionParameterSniff. The sniff targets the two call sites (the $autoload parameter sits at position 4 on add_option after a deprecated arg, and at position 3 on update_option). Calls without an explicit $autoload produce a single warning per call site; an explicit boolean true or false is left untouched, including the WP 6.6+ recommendation to pass boolean autoload instead of 'yes'/'no' strings.

A new check class Autoloaded_Options_Check registers the sniff under the performance category. It is wired into Default_Check_Repository under the autoloaded_options slug.

Files touched:

phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php (new sniff)
phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.{inc,php} (sniff unit test)
phpcs-sniffs/PluginCheck/ruleset.xml (registers the new rule)
includes/Checker/Checks/Performance/Autoloaded_Options_Check.php (check class)
includes/Checker/Default_Check_Repository.php (registration)
docs/checks.md (new row)
tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-{with,without}-errors/load.php (PHPUnit fixtures)
tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php (PHPUnit integration test)

Testing Instructions

Apply the patch and activate plugin-check in a WordPress install.
Run wp plugin-check list-checks and confirm autoloaded_options is listed in the performance category.

Create a test plugin containing both forms below and run wp plugin-check check <plugin> on it.

Triggers a warning:

add_option( 'opt_a' );
add_option( 'opt_b', 'value' );
update_option( 'opt_c' );
update_option( 'opt_d', 'value' );

Clean (no warning):

add_option( 'opt_a', 'value', '', false );
add_option( 'opt_b', 'value', '', true );
update_option( 'opt_c', 'value', false );
update_option( 'opt_d', 'value', true );

Verify four warnings appear on the first plugin (codes PluginCheck.CodeAnalysis.AutoLoadedOptions.add_option_autoloadMissing and PluginCheck.CodeAnalysis.AutoLoadedOptions.update_option_autoloadMissing) and zero autoloaded_options results on the second.

Automated tests:

composer test runs the PHPUnit integration tests against both fixtures.
Sniff unit test runs via cd phpcs-sniffs && php vendor/bin/phpunit vendor/squizlabs/php_codesniffer/tests/AllTests.php --filter AutoLoadedOptions --no-coverage.

AI Usage Disclosure

This PR was created without the help of AI tools
This PR includes AI-assisted code or content

If AI tools were used, please describe how they were used:
Used Claude Code for code generation, refactoring and documentation drafting under direction of maintainer.

Warns when add_option() or update_option() is called without explicitly setting the $autoload parameter. The option then defaults to autoloading on every page request, which bloats the alloptions row and slows down every request. The check runs a new PluginCheck.CodeAnalysis.AutoLoadedOptions sniff that flags calls where $autoload is not passed. Calls with an explicit boolean are left alone.

github-actions · 2026-07-26T02:35:05Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: faisalahammad <faisalahammad@git.wordpress.org>
Co-authored-by: swissspidy <swissspidy@git.wordpress.org>
Co-authored-by: davidperezgar <davidperez@git.wordpress.org>
Co-authored-by: mukeshpanchal27 <mukesh27@git.wordpress.org>
Co-authored-by: vishalkakadiya <vishalkakadiya@git.wordpress.org>
Co-authored-by: mehulkaklotar <mehulkaklotar@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

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

swissspidy · 2026-07-26T06:54:19Z

Would be nice to make some progress on WordPress/WordPress-Coding-Standards#2520 first, which would simplify things here.

davidperezgar · 2026-07-26T09:50:14Z

Yes, that seems reasonable.

faisalahammad · 2026-07-26T11:04:49Z

Thank you, @swissspidy and @davidperezgar.

It looks like multiple contributors are working on this: WordPress/WordPress-Coding-Standards#2520.

Should I close this PR?

mukeshpanchal27 · 2026-07-27T05:02:08Z

@faisalahammad I just left a comment on the WPCS PR. Let's see how they respond.

Copilot

Copilot review overview

🟡 Changes recommended

The sniff documentation and user-facing warning incorrectly state that every omitted autoload argument defaults to autoloading.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

Incorrectly claims omitted autoload defaults to true · New

What changed in this PR

Adds a performance check warning when WordPress option APIs omit the $autoload argument.

Changes:

Adds and registers the AutoLoadedOptions PHPCS sniff.
Integrates the stable autoloaded_options check.
Adds documentation, fixtures, and automated tests.

File	Description
`phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php`	Detects omitted autoload arguments.
`phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.inc`	Provides sniff fixtures.
`phpcs-sniffs/PluginCheck/Tests/CodeAnalysis/AutoLoadedOptionsUnitTest.php`	Defines expected sniff warnings.
`phpcs-sniffs/PluginCheck/ruleset.xml`	Registers the sniff.
`includes/Checker/Checks/Performance/Autoloaded_Options_Check.php`	Exposes the performance check.
`includes/Checker/Default_Check_Repository.php`	Registers the default check.
`docs/checks.md`	Documents the check.
`tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-with-errors/load.php`	Adds warning-producing fixtures.
`tests/phpunit/testdata/plugins/test-plugin-autoloaded-options-check-without-errors/load.php`	Adds clean fixtures.
`tests/phpunit/tests/Checker/Checks/Autoloaded_Options_Check_Tests.php`	Tests check integration.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

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

faisalahammad · 2026-09-21T17:06:16Z

@swissspidy I kept this PR open and fixed the accuracy issue independently. WPCS PR #2520 is still a draft and depends on PHPCS 4.0. This change keeps the current check and corrects its wording for WordPress 6.6+ behavior.

faisalahammad requested review from adamsilverstein, felixarntz, joemcgill, mukeshpanchal27, swissspidy and westonruter as code owners July 26, 2026 02:34

ernilambar requested a balanced review from Copilot September 21, 2026 16:07

Copilot started reviewing on behalf of ernilambar September 21, 2026 16:08 View session

Copilot AI reviewed Sep 21, 2026

View reviewed changes

Comment thread phpcs-sniffs/PluginCheck/Sniffs/CodeAnalysis/AutoLoadedOptionsSniff.php Outdated

Navigation Menu

Add Autoloaded_Options_Check for missing $autoload parameter - #1413

Add Autoloaded_Options_Check for missing $autoload parameter#1413
faisalahammad wants to merge 3 commits into
WordPress:trunkfrom
faisalahammad:fix/28-autoloaded-options-check

faisalahammad commented Jul 26, 2026 •

edited by github-actions Bot

Loading

Uh oh!

github-actions Bot commented Jul 26, 2026 •

edited

Loading

Uh oh!

swissspidy commented Jul 26, 2026

Uh oh!

davidperezgar commented Jul 26, 2026

Uh oh!

faisalahammad commented Jul 26, 2026

Uh oh!

mukeshpanchal27 commented Jul 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

faisalahammad commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

faisalahammad commented Jul 26, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

AI Usage Disclosure

Uh oh!

github-actions Bot commented Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swissspidy commented Jul 26, 2026

Uh oh!

davidperezgar commented Jul 26, 2026

Uh oh!

faisalahammad commented Jul 26, 2026

Uh oh!

mukeshpanchal27 commented Jul 27, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

faisalahammad commented Sep 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

faisalahammad commented Jul 26, 2026 •

edited by github-actions Bot

Loading

github-actions Bot commented Jul 26, 2026 •

edited

Loading