Changeset 56370

Timestamp:

08/07/2023 07:31:13 PM (16 months ago)

Author:

flixos90

Message:

Options, Meta APIs: Expand $autoload parameter documentation.

This changeset expands documentation of the $autoload parameter of the add_option() and update_option() functions, in order to provide more context on what autoloading is and which considerations should go into the decision whether to autoload an option.

Excessive autoloading of options can lead to severe performance problems on some sites, and lack of documentation is a partial cause for the issue.

Props rajinsharwar.
Fixes #58963.

File:

• trunk/src/wp-includes/option.php (modified) (2 diffs)

trunk/src/wp-includes/option.php

@@ -429 +429 @@
  * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options,
  *                              `$autoload` can only be updated using `update_option()` if `$value` is also changed.
- *                              Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options,
- *                              the default value is 'yes'. Default null.
+ *                              Accepts 'yes'|true to enable or 'no'|false to disable.
+ *                              Autoloading too many options can lead to performance problems, especially if the
+ *                              options are not frequently used. For options which are accessed across several places
+ *                              in the frontend, it is recommended to autoload them, by using 'yes'|true.
+ *                              For options which are accessed only on few specific URLs, it is recommended
+ *                              to not autoload them, by using 'no'|false. For non-existent options, the default value
+ *                              is 'yes'. Default null.
  * @return bool True if the value was updated, false otherwise.
  */
@@ -616 +621 @@
  * @param string      $deprecated Optional. Description. Not used anymore.
  * @param string|bool $autoload   Optional. Whether to load the option when WordPress starts up.
- *                                Default is enabled. Accepts 'no' to disable for legacy reasons.
+ *                                Accepts 'yes'|true to enable or 'no'|false to disable.
+ *                                Autoloading too many options can lead to performance problems, especially if the
+ *                                options are not frequently used. For options which are accessed across several places
+ *                                in the frontend, it is recommended to autoload them, by using 'yes'|true.
+ *                                For options which are accessed only on few specific URLs, it is recommended
+ *                                to not autoload them, by using 'no'|false. Default 'yes'.
  * @return bool True if the option was added, false otherwise.
  */