WordPress plugin and database data

So I’ve created the tables for my Unit Tracker plugin and created some dummy data for an initial example Tracker. As nice as this is I’m not entirely sure about how I’ve designed the tables (read that as saying “if you think this is a mistake comment“). My assumption is as follows for the pure basics, you will need at least 2 tables;

Table 1 – Trackers

A table to store all the different units being tracked, there can be a number of different units tracked, or maybe even a set of units tracked in tandem for example body-fat % , weight and stomach measures.

  • Name and Description of the tracker
  • Link to a post/page further describing the details about the tracker
  • A display Reference (something like a permalink) that can be used to display the tracker
    • for example [:tracker-weight:]
  • Validation, due to the fact that any unit may be added a validation key will be added here (regex?)
  • Unit Measurement, because people might be measuring lbs, Stone (British measure), Kg, % or Quarks the unit of measurement is left blank and assigned by a user (but there will automatically be a suggested one in the form)

Table 2 – Tracker Values

A table to store all the values recorded by the user. This is so in the future we can use this data to map graphs, allow cvs downloads e.t.c.

  • Value, this I have decided to store as a string, now I may well regret this but it seemed the easiest way to store data of any type including time (hours/days/months/years) weight can be stored in Metric and converted as necessary. The method of extracting and processing the data is based on the validation in the Tracker table. You can’t change the type after the Tracker contains data.
  • Created, the date that new a new data value was added to the tracker
  • Tracker Id the ID (primary key) of the tracker the data belongs to.

Of course this isn’t all, there will be probably options stored in the WordPress options database table to decide on appearance, widget placement etc, additional tracker values that show targets, method of display, change over a period of x, and many more…

First of all I’ll settle with the above as an Alpha 0.0.1 release and when this works I’ll add accordingly.

How to: WordPress uninstall.php

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.