update_option()
Update the value of an option that was already added.
You do not need to serialize values. If the value needs to be serialized, then it will be serialized before it is inserted into the database. Remember, resources cannot be serialized or added as an option.
If the option does not exist, it will be created.
This function is designed to work with or without a logged-in user. In terms of security, plugin developers should check the current user's capabilities before updating any options.
Hooks from the function
Return
true|false. True if the value was updated, false otherwise.
Usage
update_option( $option, $value, $autoload );
- $option(string) (required)
- Name of the option to update. Expected to not be SQL-escaped.
- $value(mixed) (required)
- Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
- $autoload(true|false|null)
- 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() $value is also changed. For backward compatibility 'yes' and 'no' are also accepted. 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
Examples
#1 Update Option Stored in Multi-Dimensional Array
Update multi-dimensional array and retrieve the entire array.
// store in one variable $multidimensional_options = array( 'inner_array' => array( 'foo' => 'bar', 'hello' => 'world', ), ); // Update entire array update_option( 'my_multi_options', $multidimensional_options ); // Get entire array $my_multi_options = get_option( 'my_multi_options' ); /* we get: Array ( [inner_array] => Array ( [foo] => bar [hello] => world ) ) */
#2 Update the existing option my_option
set it to "new value":
<?php update_option('my_option', 'new value' ); ?>
#3 Update the option extract_length to 255.
If this option does not exist, update_option() will create it automatically.
Note that since version 4.2 in update_option() we can specify the autoload parameter, which will be updated if the option exists and passed to add_option() if the option does not exist and must be created...
$newvalue = '255' ; update_option( 'extract_length', $newvalue, 'no' );
Same for WP version below 4.2:
If the option extract_length does not exist yet, add it using the function add_ooption() where we specify that the option is not loaded automatically (make it private).
$option_name = 'extract_length' ;
$newvalue = '255' ;
if ( get_option( $option_name ) != $newvalue ) {
update_option( $option_name, $newvalue );
}
else {
$deprecated = '';
$autoload = 'no';
add_option( $option_name, $newvalue, $deprecated, $autoload );
}
#4 Update option only once on the first time installed
The code below will let user change options even after new option set.
function my_switch_theme() {
update_option( 'thumbnail_size_w', 320 );
update_option( 'thumbnail_size_h', 180 );
}
add_action('switch_theme', 'my_switch_theme');
If we use after_setup_theme, it will block the options and prevent users change it.
#5 true/false case as option value
According to the WordPress Codex (and my experiences developing with WP) note an important subtlety in the return value here:
“True if option value has changed, false if not or if update failed.
It is also recommended on some forums to check for the existence of an option via code:
if ( ! get_option('my_option') ) ...
But I don’t find this works when the option exists and I have set my_option to bool FALSE!
To handle all checking of existence of options, I exploit the update_option subtlety:
if ( FALSE === get_option('my_option') && FALSE === update_option('my_option',FALSE) ) {
add_option( 'my_option', $default_value );
}
The second check yields FALSE when setting the option with the value of FALSE produces no change…therefore if the value truly didn’t exist, it will be added with (in my case) the desired $default_value.
I know this seems extreme, but to the best of my knowledge this is the only way I’ve been able to preserve bool FALSE on my plugin options, and to assert valid actions based on the actual presence of my custom options.
Another variant
According to the WordPress Codex : get_option has $default_value param. will returned when option does not exist. So we can use $default_value as check our code can smaller & faster.
if( get_option( 'otp_name', 'SOME_UNIQUE_VALUE' ) === 'SOME_UNIQUE_VALUE' ){
add_option( 'otp_name', 'init_value' );
}
So no update_option call required.
Or use such hack
One workaround is to use as values integers 1 and 0 instead of booleans.
#6 Clear the options cache
Option values retrieved via WordPress functions are cached. If you modify an options outside of the Options API, then try to update a cached option, the update will fail and return false.
Use the following method to clear the options cache before trying to get or update the options on the same request:
<?php wp_cache_delete( 'alloptions', 'options' ); ?>
#7 Avoid to pass null
Please avoid to pass null as $value, for a false-y value just use 0, false or even an empty string. A null value may lead to potential bugs and side effects.
See this ticket for details.
#8 List of all options
Use wp_load_alloptions() to print a list of all options:
$alloptions = wp_load_alloptions(); print_r( $alloptions ); /* we get: Array ( [siteurl] => https://wp-kama.com [blogname] => WordPress on your fingertips [blogdescription] => Site about the WordPress ... [users_can_register] => 1 ... ... ) */
Notes
- Global. wpdb. $wpdb WordPress database abstraction object.
Changelog
| Since 1.0.0 | Introduced. |
| Since 4.2.0 | The $autoload parameter was added. |