What Securing Your Plugin Is

Securing your plugin means properly dealing with vulnerabilities and making sure data that is input or output is reliable. You must prevent malicious attacks while also making sure that legitimate user input/output does not produce unexpected behavior.

What Securing Your Plugin Is Not

Securing your WordPress plugin code in WordPress is not a difficult or unachievable task that only security experts can do. WordPress provides nearly every function you'll ever need for making sure your plugins are secure.

How to Check current_user_can()

When using the current_user_can() function, you'll check whether a user has permission to move forward with performing a sensitive action or output an error message and die. The following example checks whether the current user has permission to install plugins. If they do not, the code bails out with an error message.

<?php
if ( ! current_user_can( 'install_plugins' ) ) {
       wp_die( 'You do not have sufficient privileges to install plugins.' );
}

Often, you'll want to check permission before outputting a link or some other HTML so that a user doesn't see actions in the UI they're not allowed to perform. The next example checks whether a user can manage options before outputting a link to the General Settings screen in the WordPress admin:

<?php if ( current_user_can( 'manage_options' ) ) {
      printf(
             '<a href="%s">Manage Settings</a>',
             esc_url( admin_url( 'options-general.php' ) )
      );
}

The install_plugins and manage_options strings in the previous two examples are called capabilities in the WordPress environment. Capabilities are a part of the user role system, which you'll learn more about in Chapter 9. For the purposes of security, you merely need to know whether the current user has a specific capability that you need to check against.

Do Not Check Too Early

Before checking whether a user has the correct authorization, you must wait until the current user's data has been set up. The current_user_can() function relies on wp_get_current_user(), a pluggable function. Pluggable functions can be overwritten by plugins. Therefore, they are not loaded until all plugins have been loaded.

Therefore, you must wait until WordPress has initialized before checking permission. The init hook is the earliest point in the load process that is a safe bet for such checks or any hook executed later.

Imagine that you wanted to build a plugin that provided a link to the user management screen to the WordPress toolbar (also called the admin bar). The toolbar has hooks that run after WordPress has initialized, so you can check whether a user has permission to edit users before appending the link.

See how the following complete plugin hooks into wp_before_admin_bar_render and checks whether the current user has the edit_users capability before adding a link to the toolbar:

<?php
/**
 * Plugin Name: Users Toolbar Link
 * Plugin URI:  http://example.com/
 * Description: Adds a toolbar link to the users admin screen.
 * Author:      WROX
 * Author URI:  http://wrox.com
 */
 
add_action( 'wp_before_admin_bar_render', 'pdev_toolbar' );
 
function pdev_toolbar() {
       global $wp_admin_bar;
 
       if ( current_user_can( 'edit_users' ) ) {
 
             $wp_admin_bar->add_menu( [
                    'id'    => 'pdev-users',
                    'title' => 'Users',
                    'href'  => esc_url( admin_url( 'users.php' ) )
             ] );
       }
}

Authority vs. Intention

If a user has permission to perform an action (i.e., their role is granted a capability), it means they have the authority to do so. Any time you're in your WordPress admin, you can click links to do all sorts of things, such as publish a post, edit a category, or manage options. Any time you click a link to take an action, WordPress will verify that you have the authority to do so by checking current_user_can().

But hackers are craftier than that. What happens if someone knew the exact URL on your site to delete a post, for example? They don't have the authority to perform an action because they don't have sufficient permission on your site, so the URL wouldn't work for them. However, what if they tricked you, an administrator with permission, into clicking a link for deleting a post? Or even a more destructive action, such as deleting a user account? You would have the authority to take these actions, but it wasn't your intention to do so. This is called a cross‐site forgery request.

What Is a Nonce?

A nonce, or a cryptographic nonce, is the abbreviation for “number used once.” In WordPress, a nonce is a short and seemingly random string that looks similar to a password. This string represents the following:

• One user
• One action, such as delete, update, or save
• One object, such as a post, term, or user
• One time frame that lasts 24 hours

You've probably seen these nonce strings in URLs in your WordPress admin from time to time. For example, the link to delete a user with the ID of 100 might look something like http://example.com/wp-admin/users.php?action=delete&user=100&_wpnonce=f73684c03c. The f73684c03c at the end of the URL is the nonce. It is valid for only one time frame (24 hours) for one user (you) to take a specific action (delete) on the specific object (user) with the ID of 100.

If another person managed to get this link, even if they had a user account, the link would be invalid. After 24 hours, the link will also be invalid for your user account, and a new nonce will be created for the given action. As you can see in Figure 4‐2, WordPress will output an expired link message if the nonce is invalid.

How to Create and Verify Nonces

WordPress has two methods of adding nonces. One method is for attaching a nonce to a URL. The second method is for outputting a hidden nonce field in HTML forms.

<?php
wp_nonce_url( $url, $action = -1, $name = '_wpnonce' );

<?php
$url = add_query_arg(
       [
             'action' => 'delete',
             'user'   => 100 
       ],
       admin_url( 'users.php' )
);
 
return wp_nonce_url( $url, 'pdev_delete_user_' . 100 );
 
// Returns (with unique nonce):
// http://example.com/wp-admin/users.php?action=delete&user=100&_wpnonce=f73684c03c

<form method="post" action="">
      <?php wp_nonce_field( 'pdev_nonce_action', 'pdev_nonce_name' ); ?>
 
      <p>
             <label>
                    Enter your name:
                    <input type="text" name="pdev_nonce_example" value="<?php echo
                      esc_attr( $value ); ?>"/>
             </label>
      </p>
 
      <?php submit_button( 'Submit', 'primary' ); ?>
</form>

<?php
/**
 * Plugin Name: Nonce Example
 * Plugin URI:  http://example.com/
 * Description: Displays an example nonce field and verifies it.
 * Author:      WROX
 * Author URI:  http://wrox.com
 */
 
add_action( 'admin_menu', 'pdev_nonce_example_menu'   );
add_action( 'admin_init', 'pdev_nonce_example_verify' );
 
function pdev_nonce_example_menu() {
 
       add_menu_page(
             'Nonce Example',
             'Nonce Example',
             'manage_options',
             'pdev-nonce-example',
             'pdev_nonce_example_template'
       );
}
 
function pdev_nonce_example_verify() {
 
       // Bail if no nonce field.
       if ( ! isset( $_POST['pdev_nonce_name'] ) ) {
             return;
       }
 
       // Display error and die if not verified.
       if ( ! wp_verify_nonce( $_POST['pdev_nonce_name'], 'pdev_nonce_action' ) ) {
             wp_die( 'Your nonce could not be verified.' );
       }
 
       // Sanitize and update the option if it's set.
       if ( isset( $_POST['pdev_nonce_example'] ) ) {
             update_option(
                   'pdev_nonce_example',
                   wp_strip_all_tags( $_POST['pdev_nonce_example'] )
             );
       }
}
 
function pdev_nonce_example_template() { ?>
 
       <div class="wrap">
             <h1 class="wp-heading-inline">Nonce Example</h1>
 
             <?php $value = get_option( 'pdev_nonce_example' ); ?>
 
             <form method="post" action="">
 
                 <?php wp_nonce_field( 'pdev_nonce_action', 'pdev_nonce_name' ); ?>
 
                 <p>
                          <label>
                                 Enter your name:
                                 <input type="text" name="pdev_nonce_example"
                                 value="<?php echo esc_attr( $value ); ?>"/>
                          </label>
                 </p>
 
                 <?php submit_button( 'Submit', 'primary' ); ?>
             </form>
       </div>
<?php }

The Need for Data Validation and Sanitization

To show the importance of validating and sanitizing data, review the following form code:

<?php $full_name = $_POST['full_name']; ?>
 
<form action="" method="POST">
       <label>
           Full Name:
           <input type="text" name="full_name" value="<?php echo $full_name; ?>"/>
       </label>
       <input type="submit" value="Submit"/>
</form>

This is a basic form that allows a user to enter their full name. However, there are two issues with the data in this case.

• The $_POST data in a real‐world scenario would likely go to the database, so it must be sanitized to make sure that it's safe.
• The $full_name variable on output as the value attribute must be escaped to make sure it doesn't break out of the HTML and allow something like a malicious script to run.

To illustrate the problems with this form, input the following examples and check the results:

1. Nonmalicious example: John “Average” Doe
2. Malicious input: John”/>Password:<input name=”password” value=”1234”
3. Malicious input: John“<script>alert(‘XSS’);</script>

Input 1 is an example of basic user input. Users input all sorts of characters both intentionally and unintentionally. It's your job to make sure this doesn't break things. The quotation marks in this case break the HTML in the form. They need to be encoded to their appropriate HTML entities.

Input 2 does the same thing as the first example. However, there is obvious malicious intent. Once the form is submitted, it breaks out of the HTML and creates an additional password field. The hacker here is potentially attempting to change a password if they get lucky. The extra HTML should've been stripped when the form was posted.

Input 3 is an example of cross‐site scripting. This is a serious vulnerability where hackers attempt to inject JavaScript to do bad things. For example, they may attempt to grab session or user cookies. The end goal is typically to gain access to privileged content or user accounts. If they're successful in gaining access, there's no limit to what they can do, such as taking down an entire site or adding hidden spam.

Figure 4‐3 illustrates the third example. As you can see, the form allows an arbitrary JavaScript code snippet to run. While an alert box is just an example, a malicious party could execute anything possible with JavaScript as if they had access to your site.

Now you can see why it's important to protect something as simple as a basic form on a web page from nonmalicious users with good intent as well as bad actors looking for ways to crack into a site. Remember that suspicion is healthy when dealing with untrusted data.

Good Practice: Identifying Potentially Tainted Data

Imagine that you created a survey to find out people's favorite fruit. Maybe you want to cross‐reference that by age so that a client can better serve their customers at their online fruit shop. Your form may have a text input for visitors to enter their age and a drop‐down for selecting from a predefined list of fruit. Consider the following code snippet that accepts the data that's input:

<?php
$safe = [];
 
$safe['age'] = absint( $_POST['age'] );
 
$valid_fruit = [
       'banana',
       'kiwi',
       'watermelon'
];
 
$safe['fruit'] = 'watermelon';
 
if ( in_array( wp_unslash( $_POST['fruit'] ), $valid_fruit, true ) ) {
       $safe['fruit'] = wp_unslash( $_POST['fruit'] );
}

Notice that the first bit of code creates an empty array named $safe. It's good practice to create a separate variable early so that you can store data that has been validated or sanitized. Because you named it $safe, you'll recognize that it's the data that you'll want to send to the database or elsewhere after the form data has been processed.

Making sure that the age input is safe is relatively simple using WordPress' built‐in absint() function, which makes sure that the data is an absolute integer. If it cannot be validated as an absolute integer, 0 will be returned.

The code example also only allows fruits to input from a specific group of allowed fruits. If an invalid value is input, the “safe” value is set to a default value. This is called whitelist validation. While not always possible, whitelisting is the method you should always strive to use to validate data because it rules out any nonvalid input. You should rarely, if ever, use blacklist validation, which only disallows specific values.

Validating or Sanitizing Input?

Deciding whether to validate or sanitize input data is sometimes a tough choice. Ultimately, it comes down to a design decision on your part. After building plugins over time, you'll start to get a feel for what the best choice is for types of inputs. Some types are easier than others.

Discussed in the previous section, whitelist validation is the ideal way to handle data input. This method often works best with form inputs that don't allow the user to manually input data and have a limited set of options. Select drop‐downs, radio inputs, and checkboxes are perfect for this type of validation because the allowed input should come only from your predefined options. Whitelist validation is a no‐brainer in these cases.

Form fields that allow direct user input, such as text inputs or textareas, are where sanitization more often comes into play. Earlier in this chapter, you saw one method of handling an age input. The expected input is an integer. Invalid input becomes a 0. You may decide to not allow the form to be submitted unless it's a valid age. For example, 1000 is also a valid integer. You should probably be a little skeptical of someone claiming to be the longest‐living human ever. You may decide to validate that against an age range if it's important to your plugin. Or, you may decide that you'll allow any integer if the person's age isn't super important.

Imagine building a plugin with a user bio textarea. Validation probably isn't ideal in this scenario. There's more room for user error and no predefined options to choose from. Sanitization is your best bet. You'll want to use a function such as wp_kses() to allow a limited set of HTML or use wp_filter_nohtml_kses() to strip all HTML.

There are some specific questions you should consider when deciding between validating and sanitizing.

• Will it be an inconvenience to the user if you reject all invalid data and require they resubmit the form after making corrections (e.g., removing invalid characters from an otherwise valid integer for an age input)?
• Can you make some assumptions about what the data should be if it's invalid and simply sanitize it (e.g., stripping HTML should affect a user's bio text input)?
• What will you do with the data immediately upon submission (e.g., attempt to send an email to an invalid email address)?

Validating and Sanitizing Cookbook

In this section, you'll learn about the many functions that WordPress provides for validating and sanitizing data. PHP also provides methods for filtering input data that you should study at https://www.php.net/filter.

<?php
$value = 100;
 
// Validate the integer.
return intval( $value ) === 100;
 
// Sanitize the integer.
return intval( $value );

<?php
$value = -100;
 
// Returns 100.
return absint( $value );

<?php
$value = '100000000000000000000';
 
// Strip anything that's not a digit.
return preg_replace( '/d/', '', $value );

<?php
$value = '100000000000000000000';
 
// Strip anything that's not a digit.
return ctype_digit( $value );

<?php
$value = "Jane Doe is    a <em>super cool</em> person!
";
 
return sanitize_text_field( $value );
 
// Returns:
// "Jane Doe is a super cool person!"

<?php
$value = "John Doe 
 is my <strong>best</strong> friend.<script>alert( 'hello'
   );</script>";
 
return wp_strip_all_tags( $value );
 
// Returns:
// "John Doe 
 is my best friend."

<?php
$value = "John Doe 
 is my <strong>best</strong> friend.<script>alert( 'hello'
   );</script>";
 
return strip_tags( $value );
 
// Returns:
// "John Doe 
 is my best friend.alert( 'hello' );"

<?php
$value = 'pdev_100';
 
// Validate:
return preg_match( '/^[a-z0-9-_]+$/', '', $value );
 
// Sanitize:
return sanitize_key( $value );

<?php
$email = '[email protected]';
 
// Validate.
return is_email( $email );
 
// Sanitize.
return sanitize_email( $email );

<?php $url = 'http://example.com'; ?>
 
<a href="<?php echo esc_url( $url ); ?>">Example</a>

<?php
$url = 'http://example.com';
 
update_option( 'pdev_url_setting', esc_url_raw( $url ) );

<?php
wp_redirect( 'http://example.com' );
exit;

<?php
wp_safe_redirect( admin_url( 'options-general.php' ) );
exit;

<?php
$value = '<h2>Hello, world!</h2>';
 
echo esc_html( $value );
 
// Returns:
// <h2>Hello, world!</h2>

<?php $class = 'example'; ?>
 
<p class="<?php echo esc_attr( $class ); ?>">
       The quick brown fox...
</p>

<?php
$html = '<p>I have a missing closing tag!';
 
return force:balance:tags( $html );
 
// Returns:
// '<p>I have a missing closing tag!</p>';

<?php
$html = '<p>My superhero name is <strong><em>Super Jane</strong></em></p>';
 
return force:balance:tags( $html );
 
// Returns:
// '<p>My superhero name is <strong><em>Super Jane</em></strong></p>';

<?php
$allowed = [
       'strong' => [],
       'em'     => []
];
 
$html = '<h1>A <strong>Bold</strong> and <em>Italic</em> Header</h1>';
 
return wp_kses( $html, $allowed );
 
// Returns:
// A <strong>Bold</strong> and <em>Italic</em> Header

<?php
$allowed = [
       'strong' => [
             'class' => []
       ],
       'em'     => [
             'class' => []
       ],
       'a'      => [
             'href'  => [],
             'title' => [],
             'class' => []
       ]
];

<?php
$html = '<p>Hello, world! My name is <strong>John Doe</strong>.
        I want to insert <script>alert( "XSS" );</script>';
 
return wp_kses_data( $html );
 
// Returns:
// Hello, world! My name is <strong>John Doe</strong>. I want to insert 
// alert( "XSS" );

<?php $value = 'Hello'; ?>
 
<button onclick="alert( '<?php echo esc_js( $value ); ?>' );">Click Me</button>

<?php $data = [
       [
              'color' => '#000'
       ]
]; ?>
 
<div data-pdev="<?php echo esc_attr( wp_json_encode( $data ) ); ?>">
</div>

<div data-pdev="[{&quot;color&quot;:&quot;#000&quot;}]">
</div>

<?php if ( isset( $_SERVER['HTTP_REFERER'] ) ) : ?>
       Welcome, visitor from <?php echo $_SERVER['HTTP_REFERER']; ?>.
<?php endif; ?>

<?php if ( isset( $_SERVER['HTTP_REFERER'] ) ) : ?>
       Welcome, visitor from <?php echo esc_url( $_SERVER['HTTP_REFERER'] ); ?>.
<?php endif; ?>

<?php
$classes = [
       'media',
       'media-object',
       'media-image'
];
 
$classes = array_map( 'sanitize_html_class', $classes );
?>
 
<figure class="<?php echo esc_attr( join( ' ', $classes ) ); ?>">
       <img src="http://example.com/image.png" alt=""/>
</figure>

<figure class="media media-object media-image">
       <img src="http://example.com/image.png" alt=""/>
</figure>

<?php
$login    = 'hacker';
$password = "123456' OR 1='1";
 
return "SELECT * FROM users WHERE `login` = '$login' AND `pass` = '$password'";
 
// Returns:
// SELECT * FROM users WHERE `login` = 'hacker' AND `pass` = '123456' OR 1='1'

<?php
$login    = esc_sql( 'hacker' );
$password = esc_sql( "123456' OR 1='1" );
 
$sql = "SELECT * FROM users WHERE `login` = '$login' AND `pass` = '$password'";
 
// Returns:
// SELECT * FROM users WHERE `login` = 'hacker' AND `pass` = '123456' OR 1='1'

The $wpdb Object

When interacting directly with the database, WordPress includes a wpdb class. On every page load, WordPress stores a single object instance of this class in the global $wpdb variable.

You should always use the $wpdb variable for database interactions instead of using PHP functions such as mysql_query() for two reasons.

• WordPress provides additional security functionality to protect against SQL injection attacks.
• Users may decide to use a different database engine such as PostGresSQL, so mysql_*() functions may not work.

You can use the $wpdb object to access any of the tables in the database created by WordPress on installation. You can also access tables created by your plugin or tables from third‐party plugins.

Why wpdb Methods Are Superior

The $wpdb object allows you to read, insert, update, or delete data from database tables. The following is an example of using the PHP mysql_*() functions for connecting to a database and updating a post title:

<?php
$title = esc_sql( 'New Post Title' );
$id    = absint( 100 );
 
mysql_connect( DB_HOST, DB_USER, DB_PASSWORD ) 
       OR die( 'Could not connect: ' . msql_error() );
       
mysql_select_db( DB_NAME );
 
mysql_query( "UPDATE wp_posts SET post_title = '$title' WHERE ID = $id" );

There are two primary issues with this code. First, it is a lot of code to write for a simple database query. Writing more code allows for more potential mistakes. Second, the wp_posts table is hard‐coded, so it may not be correct. WordPress allows users to change the default wp_ prefix for table names to something custom. Compare the preceding code with the WordPress method of handling the same query, shown here:

<?php
$title = esc_sql( 'New Post Title' );
$id    = absint( 100 );
 
$wpdb->query( "UPDATE $wpdb->posts SET post_title = '$title' WHERE ID = $id" );

This is much shorter in length and easier to read. You can also see that $wpdb‐>posts points to the correct table for posts. If the user chose to use pdev_ as their table prefix, this would become pdev_posts.

You can even take this one step further and directly update an entire row in a table via the $wpdb‐>update() method. The following example performs the same action of updating a post's title for a given post ID:

<?php
$data  = [ 'post_title' => $title ];
$where = [ 'ID' => $id ];
 
$wpdb->update( $wpdb->posts, $data, $where );

You can also update multiple columns at once with this method by adding the keys and values to the $data array. This will save you from writing out longer queries.

All‐in‐One Methods

WordPress provides methods for interacting with an entire table row that are easier to use than memorizing SQL syntax and also handle sanitizing the data for you. In the previous section, you learned about the update() method, but WordPress also has an insert() method.

<?php
$data  = [ 
       'post_title'  => 'New Post Title',
       'post_author' => 42
];
 
$where = [ 
       'ID' => $id 
];
 
$format = [
       '%s', // Maps to post_title
       '%d'  // Maps to post_author
];
 
$where_format = [
       '%d' // Maps to ID
];
 
return $wpdb->update( $wpdb->posts, $data, $where, $format, $where_format );
 
// Returns number of updated columns on success and false on failure.

<?php
$data = [
       'column_1' => 'A text string',
       'column_2' => 100
];
 
$format = [
       '%s',
       '%d'
];
 
return $wpdb->insert( $wpdb->custom, $data, $format );
 
// Returns number of updated columns on success and false on failure.

Common Methods

Sometimes, database queries will be more complex than a basic UPDATE or INSERT. You'll need to write some SQL syntax and use one of the core methods for interacting with the database.

<?php
$query = "SELECT COUNT(ID) FROM {$wpdb->posts} WHERE post_status = 'publish'";
 
return $wpdb->get_var( $query );
 
// Returns the number of published posts.

<?php
$wpdb->get_row( string|null $query = null, string $output = OBJECT, int $y = 0 );

<?php
$query = "SELECT * FROM {$wpdb->users} WHERE user_login = 'admin'";
 
return $wpdb->get_row( $query );

object(stdClass) (10) {
       ["ID"] => string(1) "1"
       ["user_login"] => string(5) "admin"
       ["user_pass"] => string(34) "xxxxxxx"
       ["user_nicename"] => string(5) "admin"
       ["user_email"] => string(23) "[email protected]"
       ["user_url"] => string(24) "http://example.com"
       ["user_registered"] => string(19) "2019-09-24 20:22:42"
       ["user_activation_key"] => string(0) ""
       ["user_status"] => string(1) "0"
       ["display_name"] => string(14) "John Doe"
}

<?php
$wpdb->get_col( string|null $query = null, int $x = 0 );

<?php
$query = "SELECT user_email FROM {$wpdb->users}";
 
return $wpdb->get_col( $query );

[
       0 => '[email protected]',
       1 => '[email protected]',
       2 => '[email protected]'
]

<?php
$query = "SELECT user_email FROM {$wpdb->users}";
 
$emails = $wpdb->get_col( $query );
 
foreach ( $emails as $email ) {
       wp_mail(
             $email,
             'Site Offline',
             'The site will be offline next Monday.'
       );
}

<?php
$query = "SELECT YEAR(post_date) AS `year`, count(ID) as posts
          FROM $wpdb->posts
          WHERE post_type = 'post' AND post_status = 'publish'
          GROUP BY YEAR(post_date)
          ORDER BY post_date DESC";
 
return $wpdb->get_results( $query, ARRAY_A );

[
       [0] => [
             "year"  => "2019",
             "posts" => "32"
       ],
       [1] => [
             "year"  => "2018",
             "posts" => "1"
       ],
       [2] => [
             "year"  => "2017",
             "posts" => "3"
       ]
]

<?php
$query = "DELETE from {$wpdb->users} 
          WHERE user_url
          LIKE '%spam.example.com%'";
 
return $wpdb->query( $query );

<?php
$user_id = 1;
 
$unsafe_query = "SELECT post_title
          FROM {$wpdb->posts}
          WHERE post_status = 'publish'
          AND post_author = %d";
 
$safe_query = $wpdb->prepare( $unsafe_query, $user_id );
 
return $wpdb->get_results( $safe_query );

Saving Cached Data

WordPress provides three primary functions for storing cached data.

<?php
wp_cache_add( int|string $key, mixed $data, string $group = '', int $expire = 0 );
 
wp_cache_replace( int|string $key, mixed $data, string $group = '', int $expire = 0 );
 
wp_cache_set( int|string $key, mixed $data, string $group = '', int $expire = 0 );

As you can see, each function looks similar. wp_cache_add() saves cached data. wp_cache_replace() replaces existing cached data. And wp_cache_set() is a combination of the previous two functions. In most situations, you'll use it as an all‐in‐one method simply because it handles both adding and replacing.

Each function accepts four parameters:

• $key (required): A unique ID to cache the data by. This key doesn't have to be unique across multiple data groups but must be unique within a group.
• $data (required): The data that you want to store and access later.
• $group (optional): A group ID to store multiple pieces of cached data.
• $expire (optional): How long the data should be stored in number of seconds. By default, this is set to 0, which tells caching systems to store the data indefinitely.

Imagine you wanted to build a plugin that gathered five posts related to the current blog post by category. The first thing you'd need to do is perform a query that retrieved the posts. You could store the result of this query using the wp_cache_set() helper.

<?php
$post_id    = get_the_ID();
$categories = get_the_category();
 
$posts = get_posts( [
       'category' => absint( $categories[0]->term_id ),
       'post__not_in' => [ $post_id ],
       'numberposts'  => 5
] );
 
if ( $posts ) {
       wp_cache_set( $post_id, $posts, 'pdev_related_posts', DAY_IN_SECONDS );
}

Loading and Using Cached Data

When you need to load cache data, WordPress provides the wp_cache_get() function. You can retrieve data by key (first parameter) and group (second parameter). If no data is found, the function will return false.

Using the related posts example from the previous section, check whether there are posts cached. If so, you can output them as a list.

<?php
$post_id = get_the_ID();
 
$posts = wp_cache_get( $post_id, 'pdev_related_posts' );
 
if ( $posts ) {
       echo '<ul>';
 
       foreach ( $posts as $post ) {
             printf(
                    '<li><a href="%s">%s</a></li>',
                    esc_url( get_permalink( $post->ID ) ),
                    esc_html( get_the_title( $post->ID ) )
             );
       }
 
       echo '</ul>';
}

Deleting Cached Data

When you need to delete cached data, use the WordPress wp_cache_delete() function. Like wp_cache_get(), it accepts a $key and a $group as the first and second parameters. The function will return true on success and false on failure.

Building from the related posts example, use the following code to delete the current post's cached related posts data:

<?php
$post_id = get_the_ID();
 
return wp_cache_delete( $post_id, 'pdev_related_posts' );

Caching Data within a Plugin

In this section, you'll build a simple related posts plugin using the functions described in the previous sections. The plugin will append a related posts list to the end of the post content on single post views. It will do so using a filter on a hook named the_content. You'll learn more about hooks in Chapter 5.

There's a few things the plugin must do.

• Check whether the user is viewing the singular post.
• Attempt to get the cached related posts.
• If no cached data is found, query new posts and cache them.
• Append the related posts HTML to the post content.

<?php
/**
 * Plugin Name: Related Posts
 * Plugin URI:  http://example.com/
 * Description: Displays a list of related posts on singular views.
 * Author:      WROX
 * Author URI:  http://wrox.com
 */
 
add_filter( 'the_content', 'pdev_related_posts' );
 
function pdev_related_posts( $content ) {
 
       // Bail if not viewing a single post.
       if ( ! is_singular( 'post' ) || ! in_the_loop() ) {
             return $content;
       }
 
       // Get the current post ID.
       $post_id = get_the_ID();
 
       // Check for cached posts.
       $posts = wp_cache_get( $post_id, 'pdev_related_posts' );
 
       // If no cached posts, query them.
       if ( ! $cache ) {
             $categories = get_the_category();
 
             $posts = get_posts( [
                    'category' => absint( $categories[0]->term_id ),
                    'post__not_in' => [ $post_id ],
                    'numberposts'  => 5
             ] );
 
             // Save the cached posts.
             if ( $posts ) {
                    wp_cache_set(
                           $post_id,
                           $posts,
                           'pdev_related_posts',
                           DAY_IN_SECONDS
                    );
             }
       }
 
       // If posts were found at this point.
       if ( $posts ) {
 
             $content .= '<h3>Related Posts</h3>';
 
             $content .= '<ul>';
 
             foreach ( $posts as $post ) {
                    $content .= sprintf(
                           '<li><a href="%s">%s</a></li>',
                           esc_url( get_permalink( $post->ID ) ),
                           esc_html( get_the_title( $post->ID ) )
                    );
             }
 
             $content .= '</ul>';
       }
 
       return $content;
}

The plugin will output a Related Posts list that looks similar to Figure 4‐4.

Saving an Expiring Option

Imagine that you're building a plugin that pulled in a video tutorial on how to use WordPress from a third‐party site. The latest video is titled How to Install WordPress. You want to store the latest video for one day.

<?php
set_transient( 'pdev_video_tutorial', 'How to Install WordPress', DAY_IN_SECONDS );

The first parameter is the unique ID for your transient. It should be prefixed like any other global identifier, as discussed in Chapter 2. The second parameter is the latest video title. In reality, this can be any arbitrary data. The final parameter is the number of seconds to store the data. DAY_IN_SECONDS is a constant defined by WordPress for easily getting a day in seconds.

Retrieving an Expiring Option

When retrieving an option stored as a transient, you will use the get_transient() function provided by WordPress. Use this to grab the latest tutorial video title.

<?php
$video = get_transient( 'pdev_video_tutorial' );

The $video variable will return one of two things.

• If the transient is stored in the database, it will return the value of the option.
• If retrieval fails or no value is stored, it will return false.

Deleting an Expiring Option

Like with setting and getting transients, WordPress packages a delete_transient() function for deleting a transient from the database. You may need to use this to invalidate a transient, such as when uninstalling the plugin. To remove the tutorial video transient, use the following code:

<?php
delete_transient( 'pdev_video_tutorial' );

Generally, you should rarely need to delete a transient. WordPress will automatically delete expiring transients from the database for you.

A Practical Example Using Transients

Now you can put together some basic plugin functions for setting and retrieving a tutorial video.

<?php
// Fetches video from third-party website.
function pdev_fetch_video_title() {
       // Connect to an API to fetch video.
       return $title;
}
 
// Returns the video title.
function pdev_get_video_title() {
 
       // Get transient.
       $title = get_transient( 'pdev_video_tutorial' );
 
       // If the transient doesn't exist or is expired, refresh it.
       if ( ! $title ) {
             $title = pdev_fetch_video_title();
 
             set_transient( 'pdev_video_tutorial', $title, DAY_IN_SECONDS );
       }
 
       return $title;
}

You'd need to actually interact with a remote API and make sure the data you retrieve is secure to create a working set of code. You'll learn more about getting remote data via WordPress' HTTP API in Chapter 12, “REST API.”

Technical Details

Because transients are volatile in nature, they benefit from caching plugins. There are various types of caching plugins that save data in different ways. Some cache systems store data in fast memory or in files on the server. While transients are stored in the database by default, you can never assume that's where they'll be when retrieving them. Always use the Transient API functions to ensure that you get the correct data.

Transient Ideas

Whenever you need to store data with a short lifetime, you should almost always use transients. The following list covers some examples of when you may want to use the Transient API:

• Displaying the latest dollar values for certain types of cryptocurrency such as Bitcoin or Ethereum on a cryptocurrency site
• Displaying the latest tweets from a Twitter account
• Showcasing the users who like a site's Facebook page
• Fetching an article from an RSS feed
• Pulling in a music playlist from a remote website