Activation/Deactivation of a Plugin

Hooks for activating and deactivating a WordPress plugin provide the execution of PHP actions when the plugin is activated or deactivated, and there is also a hook for uninstalling the plugin, but it is slightly different from the current ones and we will discuss it in another section.

When activating, it is generally necessary to run the installation procedure of the plugin to, for example:

• add default options (settings)
• set up database tables
• add URL rewrite rules
• create directories
• etc.

When deactivating, temporary data is usually cleared:

• cache in temporary options
• files in temporary directories. For example, the WP Super Cache page caching plugin deletes all created cache files upon deactivation.

To call a PHP function upon activation, use register_activation_hook() in the main plugin file:

register_activation_hook( __FILE__, 'myplugin_activation' );

To call a PHP function upon deactivation, use register_deactivation_hook(), also in the main plugin file:

register_deactivation_hook( __FILE__, 'myplugin_function_to_run' );

The first parameter in each function is the path to the main plugin file - this is the file with plugin headers.

Typically, these functions are called in the main plugin file. If the functions are placed in another file, it is necessary to change the first parameter, specifying the path to the main plugin file. This can be done by first saving the path, for example, in a constant.

How Activation Works

The plugin is activated by the function activate_plugin(), which triggers the hook activate_(plugin).

The activate_plugin() function in the core is called after loading the WP environment. This function includes the main plugin file (and everything specified in it), and then activates the specified callback function through the hook. As a result, all functions and classes of the plugin are available in our callback function. However, since all main WP hooks have already been triggered during the loading of the WP environment, no plugin events attached to hooks, for example, plugins_loaded, will be triggered when including the main plugin file. This means our plugin will be included, but not completely: not as it should be included when it is already activated.

For example, if the plugin does something during the plugins_loaded event, all these actions simply will not occur upon plugin activation. For instance, if it includes a translation file, then the translation file will not be included at the moment the callback function specified for register_activation_hook() is triggered.

Typically, after the callback function is triggered, there are 2 events on which functions can be hooked: activated_plugin and shutdown.

To do something extraordinary upon plugin activation, see example 5.

Example of Plugin Activation

One common case for the activation hook is updating WordPress permalink settings using flush_rewrite_rules() when the plugin registers a custom post type. This helps eliminate unpleasant 404 errors. Let's look at an example:

add_action( 'init', 'myplugin_setup_post_type' );
function myplugin_setup_post_type(){
	// Registering the post type "book"
	register_post_type('book', array(
		'public' => 'true'
	) );
}

register_activation_hook( __FILE__, 'myplugin_install' );
function myplugin_install(){
	// Running the function to register the post type
	myplugin_setup_post_type();

	// Resetting permalink settings so they are recreated with new data
	flush_rewrite_rules();
}

If you are not familiar with registering custom post types, read the description of the function register_post_type().

Activating a Plugin for Multisite

Often, when activating a plugin, something needs to be added to the site's database. However, in this case, activating the plugin for the network of sites means doing the same thing for all sites in the network. Automatically, register_activation_hook() does not do this.

Therefore, for a network of sites, you will need to go through all the sites in the network upon plugin activation and do what needs to be done for each site:

register_activation_hook( __FILE__, 'my_plugin_activate' );

function my_plugin_activate( $network_wide ){

	// require_once ABSPATH . 'wp-admin/includes/upgrade.php';

	if( is_multisite() && $network_wide ){

		global $wpdb;

		foreach( $wpdb->get_col("SELECT blog_id FROM $wpdb->blogs") as $blog_id ){

			switch_to_blog($blog_id);

			_activate_plugin_for_site();

			restore_current_blog();
		}

	} else {
		_activate_plugin_for_site();
	}

}

function _activate_plugin_for_site(){
	// activation code for each site
}

It is also necessary to consider that when creating another site in the network, it also needs to be processed. To do this, we carry out the plugin activation procedure when creating the network site:

add_action( 'wp_initialize_site', 'my_plugin_new_blog', 10, 2 );

function my_plugin_new_blog( $new_site, $args ){

	// replace with the base name of your plugin. For example: dirname/filename.php
	if( is_plugin_active_for_network( 'my-plugin-dir/my-plugin-name.php' ) ) {
		switch_to_blog( $new_site->site_id );

		// here we do what is needed upon activation...

		restore_current_blog();
	}

}

Example of Plugin Deactivation

Now upon deactivation, we need to reset the permalink rules again because upon deactivation our post type will be removed. That is, this is the reverse process of what was done above during activation:

register_deactivation_hook( __FILE__, 'myplugin_deactivation' );
function myplugin_deactivation() {
	// The post type is not registered, so it is automatically removed - it does not need to be deleted in any other way.

	// Resetting permalink settings so they are recreated with new data
	flush_rewrite_rules();
}

-

More examples of how to correctly use activation/deactivation functions can be found in the description of these functions:

• register_activation_hook()
• register_deactivation_hook()

Plugin Uninstall Function

In addition to activation and deactivation, an important point is the uninstallation of the plugin. You can connect to this process through the function

• register_uninstall_hook() - needed when uninstalling the plugin.

For more information on how to correctly uninstall plugins, read the special article.