set_transient( string $transient, mixed $value, int $expiration ): bool

Sets/updates the value of a transient.

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

$transientstringrequired

Transient name. Expected to not be SQL-escaped.
Must be 172 characters or fewer in length.

$valuemixedrequired

Transient value. Must be serializable if non-scalar.
Expected to not be SQL-escaped.

$expirationintoptional

Time until expiration in seconds. Default 0 (no expiration).

Return

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

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;
		wp_prime_option_caches( array( $transient_option, $transient_timeout ) );

		if ( false === get_option( $transient_option ) ) {
			$autoload = true;
			if ( $expiration ) {
				$autoload = false;
				add_option( $transient_timeout, time() + $expiration, '', false );
			}
			$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, '', false );
					$result = add_option( $transient_option, $value, '', false );
					$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 6.8.0
		 *
		 * @param string $transient The name of the transient.
		 * @param mixed $value Transient value.
		 * @param int $expiration Time until expiration in seconds.
		 */
		do_action( 'set_transient', $transient, $value, $expiration );

		/**
		 * Fires after the transient is set.
		 *
		 * @since 3.0.0
		 * @since 3.6.0 The `$value` and `$expiration` parameters were added.
		 * @deprecated 6.8.0 Use 'set_transient' instead.
		 *
		 * @param string $transient The name of the transient.
		 * @param mixed $value Transient value.
		 * @param int $expiration Time until expiration in seconds.
		 */
		do_action_deprecated( 'setted_transient', array( $transient, $value, $expiration ), '6.8.0', 'set_transient' );
	}

	return $result;
}

View all references View on Trac View on GitHub

Hooks

apply_filters( “expiration_of_transient_{$transient}”, , ,  )

Filters the expiration for a transient before its value is set.

apply_filters( “pre_set_transient_{$transient}”, , ,  )

Filters a specific transient before its value is set.

do_action_deprecated( ‘setted_transient’, , ,  )

Fires after the transient is set.

do_action( ‘set_transient’, , ,  )

Fires after the value for a transient has been set.

do_action( “set_transient_{$transient}”, , ,  )

Fires after the value for a specific transient has been set.

Related

Changelog

User Contributed Notes

1. Skip to note 7 content

   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:

   $initial = time();
   set_transient( 'foo', 'bar', 300 );
   sleep( 10 );
   $update = time();
   set_transient( 'foo', 'barbar' );

   In this case, the expiration would remain as $initial + 300 (and not change to $update + 300, or never expires), because the second set_transient() call does not include an $expiration value (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 $expiration parameter) is made.

2. Skip to note 8 content

   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.

   // Set the arguments for the custom query
   $args = array(
    'post_type' => 'post',
    'posts_per_page' => 5,
    'orderby' => 'date',
    'order' => 'DESC'
   );
   $latest_post = new WP_Query( $args );
   
   // Save the results in a transient named latest_5_posts
   set_transient( 'latest_5_posts', $latest_post, DAY_IN_SECONDS );

   To know more about how to get posts and custom post type items read the documentation of WP_Query.

   • This might seem like a good idea but caching a WP_Query in 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.

     Tom J Nowell 5 years ago
3. Skip to note 9 content

   Saving the $special_query_results object for 12 hours

   set_transient( 'special_query_results', $special_query_results, 12 * HOUR_IN_SECONDS );

4. Skip to note 10 content

   WordPress saves the transients expiration time in the form of a UNIX timestamp. When you look for the

   _transient_timeout_{$transient}

   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

5. Skip to note 11 content

   Beware! When you use a persistent object cache plugin, WordPress core stores transients in that persistent object cache, not in the wp_options table.

   Avoid the mistake of setting a transient by using the update_option API, or by writing something directly into the options table.

6. Skip to note 12 content

   Note that WP_CACHE has to be true in wp-config.php for transients to work:

   define('WP_CACHE', true);

   • Correction: WP_CACHE is not required to be true for transients to work.

     Vijay Hardaha 4 years ago