Transients are a great tool for the WordPress developer. They allow you to easily save temporary data with their own expiry time – simply pass the transients data into the easy-to-use API and it will sort everything out for you. Caching made simple.

Unfortunately, using transients is not without its downsides and recent experiences have shown a couple of issues that any developer should be aware of.

But first I need to explain how transients work.

Transients were not introduced until version 2.8 of WordPress and make use of the WordPress options table (usually named wp_options) to store their data. There aren’t enough fields in this table for the transients to be stored as one record so, instead, it’s split over 2.

Each transient is given, by the developer, a unique name. This is prefixed by either _transient_ or _transient_timeout_ and used as the option_name field. The option_value field is the transient value and the expiry time respectively. You can also store and access network wide transients and these have _site further prefixed to the beginning of the transient name.

So, let’s say you create a transient named ‘test’. Two records will be added to your options table. The first record will be named _transient_test and will have a value of whatever you wished to store in the transient. The second record will be named _transient_timeout_test and the value will be the timestamp of when it expires.

The exception to this rule is if you create a transient that is not set to timeout. In this case only the first record will be created.

If you were creating a network-wide transient then the names would be  _site_transient_test and _site_transient_timeout_test.

How to use Transients

There are 3 simple commands – set_transient, get_transient and delete_transient. The latter two have just one parameter – the transient name.

set_transient, in comparison, has 3 parameters – the transient name, the contents to store and the timeout (in seconds). Set the timeout to 0 for it to never expire.

set_transient and delete_transient both return true or false, depending on their success. get_transient returns the transient content or false if it wasn’t found.

Network-wide transients are handled by the commands set_site_transient, get_site_transient and delete_site_transient. All parameters and return values are as the non-network equivalent.

Problem #1: Transient Name Lengths

The option_name field in the options table has a record length of 64 characters. So, taking into account the prefixes added to the transient name, a transient name can only be a maximum of 45 characters (or 40 characters for network transients). The problem here is that WordPress doesn’t check. It doesn’t fail either – it creates the transients but simply truncates the name. And because each of the transient record pairs has a different length prefix then they each end up with a different name – this means the transient can’t be retrieved.

The Solution

• WordPress are aware of this and a Trac ticket is open to prevent this from happening. I have updated the ticket myself to ensure they’re aware of the 40 limit for network transients (suggesting that the limit should be a uniform 40 to avoid confusion).
• The Codex already makes mention of the 45 character limit for set_transient but didn’t mention the 40 limit for set_site_transient. I have now updated the appropriate page to reflect this.

Problem #2: Housekeeping

When you attempt to get a transient and it’s expired WordPress will automatically remove that transient from the table. However, if that transient is never accessed again then it will not be removed.

Why would this happen? Let’s say a plugin uses transients to cache some data. The transient name may be a unique name which represents the options requested – that way, if the user changes the options the, now incorrect, cached data is not used. However, the old transient will never be re-accessed.

To give you an idea of the scale of this I’ve heard one user has over 250,000 transients in his database which have expired.

The Solution

• Again, WordPress are aware of this and are due to fix it “3.7 early” by adding it to the regular housekeeping task.
• Meantime, you can install my plugin Artiss Transient Cleaner which will perform the same action.

Conclusion

Transients are a powerful and useful tool for the WordPress developer. However, be aware of their limitations and tread carefully!

I’m one of those who are guilty of writing plugins that generate transient names longer than the limit and of generating transients that won’t be accessed once they’ve expired. Now I know all of the above the way I use the transient system has changed.