When it comes to building a web app with WordPress, its powerful APIs provide a great deal of help. Adding or retrieving any data with the Options API is not a big deal. But sometimes we need to store temporary data with an expiration time. 

WordPress offers an intuitive caching via Transients to do just that, i.e. store temporary data with an expiration time. We are going to use transients, so I thought why not take a fresh look at the WordPress Transients API in this article.

According to the WordPress Codex:

The Transients API is very similar to the Options API but with the added feature of an expiration time, which simplifies the process of using the wp_options database table to temporarily store cached information. 

In the scope of this series, transients provide an efficient way for redirecting users to the welcome page when they activate a plugin by storing temporary data. 

In this article, we'll explore the concept of the Transients API in WordPress and how it differs from the Options API. So, let's get to it.

Transients API

Transients provide us with ways to temporarily store cached information by providing a custom name (key-value pairs) and an expiration time. Once the defined timeframe is over, the transients expire and get deleted. These transients improve the performance and speed up the overall web app performance.

But a question arises: Is the expiration time the only reason for using the WP Transient API? 

The answer is no! Despite the fact that the Options API serves the same purpose of data storage, sanitization and retrieval, it may not provide the best possible performance with large sets of data. 

With timeframe being added, transients become the most appropriate way of storing data temporarily. To ensure a lesser number of web queries, transients have the capability to store data in the fast memory, e.g. Memcached, instead of the traditional WordPress database. Also of note is that Transients are inherently sped up by caching plugins, where normal Options are not. As mentioned in the codex:

A Memcached plugin, for example, would make WordPress store transient values in fast memory instead of in the database. For this reason, transients should be used to store any data that is expected to expire, or which can expire at any time. Transients should also never be assumed to be in the database, since they may not be stored there at all.

Therefore, whenever you require a functionality which expires or gets deleted after a particular time span, use transients instead of options. More on that later.

Using Transients

Transients work with an incredibly simple interface. You can perform three basic functions with them:

• creating/updating a transient via the set_transient() function
• retrieving a transient via the get_transient() function
• deleting a transient via the delete_transient() function

These three basic operations can help you speed up web performance.

1. Creating/Updating a Transient

Use the set_transient() function to create or update any transient. The function takes three parameters:

• Key: (type string) Name of the transient. Must be 172 characters or fewer in length.
• Value: (type mixed) It's the data which needs to be stored. Can be a PHP variable or an array object.
• Expiration: (type int) Max time until expiration in seconds. Default 0 (no expiration).

Point to Ponder: The expiration date that you set is the maximum amount of time for which a transient will be stored. After that time, the transient gets deleted. But it can also get deleted before that time. Since it is part of the cache, it can be deleted by the user before that time. So, always think of the expiration time as the maximum amount of time for the life of a transient with only the guarantee that it will be deleted after that.

<?php set_transient( string $transient, mixed $value, int $expiration ) ?>

The first two parameters are the key-value pair and are compulsory, while the third parameter, which defines the maximum time to expire, is optional.

A practical example of calling this function is as follows:

<?php 
    // Transient max age is 60 seconds.
    set_transient( '_welcome_redirect_wpw', true, 60 );
?>

Time Constants in Transients

In the above example, I added 60 seconds as the third parameter, which defines the expiration time after which the transient gets deleted. According to the above example, the object _welcome_redirect_wpw can only have the max age of 60 seconds.

In WordPress 3.5, several constants were introduced to easily express time. These constants make the code more comprehensive and precise. Here's the list:

MINUTE_IN_SECONDS  = 60 (seconds)
HOUR_IN_SECONDS    = 60 * MINUTE_IN_SECONDS
DAY_IN_SECONDS     = 24 * HOUR_IN_SECONDS
WEEK_IN_SECONDS    = 7 * DAY_IN_SECONDS
YEAR_IN_SECONDS    = 365 * DAY_IN_SECONDS

2. Retrieving a Transient

After storing a value via the set_transient() function, you can retrieve the value by calling the get_transient() function.

It takes a single parameter, the key (i.e. the name) of the transient $transient, and returns the (type mixed) value of the transient. 

The standard format is: 

<?php get_transient( string $transient ); ?>

In the case of our example, the value is fetched via:

<?php get_transient( '_welcome_redirect_wpw' ); ?>

Pretty simple? But what would happen if the transient does not exist or has expired? If that is the case, then the get_transient() function returns a false value. 

I recommend that you use the identity operator (===) when you get the value of a transient to test if it is false or not. 

3. Deleting a Transient

There can be situations when you might want to delete the transients before they expire. The delete_transient() function helps you with it. Its format is similar to the get_transient() function. 

It takes a single parameter, the key (i.e. the name) of the transient $transient, and deletes the transient permanently.

Here is the general format:

<?php delete_transient( string $transient ); ?>

In our case, we can delete it like this:

<?php
  // Delete the redirect transient.
  delete_transient( '_welcome_redirect_wpw' );
 ?>

The Uses of Transients

Transients can be used to cache anything from the most basic type of data to a complete widget. Since their launch, transients have been utilized in different web projects. Here are a few practical usages of transients:

• Of course, you can use them in a welcome page of your plugin, which is the scope of this series.
• You can use them in a sidebar widget which lists data like top blog comments, posts, etc.
• You can speed up WordPress navigation menus with transients.
• You can cache a tag cloud with transients.

Conclusion

We're all done with the basics of the WordPress Transients API. In the next two articles, I am going to build a welcome page for a WordPress plugin. I'll put my crude thoughts into something more meaningful and practical.

Finally, you can catch all of my courses and tutorials on my profile page, and you can follow me on my blog and/or reach out on Twitter @mrahmadawais where I write about development workflows in the context of WordPress.

As usual, don't hesitate to leave any questions or comments below, and I'll aim to respond to each of them.