update_option

Update the value of an option that was already added.

Description

update_option( (string) $option, (mixed) $value, (null) $autoload = null ); 

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 can not be serialized or added as an option.

If the option does not exist, then the option will be added with the option value, with an $autoload value of yes..

Parameters (3)

0. $option (string)
Option name. Expected to not be SQL-escaped.
1. $value (mixed)
Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
2. $autoload — Optional. (null) => null
Whether to load the option when WordPress starts up. For existing options, $autoload can only be updated using update_option() if $value. is also changed. Accepts yes|true to enable or no|false to disable. For non-existent options, the default value is yes. Default null.

Usage

  1. if ( !function_exists( 'update_option' ) ) { 
  2. require_once ABSPATH . WPINC . '/option.php'; 
  3.  
  4. // Option name. Expected to not be SQL-escaped. 
  5. $option = ''; 
  6.  
  7. // Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped. 
  8. $value = null; 
  9. $autoload = null; 
  10.  
  11. // NOTICE! Understand what this does before running. 
  12. $result = update_option($option, $value, $autoload); 
  13.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/option.php  
  1. function update_option( $option, $value, $autoload = null ) { 
  2. global $wpdb; 
  3.  
  4. $option = trim($option); 
  5. if ( empty($option) ) 
  6. return false; 
  7.  
  8.  
  9. if ( is_object( $value ) ) 
  10. $value = clone $value; 
  11.  
  12. $value = sanitize_option( $option, $value ); 
  13. $old_value = get_option( $option ); 
  14.  
  15. /** 
  16. * Filters a specific option before its value is (maybe) serialized and updated. 
  17. * The dynamic portion of the hook name, `$option`, refers to the option name. 
  18. * @since 2.6.0 
  19. * @since 4.4.0 The `$option` parameter was added. 
  20. * @param mixed $value The new, unserialized option value. 
  21. * @param mixed $old_value The old option value. 
  22. * @param string $option Option name. 
  23. */ 
  24. $value = apply_filters( "pre_update_option_{$option}", $value, $old_value, $option ); 
  25.  
  26. /** 
  27. * Filters an option before its value is (maybe) serialized and updated. 
  28. * @since 3.9.0 
  29. * @param mixed $value The new, unserialized option value. 
  30. * @param string $option Name of the option. 
  31. * @param mixed $old_value The old option value. 
  32. */ 
  33. $value = apply_filters( 'pre_update_option', $value, $option, $old_value ); 
  34.  
  35. // If the new and old values are the same, no need to update. 
  36. if ( $value === $old_value ) 
  37. return false; 
  38.  
  39. /** This filter is documented in wp-includes/option.php */ 
  40. if ( apply_filters( 'default_option_' . $option, false, $option, false ) === $old_value ) { 
  41. // Default setting for new options is 'yes'. 
  42. if ( null === $autoload ) { 
  43. $autoload = 'yes'; 
  44.  
  45. return add_option( $option, $value, '', $autoload ); 
  46.  
  47. $serialized_value = maybe_serialize( $value ); 
  48.  
  49. /** 
  50. * Fires immediately before an option value is updated. 
  51. * @since 2.9.0 
  52. * @param string $option Name of the option to update. 
  53. * @param mixed $old_value The old option value. 
  54. * @param mixed $value The new option value. 
  55. */ 
  56. do_action( 'update_option', $option, $old_value, $value ); 
  57.  
  58. $update_args = array( 
  59. 'option_value' => $serialized_value,  
  60. ); 
  61.  
  62. if ( null !== $autoload ) { 
  63. $update_args['autoload'] = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes'; 
  64.  
  65. $result = $wpdb->update( $wpdb->options, $update_args, array( 'option_name' => $option ) ); 
  66. if ( ! $result ) 
  67. return false; 
  68.  
  69. $notoptions = wp_cache_get( 'notoptions', 'options' ); 
  70. if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) { 
  71. unset( $notoptions[$option] ); 
  72. wp_cache_set( 'notoptions', $notoptions, 'options' ); 
  73.  
  74. if ( ! wp_installing() ) { 
  75. $alloptions = wp_load_alloptions(); 
  76. if ( isset( $alloptions[$option] ) ) { 
  77. $alloptions[ $option ] = $serialized_value; 
  78. wp_cache_set( 'alloptions', $alloptions, 'options' ); 
  79. } else { 
  80. wp_cache_set( $option, $serialized_value, 'options' ); 
  81.  
  82. /** 
  83. * Fires after the value of a specific option has been successfully updated. 
  84. * The dynamic portion of the hook name, `$option`, refers to the option name. 
  85. * @since 2.0.1 
  86. * @since 4.4.0 The `$option` parameter was added. 
  87. * @param mixed $old_value The old option value. 
  88. * @param mixed $value The new option value. 
  89. * @param string $option Option name. 
  90. */ 
  91. do_action( "update_option_{$option}", $old_value, $value, $option ); 
  92.  
  93. /** 
  94. * Fires after the value of an option has been successfully updated. 
  95. * @since 2.9.0 
  96. * @param string $option Name of the updated option. 
  97. * @param mixed $old_value The old option value. 
  98. * @param mixed $value The new option value. 
  99. */ 
  100. do_action( 'updated_option', $option, $old_value, $value ); 
  101. return true;