Getting Started With The WordPress Transients API, Part 1

One of the nicest things about working with WordPress is the power of its API. When creating themes and/or plugins, the platform makes it incredibly easy to serialize and retrieve data. In fact, the API abstracts many of the common challenges of working with data such as data sanitization and efficiently retrieving data on request. Throughout the next two post, we’ll take a look at the Transients API, why it matters, how to use it, and take a look at a practical implementation that we can use in future projects.

Generally speaking, all of the above is accomplished with the WordPress Options API which is great for saving, updating, and reading options, but if you’re working with a large set of data the Options API may not be providing the most optimal performance possible. Specifically, you may be able to improve the overall performance of your work (and its extensibility with other software) if you were to take advantage of the Transients API.

What Is The Transients API?

Simply put, the Transients API provides a way to store information in the WordPress database with an expiration time. When saving information using the Options API, values are stored using a key and a value.

For example, say that you’re working with a plugin that saves your Twitter username in a custom field named ‘Twitter.’ You can conceptualize the way WordPress saves this information may treating ‘twitter’ as the key and your username (say, ‘MoreTom’) as the value.

The difference in the way that the Transients API saves it’s information is that a third piece of data – an expiration time – is saved to the database. This is key for speeding up performance namely with caching.

Additionally, data saved via the API (called transients) is leveraged by caching plugins and caching software whereas standard WordPress options are not. For example, when you store a value using the Transients API, caching software – such as memcached – will instruct WordPress to store values in such a way that it can easily retrieve it on each page request rather than hitting the database each time.

Cool, huh?

The caveat is that since transients have an expiration time, they aren’t guaranteed to be database so we should make sure that the values that are store are ones that aren’t critical to the theme or plugin’s success (although there is a way to manage this that we’ll check out in the next post).

The most important thing to remember is that you don’t want to store every option value using the Transients API. A good rule of thumb is store the values that are often most expensive and that aren’t required for page loads.

As useful as understanding the API really is, the real advantage comes in actually using it.

Using The Transients API

The nice thing about the Transient APIs is that it’s extremely well implemented with three functions two of which you will use regularly. The three main operations for transients are setting values, getting values, and deleting values.

Set A Transient

Saving a transient requires three specific pieces of information:

• The key that will be used to retrieve the value
• The value to serialize
• The amount of time (in seconds) to store the data before refreshing it

The signature of the method is as follows:

• set_transient($key, $value, $expiration);

Easy,right? A simple example for calling this function would be as following:

	set_transient('twitter', 'MoreTom', 60 * 60 * 12);

Get Transients

Retrieving a transient is even simpler than setting. In fact, it’s very similar to retrieving a options from the WordPress Options API. All you need to know is the key that was defined when you set the value.

The signature of the method responsible for returning the value is:

• get_transient($key);

In following with the example above, we’d retrieve the user’s Twitter username by calling:

	get_transient('twitter');

Simple, huh?

Deleting Transients

Setting and retrieving transients are the two most commonly used functions of the API, but there are times during which you may need to remove a value before the expiration time has been reached.

In that case, you can take advantage of the delete_transient function:

• delete_transient($key);

Similar to retrieving a value, you simply pass the key used to identify the transient value to the function:

	delete_transient('twitter');

The function will return true if the value is properly removed, false if the value was not removed or if the deletion of the value didn’t work correctly.

Obviously, the performance benefits pay dividends in comparison to how difficult it is take advantage of the API. Perhaps the most important thing to remember is that you don’t want to store every option value using the Transients API – only those that are the most expensive and that rarely change.

In the next post, we’ll see a practical implementation of the API by creating a plugin that takes advantage of the API.