Changeset 58949

Timestamp:

08/28/2024 10:46:27 PM (5 months ago)

Author:

flixos90

Message:

Options, Meta APIs: Soft-deprecate use of 'yes' and 'no' as $autoload parameter.

WordPress 6.6 option autoload enhancements included discouraging the use of 'yes' and 'no' to indicate whether to autoload an option when calling add_option() or update_option(). Instead, a boolean should be used.

This changeset brings the newer autoload related functions wp_set_option_autoload_values(), wp_set_options_autoload(), and wp_set_option_autoload() in line with those changes. Additionally, it soft-deprecates the values more formally, as they should no longer be used. No PHP warnings will be emitted though as this is not a hard deprecation. This change is purely about documentation.

Props flixos90, joemcgill, jrf, mukesh27.
Fixes #61929.
See #61103, #61939.

File:

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

trunk/src/wp-includes/option.php

@@ -376 +376 @@
  *
  * @since 6.4.0
+ * @since 6.7.0 The autoload values 'yes' and 'no' are deprecated.
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param array $options Associative array of option names and their autoload values to set. The option names are
- *                       expected to not be SQL-escaped. The autoload values accept 'yes'|true to enable or 'no'|false
- *                       to disable.
+ *                       expected to not be SQL-escaped. The autoload values should be boolean values. For backward
+ *                       compatibility 'yes' and 'no' are also accepted, though using these values is deprecated.
  * @return array Associative array of all provided $options as keys and boolean values for whether their autoload value
  *               was updated.
@@ -399 +400 @@
     foreach ( $options as $option => $autoload ) {
         wp_protect_special_option( $option ); // Ensure only valid options can be passed.
-        if ( 'off' === $autoload || 'no' === $autoload || false === $autoload ) { // Sanitize autoload value and categorize accordingly.
+
+        /*
+         * Sanitize autoload value and categorize accordingly.
+         * The values 'yes', 'no', 'on', and 'off' are supported for backward compatibility.
+         */
+        if ( 'off' === $autoload || 'no' === $autoload || false === $autoload ) {
             $grouped_options['off'][] = $option;
         } else {
@@ -497 +503 @@
  *
  * @since 6.4.0
+ * @since 6.7.0 The autoload values 'yes' and 'no' are deprecated.
  *
  * @see wp_set_option_autoload_values()
  *
- * @param string[]    $options  List of option names. Expected to not be SQL-escaped.
- * @param string|bool $autoload Autoload value to control whether to load the options when WordPress starts up.
- *                              Accepts 'yes'|true to enable or 'no'|false to disable.
+ * @param string[] $options  List of option names. Expected to not be SQL-escaped.
+ * @param bool     $autoload Autoload value to control whether to load the options when WordPress starts up.
+ *                           For backward compatibility 'yes' and 'no' are also accepted, though using these values is
+ *                           deprecated.
  * @return array Associative array of all provided $options as keys and boolean values for whether their autoload value
  *               was updated.
@@ -519 +527 @@
  *
  * @since 6.4.0
+ * @since 6.7.0 The autoload values 'yes' and 'no' are deprecated.
  *
  * @see wp_set_option_autoload_values()
  *
- * @param string      $option   Name of the option. Expected to not be SQL-escaped.
- * @param string|bool $autoload Autoload value to control whether to load the option when WordPress starts up.
- *                              Accepts 'yes'|true to enable or 'no'|false to disable.
+ * @param string $option   Name of the option. Expected to not be SQL-escaped.
+ * @param bool   $autoload Autoload value to control whether to load the option when WordPress starts up.
+ *                         For backward compatibility 'yes' and 'no' are also accepted, though using these values is
+ *                         deprecated.
  * @return bool True if the autoload value was modified, false otherwise.
  */
@@ -804 +814 @@
  * @since 1.0.0
  * @since 4.2.0 The `$autoload` parameter was added.
+ * @since 6.7.0 The autoload values 'yes' and 'no' are deprecated.
  *
  * @global wpdb $wpdb WordPress database abstraction object.
@@ -810 +821 @@
  * @param mixed     $value    Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
  * @param bool|null $autoload Optional. Whether to load the option when WordPress starts up.
- *                            Accepts a boolean, or `null` to stick with the initial value or, if no initial value is set,
- *                            to leave the decision up to default heuristics in WordPress.
- *                            For existing options,
- *                            `$autoload` can only be updated using `update_option()` if `$value` is also changed.
- *                            For backward compatibility 'yes' and 'no' are also accepted.
+ *                            Accepts a boolean, or `null` to stick with the initial value or, if no initial value is
+ *                            set, to leave the decision up to default heuristics in WordPress.
+ *                            For existing options, `$autoload` can only be updated using `update_option()` if `$value`
+ *                            is also changed.
+ *                            For backward compatibility 'yes' and 'no' are also accepted, though using these values is
+ *                            deprecated.
  *                            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
@@ -1027 +1039 @@
  * @since 1.0.0
  * @since 6.6.0 The $autoload parameter's default value was changed to null.
+ * @since 6.7.0 The autoload values 'yes' and 'no' are deprecated.
  *
  * @global wpdb $wpdb WordPress database abstraction object.
@@ -1035 +1048 @@
  * @param string    $deprecated Optional. Description. Not used anymore.
  * @param bool|null $autoload   Optional. Whether to load the option when WordPress starts up.
- *                              Accepts a boolean, or `null` to leave the decision up to default heuristics in WordPress.
- *                              For backward compatibility 'yes' and 'no' are also accepted.
+ *                              Accepts a boolean, or `null` to leave the decision up to default heuristics in
+ *                              WordPress. For backward compatibility 'yes' and 'no' are also accepted, though using
+ *                              these values is deprecated.
  *                              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.
+ *                              in the frontend, it is recommended to autoload them, by using true.
  *                              For options which are accessed only on few specific URLs, it is recommended
  *                              to not autoload them, by using false.