Options API: Disabling autoload for large options

WordPress automatically loads multiple options with a single query on each page request in order to be more efficient—a technique called “autoloading”. Prior to [57920], developers could control whether their option should be autoloaded by passing either "yes"/true or "no"/false to the third parameter of add_option() or update_option(). However, the decision to make that parameter optional, with a default value of "yes" has led to many options being loaded on every page unnecessarily (see #42441). 

Autoloading a large amount of data that is not used negatively impacts website performance, particularly when an option containing a large amount of data is not used.

[57920] introduces several changes to the Options APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. to optimize autoloading behavior.

Changes to the options API

To support this optimization for autoloading behavior, and to create a way to apply further optimizations going forward, the following changes to the Options API have been made.

New default $autoload value

The default value for the $autoload parameter of add_option() and update_option() is being changed from "yes" to  null, to allow WordPress to differentiate between an option with an autoload value that is explicitly set, and one where it can dynamically determine whether an option should be autoloaded. As a result, there are now three recommended values for the autoload parameter:

• true: always autoload; Use this when an option should load on every page to avoid an additional DB query.
• false:  never autoload; Use this when an option is rarely used to avoid wasted data being loaded on every page.
• null: maybe autoload; Allow the autoload value to be dynamically determined. By default, WordPress will still autoload options using the default value unless they contain large values (described below).

For backwards compatibility, the previous values of "yes" and "no" are still supported and mapped to true and false, respectively.

Updated database autoload values

Previously, all options were stored in the database with an autoload value of either “yes” or “no”. Starting with this change, the autoload value for newly updated options will now be one of the following values:

• ‘on’: Added with an explicit true value and MUST be autoloaded (needed on EVERY page).
• ‘off‘:‘ Added with an explicit false value and MUST not be autoloaded (e.g. only used on a single adminadmin (and super admin) page) .
• ‘auto’: Added without an explicit value and will rely on WP default autoloading behavior. In WordPress 6.6 these SHOULD autoload, but the default may change in the future.
• ‘auto-on’: Added with a dynamically set to true value and SHOULD be autoloaded.
• ‘auto-off’: Added with a dynamically set to false value and SHOULD NOT be autoloaded.

No upgrade routine is planned for this change, so previously added options will still be stored with “yes” or “no” values, which will be treated like “on” and “off”, respectively. If you have implemented any custom SQL to read or write autoload values, you should update them to use the new values.

Newly introduced public functions and filters

Several new functions and filters are available to make working with the new autoload values easier.

New Function

• wp_autoload_values_to_autoload() – Returns all database values that should be autoloaded. Defaults to an array containing 'yes', 'on', 'auto-on', and 'auto'.

New Filters

• wp_autoload_values_to_autoload – Edit the list of autoload values stored in the database values that should be autoloaded. At this time, the filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. only allows values to be removed.
• wp_default_autoload_value – Determine the default autoload value for an option where no explicit value is passed. Return a boolean false value to disable autoloading.
• wp_max_autoloaded_option_size – Modify the size threshold above which options will not be autoloaded by default. Defaults to 150000, i.e., 150k bytes.

Disabling autoload for large options

To address the issue of autoloading excessively large options, when an option is added via add_option() or an option’s value is changed via update_option(), WordPress will now dynamically disable the autoload behavior by checking the size of the value before updating the database. For any options that do not explicitly pass true to the $autoload parameter, a value that is greater than 150k bytes will no longer be set to autoload.

Preparing for this update

To prepare for this update, developers should update calls to add_option() and update_option() in their code to explicitly set an autoload value using the new preferred true or false values in order to control the autoload behavior for your options. Otherwise, continue using the default value to allow for autoload optimizations to be dynamically applied.

Ensuring a large option is still autoloaded

If you need to ensure a specific large option is autoloaded after this change and cannot directly change the code where that option is saved, you can make use of the new wp_default_autoload_value filter.

Note: Do this with care, and only for options that are needed on every page.

add_filter( 'wp_default_autoload_value', 'my_large_value_autoload', 10, 2 );

function my_large_value_autoload( $autoload, $option ) {
    if ( 'my-large-option' === $option ) {
        return true;
    }
    
    return $autoload;
}

Adjusting the threshold for large options

If you want to change the size threshold for when options should no longer be autoloaded, you can use the new wp_max_autoloaded_option_size filter. Increasing this value is not recommended, as it could lead to slower performance.

add_filter( 'wp_max_autoloaded_option_size', 'my_max_autoload_option_size' );

function my_max_autoload_option_size( $size ) {
    // Reduce the threshold for large sizes to 100K (Default is 150K).
    return 100000;
}

Auditing your site for large options

WordPress 6.6 will include a new Site Health check, which will display a critical issue that says “Autoloaded options could affect performance” if the total size of your autoloaded options exceeds 800 KB.

To audit your site for large options that are currently being autoloaded, you can run an enhanced version of this same Site Health check by installing the Performance Lab plugin from the WordPress Performance Team. Once activated, the pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party will add additional information to the Site Health check so you can review and disable any options that do not need to be autoloaded in the Site Health check.

Other changes to the Options API in WordPress 6.6

• Introduce wp_prime_network_option_caches() to load multiple networknetwork (versus site, blog) options with a single database request (#61053)
• Prime transient and transient timeout options in the transient and site transient APIs (#61193, #61053)
• Update default autoload values used in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. (#61045)
• Add 'label' argument to register_setting() (#61023)

This post has been co-authored by @pbearne and @joemcgill

Props to @flixos90, @peterwilsoncc,@adamsilverstein, @mukesh27 and @desrosj
for contributing to and reviewing this post.

#6-6, #dev-note, #dev-notes, #dev-notes-6-6