register_deactivation_hook() │ WP 2.0.0

Set the deactivation hook for a plugin.

When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is called. In the name of this hook, PLUGINNAME is replaced with the name of the plugin, including the optional subdirectory. For example, when the plugin is located in wp-content/plugins/sampleplugin/sample.php, then the name of this hook will become 'deactivate_sampleplugin/sample.php'.

When the plugin consists of only one file and is (as by default) located at wp-content/plugins/sample.php the name of this hook will be 'deactivate_sample.php'.

No Hooks.

Return

null. Nothing (null).

Usage

register_deactivation_hook( $file, $callback );

$file(string) (required): The filename of the plugin including the path.
$callback(callable) (required): The function hooked to the 'deactivate_PLUGIN' action.

Examples

#1 Running the function when the plugin is deactivated

Suppose the function we need to run when deactivating the plugin is called myplugin_deactivate() and it is located in the main plugin file:

wp-content/plugins/myplugin.php
or
wp-content/plugins/myplugin/myplugin.php

Then, use this code to call the deactivate function:

register_deactivation_hook( __FILE__, 'myplugin_deactivate' );

function myplugin_deactivate(){
	// do what you need to do when you deactivate the plugin.
}

This (string) will call function myplugin_deactivate() when the plugin is deactivated.

#2 Normal functions (not classes)

This demo shows how to call the Activate/Deactivate/Delete functions in a plugin file:

<?php
defined( 'ABSPATH' ) OR exit;

/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - Functions
 * Description: Example Plugin to show activation/deactivation/uninstall callbacks for plain functions.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

register_activation_hook(   __FILE__, 'WCM_Setup_Demo_on_activation' );
register_deactivation_hook( __FILE__, 'WCM_Setup_Demo_on_deactivation' );
register_uninstall_hook(    __FILE__, 'WCM_Setup_Demo_on_uninstall' );

function WCM_Setup_Demo_on_activation()
{
	if ( ! current_user_can( 'activate_plugins' ) )
		return;
	$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
	check_admin_referer( "activate-plugin_{$plugin}" );

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

function WCM_Setup_Demo_on_deactivation()
{
	if ( ! current_user_can( 'activate_plugins' ) )
		return;
	$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
	check_admin_referer( "deactivate-plugin_{$plugin}" );

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

function WCM_Setup_Demo_on_uninstall()
{
	if ( ! current_user_can( 'activate_plugins' ) )
		return;
	check_admin_referer( 'bulk-plugins' );

	// Important: check if this is the file that
	// was registered in the process of the deletion hook.
	if ( __FILE__ != WP_UNINSTALL_PLUGIN )
		return;

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

#3 Architecture for OOP (PHP classes)

If the plugin is written as a PHP class, the functions must be connected as follows:

<?php
defined( 'ABSPATH' ) OR exit;
/**
 * Plugin Name: (WCM) Activate/Deactivate/Uninstall - CLASS
 * Description: Example Plugin to show activation/deactivation/uninstall callbacks for classes/objects.
 * Author:      Franz Josef Kaiser/wecodemore
 * Author URL:  http://unserkaiser.com
 * Plugin URL:  http://wordpress.stackexchange.com/questions/25910/uninstall-activate-deactivate-a-plugin-typical-features-how-to/25979#25979
 */

register_activation_hook(   __FILE__, array( 'WCM_Setup_Demo_Class', 'on_activation' ) );
register_deactivation_hook( __FILE__, array( 'WCM_Setup_Demo_Class', 'on_deactivation' ) );
register_uninstall_hook(    __FILE__, array( 'WCM_Setup_Demo_Class', 'on_uninstall' ) );

add_action( 'plugins_loaded', array( 'WCM_Setup_Demo_Class', 'init' ) );
class WCM_Setup_Demo_Class
{
	protected static $instance;

	public static function init()
	{
		is_null( self::$instance ) AND self::$instance = new self;
		return self::$instance;
	}

	public static function on_activation()
	{
		if ( ! current_user_can( 'activate_plugins' ) )
			return;
		$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
		check_admin_referer( "activate-plugin_{$plugin}" );

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

	public static function on_deactivation()
	{
		if ( ! current_user_can( 'activate_plugins' ) )
			return;
		$plugin = isset( $_REQUEST['plugin'] ) ? $_REQUEST['plugin'] : '';
		check_admin_referer( "deactivate-plugin_{$plugin}" );

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

	public static function on_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 ( __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
	}
}

#4 Using a namespace

If you are using a namespace in the main plugin file

namespace MYNAMESAPCE;

You will need to use the __NAMESPACE__ keyword in your code for register_deactivation_hook().

register_deactivation_hook( __FILE__ , __NAMESPACE__ . '\deactivate_plugin' );

Otherwise, the code will be unable to find the function deactivate_plugin() and will produce a warning:

PHP Warning: call_user_func_array() expects parameter 1 to be a valid callback, function ‘deactivate_plugin’ not found.

Changelog

Since 2.0.0

Introduced.

`register_deactivation_hook() register deactivation hook` code ^{WP 6.7.2}

wp-includes/plugin.php

function register_deactivation_hook( $file, $callback ) {
	$file = plugin_basename( $file );
	add_action( 'deactivate_' . $file, $callback );
}