Supporting Many WordPress Versions

While the latest and greatest versions of WordPress will always provide the best APIs and features, you may not always have the luxury of basing your plugins on it exclusively. In fact, it's more likely you will have no control over what version of WordPress the users of your plugins are on. Their version could be years old, they might be testing the latest nightly build, and your plugin needs to understand the differences to avoid your plugin not working or, even worse, breaking their site completely.

The WordPress project is hugely committed to maintaining backward compatibility, sometimes going to great lengths and huge efforts to avoid breaking changes between releases. This creates a much more developer‐friendly environment than if things were breaking all the time, because you can always count on the code that you rely on to continue to do what it always has (even when a new version of WordPress is released) but also means you will have some hard decisions to make for your own plugins.

New major versions of WordPress are released about three times per year, but that can change based on leadership, goals, roadmap, and so on. A good rule of thumb for your own plugins is to maintain backward compatibility for somewhere between three and six major WordPress release cycles. This way, you are able to stay current with the latest WordPress features, while also giving all of your users a few years to get updated.

Some plugins you create will always be backward compatible because they do not use any of the newest functionality in WordPress, and other more complex plugins (like WooCommerce or BuddyPress) support many older versions because they still have hundreds of thousands of people using them.

PHP offers a few different helper functions you should use if you are planning on relying on and using the latest WordPress code available. You can tell what version of WordPress something was introduced in by looking at the documentation block for the @since tag. Here's what the block_version() function looks like:

/**
 * Returns the current version of the block format that the content string is using.
 *
 * If the string doesn't contain blocks, it returns 0.
 *
 * @since 5.0.0
 *
 * @param string $content   to test.
 * @return int The block format version is 1 if the content contains
   @one or more blocks, 0 otherwise.
 */
function block_version( $content ) {
       return has_blocks( $content ) ? 1 : 0;
}

If your plugin is using this function but you need to support both WordPress 4.9 and 5.0, you could use the PHP function function_exists() to check whether the user is using a version of WordPress that includes that function in it.

<?php
 
// Block Version is available
if ( function_exists( 'block_version' ) ) {
       $version = block_version( $content );
 
// Block Version unavailable
} else {
       $version = 0;
}
?>

The code snippet uses function_exists() to check whether the block_version() function exists. If it does exist, this means the user is using WordPress 5.0 or newer, and the plugin can use the block_version() function. If the function does not exist, the plugin can fall back to an alternative way to handle the functionality.

PHP also offers class_exists() and method_exists() to check whether a class or class method exists, and it offers is_callable() to verify that the contents of a variable can be called as a function. You will find yourself using these helpers more and more as you begin to support a wider array of WordPress releases.

Similarly, WordPress comes with dozens of its own helper functions designed to be used under specific circumstances. Some are environmental, while others help with validation or formatting. These functions will typically start with either is_ or wp_is_, but there are a few outliers.

Playing Nicely with Other WordPress Plugins

As a professional WordPress plugin developer, the code you write in your plugins will be running alongside any number of other plugins, many of which are probably not ones you authored yourself. At the time of this writing, there are more than 80,000 plugins available for free in the WordPress Plugin Directory and tens of thousands that are privately given away or sold outside it.

It is impossible for you to know what all of these plugins do or to predict which ones may be activated at the same time as yours in the future, so you will need to code defensively to avoid conflicts and collisions, which you will inevitably run into, either in your own code or in someone else's.

WordPress includes plugins in such a way that they are executed immediately inline and side by side with WordPress itself. Located in wp‐settings.php, here is the exact code that loops through active and valid plugins and includes them:

// Load active plugins.
foreach ( wp_get_active_and_valid_plugins() as $plugin ) {
       wp_register_plugin_realpath( $plugin );
       include_once( $plugin );
 
       /**
        * Fires once a single activated plugin has loaded.
        *
        * @since 5.1.0
        *
        * @param string $plugin Full path to the plugin's main file.
        */
       do_action( 'plugin_loaded', $plugin );
}
unset( $plugin );

The include_once() line in the preceding code ensures that a plugin is only ever included one single time. This is another common way to avoid fatal errors in WordPress, as including the same file multiple times would also redefine its classes and functions, leading to a broken WordPress installation. It is slower than its partner include() but is generally considered safer in WordPress due to how unpredictable including files can be.

When WordPress includes a main plugin file, the code inside that file is interpreted and executed immediately, which makes it the perfect place to do some environmental checking and preliminary setup (aka bootstrapping) but a bad place to perform much else. This is because plugins are included relatively early inside WordPress (before much of WordPress has had a chance to get set up itself), so most of what you may be hoping to modify will not even exist yet.

The way WordPress loads plugins also means that every plugin is included in the global scope. This means that every plugin has the ability to change WordPress in any way necessary, and plugins other than yours will being doing so. Everything being loaded up in the same global scope means you will want to be consistent with the following globally scoped concepts:

• Function names
• Class names
• Namespaces
• Action hooks
• Filter hooks
• Global variables

It will also help you immensely to become comfortable exploring the source code of other WordPress plugins. You will pick up on their ideas, patterns, methodologies, and approaches to solving problems similar to those you will face, which in turn will help you create plugins that play nicely with other plugins.

Some larger plugins are even designed to be just as extensible as WordPress is itself, allowing for plugin developers to extend them, essentially writing plugins for plugins. WooCommerce, Easy Digital Downloads, BuddyPress, and bbPress are just a few examples of massive plugins with thriving add‐on and third‐party communities, where developers are writing WordPress plugins that rely on or integrate specifically with another plugin.

Whether you are writing a stand‐alone plugin or one that seeks to extend an existing one, it is inevitable that someone will identify a conflict or collision between their plugin and one of yours. When this happens (and it will happen), you will find the majority of other plugin developers to be kind, helpful, and willing to share their knowledge for the betterment of your mutual WordPress users. It may be your fault or theirs, but that doesn't matter—what matters is improving the code so that users have the best possible experience regardless of what plugins they have installed.

Keeping Current with WordPress Development

One of the main reasons why WordPress is the most popular piece of software for publishing to the web is that it acts as its own compatibility layer between all of the software running on the server and the user who is actually using WordPress to write and publish their content. This means that WordPress is able to adapt to whatever libraries or modules are activated and available in the web server software being used.

Just like WordPress, software interpreters like PHP and web servers like Apache or Nginx can be configured differently from place to place, and WordPress exists to make all of those different configurations completely invisible.

In addition, the project's undying commitment to maintaining backward compatibility means that developers like you can code with confidence that a new WordPress version will not break any of the plugins you've written.

WordPress is constantly changing. Not a single day will go by without a core committer or contributor submitting a patch to fix a bug, inventing a fancy new feature, or proposing different ideas about the direction of WordPress itself. It is a vast and growing community with many moving parts and avenues where ideas are flowing in and out of various stages of implementation.

Even though WordPress changes frequently and rapidly, you will want to do your best to keep up with what is changing and why. In doing so, you will be the first to

• Find new features and functions
• Find out when old functions are deprecated or removed
• See when a WordPress bug affects one of your plugins
• Take advantage of the latest performance improvements

You will find that you can sometimes eliminate many lines of your own plugin code when new functionality is introduced into WordPress. You can remove old functionality and replace it with something new when functions are deprecated. And you can make your own life easier by not shimming work‐arounds for WordPress bugs that you have been maintaining all by yourself.

You should also know how releases are handled within WordPress. Understanding this simple concept can enable you to know when you need to do an overview of your plugins to see whether an update is needed. The two types of releases are major releases and minor (or point) releases.

• Major releases: 5.4, 5.3, 5.2, and so on. These releases are made available every few months with new features, new functionality, and bug fixes. Many code changes are made between major releases.
• Point releases: 5.3.1, 5.3.2, 5.3.3, and so on. These releases are made as needed between major releases and contain bug fixes and security improvements only. New functionality is rarely added in a minor release.

Being involved in the broader WordPress community will help your plugin development in many ways. The most important place to keep track of changes is the Make Network, located at make.wordpress.org. This is a group of blogs (one for each contributor group), general news, and upcoming team meetings and events. The development tracker located at core.trac.wordpress.org is also really important, as it is where the bulk of WordPress code changes occur. It is powered by a piece of software called Trac. It may take a little time to understand how the system works, but when you do, you'll probably even find yourself getting involved in WordPress development. The best way to start learning the system is to simply start reading some tickets and do your best to follow along with the development flow.

Starting with WordPress 5.0, the introduction of a new block‐based editor means that some development is starting to happen on GitHub, which is then later merged into WordPress itself. This is good in that it provides a bit more freedom to people contributing to that part of the source code but bad in that it further fragments and complicates the entire core development process. It is mostly up to you to decide how much value you derive from following along, but today WordPress is all about blocks, so try to follow along if you can.

Deprecation

When something is deprecated, it is being phased out and should no longer be used. When a function gets deprecated, it is almost always replaced by something newer and better. Sometimes something as small as a function parameter gets deprecated, or other times as large as an entire file gets removed.

Deprecated functions usually live within one of several WordPress files.

• wp‐includes/deprecated.php: General functions
• wp‐includes/ms‐deprecated.php: Multisite functions
• wp‐includes/pluggable‐deprecated.php: Pluggable functions
• wp‐admin/includes/deprecated.php: Admin functions

Browsing through the core code for deprecated functions might seem tedious, but it's a good idea to become familiar with them so that you can recognize them, avoid using them, and use their updated equivalents instead.

Dealing with Obsolete Client Installs

When you release a plugin to be available to the general public, you will have no control over whether those users keep their WordPress installation up‐to‐date, but when you deal directly with your clients, you can communicate directly with them and maybe even have some administration access to their WordPress installation.

If you work with clients who use an outdated version of WordPress, you should consider it your responsibility to educate them on the benefits of using the latest and most secure version, along with any plugins and themes they are using. If you have a client who does not want to update, here is a handy list of reasons why they should update:

• It makes developing their plugins easier.
• It can cut back on development time and cost.
• Performance improvements may decrease hosting costs.
• There is less chance of their site being targeted and hacked.

The most important thing you can stress is the increased security of each new version. A paying client tends to perk up and pay attention when you can tell them a story of a different site having been vandalized because of an out‐of‐date WordPress installation.

When upgrading any sites, the most important thing you can do is keep multiple backups of files and the database and make sure you are able to quickly and easily restore from a backup if needed. The WordPress update process is usually simple and painless, but if something goes wrong. you will definitely want to be able to bring everything back online fast.

Many WordPress hosting companies automatically manage backups for you and have convenient interfaces for restoring everything back to normal again.

Enabling Debugging

In this section, you will enable debugging for your entire WordPress installation. You must enable debugging whenever developing plugins. It will make your plugin better, and your job easier, by letting you know what issues arise during the development phase.

At the root of your WordPress installation, open the wp‐config.php file. This file includes all of the fundamental configuration settings that are required by WordPress to connect to the database, generate secure random numbers, and then continue loading the rest of WordPress.

Near the bottom, you should see the following:

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the Codex.
 *
 * @link https://codex.wordpress.org/Debugging_in_WordPress
 */
define( 'WP_DEBUG', false );

Just like the inline code documentation says, changing the WP_DEBUG constant from false to true will enable WordPress debugging mode. By default, debugging mode is off, and you must manually enable it here by editing this file.

That line of code should now look like this:

define( 'WP_DEBUG', true );

Enabling debugging mode makes two important things possible.

• Debug messages will now be displayed directly on the screen as they happen. This feature can be selectively toggled off by setting WP_DEBUG_DISPLAY to false.
• Allows error logging to be enabled, which is covered in the “Error Logging” section of this chapter.

Displaying Debug Output

After you enable debugging mode, refresh your WordPress installation in your preferred web browser. If you're lucky, you may suddenly see error messages displayed in various places on the page where there were none previously.

Now let's take a look at what a deprecated function looks like when used with debugging enabled. Suppose you wanted to get all of the possible category IDs. Prior to WordPress 4.0, the function you would use for this would be get_all_category_ids(), but now that this function is deprecated, using it will output a debug notice that reads as follows:

Notice: get_all_category_ids is deprecated since version 4.0.0!
Use get_terms() instead.

This notice immediately tells you several things about that function.

• The deprecated function name
• The WordPress version where the function was deprecated
• The replacement function to use instead

To update your code, simply swap out the deprecated function with the replacement function. In some instances, there is no replacement, and you will have to deal with those scenarios on a case‐by‐case basis—each situation may have a different or unique solution.

Making simple changes like this one will bring your code up‐to‐date and remove any debug messages relating to it from the rest of the site.

Understanding Debug Output

Most debug output is the result of PHP notices, which are related to but less severe than a PHP warning or alert. Even though a notice is relatively innocuous (it will not fatally error a site), it is still important to track them all down and fix them, as they are usually an indication of more severe problems with the surrounding code that could eventually cause worse breakage.

You should consider it your responsibility to always debug your code and to eliminate all notices, warnings, and alerts from your plugins. In this section are several of the most common debug outputs and how to address them.

• Deprecated WordPress functions
• Undefined variable/property notice
• Trying to get the property of a nonobject notice

To see debug notices in action, you must first write a plugin to expose them. This is one of the few times in this book that you will be asked to write code that is intentionally broken, but what better way is there to learn than by making mistakes?

For this example, we are going to keep things simple. This plugin will attempt to add the author's name and bio at the end of every post. Create a new file named pdev‐notice‐plugin.php in your /wp‐content/plugins/ directory and add the following code to the file:

<?php
/**
 * Plugin Name: Debug Notices
 * Plugin URI:  https://wrox.com
 * Description: Plugin to create debug errors
 * Version:     0.0.1
 * Author:      WROX
 * Author URI:  https://wrox.com
 */
 
add_filter( 'the_content', function( $content = '' ) {
 
    // If viewing a post with the 'post' post type
    if ( 'post' === $post->post_type ) {
        $author_box  = '<div class="author-box">';
        $author_box .= '<h3>' . get_the_author_meta( 'display_name' ) . '</h3>';
        $author_box .= '<p>' . get_the_author_description() . '</p>';
        $author_box .= '</div>';
    }
 
    // Append the author box to the content.
    $content = $content . $author_box;
 
    // Return the content.
    return $content;
} );

There are several issues with this plugin. With debugging enabled, you should be looking at a screen with three separate debug notices. There is actually a fourth problem with this code, but one is hidden away because the surrounding code is not exposing it yet.

The three notices are as follows:

Notice: Undefined variable: post in /wp-content/plugins/pdev-notice-plugin.php
        on line 14
Notice: Trying to get property 'post_type' of non-object in
        /wp-content/plugins/pdev-notice-plugin.php on line 14
Notice: Undefined variable: author_box in /wp-content/plugins/
        pdev-notice-plugin.php on line 22

The first and worst issue is with this line:

    if ( 'post' === $post->post_type ) {

PHP is attempting to interpret what the $post variable is, but because it has not been set or defined in the current scope, an “undefined variable” debug notice is triggered. In addition, because that variable does not exist, it also definitely is not an object, so a “Trying to get property of non‐object” debug notice is also triggered. Both of these problems can be fixed a few different ways in WordPress, but one way is better than all of the rest. You can use the get_post() function to get whatever the current global $post variable is, without needing to define or touch the global yourself, like so:

$post = get_post();

The reason this is the best approach is because defining global variables inside your local function or method scope puts them at risk of accidentally being overwritten. Changing the contents of a global variable almost always has negative consequences and should be avoided whenever possible.

After fixing these two issues, the third debug notice will disappear when viewing a blog post but remain when viewing a page. This notice is caused by the next line of the plugin, resulting in an “undefined variable” notice.

$content = $content . $author_box;

The problem with this line is that the $author_box variable will not always be set, so PHP is attempting to concatenate a string with an invalid variable reference. This notice is one of the issues you will run into quite frequently and is one the easiest issues to fix.

It is best practice to either explicitly set up your local variables with intelligent default values near the top of your functions or check whether they have been set before trying to use them.

In this circumstance, you may want to use the PHP function isset() to check whether the $author_box variable has been set before appending it to the $content variable.

if ( isset( $author_box ) ) {
    $content = $content . $author_box;
}

An even better way to check a variable like this while also avoiding unnecessary processing is with the PHP function empty(). The nice thing about empty() is that it returns true for all “falsy” values, including null, an empty string, or a zero value. This way, if $author_box is set but does not actually contain anything useful, PHP will not need to concatenate anything.

if ( ! empty( $author_box ) ) {
    $content = $content . $author_box;
}

Now that you've fixed these first three issues, you will see a fourth debug notice appear, letting you know that you used a deprecated function: get_the_author_description(). The message also tells you that it has been replaced by get_the_author_meta(‘description’). This debug message is caused by this line of the plugin:

$author_box .= '<p>' . get_the_author_description() . '</p>';

Once again, this is a simple problem to solve. You just need to replace the only usage of this deprecated function with the new function being recommended, and the new code will look like the following:

$author_box .= '<p>' . get_the_author_meta( 'description' ) . '</p>';

Making these small changes clears the plugin of debug notices completely. It can also make the intended functionality of the plugin work. After completing each change, your code appears as shown in the following plugin:

<?php
/**
 * Plugin Name: Debug Notices
 * Plugin URI:  https://wrox.com
 * Description: Plugin to create debug errors
 * Version:     0.0.1
 * Author:      WROX
 * Author URI:  https://wrox.com
 */
 
add_filter( 'the_content', function( $content = '' ) {
       $post = get_post();
 
    // If viewing a post with the 'post' post type
    if ( ! empty( $post ) && ( 'post' === $post->post_type ) ) {
        $author_box  = '<div class="author-box">';
        $author_box .= '<h3>' . get_the_author_meta( 'display_name' ) . '</h3>';
        $author_box .= '<p>' . get_the_author_meta( 'description' ) . '</p>';
        $author_box .= '</div>';
    }
 
    // Append the author box to the content.
       if ( ! empty( $author_box ) ) {
              $content = $content . $author_box;
       }
 
    // Return the content.
    return $content;
} );

Enabling Error Logging

By enabling error logging, you gain an easy way to keep track of all debug output on your site in a central location. It gives you the exact debug notices along with the date and time the error occurred. Each entry is saved at the end of a debug.log file, located inside the wp‐content directory.

To enable error logging, you need to edit the wp‐config.php file as you did earlier when you turned on WP_DEBUG mode. This time, you need to turn on WP_DEBUG_LOG by adding the following code to the file:

define( 'WP_DEBUG_LOG', true );

The debugging section of your wp‐config.php file should now look like this:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );

Together, these two lines tell WordPress to enable debugging mode and that all debug output should be saved to the error log file.

You may want to optionally disable the display of debug messages on the site and save them in the debug file only. This is useful if you want to keep track of debug output on a live site. To do this, you need to add two new constants to your wp‐config.php file.

define( 'WP_DEBUG_DISPLAY', false );

Internally, this also tells all of PHP to suppress displaying errors, as follows:

ini_set( 'display_errors', 0 );

Setting Log File Location

When error logging is enabled, by default WordPress will create a file named debug.log in the wp‐content folder. In most situations, this location and filename will work fine. If you want to change it to something else, you have the option to do so by setting the WP_DEBUG_LOG constant to the full path to where the log file should be located.

define( 'WP_DEBUG_LOG', '/var/log/wordpress/debug.log' );

This example tells WordPress to save the debug log to a specific server path and filename. This path must already exist, and whatever web server user is used for WordPress must also have write permissions to the directory; otherwise, the log will fail to be created or written to.

Understanding the Log File

The debug.log file can be read with any basic text editor, so you should not have any trouble opening it and reading its contents.

In the “Debugging” section, you created an error plugin. You also learned how to correct debug messages displayed on the screen. The error log file is another way to view that debug output, and the content that is saved in the log file will look exactly the same as what you saw onscreen. The following is a snippet from the debug log file that the plugin you created earlier will produce:

[01-Oct-2019 00:00:00] PHP Notice:  Undefined variable: post in
                           /wp-content/plugins/pdev-notice-plugin.php on line 14
             
[01-Oct-2019 00:00:00] PHP Notice:  Trying to get property 'post_type' of
                       non-object in /wp-content/plugins/pdev-notice-plugin.php
                       on line 14
             
[01-Oct-2019 00:00:00] PHP Notice:  Undefined variable: author_box in /wp-content/
                       plugins/pdev-notice-plugin.php on line 22

As you can see, each notice creates a new entry in the file, and each entry looks nearly the same as what it looked like in the “Debugging” section. The only exception/bonus here is that you have an exact date and time of when the output occurred.

After reading your error log entries, you should revisit the “Debugging” section to work through all of the problems that it reveals. The error log entries do not get removed from the file after you have fixed their related issue on the site and in your plugin, so be sure to pay attention to the date and time stamps so that you are not looking for issues that you have already fixed.