Professional WordPress Plugin Development. Brad Williams

      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 the following example, you can see that the uninstall procedure checks the constant and removes the pdev_manage capability added in the “Plugin Activation Hook” section earlier in this chapter:

<?php if ( ! defined( 'WP_UNINSTALL_PLUGIN' ) ) { wp_die( sprintf( __( '%s should only be called when uninstalling the plugin.', 'pdev' ), __FILE__ ) ); exit; } $role = get_role( 'administrator' ); if ( ! empty( $role ) ) { $role->remove_cap( 'pdev_manage' ); }

      Uninstall Hook

      WordPress provides an uninstall hook similar to its activation and deactivation hooks outlined earlier in this chapter. If no uninstall.php file exists for the plugin, WordPress will look for a callback registered via the register_uninstall_hook() function.

      <?php register_uninstall_hook( $file, $callback ); ?>

      Parameters:

       $file (string, required): The primary plugin file

       $callback (callable, required): A function to execute during the uninstall process

      Now look at the following example of how a plugin uninstall function works:

      <?php register_uninstall_hook( __FILE__, 'pdev_uninstall' ); function pdev_uninstall() { $role = get_role( 'administrator' ); if ( ! empty( $role ) ) { $role->remove_cap( 'pdev_manage' ); } }

      That example performs the same action as the uninstall.php file from the previous section in this chapter. However, you may have noted an important difference. There's no need to check the WP_UNINSTALL_PLUGIN constant because it's not set in the uninstall callback and unnecessary.

      It's also important to use $this or an object reference when registering an uninstall hook because this callback reference is stored in the database and is unique to the page load when it is stored.

CODING STANDARDS

      Following a set of standards when developing plugins professionally is important because it makes long‐term maintenance of your code easier and also allows other developers to quickly learn from or contribute to your plugin. WordPress maintains a coding standard for the core source code. It is a good starting point when building plugins. You can view the WordPress coding standards at https://make.wordpress.org/core/handbook/best-practices/coding-standards.

WordPress has more than 15 years of legacy code, and sometimes its standards do not align with the standards of the larger PHP community. This can be off‐putting for some PHP developers new to the WordPress community. You may also want to follow PHP Recommended Standards (PSRs) created and maintained by the PHP Framework Interprop Group (PHP‐FIG) for the larger PHP community. You can find these standards at https://www.php-fig.org/psr.

      The most important thing is to maintain consistency in your code base, regardless of the coding standards that you follow.

      Document Your Code

      One of the worst things you can do as a developer is to never document your code. While you should always strive for your code to be self‐documenting by naming things in ways that make sense and limiting functions/classes to a single responsibility, documenting your code is just as important as the code itself.

      Imagine writing a large plugin for a client today and not documenting what everything does. That same client calls you up in two years to make some big updates for them. Can you honestly say that you'll completely understand the code that you wrote two years ago? Even if you could, what about another developer? You may think that it's not your problem, but that could earn you a poor reputation in the WordPress developer community. You should be a “good citizen” and help your fellow developers.

      Documentation is also important when building plugins for public release. For others to contribute code to your plugin through patches or pull requests, other developers should have enough documentation to understand any decisions that you made with the code.

      WordPress uses PHPDoc for adding documentation to code. PHPDoc is a standard for documenting files, functions, classes, and any other code written in PHP. The following is an example of using PHPDoc to document a function:

      <?php /** * Short Description. * * Longer and more detailed description. * * @param type $param_a Description. * @param type $param_b Description. * @return type Description. */ function pdev_function( $param_a, $param_b ) { // Do stuff. }

As you can see, the inline PHPDoc describes what the function does, what parameters it accepts, and what it returns. Another developer wouldn't even have to read your code to understand what it does.

      NOTE Good documentation helps when spotting bugs. If the function's code does something different from what is outlined by the documentation, you or another developer will know either the documentation or the code is incorrect.

      Naming Variables and Functions

      Variables and functions should always be written in snake case. All characters should be written in lowercase, and multiple words should be separated with an underscore. Functions and variables in the global namespace should also be preceded with a unique prefix for your plugin, such as pdev_. The following example is the correct way to write a function:

      <?php function pdev_function( $param_a ) { // Do stuff. }

      $param_a isn't in the global scope there, so it doesn't need a prefix. While it's considered bad practice to use global variables, if you do use them, make sure to prefix.

      Naming Classes and Methods

      Class and method naming is one area where the core WordPress coding standards don't align with the PHP community. The PHP standard is to write class names in PascalCase where the first character of each word is uppercase and there are no separators between words. The standard for class methods is to write words in camelCase where the difference is that the first character of the first word is lowercase.

      The following example shows what a basic class with a single method looks like using this method:

      <?php class PDEVSetup { public function setupActions() { } }

      The WordPress coding standards follow a different set of rules. Look at the following example to spot the differences:

<?php class PDEV_Setup { public function setup_actions() { } }

      As you can see, the WordPress method uses underscores to separate class names and uses snake case for method names. You'll need to decide the best direction for your own plugins. There's no one right answer, and developers have been arguing over naming schemes for as long as programming has existed. The most important thing is to be consistent in your own code.

      Naming Files