WordPress Version: 6.4
/**
* Option API
*
* @package WordPress
* @subpackage Option
*/
/**
* Retrieves an option value based on an option name.
*
* If the option does not exist, and a default value is not provided,
* boolean false is returned. This could be used to check whether you need
* to initialize an option during installation of a plugin, however that
* can be done better by using add_option() which will not overwrite
* existing options.
*
* Not initializing an option and using boolean `false` as a return value
* is a bad practice as it triggers an additional database query.
*
* The type of the returned value can be different from the type that was passed
* when saving or updating the option. If the option value was serialized,
* then it will be unserialized when it is returned. In this case the type will
* be the same. For example, storing a non-scalar value like an array will
* return the same array.
*
* In most cases non-string scalar and null values will be converted and returned
* as string equivalents.
*
* Exceptions:
*
* 1. When the option has not been saved in the database, the `$default_value` value
* is returned if provided. If not, boolean `false` is returned.
* 2. When one of the Options API filters is used: {@see 'pre_option_$option'},
* {@see 'default_option_$option'}, or {@see 'option_$option'}, the returned
* value may not match the expected type.
* 3. When the option has just been saved in the database, and get_option()
* is used right after, non-string scalar and null values are not converted to
* string equivalents and the original type is returned.
*
* Examples:
*
* When adding options like this: `add_option( 'my_option_name', 'value' )`
* and then retrieving them with `get_option( 'my_option_name' )`, the returned
* values will be:
*
* - `false` returns `string(0) ""`
* - `true` returns `string(1) "1"`
* - `0` returns `string(1) "0"`
* - `1` returns `string(1) "1"`
* - `'0'` returns `string(1) "0"`
* - `'1'` returns `string(1) "1"`
* - `null` returns `string(0) ""`
*
* When adding options with non-scalar values like
* `add_option( 'my_array', array( false, 'str', null ) )`, the returned value
* will be identical to the original as it is serialized before saving
* it in the database:
*
* array(3) {
* [0] => bool(false)
* [1] => string(3) "str"
* [2] => NULL
* }
*
* @since 1.5.0
*
* @global wpdb $wpdb WordPress database abstraction object.
*
* @param string $option Name of the option to retrieve. Expected to not be SQL-escaped.
* @param mixed $default_value Optional. Default value to return if the option does not exist.
* @return mixed Value of the option. A value of any type may be returned, including
* scalar (string, boolean, float, integer), null, array, object.
* Scalar and null values will be returned as strings as long as they originate
* from a database stored option value. If there is no option in the database,
* boolean `false` is returned.
*/
function get_option($option, $default_value = false)
{
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 get_option($deprecated_keys[$option], $default_value);
}
/**
* Filters the value of an existing option before it is retrieved.
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* Returning a value other than false from the filter will short-circuit retrieval
* and return that value instead.
*
* @since 1.5.0
* @since 4.4.0 The `$option` parameter was added.
* @since 4.9.0 The `$default_value` parameter was added.
*
* @param mixed $pre_option The value to return instead of the option value. This differs from
* `$default_value`, which is used as the fallback value in the event
* the option doesn't exist elsewhere in get_option().
* Default false (to skip past the short-circuit).
* @param string $option Option name.
* @param mixed $default_value The fallback value to return if the option does not exist.
* Default false.
*/
$pre = apply_filters("pre_option_{$option}", false, $option, $default_value);
/**
* Filters the value of all existing options before it is retrieved.
*
* Returning a truthy value from the filter will effectively short-circuit retrieval
* and return the passed value instead.
*
* @since 6.1.0
*
* @param mixed $pre_option The value to return instead of the option value. This differs from
* `$default_value`, which is used as the fallback value in the event
* the option doesn't exist elsewhere in get_option().
* Default false (to skip past the short-circuit).
* @param string $option Name of the option.
* @param mixed $default_value The fallback value to return if the option does not exist.
* Default false.
*/
$pre = apply_filters('pre_option', $pre, $option, $default_value);
if (false !== $pre) {
return $pre;
}
if (defined('WP_SETUP_CONFIG')) {
return false;
}
// Distinguish between `false` as a default, and not passing one.
$passed_default = func_num_args() > 1;
if (!wp_installing()) {
$alloptions = wp_load_alloptions();
if (isset($alloptions[$option])) {
$value = $alloptions[$option];
} else {
$value = wp_cache_get($option, 'options');
if (false === $value) {
// Prevent non-existent options from triggering multiple queries.
$notoptions = wp_cache_get('notoptions', 'options');
// Prevent non-existent `notoptions` key from triggering multiple key lookups.
if (!is_array($notoptions)) {
$notoptions = array();
wp_cache_set('notoptions', $notoptions, 'options');
} elseif (isset($notoptions[$option])) {
/**
* Filters the default value for an option.
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* @since 3.4.0
* @since 4.4.0 The `$option` parameter was added.
* @since 4.7.0 The `$passed_default` parameter was added to distinguish between a `false` value and the default parameter value.
*
* @param mixed $default_value The default value to return if the option does not exist
* in the database.
* @param string $option Option name.
* @param bool $passed_default Was `get_option()` passed a default value?
*/
return apply_filters("default_option_{$option}", $default_value, $option, $passed_default);
}
$row = $wpdb->get_row($wpdb->prepare("SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1", $option));
// Has to be get_row() instead of get_var() because of funkiness with 0, false, null values.
if (is_object($row)) {
$value = $row->option_value;
wp_cache_add($option, $value, 'options');
} else {
// Option does not exist, so we must cache its non-existence.
$notoptions[$option] = true;
wp_cache_set('notoptions', $notoptions, 'options');
/** This filter is documented in wp-includes/option.php */
return apply_filters("default_option_{$option}", $default_value, $option, $passed_default);
}
}
}
} else {
$suppress = $wpdb->suppress_errors();
$row = $wpdb->get_row($wpdb->prepare("SELECT option_value FROM {$wpdb->options} WHERE option_name = %s LIMIT 1", $option));
$wpdb->suppress_errors($suppress);
if (is_object($row)) {
$value = $row->option_value;
} else {
/** This filter is documented in wp-includes/option.php */
return apply_filters("default_option_{$option}", $default_value, $option, $passed_default);
}
}
// If home is not set, use siteurl.
if ('home' === $option && '' === $value) {
return get_option('siteurl');
}
if (in_array($option, array('siteurl', 'home', 'category_base', 'tag_base'), true)) {
$value = untrailingslashit($value);
}
/**
* Filters the value of an existing option.
*
* The dynamic portion of the hook name, `$option`, refers to the option name.
*
* @since 1.5.0 As 'option_' . $setting
* @since 3.0.0
* @since 4.4.0 The `$option` parameter was added.
*
* @param mixed $value Value of the option. If stored serialized, it will be
* unserialized prior to being returned.
* @param string $option Option name.
*/
return apply_filters("option_{$option}", maybe_unserialize($value), $option);
}