wp-includes/option.php:844Save a setting to the options table with update_option(), which serializes non-scalar values and creates the option if it does not exist yet. It returns true only when the stored value actually changed. The third $autoload argument controls whether the option loads on every request; pass false for data only a few admin screens read.
Updates the value of an option that was already added.
$optionstring$valuemixed$autoloadbool|nulloptionalnullboolEvery example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.
Options hold arrays directly, so a plugin's whole settings screen can live under one key.
$settings = get_option( 'wppaste_settings', array() );
$settings['accent_color'] = sanitize_hex_color( '#0055aa' );
$settings['show_promo'] = true;
update_option( 'wppaste_settings', $settings );
print_r( get_option( 'wppaste_settings' ) );update_option() creates the option when it does not exist, so add_option() is rarely needed.
Autoloaded options are fetched on every single request, so anything read on one screen should opt out.
$log = get_option( 'wppaste_import_log', array() );
$log[] = array( 'time' => current_time( 'mysql' ), 'result' => 'ok' );
// false: never autoload, this is read on one admin screen only.
update_option( 'wppaste_import_log', $log, false );
echo 'rows stored: ', count( get_option( 'wppaste_import_log' ) ), "\n";
echo 'autoloaded: ', isset( wp_load_alloptions()['wppaste_import_log'] ) ? 'yes' : 'no';The autoload flag is only applied when the option is first created, not on later updates.
6 hooks fire while update_option() runs, in this order:
Filters a specific option before its value is (maybe) serialized and updated.
Filters an option before its value is (maybe) serialized and updated.
Filters the default value for an option.
Fires immediately before an option value is updated.
Fires after the value of a specific option has been successfully updated.
Fires after the value of an option has been successfully updated.
function update_option( $option, $value, $autoload = null ) { global $wpdb; if ( is_scalar( $option ) ) { $option = trim( $option ); } if ( empty( $option ) ) { return false; } /* * Until a proper _deprecated_option() function can be introduced, * redirect requests to deprecated keys to the new, correct ones. */ $deprecated_keys = array( 'blacklist_keys' => 'disallowed_keys', 'comment_whitelist' => 'comment_previously_approved', ); if ( isset( $deprecated_keys[ $option ] ) && ! wp_installing() ) { _deprecated_argument( __FUNCTION__, '5.5.0', sprintf( /* translators: 1: Deprecated option key, 2: New option key. */ __( 'The "%1$s" option key has been renamed to "%2$s".' ), $option, $deprecated_keys[ $option ] ) ); return update_option( $deprecated_keys[ $option ], $value, $autoload ); } wp_protect_special_option( $option ); if ( is_object( $value ) ) { $value = clone $value; } $value = sanitize_option( $option, $value ); $old_value = get_option( $option ); /** * Filters a specific option before its value is (maybe) serialized and updated. * * The dynamic portion of the hook name, `$option`, refers to the option name. * * @since 2.6.0 * @since 4.4.0 The `$option` parameter was added. * * @param mixed $value The new, unserialized option value. * @param mixed $old_value The old option value. * @param string $option Option name. */ $value = apply_filters( "pre_update_option_{$option}", $value, $old_value, $option ); /** * Filters an option before its value is (maybe) serialized and updated. * * @since 3.9.0 * * @param mixed $value The new, unserialized option value. * @param string $option Name of the option. * @param mixed $old_value The old option value. */ $value = apply_filters( 'pre_update_option', $value, $option, $old_value ); /* * If the new and old values are the same, no need to update. * * Unserialized values will be adequate in most cases. If the unserialized * data differs, the (maybe) serialized data is checked to avoid * unnecessary database calls for otherwise identical object instances. * * See https://core.trac.wordpress.org/ticket/38903 */ if ( $value === $old_value || maybe_serialize( $value ) === maybe_serialize( $old_value ) ) { return false; }Introduced in 1.0.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
src/wp-includes/option.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.