10 * Retrieve option value based on name of option.
12 * If the option does not exist or does not have a value, then the return value
13 * will be false. This is useful to check whether you need to install an option
14 * and is commonly used during installation of plugin options and to test
15 * whether upgrading is required.
17 * If the option was serialized then it will be unserialized when it is returned.
23 * @param string $option Name of option to retrieve. Expected to not be SQL-escaped.
24 * @param mixed $default Optional. Default value to return if the option does not exist.
25 * @return mixed Value set for the option.
27 function get_option( $option, $default = false ) {
30 $option = trim( $option );
31 if ( empty( $option ) )
35 * Filter the value of an existing option before it is retrieved.
37 * The dynamic portion of the hook name, `$option`, refers to the option name.
39 * Passing a truthy value to the filter will short-circuit retrieving
40 * the option value, returning the passed value instead.
44 * @param bool|mixed $pre_option Value to return instead of the option value.
45 * Default false to skip it.
47 $pre = apply_filters( 'pre_option_' . $option, false );
51 if ( defined( 'WP_SETUP_CONFIG' ) )
54 if ( ! defined( 'WP_INSTALLING' ) ) {
55 // prevent non-existent options from triggering multiple queries
56 $notoptions = wp_cache_get( 'notoptions', 'options' );
57 if ( isset( $notoptions[ $option ] ) ) {
59 * Filter the default value for an option.
61 * The dynamic portion of the hook name, `$option`, refers to the option name.
65 * @param mixed $default The default value to return if the option does not exist
68 return apply_filters( 'default_option_' . $option, $default );
71 $alloptions = wp_load_alloptions();
73 if ( isset( $alloptions[$option] ) ) {
74 $value = $alloptions[$option];
76 $value = wp_cache_get( $option, 'options' );
78 if ( false === $value ) {
79 $row = $wpdb->get_row( $wpdb->prepare( "SELECT option_value FROM $wpdb->options WHERE option_name = %s LIMIT 1", $option ) );
81 // Has to be get_row instead of get_var because of funkiness with 0, false, null values
82 if ( is_object( $row ) ) {
83 $value = $row->option_value;
84 wp_cache_add( $option, $value, 'options' );
85 } else { // option does not exist, so we must cache its non-existence
86 if ( ! is_array( $notoptions ) ) {
87 $notoptions = array();
89 $notoptions[$option] = true;
90 wp_cache_set( 'notoptions', $notoptions, 'options' );
92 /** This filter is documented in wp-includes/option.php */
93 return apply_filters( 'default_option_' . $option, $default );
98 $suppress = $wpdb->suppress_errors();
99 $row = $wpdb->get_row( $wpdb->prepare( "SELECT option_value FROM $wpdb->options WHERE option_name = %s LIMIT 1", $option ) );
100 $wpdb->suppress_errors( $suppress );
101 if ( is_object( $row ) ) {
102 $value = $row->option_value;
104 /** This filter is documented in wp-includes/option.php */
105 return apply_filters( 'default_option_' . $option, $default );
109 // If home is not set use siteurl.
110 if ( 'home' == $option && '' == $value )
111 return get_option( 'siteurl' );
113 if ( in_array( $option, array('siteurl', 'home', 'category_base', 'tag_base') ) )
114 $value = untrailingslashit( $value );
117 * Filter the value of an existing option.
119 * The dynamic portion of the hook name, `$option`, refers to the option name.
121 * @since 1.5.0 As 'option_' . $setting
124 * @param mixed $value Value of the option. If stored serialized, it will be
125 * unserialized prior to being returned.
127 return apply_filters( 'option_' . $option, maybe_unserialize( $value ) );
131 * Protect WordPress special option from being modified.
133 * Will die if $option is in protected list. Protected options are 'alloptions'
134 * and 'notoptions' options.
138 * @param string $option Option name.
140 function wp_protect_special_option( $option ) {
141 if ( 'alloptions' === $option || 'notoptions' === $option )
142 wp_die( sprintf( __( '%s is a protected WP option and may not be modified' ), esc_html( $option ) ) );
146 * Print option value after sanitizing for forms.
150 * @param string $option Option name.
152 function form_option( $option ) {
153 echo esc_attr( get_option( $option ) );
157 * Loads and caches all autoloaded options, if available or all options.
163 * @return array List of all options.
165 function wp_load_alloptions() {
168 if ( !defined( 'WP_INSTALLING' ) || !is_multisite() )
169 $alloptions = wp_cache_get( 'alloptions', 'options' );
173 if ( !$alloptions ) {
174 $suppress = $wpdb->suppress_errors();
175 if ( !$alloptions_db = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options WHERE autoload = 'yes'" ) )
176 $alloptions_db = $wpdb->get_results( "SELECT option_name, option_value FROM $wpdb->options" );
177 $wpdb->suppress_errors($suppress);
178 $alloptions = array();
179 foreach ( (array) $alloptions_db as $o ) {
180 $alloptions[$o->option_name] = $o->option_value;
182 if ( !defined( 'WP_INSTALLING' ) || !is_multisite() )
183 wp_cache_add( 'alloptions', $alloptions, 'options' );
190 * Loads and caches certain often requested site options if is_multisite() and a persistent cache is not being used.
196 * @param int $site_id Optional site ID for which to query the options. Defaults to the current site.
198 function wp_load_core_site_options( $site_id = null ) {
201 if ( !is_multisite() || wp_using_ext_object_cache() || defined( 'WP_INSTALLING' ) )
204 if ( empty($site_id) )
205 $site_id = $wpdb->siteid;
207 $core_options = array('site_name', 'siteurl', 'active_sitewide_plugins', '_site_transient_timeout_theme_roots', '_site_transient_theme_roots', 'site_admins', 'can_compress_scripts', 'global_terms_enabled', 'ms_files_rewriting' );
209 $core_options_in = "'" . implode("', '", $core_options) . "'";
210 $options = $wpdb->get_results( $wpdb->prepare("SELECT meta_key, meta_value FROM $wpdb->sitemeta WHERE meta_key IN ($core_options_in) AND site_id = %d", $site_id) );
212 foreach ( $options as $option ) {
213 $key = $option->meta_key;
214 $cache_key = "{$site_id}:$key";
215 $option->meta_value = maybe_unserialize( $option->meta_value );
217 wp_cache_set( $cache_key, $option->meta_value, 'site-options' );
222 * Update the value of an option that was already added.
224 * You do not need to serialize values. If the value needs to be serialized, then
225 * it will be serialized before it is inserted into the database. Remember,
226 * resources can not be serialized or added as an option.
228 * If the option does not exist, then the option will be added with the option value,
229 * with an `$autoload` value of 'yes'.
232 * @since 4.2.0 The `$autoload` parameter was added.
236 * @param string $option Option name. Expected to not be SQL-escaped.
237 * @param mixed $value Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
238 * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up. For existing options,
239 * `$autoload` can only be updated using `update_option()` if `$value` is also changed.
240 * Accepts 'yes'|true to enable or 'no'|false to disable. For non-existent options,
241 * the default value is 'yes'. Default null.
242 * @return bool False if value was not updated and true if value was updated.
244 function update_option( $option, $value, $autoload = null ) {
247 $option = trim($option);
248 if ( empty($option) )
251 wp_protect_special_option( $option );
253 if ( is_object( $value ) )
254 $value = clone $value;
256 $value = sanitize_option( $option, $value );
257 $old_value = get_option( $option );
260 * Filter a specific option before its value is (maybe) serialized and updated.
262 * The dynamic portion of the hook name, `$option`, refers to the option name.
266 * @param mixed $value The new, unserialized option value.
267 * @param mixed $old_value The old option value.
269 $value = apply_filters( 'pre_update_option_' . $option, $value, $old_value );
272 * Filter an option before its value is (maybe) serialized and updated.
276 * @param mixed $value The new, unserialized option value.
277 * @param string $option Name of the option.
278 * @param mixed $old_value The old option value.
280 $value = apply_filters( 'pre_update_option', $value, $option, $old_value );
282 // If the new and old values are the same, no need to update.
283 if ( $value === $old_value )
286 /** This filter is documented in wp-includes/option.php */
287 if ( apply_filters( 'default_option_' . $option, false ) === $old_value ) {
288 // Default setting for new options is 'yes'.
289 if ( null === $autoload ) {
293 return add_option( $option, $value, '', $autoload );
296 $serialized_value = maybe_serialize( $value );
299 * Fires immediately before an option value is updated.
303 * @param string $option Name of the option to update.
304 * @param mixed $old_value The old option value.
305 * @param mixed $value The new option value.
307 do_action( 'update_option', $option, $old_value, $value );
309 $update_args = array(
310 'option_value' => $serialized_value,
313 if ( null !== $autoload ) {
314 $update_args['autoload'] = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes';
317 $result = $wpdb->update( $wpdb->options, $update_args, array( 'option_name' => $option ) );
321 $notoptions = wp_cache_get( 'notoptions', 'options' );
322 if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
323 unset( $notoptions[$option] );
324 wp_cache_set( 'notoptions', $notoptions, 'options' );
327 if ( ! defined( 'WP_INSTALLING' ) ) {
328 $alloptions = wp_load_alloptions();
329 if ( isset( $alloptions[$option] ) ) {
330 $alloptions[ $option ] = $serialized_value;
331 wp_cache_set( 'alloptions', $alloptions, 'options' );
333 wp_cache_set( $option, $serialized_value, 'options' );
338 * Fires after the value of a specific option has been successfully updated.
340 * The dynamic portion of the hook name, `$option`, refers to the option name.
344 * @param mixed $old_value The old option value.
345 * @param mixed $value The new option value.
347 do_action( "update_option_{$option}", $old_value, $value );
350 * Fires after the value of an option has been successfully updated.
354 * @param string $option Name of the updated option.
355 * @param mixed $old_value The old option value.
356 * @param mixed $value The new option value.
358 do_action( 'updated_option', $option, $old_value, $value );
365 * You do not need to serialize values. If the value needs to be serialized, then
366 * it will be serialized before it is inserted into the database. Remember,
367 * resources can not be serialized or added as an option.
369 * You can create options without values and then update the values later.
370 * Existing options will not be updated and checks are performed to ensure that you
371 * aren't adding a protected WordPress option. Care should be taken to not name
372 * options the same as the ones which are protected.
378 * @param string $option Name of option to add. Expected to not be SQL-escaped.
379 * @param mixed $value Optional. Option value. Must be serializable if non-scalar. Expected to not be SQL-escaped.
380 * @param string $deprecated Optional. Description. Not used anymore.
381 * @param string|bool $autoload Optional. Whether to load the option when WordPress starts up.
382 * Default is enabled. Accepts 'no' to disable for legacy reasons.
383 * @return bool False if option was not added and true if option was added.
385 function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) {
388 if ( !empty( $deprecated ) )
389 _deprecated_argument( __FUNCTION__, '2.3' );
391 $option = trim($option);
392 if ( empty($option) )
395 wp_protect_special_option( $option );
397 if ( is_object($value) )
398 $value = clone $value;
400 $value = sanitize_option( $option, $value );
402 // Make sure the option doesn't already exist. We can check the 'notoptions' cache before we ask for a db query
403 $notoptions = wp_cache_get( 'notoptions', 'options' );
404 if ( !is_array( $notoptions ) || !isset( $notoptions[$option] ) )
405 /** This filter is documented in wp-includes/option.php */
406 if ( apply_filters( 'default_option_' . $option, false ) !== get_option( $option ) )
409 $serialized_value = maybe_serialize( $value );
410 $autoload = ( 'no' === $autoload || false === $autoload ) ? 'no' : 'yes';
413 * Fires before an option is added.
417 * @param string $option Name of the option to add.
418 * @param mixed $value Value of the option.
420 do_action( 'add_option', $option, $value );
422 $result = $wpdb->query( $wpdb->prepare( "INSERT INTO `$wpdb->options` (`option_name`, `option_value`, `autoload`) VALUES (%s, %s, %s) ON DUPLICATE KEY UPDATE `option_name` = VALUES(`option_name`), `option_value` = VALUES(`option_value`), `autoload` = VALUES(`autoload`)", $option, $serialized_value, $autoload ) );
426 if ( ! defined( 'WP_INSTALLING' ) ) {
427 if ( 'yes' == $autoload ) {
428 $alloptions = wp_load_alloptions();
429 $alloptions[ $option ] = $serialized_value;
430 wp_cache_set( 'alloptions', $alloptions, 'options' );
432 wp_cache_set( $option, $serialized_value, 'options' );
436 // This option exists now
437 $notoptions = wp_cache_get( 'notoptions', 'options' ); // yes, again... we need it to be fresh
438 if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
439 unset( $notoptions[$option] );
440 wp_cache_set( 'notoptions', $notoptions, 'options' );
444 * Fires after a specific option has been added.
446 * The dynamic portion of the hook name, `$option`, refers to the option name.
448 * @since 2.5.0 As "add_option_{$name}"
451 * @param string $option Name of the option to add.
452 * @param mixed $value Value of the option.
454 do_action( "add_option_{$option}", $option, $value );
457 * Fires after an option has been added.
461 * @param string $option Name of the added option.
462 * @param mixed $value Value of the option.
464 do_action( 'added_option', $option, $value );
469 * Removes option by name. Prevents removal of protected WordPress options.
475 * @param string $option Name of option to remove. Expected to not be SQL-escaped.
476 * @return bool True, if option is successfully deleted. False on failure.
478 function delete_option( $option ) {
481 $option = trim( $option );
482 if ( empty( $option ) )
485 wp_protect_special_option( $option );
487 // Get the ID, if no ID then return
488 $row = $wpdb->get_row( $wpdb->prepare( "SELECT autoload FROM $wpdb->options WHERE option_name = %s", $option ) );
489 if ( is_null( $row ) )
493 * Fires immediately before an option is deleted.
497 * @param string $option Name of the option to delete.
499 do_action( 'delete_option', $option );
501 $result = $wpdb->delete( $wpdb->options, array( 'option_name' => $option ) );
502 if ( ! defined( 'WP_INSTALLING' ) ) {
503 if ( 'yes' == $row->autoload ) {
504 $alloptions = wp_load_alloptions();
505 if ( is_array( $alloptions ) && isset( $alloptions[$option] ) ) {
506 unset( $alloptions[$option] );
507 wp_cache_set( 'alloptions', $alloptions, 'options' );
510 wp_cache_delete( $option, 'options' );
516 * Fires after a specific option has been deleted.
518 * The dynamic portion of the hook name, `$option`, refers to the option name.
522 * @param string $option Name of the deleted option.
524 do_action( "delete_option_$option", $option );
527 * Fires after an option has been deleted.
531 * @param string $option Name of the deleted option.
533 do_action( 'deleted_option', $option );
540 * Delete a transient.
544 * @param string $transient Transient name. Expected to not be SQL-escaped.
545 * @return bool true if successful, false otherwise
547 function delete_transient( $transient ) {
550 * Fires immediately before a specific transient is deleted.
552 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
556 * @param string $transient Transient name.
558 do_action( 'delete_transient_' . $transient, $transient );
560 if ( wp_using_ext_object_cache() ) {
561 $result = wp_cache_delete( $transient, 'transient' );
563 $option_timeout = '_transient_timeout_' . $transient;
564 $option = '_transient_' . $transient;
565 $result = delete_option( $option );
567 delete_option( $option_timeout );
573 * Fires after a transient is deleted.
577 * @param string $transient Deleted transient name.
579 do_action( 'deleted_transient', $transient );
586 * Get the value of a transient.
588 * If the transient does not exist, does not have a value, or has expired,
589 * then the return value will be false.
593 * @param string $transient Transient name. Expected to not be SQL-escaped.
594 * @return mixed Value of transient.
596 function get_transient( $transient ) {
599 * Filter the value of an existing transient.
601 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
603 * Passing a truthy value to the filter will effectively short-circuit retrieval
604 * of the transient, returning the passed value instead.
608 * @param mixed $pre_transient The default value to return if the transient does not exist.
609 * Any value other than false will short-circuit the retrieval
610 * of the transient, and return the returned value.
612 $pre = apply_filters( 'pre_transient_' . $transient, false );
613 if ( false !== $pre )
616 if ( wp_using_ext_object_cache() ) {
617 $value = wp_cache_get( $transient, 'transient' );
619 $transient_option = '_transient_' . $transient;
620 if ( ! defined( 'WP_INSTALLING' ) ) {
621 // If option is not in alloptions, it is not autoloaded and thus has a timeout
622 $alloptions = wp_load_alloptions();
623 if ( !isset( $alloptions[$transient_option] ) ) {
624 $transient_timeout = '_transient_timeout_' . $transient;
625 $timeout = get_option( $transient_timeout );
626 if ( false !== $timeout && $timeout < time() ) {
627 delete_option( $transient_option );
628 delete_option( $transient_timeout );
634 if ( ! isset( $value ) )
635 $value = get_option( $transient_option );
639 * Filter an existing transient's value.
641 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
645 * @param mixed $value Value of transient.
647 return apply_filters( 'transient_' . $transient, $value );
651 * Set/update the value of a transient.
653 * You do not need to serialize values. If the value needs to be serialized, then
654 * it will be serialized before it is set.
658 * @param string $transient Transient name. Expected to not be SQL-escaped. Must be
659 * 45 characters or fewer in length.
660 * @param mixed $value Transient value. Must be serializable if non-scalar.
661 * Expected to not be SQL-escaped.
662 * @param int $expiration Optional. Time until expiration in seconds. Default 0.
663 * @return bool False if value was not set and true if value was set.
665 function set_transient( $transient, $value, $expiration = 0 ) {
667 $expiration = (int) $expiration;
670 * Filter a specific transient before its value is set.
672 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
675 * @since 4.2.0 Added `$expiration` parameter.
677 * @param mixed $value New value of transient.
678 * @param int $expiration Time until expiration in seconds.
680 $value = apply_filters( 'pre_set_transient_' . $transient, $value, $expiration );
682 if ( wp_using_ext_object_cache() ) {
683 $result = wp_cache_set( $transient, $value, 'transient', $expiration );
685 $transient_timeout = '_transient_timeout_' . $transient;
686 $transient = '_transient_' . $transient;
687 if ( false === get_option( $transient ) ) {
691 add_option( $transient_timeout, time() + $expiration, '', 'no' );
693 $result = add_option( $transient, $value, '', $autoload );
695 // If expiration is requested, but the transient has no timeout option,
696 // delete, then re-create transient rather than update.
699 if ( false === get_option( $transient_timeout ) ) {
700 delete_option( $transient );
701 add_option( $transient_timeout, time() + $expiration, '', 'no' );
702 $result = add_option( $transient, $value, '', 'no' );
705 update_option( $transient_timeout, time() + $expiration );
709 $result = update_option( $transient, $value );
717 * Fires after the value for a specific transient has been set.
719 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
723 * @param mixed $value Transient value.
724 * @param int $expiration Time until expiration in seconds. Default 0.
726 do_action( 'set_transient_' . $transient, $value, $expiration );
729 * Fires after the value for a transient has been set.
733 * @param string $transient The name of the transient.
734 * @param mixed $value Transient value.
735 * @param int $expiration Time until expiration in seconds. Default 0.
737 do_action( 'setted_transient', $transient, $value, $expiration );
743 * Saves and restores user interface settings stored in a cookie.
745 * Checks if the current user-settings cookie is updated and stores it. When no
746 * cookie exists (different browser used), adds the last saved cookie restoring
751 function wp_user_settings() {
753 if ( ! is_admin() || defined( 'DOING_AJAX' ) ) {
757 if ( ! $user_id = get_current_user_id() ) {
761 if ( is_super_admin() && ! is_user_member_of_blog() ) {
765 $settings = (string) get_user_option( 'user-settings', $user_id );
767 if ( isset( $_COOKIE['wp-settings-' . $user_id] ) ) {
768 $cookie = preg_replace( '/[^A-Za-z0-9=&_]/', '', $_COOKIE['wp-settings-' . $user_id] );
770 // No change or both empty
771 if ( $cookie == $settings )
774 $last_saved = (int) get_user_option( 'user-settings-time', $user_id );
775 $current = isset( $_COOKIE['wp-settings-time-' . $user_id]) ? preg_replace( '/[^0-9]/', '', $_COOKIE['wp-settings-time-' . $user_id] ) : 0;
777 // The cookie is newer than the saved value. Update the user_option and leave the cookie as-is
778 if ( $current > $last_saved ) {
779 update_user_option( $user_id, 'user-settings', $cookie, false );
780 update_user_option( $user_id, 'user-settings-time', time() - 5, false );
785 // The cookie is not set in the current browser or the saved value is newer.
786 $secure = ( 'https' === parse_url( site_url(), PHP_URL_SCHEME ) );
787 setcookie( 'wp-settings-' . $user_id, $settings, time() + YEAR_IN_SECONDS, SITECOOKIEPATH, null, $secure );
788 setcookie( 'wp-settings-time-' . $user_id, time(), time() + YEAR_IN_SECONDS, SITECOOKIEPATH, null, $secure );
789 $_COOKIE['wp-settings-' . $user_id] = $settings;
793 * Retrieve user interface setting value based on setting name.
797 * @param string $name The name of the setting.
798 * @param string $default Optional default value to return when $name is not set.
799 * @return mixed the last saved user setting or the default value/false if it doesn't exist.
801 function get_user_setting( $name, $default = false ) {
802 $all_user_settings = get_all_user_settings();
804 return isset( $all_user_settings[$name] ) ? $all_user_settings[$name] : $default;
808 * Add or update user interface setting.
810 * Both $name and $value can contain only ASCII letters, numbers and underscores.
811 * This function has to be used before any output has started as it calls setcookie().
815 * @param string $name The name of the setting.
816 * @param string $value The value for the setting.
817 * @return bool|void true if set successfully/false if not.
819 function set_user_setting( $name, $value ) {
820 if ( headers_sent() ) {
824 $all_user_settings = get_all_user_settings();
825 $all_user_settings[$name] = $value;
827 return wp_set_all_user_settings( $all_user_settings );
831 * Delete user interface settings.
833 * Deleting settings would reset them to the defaults.
834 * This function has to be used before any output has started as it calls setcookie().
838 * @param string $names The name or array of names of the setting to be deleted.
839 * @return bool|void true if deleted successfully/false if not.
841 function delete_user_setting( $names ) {
842 if ( headers_sent() ) {
846 $all_user_settings = get_all_user_settings();
847 $names = (array) $names;
850 foreach ( $names as $name ) {
851 if ( isset( $all_user_settings[$name] ) ) {
852 unset( $all_user_settings[$name] );
858 return wp_set_all_user_settings( $all_user_settings );
865 * Retrieve all user interface settings.
869 * @global array $_updated_user_settings
871 * @return array the last saved user settings or empty array.
873 function get_all_user_settings() {
874 global $_updated_user_settings;
876 if ( ! $user_id = get_current_user_id() ) {
880 if ( isset( $_updated_user_settings ) && is_array( $_updated_user_settings ) ) {
881 return $_updated_user_settings;
884 $user_settings = array();
886 if ( isset( $_COOKIE['wp-settings-' . $user_id] ) ) {
887 $cookie = preg_replace( '/[^A-Za-z0-9=&_]/', '', $_COOKIE['wp-settings-' . $user_id] );
889 if ( strpos( $cookie, '=' ) ) { // '=' cannot be 1st char
890 parse_str( $cookie, $user_settings );
893 $option = get_user_option( 'user-settings', $user_id );
895 if ( $option && is_string( $option ) ) {
896 parse_str( $option, $user_settings );
900 $_updated_user_settings = $user_settings;
901 return $user_settings;
905 * Private. Set all user interface settings.
909 * @global array $_updated_user_settings
911 * @param array $user_settings
914 function wp_set_all_user_settings( $user_settings ) {
915 global $_updated_user_settings;
917 if ( ! $user_id = get_current_user_id() ) {
921 if ( is_super_admin() && ! is_user_member_of_blog() ) {
926 foreach ( $user_settings as $name => $value ) {
927 $_name = preg_replace( '/[^A-Za-z0-9_]+/', '', $name );
928 $_value = preg_replace( '/[^A-Za-z0-9_]+/', '', $value );
930 if ( ! empty( $_name ) ) {
931 $settings .= $_name . '=' . $_value . '&';
935 $settings = rtrim( $settings, '&' );
936 parse_str( $settings, $_updated_user_settings );
938 update_user_option( $user_id, 'user-settings', $settings, false );
939 update_user_option( $user_id, 'user-settings-time', time(), false );
945 * Delete the user settings of the current user.
949 function delete_all_user_settings() {
950 if ( ! $user_id = get_current_user_id() ) {
954 update_user_option( $user_id, 'user-settings', '', false );
955 setcookie( 'wp-settings-' . $user_id, ' ', time() - YEAR_IN_SECONDS, SITECOOKIEPATH );
959 * Retrieve site option value based on name of option.
967 * @param string $option Name of option to retrieve. Expected to not be SQL-escaped.
968 * @param mixed $default Optional value to return if option doesn't exist. Default false.
969 * @param bool $use_cache Whether to use cache. Multisite only. Default true.
970 * @return mixed Value set for the option.
972 function get_site_option( $option, $default = false, $use_cache = true ) {
976 * Filter an existing site option before it is retrieved.
978 * The dynamic portion of the hook name, `$option`, refers to the option name.
980 * Passing a truthy value to the filter will effectively short-circuit retrieval,
981 * returning the passed value instead.
983 * @since 2.9.0 As 'pre_site_option_' . $key
986 * @param mixed $pre_option The default value to return if the option does not exist.
988 $pre = apply_filters( 'pre_site_option_' . $option, false );
990 if ( false !== $pre )
993 // prevent non-existent options from triggering multiple queries
994 $notoptions_key = "{$wpdb->siteid}:notoptions";
995 $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
997 if ( isset( $notoptions[$option] ) ) {
1000 * Filter a specific default site option.
1002 * The dynamic portion of the hook name, `$option`, refers to the option name.
1006 * @param mixed $default The value to return if the site option does not exist
1009 return apply_filters( 'default_site_option_' . $option, $default );
1012 if ( ! is_multisite() ) {
1014 /** This filter is documented in wp-includes/option.php */
1015 $default = apply_filters( 'default_site_option_' . $option, $default );
1016 $value = get_option($option, $default);
1018 $cache_key = "{$wpdb->siteid}:$option";
1020 $value = wp_cache_get($cache_key, 'site-options');
1022 if ( !isset($value) || (false === $value) ) {
1023 $row = $wpdb->get_row( $wpdb->prepare("SELECT meta_value FROM $wpdb->sitemeta WHERE meta_key = %s AND site_id = %d", $option, $wpdb->siteid ) );
1025 // Has to be get_row instead of get_var because of funkiness with 0, false, null values
1026 if ( is_object( $row ) ) {
1027 $value = $row->meta_value;
1028 $value = maybe_unserialize( $value );
1029 wp_cache_set( $cache_key, $value, 'site-options' );
1031 if ( ! is_array( $notoptions ) ) {
1032 $notoptions = array();
1034 $notoptions[$option] = true;
1035 wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
1037 /** This filter is documented in wp-includes/option.php */
1038 $value = apply_filters( 'default_site_option_' . $option, $default );
1044 * Filter the value of an existing site option.
1046 * The dynamic portion of the hook name, `$option`, refers to the option name.
1048 * @since 2.9.0 As 'site_option_' . $key
1051 * @param mixed $value Value of site option.
1053 return apply_filters( 'site_option_' . $option, $value );
1057 * Add a new site option.
1059 * Existing options will not be updated. Note that prior to 3.3 this wasn't the case.
1065 * @global wpdb $wpdb
1067 * @param string $option Name of option to add. Expected to not be SQL-escaped.
1068 * @param mixed $value Optional. Option value, can be anything. Expected to not be SQL-escaped.
1069 * @return bool False if option was not added and true if option was added.
1071 function add_site_option( $option, $value ) {
1074 wp_protect_special_option( $option );
1077 * Filter the value of a specific site option before it is added.
1079 * The dynamic portion of the hook name, `$option`, refers to the option name.
1081 * @since 2.9.0 As 'pre_add_site_option_' . $key
1084 * @param mixed $value Value of site option.
1086 $value = apply_filters( 'pre_add_site_option_' . $option, $value );
1088 $notoptions_key = "{$wpdb->siteid}:notoptions";
1090 if ( !is_multisite() ) {
1091 $result = add_option( $option, $value );
1093 $cache_key = "{$wpdb->siteid}:$option";
1095 // Make sure the option doesn't already exist. We can check the 'notoptions' cache before we ask for a db query
1096 $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
1097 if ( ! is_array( $notoptions ) || ! isset( $notoptions[$option] ) )
1098 if ( false !== get_site_option( $option ) )
1101 $value = sanitize_option( $option, $value );
1103 $serialized_value = maybe_serialize( $value );
1104 $result = $wpdb->insert( $wpdb->sitemeta, array('site_id' => $wpdb->siteid, 'meta_key' => $option, 'meta_value' => $serialized_value ) );
1109 wp_cache_set( $cache_key, $value, 'site-options' );
1111 // This option exists now
1112 $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); // yes, again... we need it to be fresh
1113 if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
1114 unset( $notoptions[$option] );
1115 wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
1122 * Fires after a specific site option has been successfully added.
1124 * The dynamic portion of the hook name, `$option`, refers to the option name.
1126 * @since 2.9.0 As "add_site_option_{$key}"
1129 * @param string $option Name of site option.
1130 * @param mixed $value Value of site option.
1132 do_action( "add_site_option_{$option}", $option, $value );
1135 * Fires after a site option has been successfully added.
1139 * @param string $option Name of site option.
1140 * @param mixed $value Value of site option.
1142 do_action( "add_site_option", $option, $value );
1150 * Removes site option by name.
1154 * @see delete_option()
1156 * @global wpdb $wpdb
1158 * @param string $option Name of option to remove. Expected to not be SQL-escaped.
1159 * @return bool True, if succeed. False, if failure.
1161 function delete_site_option( $option ) {
1164 // ms_protect_special_option( $option ); @todo
1167 * Fires immediately before a specific site option is deleted.
1169 * The dynamic portion of the hook name, `$option`, refers to the option name.
1173 do_action( 'pre_delete_site_option_' . $option );
1175 if ( !is_multisite() ) {
1176 $result = delete_option( $option );
1178 $row = $wpdb->get_row( $wpdb->prepare( "SELECT meta_id FROM {$wpdb->sitemeta} WHERE meta_key = %s AND site_id = %d", $option, $wpdb->siteid ) );
1179 if ( is_null( $row ) || !$row->meta_id )
1181 $cache_key = "{$wpdb->siteid}:$option";
1182 wp_cache_delete( $cache_key, 'site-options' );
1184 $result = $wpdb->delete( $wpdb->sitemeta, array( 'meta_key' => $option, 'site_id' => $wpdb->siteid ) );
1190 * Fires after a specific site option has been deleted.
1192 * The dynamic portion of the hook name, `$option`, refers to the option name.
1194 * @since 2.9.0 As "delete_site_option_{$key}"
1197 * @param string $option Name of the site option.
1199 do_action( "delete_site_option_{$option}", $option );
1202 * Fires after a site option has been deleted.
1206 * @param string $option Name of the site option.
1208 do_action( "delete_site_option", $option );
1216 * Update the value of a site option that was already added.
1220 * @see update_option()
1222 * @global wpdb $wpdb
1224 * @param string $option Name of option. Expected to not be SQL-escaped.
1225 * @param mixed $value Option value. Expected to not be SQL-escaped.
1226 * @return bool False if value was not updated and true if value was updated.
1228 function update_site_option( $option, $value ) {
1231 wp_protect_special_option( $option );
1233 $old_value = get_site_option( $option );
1236 * Filter a specific site option before its value is updated.
1238 * The dynamic portion of the hook name, `$option`, refers to the option name.
1240 * @since 2.9.0 As 'pre_update_site_option_' . $key
1243 * @param mixed $value New value of site option.
1244 * @param mixed $old_value Old value of site option.
1246 $value = apply_filters( 'pre_update_site_option_' . $option, $value, $old_value );
1248 if ( $value === $old_value )
1251 if ( false === $old_value )
1252 return add_site_option( $option, $value );
1254 $notoptions_key = "{$wpdb->siteid}:notoptions";
1255 $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
1256 if ( is_array( $notoptions ) && isset( $notoptions[$option] ) ) {
1257 unset( $notoptions[$option] );
1258 wp_cache_set( $notoptions_key, $notoptions, 'site-options' );
1261 if ( !is_multisite() ) {
1262 $result = update_option( $option, $value );
1264 $value = sanitize_option( $option, $value );
1266 $serialized_value = maybe_serialize( $value );
1267 $result = $wpdb->update( $wpdb->sitemeta, array( 'meta_value' => $serialized_value ), array( 'site_id' => $wpdb->siteid, 'meta_key' => $option ) );
1270 $cache_key = "{$wpdb->siteid}:$option";
1271 wp_cache_set( $cache_key, $value, 'site-options' );
1278 * Fires after the value of a specific site option has been successfully updated.
1280 * The dynamic portion of the hook name, `$option`, refers to the option name.
1282 * @since 2.9.0 As "update_site_option_{$key}"
1285 * @param string $option Name of site option.
1286 * @param mixed $value Current value of site option.
1287 * @param mixed $old_value Old value of site option.
1289 do_action( "update_site_option_{$option}", $option, $value, $old_value );
1292 * Fires after the value of a site option has been successfully updated.
1296 * @param string $option Name of site option.
1297 * @param mixed $value Current value of site option.
1298 * @param mixed $old_value Old value of site option.
1300 do_action( "update_site_option", $option, $value, $old_value );
1308 * Delete a site transient.
1312 * @param string $transient Transient name. Expected to not be SQL-escaped.
1313 * @return bool True if successful, false otherwise
1315 function delete_site_transient( $transient ) {
1318 * Fires immediately before a specific site transient is deleted.
1320 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
1324 * @param string $transient Transient name.
1326 do_action( 'delete_site_transient_' . $transient, $transient );
1328 if ( wp_using_ext_object_cache() ) {
1329 $result = wp_cache_delete( $transient, 'site-transient' );
1331 $option_timeout = '_site_transient_timeout_' . $transient;
1332 $option = '_site_transient_' . $transient;
1333 $result = delete_site_option( $option );
1335 delete_site_option( $option_timeout );
1340 * Fires after a transient is deleted.
1344 * @param string $transient Deleted transient name.
1346 do_action( 'deleted_site_transient', $transient );
1353 * Get the value of a site transient.
1355 * If the transient does not exist, does not have a value, or has expired,
1356 * then the return value will be false.
1360 * @see get_transient()
1362 * @param string $transient Transient name. Expected to not be SQL-escaped.
1363 * @return mixed Value of transient.
1365 function get_site_transient( $transient ) {
1368 * Filter the value of an existing site transient.
1370 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
1372 * Passing a truthy value to the filter will effectively short-circuit retrieval,
1373 * returning the passed value instead.
1377 * @param mixed $pre_site_transient The default value to return if the site transient does not exist.
1378 * Any value other than false will short-circuit the retrieval
1379 * of the transient, and return the returned value.
1381 $pre = apply_filters( 'pre_site_transient_' . $transient, false );
1383 if ( false !== $pre )
1386 if ( wp_using_ext_object_cache() ) {
1387 $value = wp_cache_get( $transient, 'site-transient' );
1389 // Core transients that do not have a timeout. Listed here so querying timeouts can be avoided.
1390 $no_timeout = array('update_core', 'update_plugins', 'update_themes');
1391 $transient_option = '_site_transient_' . $transient;
1392 if ( ! in_array( $transient, $no_timeout ) ) {
1393 $transient_timeout = '_site_transient_timeout_' . $transient;
1394 $timeout = get_site_option( $transient_timeout );
1395 if ( false !== $timeout && $timeout < time() ) {
1396 delete_site_option( $transient_option );
1397 delete_site_option( $transient_timeout );
1402 if ( ! isset( $value ) )
1403 $value = get_site_option( $transient_option );
1407 * Filter the value of an existing site transient.
1409 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
1413 * @param mixed $value Value of site transient.
1415 return apply_filters( 'site_transient_' . $transient, $value );
1419 * Set/update the value of a site transient.
1421 * You do not need to serialize values, if the value needs to be serialize, then
1422 * it will be serialized before it is set.
1426 * @see set_transient()
1428 * @param string $transient Transient name. Expected to not be SQL-escaped. Must be
1429 * 40 characters or fewer in length.
1430 * @param mixed $value Transient value. Expected to not be SQL-escaped.
1431 * @param int $expiration Optional. Time until expiration in seconds. Default 0.
1432 * @return bool False if value was not set and true if value was set.
1434 function set_site_transient( $transient, $value, $expiration = 0 ) {
1437 * Filter the value of a specific site transient before it is set.
1439 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
1443 * @param mixed $value Value of site transient.
1445 $value = apply_filters( 'pre_set_site_transient_' . $transient, $value );
1447 $expiration = (int) $expiration;
1449 if ( wp_using_ext_object_cache() ) {
1450 $result = wp_cache_set( $transient, $value, 'site-transient', $expiration );
1452 $transient_timeout = '_site_transient_timeout_' . $transient;
1453 $option = '_site_transient_' . $transient;
1454 if ( false === get_site_option( $option ) ) {
1456 add_site_option( $transient_timeout, time() + $expiration );
1457 $result = add_site_option( $option, $value );
1460 update_site_option( $transient_timeout, time() + $expiration );
1461 $result = update_site_option( $option, $value );
1467 * Fires after the value for a specific site transient has been set.
1469 * The dynamic portion of the hook name, `$transient`, refers to the transient name.
1473 * @param mixed $value Site transient value.
1474 * @param int $expiration Time until expiration in seconds. Default 0.
1476 do_action( 'set_site_transient_' . $transient, $value, $expiration );
1479 * Fires after the value for a site transient has been set.
1483 * @param string $transient The name of the site transient.
1484 * @param mixed $value Site transient value.
1485 * @param int $expiration Time until expiration in seconds. Default 0.
1487 do_action( 'setted_site_transient', $transient, $value, $expiration );