in Tutorials, WordPress

A Quick Look at the WordPress uninstall.php File

Creating a plugin for WordPress is a fun experience. You get to build something that eventually gets used by countless people, makes their lives easier, perhaps makes you a profit and in general just makes the world a better place.

But don’t be the jerk that overstays their welcome. When your plugin creates ‘data’ on a user’s site, like a post type, page or setting, you have a responsibility to remove that data when a user decides to delete your plugin. If you neglect to clean up after yourself, you’re imposing a lifetime of DB clutter on your (ex-)user and making the world a worse place.

To be fair, when I started building plugins, I never did what I’m demanding you do now. I was unintentionally, unknowingly, trolling every single one of my users.


But I didn’t know. That’s not an excuse, but really, I didn’t know any better. So today, I’ll make sure that you don’t follow in my digital footsteps. I’ll hold on your hand as we step into undesirable territory. We never believe it will happen, but sometimes, people do delete our plugins. Let’s make sure we don’t leave a lasting impression.

Uninstall.php all the things

There are a few different ways to clean up your data. I’m not going to go into each and everyone of them. Some people like to use the register_uninstall_hook. I don’t. If you want a detailed look at all things regarding install, uninstall and deactivation, read Mike’s post. Personally, I’m going to keep it simple.

First thing you need to do is create a blank file called uninstall.php in the root of your plugin’s folder.

Now add a header and more importantly, a check to be sure that this file should be executed:

Good job. That was fun. And easy. Why doesn’t everyone do this?

Let’s start deleting stuff! Did your plugin create any settings / options? Delete them all! I personally like to create a quick array of all my options – it makes it easy to add more and I like to be concise. I then itterate through the array, checking for and deleting each option:

You may also have created some pages on the plugin’s activation. We better delete those too. You should have some dynamic way of figuring out what the page’s ID, either through an option or something like that (if through an option, be sure to add this code before you delete all the options using the code above!):

One last thing you may want to do is delete the posts that were created with your custom post types (and their post meta). Personally I think you should provide an extra setting for users to confirm they want to delete this data and not just delete it automatically, but that’s up to you (adjust the my_custom_post_type below):

In general I do like the idea of having a setting for users to confirm the data deletion, as some users tend to delete and re-install a plugin to do an update (or for no apparent reason). That’s your decision. Hopefully in the future, WordPress will include some sort of ‘check’ to see if data is being removed and then really check with the user that they want to delete it. At the moment, it just adds a little note during the deleting process saying that it will also delete the plugin’s data, but I doubt many people read this.

Screen Shot 2014-12-14 at 3.37.19 pm

Another thing to remember – if you’re supporting multisite installations, you may want to iterate through each site running the plugin and delete each site’s data, using something like switch_to_blog.

For reference and copy/pasting, here’s a complete uninstall.php that you can adjust and use in your plugins:

Now go delete all the things!

giphy (1)

Write a Comment