When developing plugins for WordPress, most of the time I deal with semi-permanent settings with my plugins. A user goes to the “Settings” page for the plugin, they set things up the way they want them, and they expect those settings to remain that way until they decide to change them again.
However, there are times when you need to store temporary information that needs to either expire or be updated on a regular basis. There are functions within WordPress to help you with that, too. They are part of the “transient API” in WordPress. Basically, transient options are options that have an expiration date.
Use Case #1 – Retrieving External Information and Storing It Locally
In the current development version of Extended Super Admins, I use transient options to store the information retrieved from the WordPress Codex. That way, if the transient option already exists, the plugin doesn’t have to hit the WordPress Codex to update the information. If the option doesn’t exist, it retrieves it from the WordPress Codex and stores it locally.
Because the process of retrieving the information and formatting it for my plugin is rather intensive, it would be ridiculous to try to perform those actions every single time someone tried to update the options for the plugin; but since the whole point of that feature is to display up-to-date information from the WordPress Codex, I didn’t want to place any sense of permanency on the information.
Use Case #2 – Processing and Presenting Local Information
In a completely separate situation, I’m using the transient API to store cached information from my own WordPress site. In this instance, I have a set of custom post types that are intertwined with user accounts, and I have to perform a lot of processing in order to output the information from the custom post and the related user account together. Again, since this is just cache information, and will need to change on a semi-regular basis (at the very least, every time someone modifies their user profiles or one of the custom posts), I decided to use the transient API to store the information.
Use Case #3 – Caching RSS Feeds
The most common usage of the transient API (as far as I can tell) is to store information from external RSS feeds. This use-case is similar to the first one I mentioned above, but it doesn’t seem that any processing is done locally before storing the feed information. Generally, developers that write feed-related plugins and widgets seem to retrieve the feed and store it as raw XML (Atom, RSS, whatever) in the database.
What Functions Are Available?
There are (as far as I know) a total of 6 transient functions available in the current version of WordPress (they appear to go back to at least version 3.0). There are three documented transient functions for transient options related to a specific instance of WordPress, and there are three similar functions for network-wide (or sitewide, if you still use the WPMU technology) settings.
Creating a Transient
To create a new transient (or, technically, you could use it to update an existing transient – but that would basically just delete the old transient and create a new one), you use the set_transient() function. The set_transient() function accepts three parameters:
- The unique name of the transient (required)
- The value to store (required – can be an array, an object or a normal variable)
- The amount of time (in seconds) until the information should expire (technically optional, though the default is 0, so the transient would be pretty useless without this parameter)
To create a new network-wide transient, you would simply use set_site_transient() instead of set_transient(). The set_site_transient() function accepts the same parameters as set_transient().
Both of these functions will return one of three possible values:
- boolean true (if the transient was added successfully)
- boolean false (if there was an issue adding the transient)
- a completely empty value (the only reason an empty value would be returned is if there is a bug somewhere in the code, but it is theoretically possible)
Removing a Transient
If you just can’t wait for a transient to expire naturally, and you decide it has to be removed immediately, you can remove it by using the delete_transient() function. The delete_transient() function only accepts a single parameter; the unique name of the transient to be removed.
If you set a network-wide transient and want to delete it, you would use delete_site_transient() instead. This function accepts the same parameter as delete_transient().
Retrieving a Transient
If you already set a transient, and you want to retrieve it from the database, you would use the get_transient() function. This function accepts a single parameter, the unique name of the transient to retrieve, as well.
If you want to retrieve a network-wide transient, can you guess which function you would use? If you guessed get_site_transient(), you’re right.
These two functions will return boolean false if the transient already expired or doesn’t exist. Otherwise, it will return the value of the transient. Because of this, the WordPress Codex recommends against storing plain boolean values in transients, as you could end up getting boolean false returned if the transient doesn’t exist, or false could be returned if the value was explicitly set to false. You would have no way of knowing which circumstance caused the false return value. Therefore, it is recommended to wrap boolean values within arrays in order to avoid that situation (example: use array(false) or array(true) instead of false and true).
What do These Functions Do?
Each of these functions actually uses the options and site_options functions in the background, but, instead of manipulating a single option, they manipulate the actual transient option and a second option that holds the transient’s expiration timestamp.
Therefore, if you ever find the need to look for a transient within the database itself, you simply need to look in the options table (for transients set with set_transient()) and the sitemeta table (for transients set with set_site_transient()). The options will be prefixed with _transient_ (for the option that actually holds the transient value) and _transient_timeout_ (for the expiration timestamp of the transient).
What Filter and Action Hooks Are Available?
These functions provide multiple action and filter hooks.
set_transient()
At the beginning of the set_transient() function, a filter is applied with the name of pre_set_transient_$transient (where $transient is the unique name you gave to your transient variable). For instance, if your transient variable was called “my_transient”, a filter called pre_set_transient_my_transient would be applied before the transient is stored in the database. This might be a good place to perform some minor processing or validation before committing the data.
After the set_transient() function is finished, two actions are applied: set_transient_$transient and setted_transient.
set_site_transient()
All of the same filters and actions applied to set_transient() are applied to set_site_transient(), except that these actions and filters have “site_” before the word “transient” in each filter/action.
delete_transient()
Two actions are available with the delete_transient() function. The first action (delete_transient_$transient) is run before the transient is deleted. The second (deleted_transient) is run afterwards.
delete_site_transient()
Again, just use the term “site_” in front of the term “transient” in the actions mentioned above.
get_transient()
The get_transient() function offers two filters. The first (pre_transient_$transient) is applied before the transient is retrieved. The second (transient_$transient) is applied after it’s been retrieved.
get_site_transient()
I don’t think I really need to say anything about this, do I?
Other Note
As I mentioned above, each of these actually uses the option and site_option functions in the background. Therefore, all of the filters and actions applied to get_option(), get_site_option(), add_option(), add_site_option(), update_option(), update_site_option(), delete_option(), and delete_site_option() functions may also be applied to these transient functions.
Where Do I Get More Information?
The Codex entry for the transient API offers a good bit of information. If you want to look at the code for the various functions mentioned in this article, they can all currently be found in the wp-includes/functions.php file.
Post Your Comment