Professional WordPress Plugin Development. Brad Williams

URL path the REST API endpoint

       includes_url(): URL path to the WordPress includes directory

       content_url(): URL path to the WordPress content directory

      All of these URL functions accept an optional first parameter of $path, which is appended to the end of the URL if provided. The following example shows how to retrieve the URL path to the General Settings page in the admin:

      <?php $url = admin_url( 'options-general.php' ); ?>

      With the exception of the content_url() function, each of these functions also accepts an optional second parameter of $scheme, which allows you to manually set the protocol, such as 'http' or 'https'. In almost all cases, you should not set this parameter and should instead allow WordPress to automatically determine the appropriate URL scheme.

      First‐time WordPress developers will also sometimes confuse site_url() and home_url(). WordPress can be installed in a subdirectory on the server while allowing the actual site to be located elsewhere. Unfortunately, the function names are part of a legacy code base and have stuck around. The trick is to remember that the “home” in home_url() refers to the URL of the site, and the “site” in site_url() refers to the URL of the WordPress installation.

      If WordPress is installed in a subdirectory, site_url() might point to a URL like https://example.com/wordpress, while home_url() points to https://example.com.

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.