ACTIVATE/DEACTIVATE FUNCTIONS
WordPress provides standard activation and deactivation hooks that allow any plugin to run code when it is activated or deactivated, respectively. This section walks through how to use both.
Plugin Activation Function
When building plugins, you'll often need to execute some code when the user first activates it. One common use case is adding custom capabilities to the administrator role (see Chapter 9, “Users and User Data”) for something like a custom post type (see Chapter 8, “Content”) that your plugin is registering. Or, you may need to set up a particular option for your plugin to perform.
WordPress provides the register_activation_hook() function that allows you to pass in a callback for handling any activation code you need to run.
<?php register_activation_hook( string $file, callable $function ); ?>
Parameters:
$file (string, required): Filesystem path to the primary plugin file
$function (callable, required): The PHP callable to be executed when the plugin is activated
It's generally best to separate your activation code from the rest of your plugin code simply for organizational purposes. The following example shows how to register an activation hook that points to a class located at src/Activation.php in your plugin and executes its activate() method:
<?php namespace PDEV; register_activation_hook( __FILE__, function() { require_once plugin_dir_path( __FILE__ ) . 'src/Activation.php'; Activation::activate(); } );
With the activation hook callback registered, you need to figure out what things you need to set upon activation. The following example gets the administrator role object and adds a custom capability to it:
<?php namespace PDEV; class Activation { public static function activate() { $role = get_role( 'administrator' ); if ( ! empty( $role ) ) { $role->add_cap( 'pdev_manage' ); } } }
There is no limit to what code you can run upon activation. It's a great time to run anything that needs to be set only once or things that shouldn't be run on every page load. For example, if your plugin needs to create custom database tables, this would be the time to do it.
While it is common practice with some plugin authors, you usually shouldn't set plugin database options at this point. It's almost always better to use sane defaults for any options your plugin has and not clutter the database until the end user has explicitly decided to save on your plugin settings screen (see Chapter 3).
Plugin Deactivation Function
Like the activation function, WordPress also allows you to execute code from a registered deactivation callback via the register_deactivation_hook() function. The following example includes the src/Deactivation.php class and executes its deactivate() method:
<?php namespace PDEV; register_deactivation_hook( __FILE__, function() { require_once plugin_dir_path( __FILE__ ) . 'src/Deactivation.php'; Deactivation::deactivate(); } );
Once you've registered your deactivation callback, you need to run some code on deactivation. The following is an example of how to set up your Deactivation class:
<?php namespace PDEV; class Deactivation { public static function deactivate() { // Run your deactivation code here. } }
Like with the activation hook, you have the freedom to run any code that you need when a user decides to deactivate your plugin.
Deactivate Is Not Uninstall
Setting up a deactivation callback is often unnecessary because most of the things you might think you'd need to unset on deactivation should actually happen when a user uninstalls the plugin. Deactivation is not an appropriate time to delete plugin options, remove database tables, delete user content, or perform any other highly destructive actions.
Users and even WordPress itself may deactivate a plugin for any number of reasons. You don't want your plugin users to lose any important data when deactivating only to reactivate and find their settings or content gone. Use with extreme caution.
UNINSTALL METHODS
Cleaning up anything left behind when a user uninstalls your plugin is an important aspect of developing plugins professionally. Running an uninstall procedure takes little work on your part but makes sure that users can trust that they can use your plugins without those plugins leaving unwanted data behind.
Why Uninstall Is Necessary
If you install an app on your mobile phone and decide at some point that you no longer want to use that app, you'll delete or “uninstall” it. You wouldn't want the app to leave behind all of its settings or any other data that is no longer useful. WordPress plugins are no different. Users should feel confident that their site doesn't have cruft left over from every plugin they've used or even just tested and decide it wasn't for them.
If there's an ultimate “no‐no” in plugin development, it's to not tidy up after yourself. When your plugin is uninstalled, make sure to delete any options or other data that your plugin has added.
However, there are times when you want to ignore this rule. In general, user‐created content, such as that created by custom post types or custom database tables, may need to be retained. In these situations, it's best to provide a setting that a user can opt into that allows you to delete that data on uninstall. The rule of thumb here is to always be respectful of their content. When in doubt, get the user's permission before deleting anything they might want to keep.
WordPress provides two different methods for uninstalling a plugin: the uninstall.php file and the uninstall hook.
Uninstall.php
The first method of uninstalling a plugin is by creating an uninstall.php file in the root of your plugin folder. This is the method that you'll most likely be using and is the recommended route to take.
Using uninstall.php is the preferred method of uninstalling a plugin because it isolates your uninstall code from the rest of your plugin and doesn't allow arbitrary code to run from your other plugin files. Ideally, your plugin should be structured such that arbitrary code is never run. However, uninstall.php protects against this and makes sure only the code contained within the file is executed.
It's also important to check that WP_UNINSTALL_PLUGIN is set before executing your uninstall code. Otherwise, it's possible the file will be inadvertently called and your plugin will delete everything when it shouldn't.
In
