wpseek.com
A WordPress-centric search engine for devs and theme authors
get_option › WordPress Function
Since1.5.0
Deprecatedn/a
› get_option ( $option, $default_value = false )
| Parameters: (2) |
|
| Returns: |
|
| Defined at: |
|
| Codex: |
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 booleanfalse 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 'preoption$option'},
{@see 'defaultoption$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
}Source
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 );
}