Delete Transients on Plugin Deactivation

When I was a child, my mother often reminded me to clean up after myself. While I’m pretty sure she was talking about the kitchen, this is great advice for plugin authors as well. When someone deactivates your plugin, it is good form to remove anything you added to the database.

The most common place WordPress transients are stored is in the database. Even though you set an expiration time, the transient values are only deleted from the database when you try to read them after the expiration time has passed. This means if you deactivate your plugin that was using a transient, that transient will never be read again, which means the values in your database are never deleted.

How to Delete Your Transient on Plugin Deactivation

The solution to this is to delete the transient on plugin deactivation.

register_deactivation_hook( __FILE__, 'fe_my_example_delete_transient' );
function fe_my_example_delete_transient() {
    delete_transient( 'fe_my_example_transient' );
}

Important Note: The registration_deactivation_hook() function should be called in the primary plugin file because the first parameter ( __FILE__ ) needs to be the path to the main plugin file inside the wp-content/plugins directory.

In my WordPress Transient Introductory Post, we looked at the basics of using transients but I did not cover deleting the transient on plugin deactivation. To be honest, this isn’t always something I’ve kept in mind but Kevin Cristiano‘s feedback after my presentation on transients at WordCamp Lehigh Valley 2017 made me realize I should.

There are two different points where plugin cleanup is appropriate. On uninstall or on deactivation. Because data stored in transients should always be able to be recreated, deactivation is my preferred point to delete the transient. You can see where I added this code to my demo plugin Lehigh Valley Current Temp Widget.

How Transients are Stored

To understand why it is important to delete transients in the database, we first need to understand how they are stored.

To add to the complexity transients are stored in two different ways depending on how your server is setup.

We’re going to look at the default storage method for transients, which is to store the transient in the options table (often named wp_options). If you have a third-party caching platform setup, like Redis or Memcached, it is used instead of the options table.

The Options Table

When a transient is stored using the options table, two rows are written to your table.

Transient Value Row

Your transient key (e.g. fe_lv_temp) is prefixed with _transient_ for the key and the value you are caching is stored as the value (e.g. 48.68).

Transient Expiration Row

Your transient key (e.g. fe_lv_temp) is prefixed with _transient_timeout_ for the key and the expiration time (e.g. 30 minutes from now) is stored as a unix timestamp.

When Transients are Deleted from the Options Table

These transients are only deleted on a get_transient() call where the expiration time has passed or when delete_transient() is called specifically for the transient. This is why deactivating your plugin (and never calling get_transient() on your particular transient again) results in extraneous rows in your database.

Deleting Expired Transients Left Behind By Other Plugins

You can delete all expired transients by using a third-party plugin, like Transients Manager.

Photo Credit

Photo by Catt Liu

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.