register_uninstall_hook() │ WP 2.7.0

Set the uninstallation hook for a plugin.

Registers the uninstall hook that will be called when the user clicks on the uninstall link that calls for the plugin to uninstall itself. The link won't be active unless the plugin hooks into the action.

The plugin should not run arbitrary code outside of functions, when registering the uninstall hook. In order to run using the hook, the plugin will have to be included, which means that any code laying outside of a function will be run during the uninstallation process. The plugin should not hinder the uninstallation process.

If the plugin can not be written without running code within the plugin, then the plugin should create a file named 'uninstall.php' in the base plugin folder. This file will be called, if it exists, during the uninstallation process bypassing the uninstall hook. The plugin, when using the 'uninstall.php' should always check for the 'WP_UNINSTALL_PLUGIN' constant, before executing.

No Hooks.

Return

null. Nothing (null).

Usage

register_uninstall_hook( $file, $callback );
$file(string) (required)
Plugin file.
$callback(callable) (required)
The callback to run when the hook is called. Must be a static method or function.

Examples

0

#1 Registering the uninstall hook, in the plugin file: 

// above there should be no open codes, connected directly, not using hooks.

// Perform Uninstall hook inside register_activation_hook
// TO not check NOT autoload options every time

register_activation_hook( __FILE__, 'your_plugin_activate' );

function your_plugin_activate(){
	register_uninstall_hook( __FILE__, 'wm_ya_db_uninstall' );
}

function wm_ya_db_uninstall() {
	delete_option("option_name");
}

// there should be no open codes below, connected directly, not using hooks.

// plugin code

add_action( 'init', 'plugin_function' );

function plugin_function(){
	// plugin function code
}

It is recommended to register the delete hook only once when activating a plugin, because this function checks and, if necessary, writes the delete function to the WP option. See https://core.trac.wordpress.org/ticket/31792

This means that your plugin will make one extra query to the database every time you visit any page on the site, which is not good for performance.

Also, if the function attached to the hook has changed (changed its name), you need to call that function again to rewrite the callback value.

0

#2 Plugin Deletion for OOP

This example shows how to register an uninstall hook for classes.

register_uninstall_hook() should NOT be called inside the class, it must be called outside and point to a class method.

// Perform Uninstall hook inside register_activation_hook
// TO not check NOT autoload options every time

register_activation_hook( __FILE__, 'your_plugin_activate' );

function your_plugin_activate(){
	register_uninstall_hook( __FILE__, array( 'Demo_Class', 'uninstall' ) );
}

class Demo_Class {

	public static function uninstall() {

		if ( ! current_user_can( 'activate_plugins' ) ) {
			return;
		}

		check_admin_referer( 'bulk-plugins' );

		// Important: check if this is the file that
		// was registered at the time the plugin was removed.
		if ( plugin_basename(__FILE__) !== WP_UNINSTALL_PLUGIN )
			return;

		// Uncomment this line to see the function in action
		// exit( var_dump( $_GET ) );
	}

	public function __construct() {
		// Run the plugin: add hooks to the desired functions
	}

}

It's important to uninstall() method must be static OR it must be a simple PHP function, because it writes as string in WP options.

0

#3 File uninstall.php

Instead of using quirky function register_uninstall_hook()? it's better to use uninstall.php file.

An example of what the uninstall.php file should look like

// If the file is accessed directly, close access
if ( !defined( 'WP_UNINSTALL_PLUGIN' ) ) 
	exit();

$option_name = 'plugin_option_name';

// For the regular site.
if ( !is_multisite() ) {
	delete_option( $option_name );
} 
// For multisite assembly.
else {
	global $wpdb;

	$blog_ids = $wpdb->get_col( "SELECT blog_id FROM $wpdb->blogs" );
	$original_blog_id = get_current_blog_id();

	foreach ( $blog_ids as $blog_id )   {
		switch_to_blog( $blog_id );
		delete_site_option( $option_name );  
	}

	switch_to_blog( $original_blog_id );
}

Changelog

Since 2.7.0 Introduced.

register_uninstall_hook() code WP 6.5.2

wp-includes/plugin.php 
function register_uninstall_hook( $file, $callback ) {
	if ( is_array( $callback ) && is_object( $callback[0] ) ) {
		_doing_it_wrong( __FUNCTION__, __( 'Only a static class method or function can be used in an uninstall hook.' ), '3.1.0' );
		return;
	}

	/*
	 * The option should not be autoloaded, because it is not needed in most
	 * cases. Emphasis should be put on using the 'uninstall.php' way of
	 * uninstalling the plugin.
	 */
	$uninstallable_plugins = (array) get_option( 'uninstall_plugins' );
	$plugin_basename       = plugin_basename( $file );

	if ( ! isset( $uninstallable_plugins[ $plugin_basename ] ) || $uninstallable_plugins[ $plugin_basename ] !== $callback ) {
		$uninstallable_plugins[ $plugin_basename ] = $callback;
		update_option( 'uninstall_plugins', $uninstallable_plugins );
	}
}

Plugins, Hooks