set_transient( string $transient, mixed $value, int $expiration ): bool
Sets/updates the value of a transient.
Contents
Description
You do not need to serialize values. If the value needs to be serialized, then it will be serialized before it is set.
Parameters
-
$transientstring Required -
Transient name. Expected to not be SQL-escaped.
Must be 172 characters or fewer in length. -
$valuemixed Required -
Transient value. Must be serializable if non-scalar.
Expected to not be SQL-escaped. -
$expirationint Optional -
Time until expiration in seconds. Default 0 (no expiration).
Return
bool True if the value was set, false otherwise.
More Information
For parameter $transient, if memcached is not enabled the name should be 172 characters or less in length as WordPress will prefix your name with “_transient_” or “_transient_timeout_” in the options table (depending on whether it expires or not). Longer key names will silently fail. See Trac #15058.
If a transient exists, this function will update the transient’s expiration time.
NB: transients that never expire are autoloaded, whereas transients with an expiration time are not autoloaded. Consider this when adding transients that may not be needed on every page, and thus do not need to be autoloaded, impacting page performance.
WordPress provides some constants for specifying time in seconds. Instead of multiplying out integers, see Transients_API#Using_Time_Constants.
Transient key names are limited to 191 characters due to the database schema in the wp_options table ( option_name: varchar(191) ).
In WordPress versions previous to 4.4, the length limitation was 45 in set_transient (now 172) and 64 in the database (now 191).
Source
File: wp-includes/option.php.
View all references
function set_transient( $transient, $value, $expiration = 0 ) {
$expiration = (int) $expiration;
/**
* Filters a specific transient before its value is set.
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* @since 3.0.0
* @since 4.2.0 The `$expiration` parameter was added.
* @since 4.4.0 The `$transient` parameter was added.
*
* @param mixed $value New value of transient.
* @param int $expiration Time until expiration in seconds.
* @param string $transient Transient name.
*/
$value = apply_filters( "pre_set_transient_{$transient}", $value, $expiration, $transient );
/**
* Filters the expiration for a transient before its value is set.
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* @since 4.4.0
*
* @param int $expiration Time until expiration in seconds. Use 0 for no expiration.
* @param mixed $value New value of transient.
* @param string $transient Transient name.
*/
$expiration = apply_filters( "expiration_of_transient_{$transient}", $expiration, $value, $transient );
if ( wp_using_ext_object_cache() || wp_installing() ) {
$result = wp_cache_set( $transient, $value, 'transient', $expiration );
} else {
$transient_timeout = '_transient_timeout_' . $transient;
$transient_option = '_transient_' . $transient;
if ( false === get_option( $transient_option ) ) {
$autoload = 'yes';
if ( $expiration ) {
$autoload = 'no';
add_option( $transient_timeout, time() + $expiration, '', 'no' );
}
$result = add_option( $transient_option, $value, '', $autoload );
} else {
// If expiration is requested, but the transient has no timeout option,
// delete, then re-create transient rather than update.
$update = true;
if ( $expiration ) {
if ( false === get_option( $transient_timeout ) ) {
delete_option( $transient_option );
add_option( $transient_timeout, time() + $expiration, '', 'no' );
$result = add_option( $transient_option, $value, '', 'no' );
$update = false;
} else {
update_option( $transient_timeout, time() + $expiration );
}
}
if ( $update ) {
$result = update_option( $transient_option, $value );
}
}
}
if ( $result ) {
/**
* Fires after the value for a specific transient has been set.
*
* The dynamic portion of the hook name, `$transient`, refers to the transient name.
*
* @since 3.0.0
* @since 3.6.0 The `$value` and `$expiration` parameters were added.
* @since 4.4.0 The `$transient` parameter was added.
*
* @param mixed $value Transient value.
* @param int $expiration Time until expiration in seconds.
* @param string $transient The name of the transient.
*/
do_action( "set_transient_{$transient}", $value, $expiration, $transient );
/**
* Fires after the value for a transient has been set.
*
* @since 3.0.0
* @since 3.6.0 The `$value` and `$expiration` parameters were added.
*
* @param string $transient The name of the transient.
* @param mixed $value Transient value.
* @param int $expiration Time until expiration in seconds.
*/
do_action( 'setted_transient', $transient, $value, $expiration );
}
return $result;
}
Hooks
-
apply_filters( "expiration_of_transient_{$transient}",
int $expiration ,mixed $value ,string $transient ) -
Filters the expiration for a transient before its value is set.
-
apply_filters( "pre_set_transient_{$transient}",
mixed $value ,int $expiration ,string $transient ) -
Filters a specific transient before its value is set.
-
do_action( 'setted_transient',
string $transient ,mixed $value ,int $expiration ) -
Fires after the value for a transient has been set.
-
do_action( "set_transient_{$transient}",
mixed $value ,int $expiration ,string $transient ) -
Fires after the value for a specific transient has been set.
Changelog
| Version | Description |
|---|---|
| 2.8.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Unless you’re using an external object cache, when using
set_transient()to update an existing transient that has an existing expiration, not providing an expiration value will maintain the existing expiration.For example:
In this case, the expiration would remain as
$initial + 300(and not change to$update + 300, or never expires), because the secondset_transient()call does not include an$expirationvalue (only the transient’s value is updated).Be careful though, because you may unintentionally set a transient to never expire, if the transient expired before the second call (without the
$expirationparameter) is made.This example shows how to set a transient with the latest five blog posts. It expires after one day.
It uses time constants to set the expiration time.
To know more about how to get posts and custom post type items read the documentation of WP_Query.
Top ↑
Feedback
This might seem like a good idea but caching a
WP_Queryin a transient like this will cause a performance hit. This is because WP_Query bulk fetches the post objects, their terms, and their taxonomies in advance into WP_Cache to avoid database queries. But when the transient is used and WP_Query is recreated, none of that has happened. As a result WordPress has to pause constantly to make small database queries to fetch the post meta and terms that were previously cached. Instead store the result as an array of post IDs. Post IDs are super fast to fetch and may even be in WP_Cache already. After all the most expensive part of the query is figuring out which post IDs match the desired results. — By Tom J Nowell —Saving the $special_query_results object for 12 hours
WordPress saves the transients expiration time in the form of a UNIX timestamp. When you look for the
option name in the options table of WordPress, it will look like 1636453079 which is in UNIX timestamp not in seconds.
See the code on GitHub
Note that
WP_CACHEhas to be true inwp-config.phpfor transients to work:Top ↑
Feedback
Correction: WP_CACHE is not required to be true for transients to work. — By Vijay Hardaha —