From 65a442fbcd370e395be94fe0aa3e824225f7edc5 Mon Sep 17 00:00:00 2001
From: Felix Arntz <felix-arntz@leaves-and-love.net>
Date: Mon, 7 Aug 2023 19:33:32 +0000
Subject: [PATCH] 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.

Built from https://develop.svn.wordpress.org/trunk@56370


git-svn-id: http://core.svn.wordpress.org/trunk@55882 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/option.php  | 16 +++++++++++++---
 wp-includes/version.php |  2 +-
 2 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/wp-includes/option.php b/wp-includes/option.php
index be68945d61..abeb0ae2f7 100644
--- a/wp-includes/option.php
+++ b/wp-includes/option.php
@@ -428,8 +428,13 @@ function wp_load_core_site_options( $network_id = null ) {
  * @param mixed       $value    Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
  * @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.
  */
 function update_option( $option, $value, $autoload = null ) {
@@ -615,7 +620,12 @@ function update_option( $option, $value, $autoload = null ) {
  *                                Expected to not be SQL-escaped.
  * @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.
  */
 function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 810ed10703..a73594e0e1 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.4-alpha-56365';
+$wp_version = '6.4-alpha-56370';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.