WordPress Plugin Activation, Deactivation, and Uninstallation

Know when you are deleting a plugin from WordPress and this message pops up?

WordPress Plugin Delete Files and Data

The message “Are you sure you wish to delete these files and data?” appears when the user clicks to delete a plugin. It’s important to note that deactivating a plugin and deleting a plugin are two different things. Users will deactivate plugins for a variety of reasons, including diagnosing compatibility issues, freeing up PHP memory, or they simply don’t need the plugin at the time.

This is why it’s important as developers to know the difference between the Deactivation Hook and the Uninstall Hook.

A good practice to follow is to leave data and files when a plugin is deactivated, but remove any trace of the plugin when it is uninstalled/deleted. That way, when the user deactivates a plugin to see if it’s interfering with their theme or another plugin, they can reactivate without having to input information again.

Let’s walk through a basic scenario… So, let’s say your plugin is using Options to store the users’ information in the database. You should register your Options (and run other functions) in an activation hook like this:

function rose_plugin_activate() {
  add_option( 'option_name', 'Some Value' );
  // Some other code to run on plugin activation.
  // Can register Custom Post Types here, etc.
}
register_activation_hook( __FILE__, 'rose_plugin_activate' );

That way, when the plugin is no longer active, the Options will not be registered. This is perfect for a user deactivating the plugin, but what about if they want to remove the plugin entirely? With just this piece, the Options will remain in the database even after the plugin is uninstalled/deleted.

There are two methods to register a plugin’s uninstallation:

Use the function register_uninstall_hook(), or
Create an uninstall.php file in your plugin’s root folder.

Here is the difference as stated in the Plugin Handbook:

“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 uninstall process. The plugin should not hinder the uninstall 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 uninstall process bypassing the uninstall hook.”

The important part to note in this is, “any code laying outside of a function will be run during the uninstall process.” So basically, if you have code that is not wrapped within functions in your plugin file, use the uninstall.php method. So, for our example, we can just use register_uninstall_hook:

function rose_plugin_uninstall() {
  delete_option( 'option_name' );
  // Some other code to run on plugin uninstall/deletion.
  // If your plugin file contains arbitrary code,
  // you must create an uninstall.php file.
}
register_uninstall_hook( __FILE__, 'rose_plugin_uninstall' );

The delete_option function will safely remove the Option from the database, so now when a user deletes the plugin, it will be as if it never existed.

Megabyte

WordPress Plugin Activation, Deactivation, and Uninstallation

Read More in the Plugin Handbook:

Be My Editor!