Jacob Santos

The “uninstall” hook runs when the user deletes a plugin that is deactivated. The implementation is basic and doesn’t allow for much in the way of what the original implementation calls for, but hey at least it exists. The point now is that you can do what you want, but WordPress won’t hold your hand while you’re doing it. It isn’t the WordPress way to do so.

Would have been nice, but I’m glad it is in. It will make the uninstall process a lot easier. Not to mention that deleting a plugin isn’t going to be so bad, since you can always use the Plugin Installer to automatically download and activate the plugin again. That should allow for more plugins to support uninstall feature.

Registering the Plugin Uninstaller

There are two ways to register the uninstaller with WordPress.

1. Create uninstall.php at the base of your plugin folder.
2. Register your plugin’s uninstall hook.

Uninstall.php Uninstaller Method

This is the preferred uninstall method and if the file exists, then it will be run instead of the uninstall hook. You should do some checking for either the ABSPATH or the WP_UNINSTALL_PLUGIN constants. You would be more secure, if you choose the latter of the two. The WP_UNINSTALL_PLUGIN allows for you to be even more secure or paranoid by checking the path of your plugin. Most cases, all you will need to do is just check for the existence of the constant.

Your plugin will be deleted after the uninstaller is ran should you can clean up all database tables, options, extra files, and take the time to save or delete custom files that the user made. There is no way to stop the process once it is started or that is to say, that you shouldn’t try to stop the process once it is started.

The user wants to delete your plugin and it will be a bad user experience if that person finds their plugin still accessible. Come to think of it, it is probably possible and allow for the user to still delete your plugin, but there are no internal means to do so.

if( !defined( 'ABSPATH') && !defined('WP_UNINSTALL_PLUGIN') )
    exit();

delete_option('my_option');

Register Your Plugin’s Uninstall Hook

This doesn’t work like the other plugin register functions, like activate and deactivate. Your plugin will be deactivated, so it is not going to be possible for WordPress to check for your uninstall functions if it used the same method as the other two functions. Instead it creates an option that lists your plugin and its uninstall hook.

When the plugin is deleted and there is no uninstall.php file, but the uninstall hook exists, then the plugin will be ran one last time in order to run the hook. This is not the preferred method of your plugin runs code during the inclusion of the main plugin file, like some plugins do. If that is the case, then use the uninstall.php, which is the only file that will be called when you plugin is uninstalled.

Special care then should be taken when using this method to ensure that your plugin isn’t doing anything it shouldn’t when uninstalling. Your hook will be called and then your plugin will be deleted.

An example might be:

register_uninstall_hook(__FILE__, 'my_uninstall_hook');

function my_uninstall_hook()
{
    delete_option('my_option');
}

As opposed to the other method using a checkbox or just automatically uninstalling on deactivate, I think this is a far better way of knowing when to clean up after your plugin.

You can provide backwards compatibility, but using function_exists() function before calling register_uninstall_hook().

if ( function_exists('register_uninstall_hook') )
    register_uninstall_hook(__FILE__, 'my_uninstall_hook');

function my_uninstall_hook()
{
    delete_option('my_option');
}

Possibly Related Posts:

• Bullet: E-Book Library Management and Content Server
• Using ZendFramework 2 beta1 For Directory Project
• The Way of Kings and Cosmere Theory
• “In Time” Movie Premise Flawed
• Completing HTTP Library For PHP