I have been having great fun, and when you read ‘fun’ realise that I mean ‘endless-irritations’, trying to get my plugin for WordPress to cleanly remove all of it’s stored options and items recorded during it’s usage. So here’s a quick explanation of how to create a WordPress plugin that plays nice and truly uninstalls everything upon deletion. N.B. It’s not that the information wasn’t available to do this, I found lots of previous tutorials, but they weren’t really as clear as I would I have liked.
Why bother with an uninstall method?
Good programming practise usually recommends that there is an undo button that lets us take back an undesired action. It also should allow a user to uninstall and remove a plugin without the worry of having leftover data or tables resting in their system clogging up their database schema. Thankfully this functionality has been available in WordPress for some time, although it is woefully underused. Probably due to the lack of articles that tell you how to implement it. The WordPress Codex lists the detail on the Uninstall hook is located at https://codex.wordpress.org/Function_Reference/register_uninstall_hook
How do you implement it?
This is simplicity itself, all you need to do is place a file named uninstall.php in the root directory of your plugin. All your logic for removing the the plugin data will be written here, therefore your plugin should start with something like the following;
- /plugin-name/
- plugin-file.php
- uninstall.php
Nothing needs to be added to the main plugin-file.php to activate the process, it is automatically searched for when the user agrees to delete the plugin.
When is the uninstall.php run?
It is important to realise that the uninstall.php is not actioned when the user disables the plugin, if you wish to remove all stored data on plugin disable there is a separate hook that can be called from the main plugin file. The uninstall.php is actually run when you confirm the deletion of the plugin. This is probably cleaner and safer because a programmer may well disable plugins to track errors in a WordPress install and unknowingly remove all the database entries. When someone is deleting a plugin permanently one expects that all data related to the plugin will be deleted as well.
What do we put in the uninstall.php?
The first thing we need to add to the uninstall script is the following if statement to check for WP_UNINSTALL_PLUGIN:
if(defined( ‘WP_UNINSTALL_PLUGIN’ )){
… uninstall code here
}
The reason for this is to stop malicious attacks on the site using the plugin by directly accessing the uninstall file (by using the url www.mydomain.com/wp-content/plugins/plugin-name/uninstall.php). This would allow an attacker to drop tables and remove saved options depending what was contained in the removal script.
The two main possibilities that a plugin would want to remove are saved options and database tables with data. This would be actioned in the following manner. In the case of the WordPress options:
delete_option(‘my_option’);
and in the case of removing a database table:
global $wpdb;
$table = $wpdb->prefix . ‘name_of_table’;
$wpdb->query(“DROP TABLE $table”);
Conclusions
It is a good idea to create a plugin that can be removed as reliably as it is installed, cleanly deleting all the tables and options stored by WordPress. The system is easy to implement and with the inclusion of uninstall.php and only takes a few short minutes to reverse what work you’ve already done in your main plugin class.
When I have finished the UnitTracker plugin I’ll add a link to download the source code here so you can see how I implemented the uninstall.php in a real life context.
