On Activation, Deactivation or Uninstall Functions

WordPress has a cool little three functions that can help plugin developers do something when the plugin is activated, deactivated or uninstalled.

All three are equally important. If you use activation function to set up your plugin, you should also use at least one of the other two, deactivation or uninstall function. Something that most developers do not do. Result you might ask? A mess in options table. To the gallows with them. ;)

Let’s first take a look at the register_activation_hook function.

All three functions accept the same two arguments and both are required.

The first argument should always be __FILE__ which is a PHP magic constant. In other words, it returns full path and filename of the current file where __FILE__ is called.

The second argument is callback function. The name of the function that you wish to run.

You should always put register_activation_hook function inside the main file of your plugin.

register_activation_hook function is called when user clicks on “Activate” link in the plugin page. It is perfect to set default plugin settings, custom roles, capabilities, create custom pages and so on.. If you are very smart, you can even destroy my secret castle on my secret island. Just kidding, I’ve hidden the island too well.

While you are trying to locate my secret island with my secret castle, a task at which you will fail, let’s create the code that will be activated during plugin activation.

In this how to, I will use a class.

//	Call the activation function with a callback to static class method
register_activation_hook( __FILE__, array( 'LTW_SecretCastle', 'activate' ) );

/**
 * LTW_SecretCastle Class
 */
class LTW_SecretCastle {
	/**
	 * When plugin is activated, let's save something to options table.
	 *
	 * @param	void
	 * @return	boolean|void
	 * @since	1.0
	 *
	 */
	public static function activate() {
		//	First you should always check that the user who is trying to activate has the required capability.
		if ( ! current_user_can( 'activate_plugins' ) ) {
            return false;
		}

		//	Check nonce
		$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';

        check_admin_referer( 'activate-plugin_' . $plugin );

        //	Let's save the location of my secret castle into options table
        add_option( 'secret_castle_location', '5.884663, -162.079791' );
    }

That’s it, a custom option will be save to options table when the plugin is activated.

Now the next step is to remove what we have done during the plugin activation, if the user chooses to deactivate or remove the plugin from the site. In other words, clean up the trash.

For cleaning the trash that the plugin made on activation, we will call this function register_uninstall_hook.

/**
	 * When plugin is uninstalled (deleted), let's clear the junk that the plugin made on activation.
	 *
	 * @param	void
	 * @return	boolean|void
	 * @since	1.0
	 *
	 */
	public static function uninstall() {
		//	First you should always check that the user who is trying to activate has the required capability.
		if ( ! current_user_can( 'activate_plugins' ) ) {
            return false;
		}

        //	Let's delete the option that we create on plugin activation.
        delete_option( 'secret_castle_location', '5.884663, -162.079791' );
    }

What about register_deactivation_hook?

The register_deactivation_hook function is called when the plugin is deactivated but not uninstalled.

Which one to use then? It depends on what you want to do. The register_uninstall_hook function is perfect for cleaning the custom options from options table, for removing custom tables, etc. Things that your plugin created and would be used only by your plugin.

The register_deactivation_hook function on the other hand is useful for removing custom permalinks, flushing cache, etc. You should not remove custom tables and custom options here as the plugin itself was not yet removed at this stage, just deactivated.

/**
	 * When plugin is deactivated, let's remove things like custom permalinks, flush cache...
	 *
	 * @param	void
	 * @return	boolean|void
	 * @since	1.0
	 *
	 */
	public static function deactivate() {
		//	First you should always check that the user who is trying to activate has the required capability.
		if ( ! current_user_can( 'activate_plugins' ) ) {
            return false;
		}

		//	Check nonce
		$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';

        check_admin_referer( 'deactivate-plugin_' . $plugin );

        //	On deactivation you should remove custom permalinks, flush cache and so on.
        //	Things that are more dynamic in nature.
    }

And that’s it folks. Three simple functions that every plugin should use.