Skip to content

Commit f384fb0

Browse files
rodrigoprimorodrigoprimo
committed
✨ New WordPress.WP.OptionAutoload sniff
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.
1 parent 38c0039 commit f384fb0

File tree

6 files changed

+1102
-0
lines changed

6 files changed

+1102
-0
lines changed

‎WordPress-Extra/ruleset.xml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,13 @@
192192
https://github.com/WordPress/WordPress-Coding-Standards/issues/2459 -->
193193
<rule ref="WordPress.WP.GetMetaSingle"/>
194194

195+
<!-- Flags calls to add_option(), update_option(), wp_set_options_autoload(),
196+
wp_set_option_autoload(), wp_set_option_autoload_values() functions when the
197+
`$autoload` parameter is missing or contain an invalid, internal-only or
198+
deprecated value.
199+
https://github.com/WordPress/WordPress-Coding-Standards/issues/2473 -->
200+
<rule ref="WordPress.WP.OptionAutoload"/>
201+
195202
<!--
196203
#############################################################################
197204
Code style sniffs for more recent PHP features and syntaxes.

‎WordPress/Docs/WP/OptionAutoloadStandard.xml

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
<?xml version="1.0"?>
2+
<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
3+
xsi:noNamespaceSchemaLocation="https://phpcsstandards.github.io/PHPCSDevTools/phpcsdocs.xsd"
4+
title="Option Autoload"
5+
>
6+
<standard>
7+
<![CDATA[
8+
When using `add_option()`, `update_option()`, `wp_set_options_autoload()`,
9+
`wp_set_option_autoload()`, or `wp_set_option_autoload_values()`, it is recommended to
10+
explicitly set the autoload value to ensure predictable behavior. This value determines whether
11+
the option is automatically loaded on every page load, which can impact site performance.
12+
13+
Check https://felix-arntz.me/blog/autoloading-wordpress-options-efficiently-and-responsibly/ for
14+
more information on when to set autoload to `true` or `false`.
15+
]]>
16+
</standard>
17+
<standard>
18+
<![CDATA[
19+
Even though the autoload parameter is optional for `add_option()` and `update_option()`, it is
20+
recommended to always explicitly set it.
21+
]]>
22+
</standard>
23+
<code_comparison>
24+
<code title="Valid: Explicitly setting the autoload parameter.">
25+
<![CDATA[
26+
add_option(
27+
'my_option',
28+
'value',
29+
'',
30+
<em>true</em>
31+
);
32+
]]>
33+
</code>
34+
<code title="Invalid: Autoload parameter missing.">
35+
<![CDATA[
36+
add_option(
37+
'my_option',
38+
'value',
39+
''
40+
);
41+
]]>
42+
</code>
43+
</code_comparison>
44+
<standard>
45+
<![CDATA[
46+
Using 'yes' or 'no' is not recommended. Those values are deprecated. Instead, use
47+
`true`|`false`|`null` if using `add_option()` or `update_option()` or `true`|`false` if using
48+
`wp_set_option_autoload_values()`, `wp_set_option_autoload()`, or `wp_set_options_autoload()`.
49+
]]>
50+
</standard>
51+
<code_comparison>
52+
<code title="Valid: Using boolean values.">
53+
<![CDATA[
54+
update_option(
55+
'my_option',
56+
'value',
57+
<em>true</em>
58+
);
59+
]]>
60+
</code>
61+
<code title="Invalid: Using deprecated values.">
62+
<![CDATA[
63+
update_option(
64+
'my_option',
65+
'value',
66+
<em>'yes'</em>
67+
);
68+
]]>
69+
</code>
70+
</code_comparison>
71+
<standard>
72+
<![CDATA[
73+
It is not recommended to use internal-only values ('auto', 'auto-on', 'auto-off', 'on', 'off')
74+
in plugin or theme code. Instead, use `true`|`false`|`null` if using `add_option()` or
75+
`update_option()` or `true`|`false` if using `wp_set_option_autoload_values()`,
76+
`wp_set_option_autoload()`, or `wp_set_options_autoload()`.
77+
]]>
78+
</standard>
79+
<code_comparison>
80+
<code title="Valid: Using boolean values.">
81+
<![CDATA[
82+
wp_set_option_autoload_values(
83+
array(
84+
'my_option_1' => <em>true</em>,
85+
'my_option_2' => <em>false</em>
86+
)
87+
);
88+
]]>
89+
</code>
90+
<code title="Invalid: Using internal-only values.">
91+
<![CDATA[
92+
wp_set_option_autoload_values(
93+
array(
94+
'my_option_1' => <em>'auto-on'</em>,
95+
'my_option_2' => <em>'auto-off'</em>
96+
)
97+
);
98+
]]>
99+
</code>
100+
</code_comparison>
101+
<standard>
102+
<![CDATA[
103+
Only `true` and `false` are valid values for the autoload parameter, with one exception: `null`
104+
is also valid for `add_option()` and `update_option()`.
105+
]]>
106+
</standard>
107+
<code_comparison>
108+
<code title="Valid: Using `true`, `false`, or `null`.">
109+
<![CDATA[
110+
wp_set_options_autoload(
111+
array( 'my_option_1', 'my_option_2' ),
112+
<em>false</em>
113+
);
114+
115+
wp_set_option_autoload(
116+
'my_option',
117+
<em>false</em>
118+
);
119+
]]>
120+
</code>
121+
<code title="Invalid: Using invalid values.">
122+
<![CDATA[
123+
wp_set_options_autoload(
124+
array( 'my_option_1', 'my_option_2' ),
125+
<em>1</em>
126+
);
127+
128+
wp_set_option_autoload(
129+
'my_option',
130+
<em>null</em> // `null` is invalid for this function.
131+
);
132+
]]>
133+
</code>
134+
</code_comparison>
135+
</documentation>

0 commit comments

Comments
 (0)