Cleaning Up After Your Plugin

In this tutorial we're going to look into how you can clean up after your WordPress plugin when it's deactivated or uninstalled. This is an area of plugin development that is often overlooked or forgotten about but it's important area of your WordPress plugin as it helps keeps the user's WordPress site clean. WordPress has a few hooks that you need to be aware of that can help with keeping the WordPress site clean when users activate, deactivate and uninstall your WordPress plugin.

• register_activation_hook - Runs when your plugin is activated
• register_deactivation_hook - Runs when your plugin is deactivated
• register_uninstall_hook - Run when your plugin is uninstalled

#Activation Hook

The activation hook is ran only when the plugin is activated it's important to not confuse this with when the plugin is installed. It will only run after the user has installed the plugin and then clicked the link to activate the plugin. The function register_activation_hook is a wrapper for the action hook activate_${PLUGINNAME}, therefore if your plugin filename is called plugin-file-name.php this activate hook will be activate_plugin-file-name.php.

register_activation_hook( $file, $function );

The first parameter of this function is the main file for the plugin, the second parameter is the function to run on plugin file activation. Therefore if you put this function in your main plugin file you can use the following code.

register_activation_hook( __FILE__, 'plugin_activation_function' );
function plugin_activation_function()
{
  // code to run on plugin activation
}

There are a few situations where this is needed the best way to demonstrate the need for this is in the situation when your plugin needs to create custom database tables then this is the perfect place to create those tables.

register_activation_hook( __FILE__, 'pu_create_plugin_tables' );

function pu_create_plugin_tables()
{
    // enter code to create tables
}

#Deactivation Hook

Along with the activation hook there is a deactivation hook which is ran when the user deactivates the plugin, not uninstall. It's important to understand the difference between a deactivate and an uninstall as you will do different things with your code. For example a user might want to deactivate the plugin to simply turn off the functionality for a while during testing a new feature, therefore you don't want to clean up after your plugin on the deactivation hook you'll want to save this for the uninstall hook. The function register_deactivation_hook works in a similar way of to the activation hook where it behaves as a wrapper to the deactivate_${PLUGINNAME} hook.

register_deactivation_hook($file, $function);

This takes 2 parameters, the first being the file for the main plugin file, the second parameter is the function that will run on deactivating the plugin.

register_deactivation_hook( __FILE__, 'plugin_deactivation_function' );
function plugin_deactivation_function()
{
  // code to run on plugin deactivation
}

#Uninstall Hook

The uninstall hook will run when the user uninstalls the plugin and this should be used to help clean up after your plugin. When the user uninstalls the plugin they obviously don't want to use the code anymore on their site, so there is no need to have your custom tables or the wp_options record anymore in the database. There are two ways you can activate the uninstall hook for your plugin, you can either use the function register_uninstall_hook or you can create a file at the root of your plugin called uninstall.php, if this file exists then WordPress will run the code install this file. The function register_uninstall_hook again works in a similar way to the above functions.

register_uninstall_hook( $file, $function )

The function takes 2 parameters the first is the main file of the plugin, the second is the function to run on uninstall of your plugin.

register_uninstall_hook( __FILE__, 'plugin_uninstall_function' );
function plugin_uninstall_function()
{
  // code to run on plugin uninstall

  // delete the registered options
  delete_option( 'plugin_option' );
}

If you're using the uninstall.php file then you can start the file with the following code.

if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) {
	exit;
}

// Uninstallation code here