get_site_transient()
云策文档标注
概述
get_site_transient() 函数用于检索站点瞬态（site transient）的值。如果瞬态不存在、无值或已过期，则返回 false。该函数支持通过过滤器钩子进行值修改，并处理外部对象缓存和数据库存储。
关键要点
- 函数返回瞬态的值，若瞬态无效则返回 false。
- 参数 $transient 为瞬态名称，不应进行 SQL 转义。
- 支持 pre_site_transient_{$transient} 过滤器，允许在检索前修改返回值。
- 根据 wp_using_ext_object_cache() 或 wp_installing() 状态，选择从缓存或数据库获取数据。
- 核心瞬态（如 update_core）无超时设置，其他瞬态则检查超时选项。
代码示例
function get_site_transient( $transient ) {
$pre = apply_filters( "pre_site_transient_{$transient}", false, $transient );
if ( false !== $pre ) {
return $pre;
}
if ( wp_using_ext_object_cache() || wp_installing() ) {
$value = wp_cache_get( $transient, 'site-transient' );
} else {
$no_timeout = array( 'update_core', 'update_plugins', 'update_themes' );
$transient_option = '_site_transient_' . $transient;
if ( ! in_array( $transient, $no_timeout, true ) ) {
$transient_timeout = '_site_transient_timeout_' . $transient;
wp_prime_site_option_caches( array( $transient_option, $transient_timeout ) );
$timeout = get_site_option( $transient_timeout );
if ( false !== $timeout && $timeout < time() ) {
delete_site_option( $transient_option );
delete_site_option( $transient_timeout );
return false;
}
}
$value = get_site_option( $transient_option );
}
return apply_filters( "site_transient_{$transient}", $value, $transient );
}注意事项
- 瞬态名称不应包含 SQL 转义字符，以避免潜在问题。
- 使用外部对象缓存时，瞬态通过 wp_cache_get() 获取，否则依赖数据库选项表。
- 核心更新相关瞬态（如 update_core）没有超时机制，需特殊处理。
- 过滤器钩子 pre_site_transient_{$transient} 和 site_transient_{$transient} 可用于自定义逻辑。
原文内容
Retrieves the value of a site transient.
Description
If the transient does not exist, does not have a value, or has expired, then the return value will be false.
See also
Parameters
$transientstringrequired-
Transient name. Expected to not be SQL-escaped.
Source
function get_site_transient( $transient ) {
/**
* Filters the value of an existing site transient before it is retrieved.
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* Returning a value other than boolean false will short-circuit retrieval and
* return that value instead.
*
* @since 2.9.0
* @since 4.4.0 The `$transient` parameter was added.
*
* @param mixed $pre_site_transient The default value to return if the site transient does not exist.
* Any value other than false will short-circuit the retrieval
* of the transient, and return that value.
* @param string $transient Transient name.
*/
$pre = apply_filters( "pre_site_transient_{$transient}", false, $transient );
if ( false !== $pre ) {
return $pre;
}
if ( wp_using_ext_object_cache() || wp_installing() ) {
$value = wp_cache_get( $transient, 'site-transient' );
} else {
// Core transients that do not have a timeout. Listed here so querying timeouts can be avoided.
$no_timeout = array( 'update_core', 'update_plugins', 'update_themes' );
$transient_option = '_site_transient_' . $transient;
if ( ! in_array( $transient, $no_timeout, true ) ) {
$transient_timeout = '_site_transient_timeout_' . $transient;
wp_prime_site_option_caches( array( $transient_option, $transient_timeout ) );
$timeout = get_site_option( $transient_timeout );
if ( false !== $timeout && $timeout < time() ) {
delete_site_option( $transient_option );
delete_site_option( $transient_timeout );
$value = false;
}
}
if ( ! isset( $value ) ) {
$value = get_site_option( $transient_option );
}
}
/**
* Filters the value of an existing site transient.
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* @since 2.9.0
* @since 4.4.0 The `$transient` parameter was added.
*
* @param mixed $value Value of site transient.
* @param string $transient Transient name.
*/
return apply_filters( "site_transient_{$transient}", $value, $transient );
}
Hooks
- apply_filters( “pre_site_transient_{$transient}”, mixed $pre_site_transient, string $transient )
-
Filters the value of an existing site transient before it is retrieved.
- apply_filters( “site_transient_{$transient}”, mixed $value, string $transient )
-
Filters the value of an existing site transient.
Changelog
| Version | Description |
|---|---|
| 2.9.0 | Introduced. |