update_option( string $option, mixed $value, bool|null $autoload = null ): bool

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$optionstring

Name of the option to update. Expected to not be SQL-escaped.

$valuemixed

Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.

$autoloadbool|nulloptional

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, 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 true.
For options which are accessed only on few specific URLs, it is recommended to not autoload them, by using false.
For non-existent options, the default is null, which means WordPress will determine the autoload value.Default: null

Return value

bool

True if the value was updated, false otherwise.

Code examples

Every 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.

$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' ) );

$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';

Performance profile

How much work a call to update_option() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->get_var().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

9–171

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 248.

Plugin surface

6 hooks

Third-party callbacks on 'pre_update_option_{$option}', 'pre_update_option', 'default_option_{$option}' run inside this call, and their cost is not bounded by anything here.

Called by

50

50 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeupdate_option()this function does it
• hookthird-party callbacksapply_filters()called directly
• serializeserialisationmaybe_serialize()called directly
• cacheobject cachewp_cache_get()called directly
• sqldatabase query->get_var()called directly

Further down the call graph this can also reach query and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 74 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost update_option() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 6

6 hooks fire while update_option() runs, in this order:

1. 1
   apply_filters( pre_update_option_{$option} )filterline 899 (+55 into the body)

   Filters a specific option before its value is (maybe) serialized and updated.

2. 2
   apply_filters( pre_update_option )filterline 910 (+66 into the body)

   Filters an option before its value is (maybe) serialized and updated.

3. 3
   apply_filters( default_option_{$option} )filterline 926 (+82 into the body)

   Filters the default value for an option.

4. 4
   do_action( update_option )actionline 941 (+97 into the body)

   Fires immediately before an option value is updated.

5. 5
   do_action( update_option_{$option} )actionline 1017 (+173 into the body)

   Fires after the value of a specific option has been successfully updated.

6. 6
   do_action( updated_option )actionline 1028 (+184 into the body)

   Fires after the value of an option has been successfully updated.

Uses · 17

• wp_installing()Checks or sets whether WordPress is in "installation" mode.
• _deprecated_argument()Marks a function argument as deprecated and inform when it has been used.
• __()Retrieves the translation of $text.
• update_option()Updates the value of an option that was already added.
• wp_protect_special_option()Protects WordPress special option from being modified.
• sanitize_option()Sanitizes various option values based on the nature of the option.
• get_option()Retrieves an option value based on an option name.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• maybe_serialize()Serializes data, if needed.
• add_option()Adds a new option.
• do_action()Calls the callback functions that have been added to an action hook.
• wp_determine_option_autoload_value()Determines the appropriate autoload value for an option based on input.

Used by · 50

• Featured_Content::delete_post_tag()Resets tag option when the saved tag is deleted.
• Plugin_Upgrader::bulk_upgrade()Upgrades several plugins at once.
• Plugin_Upgrader::upgrade()Upgrades a plugin.
• Theme_Upgrader::bulk_upgrade()Upgrades several themes at once.
• Theme_Upgrader::upgrade()Upgrades a theme.
• WP_Automatic_Updater::send_plugin_theme_email()Sends an email upon the completion or failure of a plugin or theme background update.
• WP_Customize_Manager::save_changeset_post()Saves the post for the loaded changeset.
• WP_Customize_Manager::update_stashed_theme_mod_settings()Updates stashed theme mod settings.
• WP_Customize_Nav_Menu_Setting::update()Create/update the nav_menu term for this setting.
• WP_Customize_Setting::set_root_value()Set the root value for a setting, especially for multidimensional ones.
• WP_Paused_Extensions_Storage::delete()Forgets a previously recorded extension error.
• WP_Paused_Extensions_Storage::delete_all()Remove all paused extensions.

Source code

View on Trac ↗View on GitHub ↗

844function update_option( $option, $value, $autoload = null ) {845	global $wpdb;846 847	if ( is_scalar( $option ) ) {848		$option = trim( $option );849	}850 851	if ( empty( $option ) ) {852		return false;853	}854 855	/*856	 * Until a proper _deprecated_option() function can be introduced,857	 * redirect requests to deprecated keys to the new, correct ones.858	 */859	$deprecated_keys = array(860		'blacklist_keys'    => 'disallowed_keys',861		'comment_whitelist' => 'comment_previously_approved',862	);863 864	if ( isset( $deprecated_keys[ $option ] ) && ! wp_installing() ) {865		_deprecated_argument(866			__FUNCTION__,867			'5.5.0',868			sprintf(869				/* translators: 1: Deprecated option key, 2: New option key. */870				__( 'The "%1$s" option key has been renamed to "%2$s".' ),871				$option,872				$deprecated_keys[ $option ]873			)874		);875		return update_option( $deprecated_keys[ $option ], $value, $autoload );876	}877 878	wp_protect_special_option( $option );879 880	if ( is_object( $value ) ) {881		$value = clone $value;882	}883 884	$value     = sanitize_option( $option, $value );885	$old_value = get_option( $option );886 887	/**888	 * Filters a specific option before its value is (maybe) serialized and updated.889	 *890	 * The dynamic portion of the hook name, `$option`, refers to the option name.891	 *892	 * @since 2.6.0893	 * @since 4.4.0 The `$option` parameter was added.894	 *895	 * @param mixed  $value     The new, unserialized option value.896	 * @param mixed  $old_value The old option value.897	 * @param string $option    Option name.898	 */899	$value = apply_filters( "pre_update_option_{$option}", $value, $old_value, $option );900 901	/**902	 * Filters an option before its value is (maybe) serialized and updated.903	 *904	 * @since 3.9.0905	 *906	 * @param mixed  $value     The new, unserialized option value.907	 * @param string $option    Name of the option.908	 * @param mixed  $old_value The old option value.909	 */910	$value = apply_filters( 'pre_update_option', $value, $option, $old_value );911 912	/*913	 * If the new and old values are the same, no need to update.914	 *915	 * Unserialized values will be adequate in most cases. If the unserialized916	 * data differs, the (maybe) serialized data is checked to avoid917	 * unnecessary database calls for otherwise identical object instances.918	 *919	 * See https://core.trac.wordpress.org/ticket/38903920	 */921	if ( $value === $old_value || maybe_serialize( $value ) === maybe_serialize( $old_value ) ) {922		return false;923	}

Changelog

Introduced in 1.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/option.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.