When I started building WordPress sites over 10 years ago things were much simpler than they are now. Install WordPress and help the client get their content into the site. Build them a theme and install some plugins. Maybe build a custom plugin if it was a complex site.

Today though it’s much more likely that I’ll be building multiple custom plugins and in a few of them calling out to some API to get the information we’ll use on the site. Then we need to make sure the site is fast, and it almost always comes down to lots of API calls that are slowing down the site.

Today we’re going to look at one of the built-in methods that WordPress provides developers to help speed up those API calls, by caching the results with the WordPress Transients API.

What are Transients Anyway?

WordPress transients are a way of storing information in your database (or your object cache) for a limited amount of time. We’re going to focus on saving data that comes from external API calls today, but the WordPress Transients API can be used for any type of data that takes a while to generate, like a long WP Query call that doesn’t need to get live data.

When you’re accessing an API without any form of caching, your site is going to call that API for each user that visits each page on your site. Each user will have to wait for the API call to complete before the content renders on their screen. Not only is waiting annoying for users, but it can also take up huge amounts of resources on your server if you have a site with even medium amounts of traffic. 

If you’re unfamiliar with an API call data flow, a basic API request would involve these steps.

This is where transients can step in. WordPress transients are a way of storing information in your database (or your object cache but we’ll get to that) for a limited amount of time. When using transients the above logic flow would change slightly.

The reason that transients are awesome is that they take out the whole waiting for information part of the equation and let your users get back to viewing your content. A simple way to use this would be to use your email marketing list API to get the number of subscribers that you have to your list and then save that data so it can be displayed on your site. Updating this every few hours, or days still shows people the size of your list without an API request every time someone visits a page on your site.

There are six functions that deal specifically with the Transients API.

We’re going to focus on set_transient, get_transient, and delete_transient for this tutorial. The site variations do the same thing, except they’re for making a transient available site-wide in a WordPress Multisite environment.

When you set your transient you need three parameters:

1. key: The name of the transient
2. value: The data you want to store
3. timeframe: The time in seconds until the transient should expire

One big note here is that if you don’t set the timeframe for your transient it will be autoloaded for every page load for each user and it will never expire. I have never encountered a situation where this was the behaviour I wanted with my transients. So make sure you set a timeframe for your transients.

To use get_transient or delete_transient you only need the key to use the corresponding functions.

How to Use Transients

Now that we have a bit of an idea of what a transient is and what it can do let’s take a look at how to use transients in your WordPress code. An easy API to use for this is Github’s REST API. We’re going to use it today to get a list of my public repositories. To do this for your Github account you’ll need to generate a personal access token

I’m going to assume you have some understanding of the HTTP API built into WordPress. We’re going to be using it to make our calls to YouTube.

To make a basic request you’ll need the code below. Make sure you add your username and access token.

function github_repo(){

        $url="https://api.github.com/user/repos?type=public";
        $username="YOUR_USER_NAME";
        $token = 'ACCESS_TOKEN';

        $args = array(
            'headers' => array(
                'Authorization' => 'Basic '. base64_encode( $username.':'.$token ),
            ),
        );

        $response = wp_remote_request( $url, $args );
        $repos = json_decode( $response['body'], true );

        $html="

“;
foreach( $repos as $r ){
$html .= ‘
• ‘. esc_attr( $r[‘name’] ) .’

‘;
}
$html .= ‘

‘;

return $html;
}

Currently, that code will call out the Github API every time the page loads so let’s add a transient to this so that we can save the final HTML and simply get it and show it if the transient is found.

  function github_repo(){

        $html = get_transient( 'repository_html' );

        if ( empty( $html ) ){

            $url="https://api.github.com/user/repos?type=public";
          $username="YOUR_USER_NAME";
          $token = 'ACCESS_TOKEN';

            $args = array(
                'headers' => array(
                    'Authorization' => 'Basic '. 
base64_encode( $username.':'.$token ),
                ),
            );

            $response = wp_remote_request( $url, $args );
            $repos = json_decode( $response['body'], true );

            $html="

“;
foreach( $repos as $r ){
$html .= ‘
• ‘. esc_attr( $r[‘name’] ) .’

‘;
}
$html .= ‘

‘;

set_transient( ‘repository_html’, $html, DAY_IN_SECONDS );
}

return $html;
}

Now the code above checks to see if we have a transient set. If we find it, we simply move to the end and return it so it can be displayed. If we don’t find it, we run through our API call and generate the list of public repositories. Then we save the generated HTML to our transient so we don’t have to call the API next time.

The code above saved 2 HTTP requests when our transient was populated and around 200ms on page load. While this isn’t a huge speed increase in the grand scheme of things, many other API calls will take much longer and have more data so your savings will be bigger.

Pitfalls and Tips for Transients

There are a few things that you need to make sure you take into account when you’re dealing with transients. First, you must remember that a transient can disappear at any time. Yes, that means even if it was called 15 seconds ago and you told it to stay around for a month it might be gone. For really big API calls I’ve occasionally saved the results to a regular option in WordPress and if my transient fails grabbed what I wanted out of the option to display it. Then we generate the transient again in the background with the shutdown action hook so that next time we can get the data out of our site cache.

If you’re dealing with an API that always needs a fresh response you wouldn’t use transients to speed it up. This could be a payment gateway where you need to ensure that you get the real payment status for a client instead of some cached value. Make sure that any data you’re saving in a transient needs to be shown again to multiple users over time.

When you’re using a transient in a plugin you’re releasing to the world, make sure you deal with clearing any transients that would have been generated for the older version of the plugin. Since they expire on their own, I find the best way to do this is to include the version number of your plugin in the transient name.

VERSON_NUMBER = ‘1.1’;

set_transient( ‘repository_html’ . VERSION_NUMBER, $html, DAY_IN_SECONDS );

When I release a new version of a plugin I can update the VERSION_NUMBER constant and know that all clients will be getting the newest versions of any data. I’d also need to ensure that I delete the old transients by calling delete_transient( ‘repository_html’. OLD_VERSION_NUMBER ); so that they don’t build up in your database. This is specifically a problem on sites that are not using object caching because every single transient will be sitting in the options table which can cause site speed issues.

While you can pretty much add anything you want to a transient name to make it unique, there is a 172 character limit on the name. Don’t get too carried away with your transient names or you’ll hit that limit and the world will stop spinning.

I have no idea how long a year is in seconds, and I’m betting most of you don’t either. Lucky for us WordPress provides a bunch of time constants to use for defining the time a transient should live. I almost always use these constants because they fit with the life my data should have.

Finally, be careful what data you store in your transients. In the example above I could store the result of wp_remote_request but that’s not useful to me. I’d still have to loop through the data and build out the list of repositories I wanted to list. Instead, I always prefer to store the final output I want to show to the frontend of the site so that I can save any extra processing time that may be required.

Plugins for Dealing with Transients

There are a few plugins that can make working with transients a bit easier during development. First, Transients Manager lets you see the content stored in your transients. One caveat is that this isn’t showing you transients stored in your object cache, only transients in your database will be available in this plugin. Still, during local development, I’m not running an object cache so this proves useful.

For a plugin that does a bit more than deal with just transients, you can look at Query Monitor. In addition to seeing the transients in your database and the object cache, it provides lots of information about what’s going on with your WordPress site in many other areas. This is one of the first plugins I install when I’m working on a WordPress project.

If you find a bunch of expired transients that are sitting around in your database then you can use Delete Expired Transients. This plugin will schedule a daily task which deletes any transients that should have expired but haven’t been called yet.

By using the WordPress Transients API you can speed up your site so that your users get the best experience possible. While it can seem a bit daunting at first, as I’ve shown above it’s quite simple to put into practice.