✨ New WordPress.WP.OptionAutoload sniff

[rodrigoprimo]

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

It includes tests and sniff documentation in the XML format.

Closes #2473

Sniff behavior

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 unsupported, and a list of supported values is provided.

Open questions

I'm unsure about a few choices that I made in the XML documentation and could use some feedback on the following:

• I opted to include a link to a document explaining how to decide which value to use for the $autoload parameter. Since I could not find something wp.org, I ended up linking to a post written by a core committer in their blog. I'm not sure if this is a problem or not.
• Maybe combining the <standard> blocks for invalid, deprecated, and internal-only values in a single block would be better? I created a block for each, but there is some repetition in the block description and the valid examples.
• I added a <standard> block without code examples at the top with a general description of what the sniff does before creating blocks for each of the warnings generated by the sniff.

[dingo-d]

I opted to include a link to a document explaining how to decide which value to use for the $autoload parameter. Since I could not find something wp.org, I ended up linking to a post written by a core committer in their blog. I'm not sure if this is a problem or not.

The only problem is that that is not official documentation. And if their site goes down, you have a dead link in the documentation.

I added a block without code examples at the top with a general description of what the sniff does before creating blocks for each of the warnings generated by the sniff.

Does the validation passes against the phpcsdocs.xsd?

[rodrigoprimo]

Thanks for your review, @dingo-d and @jrfnl! I believe I addressed all of your comments except two that are still pending, and I will need a bit more time (https://github.com/WordPress/WordPress-Coding-Standards/pull/2520#discussion_r1974686099 and https://github.com/WordPress/WordPress-Coding-Standards/pull/2520#discussion_r1974641122).

The only problem is that that is not official documentation. And if their site goes down, you have a dead link in the documentation.

That makes sense. As @jrfnl suggested, I removed the paragraph that included this link.

Does the validation passes against the phpcsdocs.xsd?

I believe so. This is how I tested:

$ xmllint --schema phpcsdocs.xsd WordPress/Docs/WP/OptionAutoloadStandard.xml --noout 
WordPress/Docs/WP/OptionAutoloadStandard.xml validates

Let me know if I'm missing something.

[rodrigoprimo]

@jrfnl, I addressed the two points that were pending. Could you please take another look at this PR when you get a chance?

[rodrigoprimo]

Thanks for taking another look at this PR, @jrfnl. I started replying to your feedback and implementing the changes, but I was unable to finish everything today. I won't be able to look into this next week. The following week, I will address the comments that I was unable to address today.

[rodrigoprimo]

Rebased without changes to fix an unrelated failing test. 39524bc is the first commit addressing the latest feedback.

[rodrigoprimo]

@jrfnl, thanks again for your review! I finished addressing all the comments that I was not able to address before, and now this PR is ready for another review. Just a reminder that https://github.com/WordPress/WordPress-Coding-Standards/commit/39524bc37f657edf83458776eb801e8a818f40a0 is the first commit addressing the latest feedback, as I had to rebase without changes to fix an unrelated failing test.

Also, just noting here that I had to force push the last commit as the build was failing due to a temporary PHPStan error. Documenting here in case we start seeing this error more often (https://github.com/rodrigoprimo/WordPress-Coding-Standards/actions/runs/16300169675/job/46032411241):

==> Setup Tools
✓ composer Added composer 2.8.10
✗ phpstan 403: rate limit exceeded

[rodrigoprimo]

What about moving it into the condition ?

Regarding the comment quoted above, I'm not sure why I cannot reply directly to it, but it was addressed, and now the param missing metric will only be recorded for add_option() and update_option().

[rodrigoprimo]

This will need to be updated to work on PHPCS 4.0 before it is reviewed again.