Understand Caching with WordPress Transients API

Why Use WordPress Transients for Caching

In a WordPress context, caching most often means “full page” caching: storing a full webpage just before it’s sent out to a visitor, so that the next visitor to ask for that page will get the stored version without your server having to rebuild it. This is the approach of many caching plugins, such as WP Super Cache. In some situations this is ideal, and can have a major impact on site speed.

You can improve performance by caching things other than full pages, such as slow results from remote servers like Facebook’s, or large database queries.

Understanding the WordPress Transients API

The WordPress Transients API creates its own, easy-to-use interface for the various means and methods of caching data in a given server environment, so that WordPress developers don’t have to worry too much about the specifics of that environment.

In-Memory Storage and In-Database Storage

As a note on how the Transients API actually works: when Memcached or other forms of caching aren’t available, WordPress stores the cached data in the options table of its regular database. This lets WordPress provide the same functionality as an in-memory cache—although, unfortunately, somewhat slower, since the objects are cached all the way in the MySQL database, and not in the server’s memory where they’re easier to get to.

Transients Should Be Transient!

These “caches” or “transients” aren’t meant to be permanent. (Permanent data should live in the Options API; see Mastering the Options API in WordPress.)

How to use the Transients API

The WordPress Transients API is quite simple: you first store a name-value pair, and then you retrieve it.

set_transient()

Here’s what setting a transient looks like:

$string = "Cache me for a day!";
$bool_response = set_transient( 'wpshout_cache_me', $string, 86400 );

get_transient()

Retrieving a transient for use looks like this:

$transient_string = get_transient( 'wpshout_cache_me' );

if ( false === $transient_string ) {
	return; // In real life we'd want to set_transient() here
}

echo '<h1>' . $transient_string . '</h1>';

An Example: Fun With Transients

Let’s look at how transients work, in a full-fledged example called “WPShout Cache Hard Math.”

How the Finished Product Works

Our plugin is a demo of object caching: it tells the server to do millions of complex calculations, and then to cache the results for ten seconds. So every ten seconds, the site loads painfully slowly—but in the seconds between, it loads quickly! That’s caching at work.

The Code

We’re about to show you a whole plugin file, in chunks. Each chunk comes immediately after the previous chunk, so if you copy-paste them all you’ll have a working—but silly and not-to-be-deployed—plugin.

This first section does a huge amount of calculations, and returns an array with two elements: the input value before the calculations, and the output value after them:

<?php
/*
Plugin Name: WPShout Cache Hard Math
*/

function wpshout_do_hard_math( $int ) {
	// $start is the starting integer
	$start = $int;

	// Insanely processing-intensive calculations
	$i = 0;
	while( $i < 100000 ) {
		$int = pow( sqrt( sqrt( sqrt( sqrt( $int) ) ) ), 16.0001);
		$i++;
	}

	// Return our array: what we started with and what resulted
	return array ( $start, $int );
}

This next section attempts to get the transient that is the result of the wpshout_do_hard_math() calculations. If it finds there’s no transient, it will try to set the transient, then get it. It then returns either the transient, or false if getting the transient failed:

function wpshout_get_hard_math_transient() {
	// Get the transient
	$result = get_transient( 'hard_math' );
	
	if ( false !== $result ) {
		// Transient exists, so return it
		return $result;
	}

	// Get array from doing "hard math" (on seconds elapsed in current minute)
	$mathed = wpshout_do_hard_math( date( 's' ) );

	// Attempt to set transient with array results; timeout is 10 seconds
	$bool_response = set_transient( 'hard_math', $mathed, 10 );

	if( false === $bool_response ) {
		// Setting the transient didn't work, so return false for failure
		return false;
	}

	// Transient is now set, so get it and return it
	return get_transient( 'hard_math' );
}

This section attempts to retrieve the transient. If it succeeds, it hooks into the_content to print a string containing the transient’s calculations at the top of the post’s content:

function wpshout_filter_content_with_hard_math_transient( $content ) {
	// Get the transient 
	$result = wpshout_get_hard_math_transient();

	// If transient isn't an array, just return content unaltered
	if ( ! is_array( $result ) ) {
		return $content;
	}

	// Prepend string with transient data to content and return it
	return '<p>(<small>I did some terrifyingly inefficient math on the number ' . ltrim( $result[0], '0' ) . ', and the result was: ' . $result[1] . '</small>)</p>' . $content;
}
add_filter( 'the_content', 'wpshout_filter_content_with_hard_math_transient' );

If you understood this example right away, you’re really getting WordPress at a deep level! If not, don’t worry too much about the specifics—just try to absorb the basic uses of get_transient() and set_transient() that this example exists to show off.

A More Practical Example Use Case for Transients

In case you’re having trouble picturing how transients could benefit a site (rather than make it virtually unusable), we’ll link to a very beautiful real-world example of caching a nav menu, which includes a use of delete_transient() to invalidate the cache when the nav menu changes: https://leaves-and-love.net/blog/transients-speed-up-wordpress-theme/.

What We’ve Learned about WordPress Transients

We’ve learned how and why to use transients in WordPress, and gotten deep into an example that shows them at work. We’re a lot better-equipped to cache expensive operations in WordPress—and our sites will be faster for it. Onward!