WordPress features many different APIs for use in your plugin. Each API, or application programming interface, helps interact with WordPress in a different way. Following is a list of the main available APIs in WordPress and their function:

WordPress also features pluggable functions. These functions enable you to override specific core functions in a plugin. For example, the wp_mail() function is a pluggable function. You can easily define this function in your plugin and send email using SMTP rather than the default method. All pluggable functions are defined in the /wp-includes/pluggable.php Core WordPress file.

You can use some predefined functions during specific plugin tasks, such as when a plugin is activated or deactivated and even when a plugin is uninstalled. chapter 2, "Plugin Foundation," covers these functions in detail.

Plugins are loaded early in the process when a WordPress powered web page is called. Figure 1-1 shows a diagram of the standard loading process when loading a page in WordPress:

Figure 1.1. FIGURE 1-1

Figure 1-1 illustrates the standard process when loading a page in WordPress. The flow changes slightly when loading an admin page. The differences are minor and primarily concern what theme is loaded: admin theme versus your web site theme.

The first place to start when researching available WordPress plugins is the official Plugin Directory at WordPress.org. The Plugin Directory is located at http://wordpress.org/extend/plugins/. With more than 10,000 plugins available and well over 100 million plugin downloads, it's easy to see the vital role plugins play in every WordPress web site. All plugins available in the Plugin Directory are 100% GPL and free to use for personal or commercial use.

Take a look at the five most downloaded WordPress plugins available to get a sense of their diversity:

As you can see, the preceding plugins can handle any task. The features added by these plugins are universal and features that most web sites on the Internet should have.

Now you will look at some popular tags for plugins. Plugin tags are just like blog post tags, simple keywords that describe a plugin in the Plugin Directory. This makes it easy to search for existing plugins by tag. Following are popular examples:

Viewing popular plugin tags is a great way to get inspiration when developing new plugins for WordPress.

One of the main advantages to plugins is the ability to modify the behavior of WordPress without modifying any core files. Core files refer to any file that is a part of the default WordPress installation.

Hacking core files can make it difficult to update WordPress when a new version is released. If you made any modifications to a core file, that modification would be overwritten when the update occurs. Keeping WordPress up to date with the latest version is essential in keeping your web site secure.

Modifying core files can also lead to an unstable web site. Different areas of WordPress rely on other areas to function as expected. If you modify a core file and it no longer works as expected, it can cause instability and quite possibly break a completely unrelated feature in WordPress.

Another advantage to building plugins is the structure that already exists for your plugin. Many of the common features have already been developed and are ready for use in your plugin. For example, you can take advantage of the built-in user roles in WordPress. Using the user roles you can easily restrict your code to execute only if a user is an administrator. Look at an example:

<?php
if ( current_user_can( 'manage_options' ) ) {
  //any code entered here will only be executed IF
  //user is an administrator
}
?>

As you can see it's easy to verify a user has proper permissions prior to executing any code in your plugin. You learn about user accounts and roles in chapter 8, "Users."

As another example, look at sending an email in WordPress. Sure you could create a new function in your plugin to send email, but why? WordPress has a handy function called wp_mail() for sending email. Look at an example:

<?php
$email_to = 'you@example.com';
$email_subject = 'Plugin email example';
$email_message = 'How do you like my new plugin?';

wp_mail( $email_to, $email_subject, $email_message );
?>

As you can see sending an email in WordPress couldn't be easier. Unless your plugin needs some customized emailing functionality, you don't need to re-create this function from scratch. Using this function also ensures the widest adoption for sending emails from WordPress because you use the built-in function.

Using the available built-in features of WordPress can greatly reduce the time to develop a plugin. Another advantage to not reinventing the wheel is that this approach more often than not will allow for your plugins to work across a greater number of servers and setups, thereby maximizing compatibility. Don't reinvent the wheel with features that already exist in WordPress.

A plugin can take control of the rendering process; therefore, the plugin can become a "theme." Similarly a theme can have plugin functionality included. Because of this the difference between the two can sometimes become blurred, so why not just include your plugin code directly in a theme? This is a common question and one that can have a few different answers.

Should themes include plugin functionality? The short answer is no. The primary reason for this is because plugins are meant to add features and functionality to WordPress, regardless of the theme used. This creates a nice separation between your web site design and the functionality of your web site. The reason this separation is needed is so your theme is not directly tied to the functionality required. WordPress is built so that you can easily change your design, or theme, at any point with just a couple clicks. If all plugin functionality existed in your theme, and you switched themes, you will have lost all that functionality you required.

There is also a strong argument that certain features should be included in a theme. A common feature most themes include is breadcrumb navigation. This feature could certainly exist in a plugin, but being a navigation-centric feature it makes sense to include this in the theme. Search engine optimization features are also a common feature found in themes today.

WordPress makes it easy to update a plugin to the latest version. Every plugin installed from the WordPress.org Plugin Directory alerts you when a new version of the plugin has been released. Updating the plugin is as simple as clicking the update notification listed just below the plugin details on the Plugin screen.

Plugins not installed from the Plugin Directory can also be updated using the auto-update functionality of WordPress. The plugin author must define where WordPress can download the latest version, and it will take care of the rest. If the plugin author doesn't define this location, you must manually update the plugin.

Keeping plugins updated is an important part in keeping your web site free from security vulnerabilities and bugs.

Plugins are easy to share with others. It's much easier to share a plugin than tell someone to modify specific lines of code in your theme or WordPress. Using plugins also makes it easy to use the same functionality across multiple sites. If you find a group of plugins that you like, you can easily install them on every WordPress web site you create.

When you activate a broken plugin in WordPress, it won't break your site. If the plugin triggers a fatal error, WordPress automatically deactivates the plugin before it has a chance to. This fail-safe feature makes it less risky when activating and testing out new plugins. Even if the plugin does cause a white screen of death (error message), you can easily rename the plugin folder, and WordPress deactivates the plugin. This makes it impossible for a rogue plugin to lock you out of your own site because of an error.

On the other hand, if you were to hack the WordPress core, you can most certainly cause fatal errors that will crash your web site. This can also include making unrecoverable damage to WordPress.

A huge community is centered around plugin development, sharing knowledge and code, and creating wonderful plugins. Getting involved in the community is a great way to take your plugin development skills to the next level. chapter 18, "The Developer Toolbox," covers many of these resources.

WordPress features three different methods for installing a new plugin. Your server setup dictates which method is the best to use.

The first method uses the built-in auto installer. This method enables you to search the Plugin Directory on WordPress.org directly from the admin dashboard of your WordPress web site. After you find a plugin to install, simply click the Install link, and the plugin automatically downloads and installs.

The second method uses the zip uploader. Zipped plugin files can be uploaded, extracted, and installed by WordPress. To use this method click the Upload link at the top of the Install Plugins page. Click the Browser button and select the plugin zip file you want to install. After you select the plugin, click the Install Now button, as shown in Figure 1-3.

Figure 1.3. FIGURE 1-3

The third and final method to install a plugin in WordPress uses File Transfer Protocol (FTP). Using FTP is simply connecting to your web server using an FTP client and manually uploading the plugin to your WordPress installation. To use this method upload the uncompressed plugin folder or file to the wp-content/plugins directory on your web server.

After you install a plugin in WordPress, you can manage it, along with all other plugins, under the Plugins

The Plugin screen also features bulk actions for activating, deactivating, updating, and deleting plugins. Check all the plugins you want to manage and then select the appropriate bulk action from the drop-down menu. This process makes managing multiple plugins a breeze!

WordPress features a built-in plugin editor under the Plugins Í Editor screen. The plugin editor enables you to view and edit the source code of any plugin installed in WordPress. Keep in mind you can only edit the source code if the plugin file is writeable by the web server, otherwise you can only view the code.

To use the editor, select the plugin from the drop-down menu on the top-left portion of the Edit Plugins page. The editor lists all files associated with the selected plugin. There is also a documentation lookup feature making it easy to research a specific function's purpose in the plugin you are reviewing.

A lesser known fact is WordPress actually features two plugin directories. The primary plugin directory is located under wp-content/plugins in a standard WordPress installation. The second, lesser known, plugin directory is located under wp-content/mu-plugins. The mu-plugins directory, which stands for Must-Use, is not auto-created by WordPress, so it must be manually created to be used.

The primary difference between the two is the mu-plugins directory is for plugins that are always executed. This means any plugin included in this directory will automatically be loaded in WordPress and across all sites in the network if you run Multi-site.

WordPress features a few different types and statuses for plugins, as shown in Figure 1-4. You need to understand the difference when administering and creating plugins for WordPress.

Figure 1.4. FIGURE 1-4

The last four drop-in plugins are specific to the WordPress Multisite feature. A standard WordPress installation will have no use for these plugins.

When developing a new plugin, determine what type of plugin you want to create before you start the development process. Most plugins will be standard WordPress plugins, but occasionally you might need to create a Must-Use or Drop-in specific plugin.

On occasion you may want to test some plugin functionality without actually creating a plugin to do so. Many developers will place code directly in the wp-config.php file to do so. This is a bad technique and should not be used because when the config file is parsed and loaded, WordPress is not wholly instantiated yet.

Instead of hacking wp-config.php, make a test.php file with the following code snippet and place it in your WordPress root directory:

<?php
// Load the WordPress Environment
// define( 'WP_DEBUG', true ); /* uncomment for debug mode */
require('./wp-load.php');
// require_once ('./wp-admin/admin.php'); /* uncomment for is_admin() */
?>
<pre>
<?php

/* test stuff here */
var_dump( is_admin() );

?>
</pre>

Code snippet test.php

This is a quick way to load all of the required WordPress functions to test plugin functionality without actually creating a plugin. As you can see wp-load.php is included at the beginning of the file. You can also include wp-admin/admin.php if you want to test admin side functionality. Once you have included the required WordPress core files, you want test any code that would otherwise exist reside in your plugin. Don't forget to remove your test.php file when you are done testing.

When choosing a name for your plugin, it's good practice to consider a name based on what your plugin actually does. For example, if you create an SEO-focused plugin, you wouldn't want to name it Bob's Plugin. Your audience would have no idea what your plugin actually does based on the plugin name. Your plugin name should be unique to your plugin and should also be descriptive of your plugin's purpose.

It's also a good idea to search the Plugin Directory on WordPress.org (http://wordpress.org/extend/plugins/) for similar plugins to avoid confusion. If you decide to name your plugin SEO Gold, and a plugin named SEO Silver already exists, there might be some confusion on whether your plugin is new or just a newer version of an old plugin. You don't want the first impression of your plugin to be met with confusion. Chapter 17, "Marketing Your Plugins," covers this in more detail.

It's highly recommended to store all your plugin files inside a folder within the plugins directory in WordPress. All plugins downloaded from the WordPress.org Plugin Directory are automatically structured in subfolders. This enables your plugin to easily contain multiple files and any other items you want to include, such as images. You can also include subfolders to help organize your plugin files better. The folder name should be the same as the main plugin filename. You shouldn't include any spaces or underscores in the folder name; instead use hyphens if needed. Subfolders and the hierarchical directory structure of the files are discussed further in the "Sanity Practices" section of this chapter.

When building a custom plugin, it's essential that you prefix everything with a unique prefix. This means all plugins files, function names, variable names, and everything included with your plugin. Why? Simple, one of the most common errors in plugins is using all too common names for function and variables. For example, if you have a function named update_options() and the user installs another plugin with the same function name, the website will break because you can't have two functions with the same name in PHP.

A good rule of thumb is to prefix everything with your plugin initials and your own initials. For instance if your name is Michael Myers and your plugin is named Halloween Revenge, you would prefix the function as mm_hr_update_options(). There is a strong chance no other plugin in the world exists with the same function name; therefore there is little risk of having conflicts with other plugins.

This is also a good rule for variable names. Don't use general names when creating variables. For instance, say your plugin creates and uses a variable called $post. That could cause unexpected results because $post is a global variable in WordPress containing the post data. If your plugin overwrites the data in $post and something else in WordPress expects the post data to still exist, you might have a serious problem. Instead you can use the same prefix method previously described and name your variable $mm_hr_post. This is a unique variable name most likely not used in any other plugin.

This book prefixes everything with boj_ (a mashup of the Authors' initials) and myplugin_ (assuming the fictitious plugin is named My Plugin) like so: boj_myplugin_function_name().

Keeping your plugin files organized is a key step in producing a professional plugin. Generally speaking, you should have only two files in your plugin folder: the primary plugin PHP file and your uninstall.php file. For organizational reasons, store all other plugin files in a subdirectory.

It is also recommended you split your plugin into several smaller files. One primary reason for doing so is for performance reasons. For instance, you should group all admin interface functions in a separate file. This allows you to conditionally include the admin code only when the user is viewing the admin side of WordPress:

<?php
if ( is_admin() ) {
    // we're in wp-admin
    require_once( dirname(__FILE__).'/includes/admin.php' );
}
?>

The preceding example uses the is_admin() conditional statement to verify the user is in the admin dashboard of WordPress. If so your plugin should include and process the /includes/admin.php file for your plugin.

Another important step to a professional plugin is maintaining a clean folder structure, which pertains to keeping all similar files together. For example, if your plugin requires JavaScript files, create a /js folder and store all the JavaScript files in this directory. If you have custom style sheet files, create a /css folder to store all your CSS files. Keep all images stored in a /images folder.

Now look at a standard folder structure for a plugin:

As you can see, keeping your files organized using a clean folder structure can make it much easier to track the flow of your plugin over time. It can also make it much easier for other plugin developers to follow your logic when they view your plugin's source code.

Following is an example of a plugin header:

<?php
/*
Plugin Name: My Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A brief description of my plugin
Version: 1.0
Author: Brad Williams
Author URI: http://example.com
License: GPLv2
*/
?>

Code snippet header-example.php

As you can see, the plugin header is straightforward. The only required line for WordPress to recognize your plugin is the plugin name, but it's good practice to fill in the entire header as shown.

The Plugin URI is a direct link to your plugin detail web page. The description is a short description of your plugin, which displays on the Plugin screen in WordPress. The version number is the current version of the plugin. WordPress uses the version number set here to check for new plugin updates at WordPress.org. The next two lines are the Author and Author URI. The Author is listed on the Plugin screen with a link to the Author URI set here. The final line is the software license the plugin is released under.

Figure 2-1 shows how your plugin header is rendered in WordPress.

Figure 2.1. FIGURE 2-1

The plugin Author's name, Brad Williams in this case, will link directly to the Author URI. The "Visit plugin site" text will link to the Plugin URI as defined in your plugin header. As you can see, both of these links can help users of your plugin find additional information about you and your plugin.

Below the plugin header comment block, it's a good idea to include the license for your plugin. This is not a requirement for your plugin to function, but anytime you release code to the public, it's a good idea to include a license with that code. This gives your users clear answers in how your plugin is licensed and how they can use your code. Chapter 17, "Marketing Your Plugins," covers this topic.

WordPress is licensed under the GNU General Public License (GPL) software license and as such any plugin distributed for WordPress should be compatible with the GPL. Following is an example of a standard GPL license comment block:

<?php
/*  Copyright YEAR  PLUGIN_AUTHOR_NAME  (email : PLUGIN AUTHOR EMAIL)

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/
?>

Code snippet license-example.php

Simply fill out the year, plugin author name, and email in the preceding license code. Now place the license code just below your plugin header. By including this software license, your plugin will be licensed under the GPL.

A common task in any plugin is referencing files and folders in your WordPress installation. You can reference files in your code in two ways: using the local server path or by using a standard URL. Think of the local server path as nothing more than the directory path on a computer. The local server path is generally used whenever you need to include something that is local on your server. A URL is typically used to link to something external to your server, but that doesn't mean you can't link to images and such using the URL path.

WordPress features the ability to move the wp-content directory to a different location. Because of this you shouldn't hardcode directory paths in WordPress, but rather use the available functions to determine the correct path.

Here's one common question in plugin development: What is the proper way to determine the local path to your plugin files? To determine the local path to your plugin, you need to use the plugin_dir_path() function. The plugin_dir_path() function extracts the physical location relative to the plugins directory from its filename.

<?php plugin_dir_path( $file ); ?>

Parameters:

Now look at an example on how to determine the local path to your plugin folder:

<?php
echo plugin_dir_path( __FILE__ );
?>

You can see you pass the __FILE__ PHP constant to the plugin_dir_path() function. This produces the full local server path to your plugin directory:

/public_html/wp-content/plugins/my-custom-plugin/

What if you need to get the local path to a file in a subdirectory inside your plugin directory? You can also use the plugin_dir_path() function along with the subdirectory and files you want to reference:

<?php
echo plugin_dir_path( __FILE__ ) .'js/scripts.js';
?>

This code would produce the following results:

/public_html/wp-content/plugins/my-custom-plugin/js/scripts.js

As you can see, this function will be instrumental in developing a solid WordPress plugin. Using the proper methods to access your plugin files and directories can ensure maximum compatibility with all WordPress installations, regardless of how custom it is.

Functions are also available to help determine URLs in WordPress. Following is a list of those functions:

The site_url() and home_url() functions are similar and can lead to confusion in how they work. The site_url() function retrieves the value as set in the wp_options table value for siteurl in your database. This is the URL to the WordPress core files. If your core files exist in a subdirectory /wordpress on your web server, the value would be http://example.com/wordpress.

The home_url() function retrieves the value for home in the wp_options table. This is the address you want people to visit to view your WordPress web site. If your WordPress core files exist in /wordpress, but you want your web site URL to be http://example.com the home value should be http://example.com.

The plugins_url() function will be one of your best friends when building plugins in WordPress. This function can help you easily determine the full URL to any file within your plugin directory.

<?php plugins_url( $path, $plugin ); ?>

Parameters:

For example, say you want to reference an image file to use as an icon in your plugin. You could easily accomplish this using the following example:

<?php
echo '<img src="' .plugins_url( 'images/icon.png', __FILE__ ). '">';
?>

The first parameter value you pass to the function is the relative path to the image file you want to include. The second parameter is the plugin file that you want to be relative, which in this case you can simply send in the PHP constant __FILE__. The preceding code would generate the HTML img tag as follows:

<img src="http://example.com/wp-content/plugins/my-custom-plugin/images/icon.png">

Following are some of the advantages to using the plugins_url() function to determine plugin URLs:

The plugin activation function is triggered when, you guessed it, a plugin is activated in WordPress. This function is called register_activation_hook(). Using this function is a great way to set some default options for your plugin. It can also verify that the version of WordPress is compatible with your plugin. The function accepts two parameters as shown here:

<?php register_activation_hook( $file, $function ); ?>

Parameters:

Now look at an example of this function in action:

<?php
register_activation_hook( __FILE__, 'boj_myplugin_install' );

function boj_myplugin_install() {
    //do cool activation stuff
}
?>

The first parameter you send the function is the path to your file, using the __FILE__ constant. This is a PHP constant that always contains the absolute path to the file it is called from. The second parameter is the unique function you want to call when your plugin is activated.

Now that you understand how the register_activation_hook() function works, look at a real-world example. Following is an example of how you can easily verify the version of WordPress is compatible with your plugin.

<?php
register_activation_hook( __FILE__, 'boj_install' );

function boj_install() {
    If ( version_compare( get_bloginfo( 'version' ), '3.1', '<' ) ) {
        deactivate_plugins( basename( __FILE__ ) ); // Deactivate our plugin
    }
}
?>

Code snippet version-requirement.php

Your install function boj_install() uses the get_bloginfo() function to retrieve the current version of WordPress the user runs. Next you use the PHP function version_compare() to verify the installed version of WordPress is at least 3.1. If the WordPress version is older than 3.1, deactivate your plugin using the deactivate_plugins() function.

Another common plugin activation technique is to set some default settings when your plugin is activated. Imagine your plugin has an entire page worth of options available. Chances are some of those options need to be defined for your plugin to work properly. Rather than forcing the user to visit your settings page and set those options, you can automatically set default options when the plugin is activated.

<?php
register_activation_hook( __FILE__, 'boj_install' );

function boj_install() {
    $boj_myplugin_options = array(
        'view' => 'grid',
        'food' => 'bacon',
        'mode' => 'zombie'
    );
    update_option( 'boj_myplugin_options', $boj_myplugin_options );
}
?>

The preceding code example creates an array of default options and stores them in WordPress when your plugin is activated. Chapter 7, "Plugin Settings," covers creating and saving options in WordPress in more detail.

Just as there is an activation function, there is also a deactivation function. This is called the register_deactivation_hook() function. This function is triggered when your plugin is deactivated in the WordPress Plugins screen. This function accepts the same two parameters as the previous activation function.

<?php register_ deactivation_hook( $file, $function ); ?>

Parameters:

Now look at an example of the deactivation function in action:

<?php
register_deactivation_hook( __FILE__, 'boj_myplugin_uninstall' );

function boj_myplugin_uninstall() {
    //do something
}
?>

The preceding example would execute your boj_myplugin_uninstall() function when your plugin is deactivated in WordPress.

When dealing with the deactivation function, you shouldn't include uninstall functionality when a plugin is deactivated. Imagine if you accidentally deactivate a plugin and upon reactivation you realize all your settings for that plugin have been deleted. Also, remember the WordPress automatic update feature deactivates all plugins prior to installing the new version of WordPress.

Think of your plugin as a piece of software installed on your computer. You expect that piece of software to have an easy way to uninstall it from your computer. You also expect the uninstaller to remove any trace of that software from your computer. A plugin in WordPress is no different; it's essentially a piece of software installed in WordPress. If users want to uninstall your plugin, you should provide the necessary uninstall functionality to remove all traces of the plugin from their WordPress site.

A good rule of thumb is to be considerate of your plugin user's data. For example if your plugin creates events as a custom post type, chances are the user does not want all of their events deleted if they uninstall your plugin. In that case you might want to ask the user if they want to delete all plugin data or not.

WordPress provides two different methods for uninstalling a plugin: the uninstall.php file and the uninstall hook.

The first method is the uninstall.php file. This is typically the preferred method because it keeps all your uninstall code in a separate file. To use this method, create an uninstall.php file and place it in the root directory of your plugin. If this file exists WordPress executes its contents when the plugin is deleted from the WordPress Plugins screen page. Now look at an example using the uninstall.php file:

<?php
// If uninstall not called from WordPress exit
if( !defined( 'WP_UNINSTALL_PLUGIN' ) )
    exit ();

// Delete option from options table
delete_option( 'boj_myplugin_options' );

//remove any additional options and custom tables
?>

The first thing you want to do is verify that WordPress is actually calling the uninstall.php file. Do this by verifying the WP_UNINSTALL_PLUGIN constant is defined. If it is not, immediately exit the script. This is a security measure to ensure this file is not executed except during the uninstall process of your plugin.

After you have verified this is a valid uninstall call, you can delete your plugin options from the database. The goal of a plugin uninstall script is to remove any trace of the plugin from the WordPress database. This includes deleting all options and dropping any custom tables that may have been created. You don't need to worry about deleting the actual plugin files or directories in this function. WordPress will do that for you once your uninstall script runs.

The second uninstall method available is the uninstall hook. If you delete a plugin in WordPress and uninstall.php does not exist, WordPress executes the uninstall hook (if it exists).

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

Parameters:

Now look at an example of the uninstall function in action:

<?php
register_activation_hook( __FILE__, 'boj_myplugin_activate' );

function boj_myplugin_activate() {

    //register the uninstall function
    register_uninstall_hook( __FILE__, 'boj_myplugin_uninstaller' );

}

function boj_myplugin_uninstaller() {

    //delete any options, tables, etc the plugin created
    delete_option( 'boj_myplugin_options' );

}
?>

As you can see, the register_uninstall_hook() should be called on activation and not on every plugin load. To do this you'll include the uninstall hook when the plugin is activated using the register_activation_hook(). Next call the uninstall function. Again pass the __FILE__ constant as the first parameter. The second parameter is your uninstall function that you want to execute.

Inside your boj_myplugin_uninstaller() function is where all uninstall procedures take place. Remember if the uninstall.php file exists in your plugins root folder, the uninstall hook won't actually execute.

As suggested in this section, there are many pitfalls to using the uninstall hook. It's a much cleaner, and easier, process to use the uninstall.php method described earlier for removing plugin settings and options when a plugin is deleted in WordPress.

One of the most obvious, yet commonly skipped steps, is code commenting. Commenting your plugin's source code is a quick and easy way to document exactly how your plugin works. There are many benefits to commenting your code. The major benefit to code commenting is to explain what your code actually does, in plain English.

Imagine writing an extremely complex plugin without a single comment. If you don't review the code for months and then return to it, you might have a hard time understanding what your code actually does. Now imagine other developers are reviewing your code; without comments it could take them a much longer time to follow your code logic and understand how your plugin functions. Comments are beneficial to everyone involved, so for everyone's sanity, always comment your code!

Nearly all functions in WordPress core contain inline documentation in PHPDoc form. PHPDoc is a standardized method of describing a function's usage in PHP comment form. Following is a basic example of a PHPDoc formatted function comment:

<?php
/**
 * Short description
 *
 * Longer more detailed description
 *
 * @param   type    $varname1   Description
 * @param   type    $varname2   Description
 * @return  type    Description
*/
function boj_super_function( $varname1, $varname2 ) {
    //do function stuff
}
?>

As you can see, the preceding PHPDoc comment helps to describe the function directly below the comment block. If I'm a developer looking over your plugin's code, I can quickly determine exactly how your function works, what parameters it accepts, and what I can expect returned without even reading your function's code. These comments are also used by more visual tools such as PHPDocumentor and PHPXref.

Variable and function names should always be written in lowercase. Words should also be separated using underscores. Following is an example showing the proper way to name a function and variable:

<?php
function boj_myplugin_function_name ( $boj_myplugin_variable ) {
    //do something
}
?>

Files should also be named using only lowercase letters; however, filenames should use hyphens to separate words and not underscores. For example you might name your plugin: boj-plugin-name.php.

PHP enables you to define strings using single or double quotes. In WordPress it's recommended to use single quotes whenever possible. One of the benefits of using single quotes is you rarely need to escape HTML quotes in a string. Following is an example showing how to echo a link using the single quote method:

<?php
echo '<a href="http://example.com/">Visit Example.com</a>';
?>

You can also use the double quote method when concatenating a string in PHP. For example, look at a simple way to insert a variable for your website URL:

<?php
$boj_myplugin_website = 'http://example.com/';
echo "<a href='$boj_myplugin_website'>Visit Example.com</a>";?>

Set the $boj_myplugin_website variable to the URL you want to include in your HTML link. Then concatenate the string to include the web site URL in your echo statement.

Indentation should always reflect the logical structure of the code. This means using real tabs, and not spaces, when indenting your code. As an example look at a poorly indented if statement:

if ( condition ) {
echo 'Yes';
} elseif ( condition2 ) {
echo 'No';
}

The preceding code logic is hard to follow because no indentation reflects the logical structure of the if statement. Now look at the same code sample using proper indentation:

<?php
if ( condition ) {
    echo 'Yes';
} elseif ( condition2 ) {
    echo 'No';
}
?>

Notice how using proper indentation makes reading the logic of the preceding if statement much easier to follow. You can easily skim this code and understand the outcome of the statement. This is why proper indentation is a must with any code you write.

Braces should always be used for multiline blocks of code. The brace should be positioned on the same line as the conditional statement you are checking. Look at an example using the proper bracing technique:

<?php
if ( condition ) {
    action1();
    action2();
} elseif ( condition2 || condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
}
?>

If you have an extremely long block of code, it's a good idea to put a short comment at the ending brace to help determine at a glance what that ending brace actually ends:

<?php
if ( condition ) {
    action1();
    action2();
} elseif ( condition2 || condition3 ) {
    action3();
    action4();
} else {
   defaultaction();
} //end of condition check
?>

Spaces should always be used after commas and on both sides of logical and assignment operators. Now look at a few different examples using the proper spacing methods:

<?php
if ( $foo == 34 ) {
    //do something
}

foreach ( $foo as $bar ) {
    //do something
}

$foo = array( 34, 16, 8 );

function super_function( $param1 = 'foo', $param2 = 'bar' ) {
    //do something
}
?>

Notice the spacing technique for each statement. This makes reading and following your code logic much easier because the code examples are clean and consistent throughout.

You shouldn't use the shorthand PHP tags ( <? ?> ) in your code. The reason for this is that shorthand PHP tags must be enabled on your server before they will function. Many hosting configurations have this feature disabled by default, which means your plugin would immediately break when activated in WordPress. Instead, you should wrap your PHP code in standard tags: <?php ?>

When making database calls in WordPress you may need to write custom SQL statements to query the proper data from the database. SQL statements can be broke into multiple lines if the complexity of the statement warrants it. Even though SQL is not case-sensitive, it's good practice to capitalize the SQL commands in the statement.

SELECT username FROM table1 WHERE status = 'active'

Chapter 6, "Plugin Security," discusses the proper way to use SQL statements in WordPress.

An action is technically a PHP function. For a function to be considered an action, it would need to be registered for an action hook. In the previous section, you can see what action hooks are, but for action hooks to serve any purpose, they need to have an action registered for them.

That's where plugins come in. You develop custom functions (actions) that perform a specific task when the action hook is fired. To do this, you would use the add_action() function.

<?php
add_action( $tag, $function, $priority, $accepted_args );
?>

Action hooks aren't limited to a single action. Your plugin can add multiple functions to an action hook. Other plugins, and even WordPress core, often add functions to the same hook.

Now it's time for you to put action hooks to use. One common action hook is wp_footer. It is fired on the front end of the site by the user's WordPress theme. Generally, it is fired just before the closing </body> tag in the HTML. In this example, you're going to register an action for the wp_footer hook that adds a custom message to the footer.

<?php

add_action( 'wp_footer', 'boj_example_footer_message', 100 );

function boj_example_footer_message() {

    echo 'This site is built using <a href="http://wordpress.org"
    title="WordPress publishing platform">WordPress</a>.';

}

?>

Code snippet boj-example-footer-message.php

Take a closer look at how you used add_action() from the preceding code.

<?php
add_action( 'wp_footer', 'boj_example_footer_message', 100 );
?>

The first parameter is the name of the hook (wp_footer). The second parameter is a callback to your custom function (boj_example_footer_message). The third parameter is the priority (100). Your function will likely be executed much later than other functions hooked to wp_footer because of its priority of 100. If this number were changed to 1, it would be called earlier.

You've now learned how the two most basic action hook functions work: do_action() and add_action(). WordPress also has other functions for working with action hooks that can be useful in your plugins.

<?php
do_action_ref_array( $tag, $args );
?>

<?php
do_action_ref_array( 'pre_get_posts', array( &$this ) );
?>

<?php

add_action( 'pre_get_posts', 'boj_randomly_order_blog_posts' );

function boj_randomly_order_blog_posts( $query ) {

    if ( $query->is_home && empty( $query->query_vars['suppress_filters'] ) )
        $query->set( 'orderby', 'rand' );
}

?>

<?php
remove_action( $tag, $function_to_remove, $priority, $accepted_args );
?>

<?php
add_action( 'wp_head', 'rel_canonical' );
?>

<?php
remove_action( 'wp_head', 'rel_canonical' );
?>

<?php
remove_all_actions( $tag, $priority );
?>

<?php
remove_all_actions( 'wp_head' );
?>

<?php
remove_all_actions( 'wp_head', 1 );
?>

<?php
has_action( $tag, $function_to_check );
?>

<?php

if ( has_action( 'wp_footer' ) )
    echo '<p>An action has been registered for the footer.</p>';

else
    echo '<p>An action hasn\'t been registered for the footer.</p>';

?>

<?php
add_action( 'wp_footer', 'wp_print_footer_scripts' );
?>

<?php

if ( has_action( 'wp_footer', 'wp_print_footer_scripts' ) )
    echo '<p>The wp_print_footer_scripts is registered for wp_footer.</p>';

?>

<?php
did_action( $tag );
?>

<?php

if ( did_action( 'plugins_loaded' ) )
    define( 'BOJ_MYPLUGIN_READY', true );

?>

WordPress has many action hooks, but some of them are used more often than others. Knowing what these hooks are can help you lay down the groundwork for your plugins.

<?php

add_action( 'plugins_loaded', 'boj_footer_message_plugin_setup' );

function boj_footer_message_plugin_setup() {

    /* Add the footer message action. */
    add_action( 'wp_footer', 'boj_example_footer_message', 100 );

}

function boj_example_footer_message() {

    echo 'This site is built using <a href="http://wordpress.org"
    title="WordPress publishing platform">WordPress</a>.';

}

?>

<?php

add_action( 'init', 'boj_add_excerpts_to_pages' );

function boj_add_excerpts_to_pages() {

    add_post_type_support( 'page', array( 'excerpt' ) );

}

?>

<?php

add_action( 'admin_menu', 'boj_admin_settings_page' );

function boj_admin_settings_page() {

    add_options_page(
        'BOJ Settings',
        'BOJ Settings',
        'manage_options',
        'boj_admin_settings',
        'boj_admin_settings_page'
    );

}

?>

<?php

add_action( 'template_redirect', 'boj_singular_post_css' );

function boj_singular_post_css() {

    if ( is_singular( 'post' ) ) {
        wp_enqueue_style(
            'boj-singular-post',
            'boj-example.css',
            false,
            0.1,
            'screen'
        );
    }

}

?>

<?php

add_action( 'wp_head', 'boj_front_page_meta_description' );

function boj_front_page_meta_description() {

    /* Get the site description. */
    $description = esc_attr( get_bloginfo( 'description' ) );

    /* If a description is set, display the meta element. */
    if ( !empty( $description ) )
        echo '<meta name="description" content="' . $description . '" />';
}

?>

A filter is a function registered for a filter hook. The function itself would take in at least a single parameter and return that parameter after executing its code. Without a filter, filter hooks don't do anything. They exist so that plugin developers can change different variables. This can be anything from a simple text string to a multidimensional array.

When a filter hook is called by the apply_filters() function, any filters registered for the hook are executed. To add a filter, use the add_filter() function.

<?php
add_filter( $tag, $function, $priority, $accepted_args );
?>

You can add multiple filters to the same filter hook. Other plugins and WordPress can also add filters to the hook. Filter hooks aren't limited to a single filter. It is important to note this because each filter must always return a value for use by the other filters. If your function doesn't return a value, you risk breaking the functionality of both WordPress and other plugins.

Now look at the wp_title filter hook in WordPress, which is a filter hook responsible for the <title> element on a page.

<?php
apply_filters( 'wp_title', $title, $sep, $seplocation );
?>

You're now going to write a function that filters the output of $title by appending the site's name to the end of page title.

<?php

add_filter( 'wp_title', 'boj_add_site_name_to_title', 10, 2 );

function boj_add_site_name_to_title( $title, $sep ) {

    /* Get the site name. */
    $name = get_bloginfo( 'name' );

    /* Append the name to the $title variable. */
    $title .= $sep . ' ' . $name;

    /* Return the title. */
    return $title;
}

?>

Take a look at the line telling WordPress to add a filter to wp_title.

<?php
add_filter( 'wp_title', 'boj_add_site_name_to_title', 10, 2 );
?>

It says that you want to add a filter named boj_add_site_name_title_title to the wp_title filter hook. You set a priority of 10 and tell your filter to accept two parameters.

The boj_add_site_name_to_title() function manipulates the $title parameter and returns it back to WordPress. The $sep parameter can be used within the function but is not returned.

Aside from the apply_filters() and add_filter() functions covered in the previous sections of this chapter, WordPress has several other functions for working with filter hooks.

<?php
apply_filters_ref_array( $tag, $args );
?>

<?php
$this->posts =
apply_filters_ref_array(
    'posts_results', array( $this->posts, &$this )
);
?>

<?php

add_filter( 'posts_results', 'boj_custom_home_page_posts' );

function boj_custom_home_page_posts( $results ) {
    global $wpdb, $wp_query;

    /* Check if viewing the home page. */
    if ( is_home() ) {

        /* Posts per page. */
        $per_page = get_option( 'posts_per_page' );

        /* Get the current page. */
        $paged = get_query_var( 'paged' );

        /* Set the $page variable. */
        $page = ( ( 0 == $paged || 1 == $paged ) ? 1 : absint( $paged ) );

        /* Set the number of posts to offset. */
        $offset = ( $page - 1 ) * $per_page . ', ';

        /* Set the limit by the $offset and number of posts to show. */
        $limits = 'LIMIT '. $offset . $per_page;

        /* Get results from the database. */
        $results = $wpdb->get_results( "
            SELECT SQL_CALC_FOUND_ROWS $wpdb->posts.*
            FROM $wpdb->posts
            WHERE 1=1
            AND post_type = 'page'
            AND post_status = 'publish'

ORDER BY post_title ASC
            $limits
        " );
    }

    return $results;
}

?>

<?php
remove_filter( $tag, $function_to_remove, $priority, $accepted_args );
?>

<?php
add_filter( 'the_content', 'wpautop' );
?>

<?php

remove_filter( 'the_content', 'wpautop' );

?>

<?php
remove_all_filters( $tag, $priority );
?>

<?php
remove_all_filters( 'the_content' );
?>

<?php
remove_all_filters( 'the_content', 11 );
?>

<?php
has_filter( $tag, $function_to_check );
?>

<?php

if ( has_filter( 'the_content' ) )
    echo 'The content filter hook has at least one filter.';

else
    echo 'The content filter hook has no filters.';

?>

<?php

if ( has_filter( 'the_content', 'wpautop' ) )
    echo 'Paragraphs are automatically formatted for the content.';

?>

<?php

add_filter( 'the_content', 'boj_replace_unwanted_words' );
add_filter( 'the_title', 'boj_replace_unwanted_words' );

function boj_replace_unwanted_words( $text ) {

/* If the_content is the filter hook, set its unwanted words. */
    if ( 'the_content' == current_filter() )
        $words = array( 'profanity', 'curse', 'devil' );

    /* If the_title is the filter hook, set its unwanted words. */
    elseif ( 'the_title' == current_filter() )
        $words = array( 'profanity', 'curse' );

    /* Replace unwanted words with "Whoops!" */
    $text = str_replace( $words, 'Whoops!', $text );

    /* Return the formatted text. */
    return $text;
}

?>

Often, you'll need to write a function that returns a common value to a filter hook such as true, false, or an empty array. You might even be tempted to use PHP's create_function() function to quickly return a value.

WordPress has several functions for handling scenarios such as this. With the next example code, you disable the user contact methods, which are a list of <input> boxes on individual user edit screens in the WordPress admin. To disable these boxes, you would need to return an empty array. Normally, you'd have to add the filter hook call and code the function.

<?php

add_filter( 'user_contactmethods', 'boj_return_empty_array' );

function boj_return_empty_array() {
    return array();
}

?>

Writing the code for that isn't so bad if doing it once or twice. However, it almost seems silly to have to write an entire function to return an empty array. WordPress makes this much easier. Because you're simply disabling these boxes, you can use WordPress's __return_empty_array() function as a filter for quickly returning an empty array, replacing the previous code snippet with the following.

<?php

add_filter( 'user_contactmethods', '__return_empty_array' );

?>

Using __return_empty_array is important here. WordPress will expect the value returned to be an array, so returning something other than an array would result in a PHP error.

The WordPress functions for quickly returning values can come in handy when developing plugins. It's always important to check the core code to see what value is expected after filters have been applied. Each scenario will call for a specific return value type:

These are simply a few functions WordPress makes available for use within plugins. If you find yourself writing one-line functions just to return a single value to a filter hook, you have the option of creating your own functions for handling this if the previous list of functions doesn't cover your use case.

WordPress has hundreds of filter hooks for use by plugin developers. Narrowing these down to a small list of some commonly used hooks doesn't come close to accurately representing what a plugin can accomplish by using the hook system. In this section, you learn how to use some of the more common filter hooks that plugin developers use in their plugins.

<?php

add_filter( 'the_content', 'boj_add_related_posts_to_content' );

function boj_add_related_posts_to_content( $content ) {

    /* If not viewing a singular post, just return the content. */
    if ( !is_singular( 'post' ) )
        return $content;

    /* Get the categories of current post. */
    $terms = get_the_terms( get_the_ID(), 'category' );

    /* Loop through the categories and put their IDs in an array. */

$categories = array();
    foreach ( $terms as $term )
        $categories[] = $term->term_id;

    /* Query posts with the same categories from the database. */
    $loop = new WP_Query(
        array(
            'cat__in' => $categories,
            'posts_per_page' => 5,
            'post__not_in' => array( get_the_ID() ),
            'orderby' => 'rand'
        )
    );

    /* Check if any related posts exist. */
    if ( $loop->have_posts() ) {

        /* Open the unordered list. */
        $content .= '<ul class="related-posts">';

        while ( $loop->have_posts() ) {
            $loop->the_post();

            /* Add the post title with a link to the post. */
            $content .= the_title(
                '<li><a href="' . get_permalink() . '">',
                '</a></li>',
                false
            );
        }

        /* Close the unordered list. */
        $content .= '</ul>';

        /* Reset the query. */
        wp_reset_query();
    }

    /* Return the content. */
    return $content;
}

?>

<?php

add_filter( 'the_title', 'boj_strip_tags_from_titles' );

function boj_strip_tags_from_titles( $title ) {

    $title = strip_tags( $title );

    return $title;
}

?>

<?php

add_filter( 'comment_text', 'boj_add_role_to_comment_text' );

function boj_add_role_to_comment_text( $text ) {
    global $comment;

    /* Check if comment was made by a registered user. */
    if ( $comment->user_id > 0 ) {

        /* Create new user object. */
        $user = new WP_User( $comment->user_id );

        /* If user has a role, add it to the comment text. */
        if ( is_array( $user->roles ) )
            $text .= '<p>User Role: ' . $user->roles[0] . '</p>';
    }

    return $text;
}

?>

<?php

add_filter( 'single_template', 'boj_single_template' );

function boj_single_template( $template ) {
    global $wp_query;

    /* Check if viewing a singular post. */
    if ( is_singular( 'post' ) ) {
        /* Get the post ID. */
        $post_id = $wp_query->get_queried_object_id();

        /* Get the post categories. */
        $terms = get_the_terms( $post_id, 'category' );

        /* Loop through the categories, adding slugs as part of the file name. */
        $templates = array();
        foreach ( $terms as $term )
            $templates[] = "single-category-{$term->slug}.php";

/* Check if the template exists. */
        $locate = locate_template( $templates );

        /* If a template was found, make it the new template. */
        if ( !empty( $locate ) )
            $template = $locate;
    }

    /* Return the template file name. */
    return $template;
}

?>

Custom hooks make your plugin more flexible, allow it to be extended by others, and gives you the ability to hook into the execution of various processes throughout your plugin within the plugin itself.

Using custom hooks also keep users from editing your work directly. The importance of this is that when you provide an update for the plugin, users won't lose any modifications they've made.

In this custom action hook example, you create a plugin setup function. The function defines a constant that can be altered. Other plugins may also execute any code they want on the hook. You provide it so that they have an opportunity to run code at that point.

<?php

add_action( 'plugins_loaded', 'boj_myplugin_setup' );

function boj_myplugin_setup() {

    /* Allow actions to fire before anything else. */
    do_action( 'boj_myplugin_setup_pre' );

    /* Check if the root slug is defined. */
    if ( !defined( 'BOJ_MYPLUGIN_ROOT_SLUG' ) )
        define( 'BOJ_MYPLUGIN_ROOT_SLUG', 'articles' );
}

?>

Other plugins or themes may hook into boj_myplugin_setup_pre and execute any function. Suppose you want to change the BOJ_MYPLUGIN_ROOT_SLUG constant from "articles" to "papers." You can create a custom action to add to the hook.

<?php

add_action( 'boj_myplugin_setup_pre', 'boj_define_myplugin_constants' );

function boj_define_myplugin_constants() {

    define( 'BOJ_MYPLUGIN_ROOT_SLUG', 'papers' );
}

?>

Suppose you have a function that displays a list of posts given a specific set of arguments. You may want to grant others the ability to filter the arguments and filter the final output.

In this example, you write a function that lists the top 10 posts by the number of comments a post has received. The function enables users to filter the arguments for grabbing the posts from the database and enables them to filter the final HTML output of the list.

<?php

function boj_posts_by_comments() {

    /* Default arguments. */
    $args = array(
        'post_type' => 'post',
        'posts_per_page' => 10,
        'order' => 'DESC',
        'orderby' => 'comment_count'
    );

    /* Apply filters to the arguments. */
    $args = apply_filters( 'boj_posts_by_comments_args', $args );

    /* Set up the output variable. */
    $out = '';

    /* Query posts from the database by the given arguments. */
    $loop = new WP_Query( $args );

    /* Check if posts are found. */
    if ( $loop->have_posts() ) {

        /* Open the unordered list. */
        $out .= '<ul class="posts-by-comments">';

        /* Loop through the posts. */
        while ( $loop->have_posts() ) {

            $loop->the_post();

            /* Add the post title to the list. */
            $out .= the_title( '<li>', '</li>', false );
        }

        /* Close the unordered list. */
        $out .= '</ul>';
    }

    /* Apply filters to the final output. */
    $out = apply_filters( 'boj_posts_by_comments', $out );

/* Display the HTML. */
    echo $out;
}

?>

To filter the arguments, add a filter to boj_posts_by_comments_args. Suppose you want to change the default number of 10 posts to 15. You add a custom filter for this.

<?php

add_filter( 'boj_posts_by_comments_args', 'boj_change_posts_by_comments_args' );

function boj_change_posts_by_comments_args( $args ) {

    /* Change the value of the posts_per_page array key. */
    $args['posts_per_page'] = 15;

    /* Return the $args parameter. */
    return $args;
}

?>

To filter the final HTML output, add a filter to boj_posts_by_comments. Suppose you want to change the unordered list to an ordered list with a custom filter.

<?php

add_filter( 'boj_posts_by_comments', 'boj_change_posts_by_comments' );

function boj_change_posts_by_comments( $out ) {

    /* Change the opening <ul> to an <ol>. */
    $out = str_replace( '<ul ', '<ol ', $out );

    /* Change the closing </ul> to an </ol>. */
    $out = str_replace( '</ul>', '</ol>', $out );

    /* Return the filtered HTML. */
    return $out;
}

?>

As a plugin developer, you should become familiar with the core WordPress code. Looking for hooks is a great way to start familiarizing yourself with how WordPress works. There's no better process for understanding how PHP code works than actually looking at the code and following each statement made within the code.

An easy way to search for hooks is to open a file from the wordpress folder in your preferred text editor and run a text search for one of four function names.

Those are the functions you learned to use earlier in the chapter. Each function creates a hook, so by searching for one of those strings, you can find new hooks in WordPress.

When searching for hooks throughout the core WordPress code, you will come across what's known as "variable hooks." Normally, hook names are a static string of text. However, variable hook names change based on a specific variable.

A good example of this is the load-$pagenow action hook. The $pagenow variable changes depending on the WordPress admin page currently viewed. The hook looks like the following in the core code.

<?php
do_action( "load-$pagenow" );
?>

The $pagenow variable will become the page name being viewed. For example, the hook for the new post page in the admin would be load-post-new.php and the hook on the edit posts screen would be load-post.php. This enables plugins to run code only for specific page views in the admin.

WordPress has several action and filter hooks with variables as part of the hook name. Generally, these hook names change to provide context to plugin developers so that they can execute code only when specific circumstances are met. It is important to keep this in mind when searching for just the right hook to use in your plugin.

Although searching for hooks within the core code can be beneficial to your learning experience, sometimes you may find it easier to access some of the publicly available reference lists on the Web. These lists can sometimes save you time and may also have descriptions about the hook.

WordPress has both an official action and filter hook reference list in its Codex.

Chapter 18, "The Developer Toolbox," covers more materials and tools to help plugin developers.

The first menu method for your plugin to explore in WordPress is a new top-level menu, which is added to the admin dashboard menu list. For example, Settings is a top-level menu. A top-level menu is common practice for any plugin that needs multiple option pages. To register a top-level menu, you use the add_menu_page() function.

<?php add_menu_page( page_title, menu_title, capability, menu_slug, function,
        icon_url, position ); ?>

The add_menu_page() function accepts the following parameters:

Now create a new menu for your plugin to see the menu process in action. Use the admin_menu action hook to trigger your menu code. This is the appropriate hook to use whenever you create menus and submenus in your plugins.

<?php
add_action( 'admin_menu', 'boj_menuexample_create_menu' );

function boj_menuexample_create_menu() {

    //create custom top-level menu
    add_menu_page( 'My Plugin Settings Page', 'Menu Example Settings',
        'manage_options', __FILE__, 'boj_menuexample_settings_page',
        plugins_url( '/images/wp-icon.png', __FILE__ ) );

}

?>

As you can see, the admin_menu action hook calls your custom boj_menuexample_create_menu() function. Next you need to call the add_menu_page() function to register the custom menu in WordPress. Set the name of your menu to Menu Example Settings, which requires that the user has manage_options capabilities (that is, is an administrator), and even set a custom icon located in the /images folder of your plugin, as shown in Figure 4-1.

Figure 4.1. FIGURE 4-1

Now that you have a new top-level menu created, create some submenus for it, which are menu items listed below your top-level menu. For example, Settings is a top-level menu whereas General, listed below Settings, is a submenu of the Settings menu. To register a submenu, use the add_submenu_page() function.

<?php add_submenu_page( parent_slug, page_title, menu_title, capability,
        menu_slug, function ); ?>

The add_submenu_page() function accepts the following parameters:

Now that you know how submenus are defined, you can add one to your custom top-level menu:

<?php
add_action( 'admin_menu', 'boj_menuexample_create_menu' );

function boj_menuexample_create_menu() {

    //create custom top-level menu
    add_menu_page( 'My Plugin Settings Page', 'Menu Example Settings',
        'manage_options', __FILE__, 'boj_menuexample_settings_page',
        plugins_url( '/images/wp-icon.png', __FILE__ ) );

    //create submenu items
    add_submenu_page( __FILE__, 'About My Plugin', 'About', 'manage_options',
        __FILE__.'_about', boj_menuexample_about_page );
    add_submenu_page( __FILE__, 'Help with My Plugin', 'Help', 'manage_options',
        __FILE__.'_help', boj_menuexample_help_page );
    add_submenu_page( __FILE__, 'Uninstall My Plugin', 'Uninstall', 'manage_options',
        __FILE__.'_uninstall', boj_menuexample_uninstall_page );

}
?>

Code snippet boj-custom-menu-plugin.php

The preceding code creates three submenus for your custom top-level menu: About, Help, and Uninstall, as shown in Figure 4-2. Each of these submenu items link to a different custom function that can contain any code you want to use for that submenu page.

Figure 4.2. FIGURE 4-2

If your plugin requires only a single options page, you do not need to create a custom top-level menu. Instead you can simply add a submenu to an existing menu, such as the Settings menu.

WordPress features many different functions to add submenus to the existing default menus in WordPress. One of these functions is the add_options_page() function. Now explore how the add_options_page() function works to add a submenu item to the Settings menu.

<?php add_options_page( page_title, menu_title, capability, menu_slug, function);?>

The add_options_page() function accepts the following parameters:

Now add a submenu item to the Settings menu:

<?php
add_action( 'admin_menu', 'boj_menuexample_create_menu' );

function boj_menuexample_create_menu() {

    //create a submenu under Settings
    add_options_page( 'My Plugin Settings Page', 'Menu Example Settings',
        'manage_options', __FILE__, 'boj_menuexample_settings_page' );

}
?>

Code snippet boj-options-page-plugin.php

The preceding code adds a submenu labeled Menu Example Settings under the Settings menu, as shown in Figure 4-3. Set the page title to My Plugin Settings Page, set the capability to manage_options so that only administrators can view it, and set the function boj_menuexample_settings_page() to be called when the submenu is clicked.

Following is a list of all available submenu functions in WordPress.

To use any of these functions, simply swap out the function name in the code shown earlier.

Figure 4.3. FIGURE 4-3

You create all widgets in WordPress using the WP_Widget class. To understand how the widget class works, it's helpful to look at an overview of the class:

<?php
class My_Widget extends WP_Widget {

    function My_Widget() {
        // processes the widget
    }

    function form($instance) {

// displays the widget form in the admin dashboard
    }

    function update($new_instance, $old_instance) {
        // process widget options to save
    }

    function widget($args, $instance) {
        // displays the widget
    }

}
?>

As you can see, the WP_Widget class features multiple functions for your widget, each with a specific purpose.

Now it's time to create a widget for your plugin. For this first widget, you create a simple text-based widget to save and display your favorite movie and song. It is a simple example that demonstrates how to save text data in a WordPress widget.

To start you use the widgets_init action hook. This hook is triggered after the default widgets have been registered in WordPress.

<?php
// use widgets_init action hook to execute custom function
add_action( 'widgets_init', 'boj_widgetexample_register_widgets' );

 //register our widget
function boj_widgetexample_register_widgets() {
    register_widget( 'boj_widgetexample_widget_my_info' );
}
?>

The widgets_init hook triggers the custom function to register your widget, in this case boj_widgetexample_register_widgets(). Next you use the register_widget() function to register your new widget; in this example you register the class name as boj_widgetexample_widget_my_info(). This function accepts one parameter, and that is the class name that will extend WP_Widget. The widget class name can be anything, but it must be unique and should always be descriptive of your widget. You can also register as many widgets as needed using this function.

Now that you've registered your widget, it's time to set up the widget class.

<?php
//boj_widgetexample_widget_my_info class
class boj_widgetexample_widget_my_info extends WP_Widget {
?>

You need to extend the WP_Widget class by creating a new class with the unique name you defined when you registered your widget. Now that you've defined the class, it's time to start building the widget.

<?php
    //process the new widget
    function boj_widgetexample_widget_my_info() {
        $widget_ops = array(
            'classname' => 'boj_widgetexample_widget_class',
            'description' => 'Display a user\'s favorite movie and song.'
        );
        $this->WP_Widget( 'boj_widgetexample_widget_my_info', 'My Info Widget',
            $widget_ops );
    }
?>

First, make a new array to store your widget options called $widget_ops. This array can hold the classname and description options. The classname option is the class name added to the <li> element of the widget. Sidebars, by default, display all widgets in an unordered list. Each individual widget is a list item in that list, so by adding a custom classname and ID, you can easily create custom styles and designs for your widget. The description displays under the widget on the Appearance

After building your options array, you then pass those values to WP_Widget. The first value you pass is the ID for the list item of your widget, in this case boj_widgetexample_widget_my_info(). The second value to pass is the widget name displayed in the Widgets screen. The widget name should be a short and sweet name describing your widget. The final value to pass is your array of options you set earlier.

Next you need to create your widgets settings form. This widget accepts three values: Title, Favorite movie, and Favorite song.

<?php
    //build the widget settings form
    function form($instance) {
        $defaults = array( 'title' => 'My Info', 'movie' => '', 'song' => '' );
        $instance = wp_parse_args( (array) $instance, $defaults );
        $title = $instance['title'];
        $movie = $instance['movie'];
        $song = $instance['song'];
        ?>
        <p>Title: <input class="widefat" name="
            <?php echo $this->get_field_name( 'title' ); ?>"  type="text"
            value="<?php echo esc_attr( $title ); ?>" /></p>
        <p>Favorite Movie: <input class="widefat" name="
            <?php echo $this->get_field_name( 'movie' ); ?>"  type="text"
            value="<?php echo esc_attr( $movie ); ?>" /></p>
        <p>Favorite Song: <textarea class="widefat" name="
            <?php echo $this->get_field_name( 'song' ); ?>" / >
            <?php echo esc_attr( $song ); ?></textarea></p>
        <?php
    }
?>

First, you create a $defaults variable to set the default values of each option. In this example, you set only the default title to My Info. Next pull in the instance values; that is, the widget settings that have been saved. If this is a new widget and was just added to a sidebar, there won't be any settings saved, so this value will be empty.

The final part to your widget settings is to display the form elements for entering the widget information. Use a standard HTML input text field for all three of your fields: title, movie, and song. You'll notice you don't need to include the <form> tags or submit button; the widget class handles that for you. Also notice you use the esc_attr() function to escape the saved value prior to displaying it in the field.

Now it's time to save your widget settings using the update function of the widget class.

<?php
    //save the widget settings
    function update($new_instance, $old_instance) {
        $instance = $old_instance;
        $instance['title'] = strip_tags( $new_instance['title'] );
        $instance['movie'] = strip_tags( $new_instance['movie'] );
        $instance['song'] = strip_tags( $new_instance['song'] );

        return $instance;
    }
?>

As you can see, the widget class handles all the saving for you. You simply pass in the $new_instance values for each of your widget settings. Always be sure to sanitize any user-entered data, in this case using the strip_tags() PHP function.

The final piece to the widget puzzle is displaying your widget in the sidebar. To do this you use the widget function of the widget class.

<?php
    //display the widget
    function widget($args, $instance) {
        extract($args);

        echo $before_widget;
        $title = apply_filters( 'widget_title', $instance['title'] );
        $movie = empty( $instance['movie'] ) ? '&nbsp;' : $instance['movie'];
        $song = empty( $instance['song'] ) ? '&nbsp;' : $instance['song'];

        if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };
        echo '<p>Fav Movie: ' . $movie . '</p>';
        echo '<p>Fav Song: ' . $song . '</p>';
        echo $after_widget;
    }
?>

The first step is to extract the $args parameter. This variable holds global theme values such as $before_widget and $after_widget. These values can be defined when a sidebar is registered and can be used to customize the code that wraps your widget, such as adding a custom <div> tag.

Next you set the $title variable for the title of your widget. You need to apply the widget_title filter hook to the title. This enables other developers to modify the display of the widget title if needed. To set the $movie and $song variables, use a PHP ternary operator. In plain English this line breaks down as follows: If $movie is empty, set it to ' ', if it's not empty set it to $instance['movie'].

Figure 4.4. FIGURE 4-4

Now that you've defined all your widget setting variables and populated their values, it's time to display them. First, display the $title variable. It's always important to wrap this value with the $before_title and $after_title variables. These global variables can also be set by developers when registering a sidebar. After displaying the $title value, display the favorite movie and song values. Finally, remember to end your widget display with the $after_widget global value.

Congratulations! You just created a WordPress widget! Now you can add your newly created widget and fill in the widget settings, as shown in Figure 4-4.

Your new widget then displays in your sidebar, as shown in Figure 4-5.

Figure 4.5. FIGURE 4-5

Now review the full widget code that's put together:

<?php
/*
Plugin Name: Widget Example Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A plugin to create widgets in WordPress
Version: 1.0
Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2
*/

// use widgets_init action hook to execute custom function
add_action( 'widgets_init', 'boj_widgetexample_register_widgets' );

 //register our widget
function boj_widgetexample_register_widgets() {
    register_widget( 'boj_widgetexample_widget_my_info' );
}

//boj_widget_my_info class
class boj_widgetexample_widget_my_info extends WP_Widget {

    //process the new widget
    function boj_widgetexample_widget_my_info() {
        $widget_ops = array(
            'classname' => 'boj_widgetexample_widget_class',
            'description' => 'Display a user\'s favorite movie and song.'
            );
        $this->WP_Widget( 'boj_widgetexample_widget_my_info', 'My Info Widget',
            $widget_ops );
    }

     //build the widget settings form

function form($instance) {
        $defaults = array( 'title' => 'My Info', 'movie' => '', 'song' => '' );
        $instance = wp_parse_args( (array) $instance, $defaults );
        $title = $instance['title'];
        $movie = $instance['movie'];
        $song = $instance['song'];
        ?>
            <p>Title: <input class="widefat" name="
                <?php echo $this->get_field_name( 'title' ); ?>"
                type="text" value="<?php echo esc_attr( $title ); ?>" /></p>
            <p>Favorite Movie: <input class="widefat" name="
                <?php echo $this->get_field_name( 'movie' ); ?>"
                type="text" value="<?php echo esc_attr( $movie ); ?>" /></p>
            <p>Favorite Song: <textarea class="widefat" name="
                <?php echo $this->get_field_name( 'song' ); ?>" / >
                <?php echo esc_attr( $song ); ?></textarea></p>
        <?php
    }

    //save the widget settings
    function update($new_instance, $old_instance) {
        $instance = $old_instance;
        $instance['title'] = strip_tags( $new_instance['title'] );
        $instance['movie'] = strip_tags( $new_instance['movie'] );
        $instance['song'] = strip_tags( $new_instance['song'] );

        return $instance;
    }

    //display the widget
    function widget($args, $instance) {
        extract($args);

        echo $before_widget;
        $title = apply_filters( 'widget_title', $instance['title'] );
        $movie = empty( $instance['movie'] ) ? '&nbsp;' : $instance['movie'];
        $song = empty( $instance['song'] ) ? '&nbsp;' : $instance['song'];

        if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };
        echo '<p>Fav Movie: ' . $movie . '</p>';
        echo '<p>Fav Song: ' . $song . '</p>';
        echo $after_widget;
    }
}
?>

Code snippet boj-widget-plugin.php

Now that you have a solid understanding of how widgets work, you can create a more advanced widget. In this example, you create a widget that retrieves an RSS feed and displays its results. You also use different types of form elements for your widget options. First, you need to register your new widget.

<?php
// use widgets_init action hook to execute custom function
add_action( 'widgets_init', 'boj_awe_register_widgets' );

//register our widget
function boj_awe_register_widgets() {
    register_widget( 'boj_awe_widget' );
}
?>

Register your new widget as boj_awe_widget. Now that your widget is registered, it's time to extend the WP_Widget class for your new widget.

<?php
//boj_widget_my_info class
class boj_awe_widget extends WP_Widget {

    //process the new widget
    function boj_awe_widget() {

        $widget_ops = array(
        'classname' => 'boj_awe_widget_class',
        'description' => 'Display an RSS feed with options.'
    );

        $this->WP_Widget( 'boj_awe_widget', 'Advanced RSS Widget', $widget_ops );
    }
?>

As before, you set the class name and description of your new widget. In this example, the new widget title is set to Advanced RSS Widget. Next create the widget options.

<?php
     //build the widget settings form
    function form($instance) {
        $defaults = array(
            'title' => 'RSS Feed',
            'rss_feed' => 'http://strangework.com/feed',
            'rss_items' => '2'
        );
        $instance = wp_parse_args( (array) $instance, $defaults );
        $title = $instance['title'];
        $rss_feed = $instance['rss_feed'];
        $rss_items = $instance['rss_items'];
        $rss_date = $instance['rss_date'];
        $rss_summary = $instance['rss_summary'];
        ?>
            <p>Title: <input class="widefat" name="
                <?php echo $this->get_field_name( 'title' ); ?>"

type="text" value="<?php echo esc_attr( $title ); ?>" /></p>
            <p>RSS Feed: <input class="widefat" name="
                <?php echo $this->get_field_name( 'rss_feed' ); ?>"
                type="text" value="<?php echo esc_attr( $rss_feed ); ?>" /></p>
            <p>Items to Display:
            <select name="<?php echo $this->get_field_name( 'rss_items' ); ?>">
                <option value="1" <?php selected( $rss_items, 1 ); ?>>1</option>
                < option value="2" <?php selected( $rss_items, 2 ); ?>>2</option>
                < option value="3" <?php selected( $rss_items, 3 ); ?>>3</option>
                < option value="4" <?php selected( $rss_items, 4 ); ?>>4</option>
                < option value="5" <?php selected( $rss_items, 5 ); ?>>5</option>
            </select>
            </p>
            <p>Show Date?: <input name="
                <?php echo $this->get_field_name( 'rss_date' ); ?>"
                type="checkbox" <?php checked( $rss_date, 'on' ); ?> /></p>
            <p>Show Summary?: <input name="
                <?php echo $this->get_field_name( 'rss_summary' ); ?>"
                type="checkbox" <?php checked( $rss_summary, 'on' ); ?> /></p>
        <?php
    }
?>

This widget features five options enabling the user to set the title, RSS feed, items to display, and whether a date and summary of each post will be displayed. The title and RSS feed options are standard text fields.

The items to display option is an HTML select list. Notice the use of the selected() function, which is an extremely useful tool for comparing two values in a select field to determine if that option is selected. If the option value compared is the option that is saved, WordPress adds selected='selected' value to the option field, which makes it the selected option.

The show date and show summary options are both check box form fields. Here you use the checked() WordPress function. This function works just like the selected() function in that it compares two values and determines if they are identical, but the difference is the checked() function outputs checked='checked', which makes the option checked.

Now that your widget form is set up, it's time to save your widget options.

<?php
    //save the widget settings
    function update($new_instance, $old_instance) {
        $instance = $old_instance;
        $instance['title'] = strip_tags( $new_instance['title'] );
        $instance['rss_feed'] = strip_tags( $new_instance['rss_feed'] );
        $instance['rss_items'] = strip_tags( $new_instance['rss_items'] );
        $instance['rss_date'] = strip_tags( $new_instance['rss_date'] );
        $instance['rss_summary'] = strip_tags( $new_instance['rss_summary'] );

        return $instance;
    }
?>

As always make sure you sanitize the widget option values using the proper sanitizing function, in this case strip_tags(). Now that the widget options are saved, it's time to display the widget based on the set options.

<?php
    //display the widget
    function widget($args, $instance) {
        extract($args);

        echo $before_widget;

        //load the widget settings
        $title = apply_filters( 'widget_title', $instance['title'] );
        $rss_feed = empty( $instance['rss_feed'] ) ? '' : $instance['rss_feed'];
        $rss_items = empty( $instance['rss_items'] ) ? 2 : $instance['rss_items'];
        $rss_date = empty( $instance['rss_date'] ) ? 0 : 1;
        $rss_summary = empty( $instance['rss_summary'] ) ? 0 : 1;

        if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };

            if ( $rss_feed ) {
                //display the RSS feed
                wp_widget_rss_output( array(
                    'url' => $rss_feed,
                    'title' => $title,
                    'items' => $rss_items,
                    'show_summary' => $rss_summary,
                    'show_author' => 0,
                    'show_date' => $rss_date
                ) );
            }

        echo $after_widget;
    }
?>

First, you need to load all the widget options to determine how the RSS feed should display. The defaults for each option are set using a ternary operator. For example, if the RSS date option is checked by the user, the $rss_date variable will be set to 1; if not it will be set to 0.

You have just created an advanced RSS widget in WordPress! This widget is a great example of how to create and set different types of options and use them appropriately in your widget's display. Now look at the full source code for the widget.

<?php
/*
Plugin Name: Advanced Widget Example Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A plugin to create widgets in WordPress
Version: 1.0
Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2

*/

// use widgets_init action hook to execute custom function
add_action( 'widgets_init', 'boj_awe_register_widgets' );

//register our widget
function boj_awe_register_widgets() {
    register_widget( 'boj_awe_widget' );
}

//boj_widget_my_info class
class boj_awe_widget extends WP_Widget {

    //process the new widget
    function boj_awe_widget() {

        $widget_ops = array(
            'classname' => 'boj_awe_widget_class',
            'description' => 'Display an RSS feed with options.'
            );

        $this->WP_Widget( 'boj_awe_widget', 'Advanced RSS Widget', $widget_ops );
    }

     //build the widget settings form
    function form($instance) {
        $defaults = array(
            'title' => 'RSS Feed',
            'rss_feed' => 'http://strangework.com/feed',
            'rss_items' => '2'
        );
        $instance = wp_parse_args( (array) $instance, $defaults );
        $title = $instance['title'];
        $rss_feed = $instance['rss_feed'];
        $rss_items = $instance['rss_items'];
        $rss_date = $instance['rss_date'];
        $rss_summary = $instance['rss_summary'];
        ?>
            <p>Title: <input class="widefat" name="
                <?php echo $this->get_field_name( 'title' ); ?>"
                type="text" value="<?php echo esc_attr( $title ); ?>" /></p>
            <p>RSS Feed: <input class="widefat" name="
                <?php echo $this->get_field_name( 'rss_feed' ); ?>"
                type="text" value="<?php echo esc_attr( $rss_feed ); ?>" /></p>
            <p>Items to Display:
                <select name="<?php echo $this->get_field_name( 'rss_items' ); ?>">
                    <option value="1" <?php selected( $rss_items, 1 ); ?>>1</option>
                    <option value="2" <?php selected( $rss_items, 2 ); ?>>2</option>
                    <option value="3" <?php selected( $rss_items, 3 ); ?>>3</option>
                    <option value="4" <?php selected( $rss_items, 4 ); ?>>4</option>
                    <option value="5" <?php selected( $rss_items, 5 ); ?>>5</option>
                </select>
            </p>
            <p>Show Date?: <input name="

<?php echo $this->get_field_name( 'rss_date' ); ?>"
                type="checkbox" <?php checked( $rss_date, 'on' ); ?> /></p>
            <p>Show Summary?: <input name="
                <?php echo $this->get_field_name( 'rss_summary' ); ?>"
                type="checkbox" <?php checked( $rss_summary, 'on' ); ?> /></p>
        <?php
    }

    //save the widget settings
    function update($new_instance, $old_instance) {
        $instance = $old_instance;
        $instance['title'] = strip_tags( $new_instance['title'] );
        $instance['rss_feed'] = strip_tags( $new_instance['rss_feed'] );
        $instance['rss_items'] = strip_tags( $new_instance['rss_items'] );
        $instance['rss_date'] = strip_tags( $new_instance['rss_date'] );
        $instance['rss_summary'] = strip_tags( $new_instance['rss_summary'] );

        return $instance;
    }

    //display the widget
    function widget($args, $instance) {
        extract($args);

        echo $before_widget;

        //load the widget settings
        $title = apply_filters( 'widget_title', $instance['title'] );
        $rss_feed = empty( $instance['rss_feed'] ) ? '' : $instance['rss_feed'];
        $rss_items = empty( $instance['rss_items'] ) ? 2 : $instance['rss_items'];
        $rss_date = empty( $instance['rss_date'] ) ? 0 : 1;
        $rss_summary = empty( $instance['rss_summary'] ) ? 0 : 1;

        if ( !empty( $title ) ) { echo $before_title . $title . $after_title; };

        if ( $rss_feed ) {
            //display the RSS feed
            wp_widget_rss_output( array(
                'url' => $rss_feed,
                'title' => $title,
                'items' => $rss_items,
                'show_summary' => $rss_summary,
                'show_author' => 0,
                'show_date' => $rss_date
            ) );
        }

        echo $after_widget;
    }
}
?>

Code snippet boj-advanced-rss-widget.php

WordPress also features a dashboard widget API. You can use this API to create custom widgets on the WordPress dashboard screen.

To create your dashboard widget, you use the wp_add_dashboard_widget() function. Here's how to use this function to create a dashboard widget:

<?php wp_add_dashboard_widget( widget_id, widget_name, callback,
        control_callback ); ?>

The wp_add_dashboard_widget() function accepts the following parameters:

Following are some different examples. First, you create a simple dashboard widget that displays a piece of content to the user.

To create a dashboard widget, use the wp_dashboard_setup action hook. This hook is executed directly after the default dashboard widgets have been initialized, but prior to them being displayed.

<?php
add_action( 'wp_dashboard_setup', 'boj_dashboard_example_widgets' );

function boj_dashboard_example_widgets() {

    //create a custom dashboard widget
    wp_add_dashboard_widget( 'dashboard_custom_feed',
        'My Plugin Information', 'boj_dashboard_example_display' );

}
?>

The wp_dashboard_setup hook can call your custom boj_dashboard_example_widgets() function. Next use the wp_add_dashboard_widget() function to register your new dashboard widget. Set the widget title to My Plugin Information, and call the custom function boj_dashboard_example_display(). Now that your dashboard widget is registered, you need to set up the custom function to display a message to your users.

<?php
function boj_dashboard_example_display()
{
    echo '<p>Please contact support@example.com to report bugs.</p>';
}
?>

You now have a custom dashboard widget with a simple message displayed to your users, as shown in Figure 4-6. The Dashboard Widget API automatically makes your widget draggable, collapsible, and even adds your widget to the Screen Options tab so that users can easily hide it if they choose.

Figure 4.6. FIGURE 4-6

Now review the widget code in its entirety:

<?php
/*
Plugin Name: Dashboard Widget Example Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A plugin to create dashboard widgets in WordPress
Version: 1.0
Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2
*/

add_action( 'wp_dashboard_setup', 'boj_dashboard_example_widgets' );

function boj_dashboard_example_widgets() {

    //create a custom dashboard widget
    wp_add_dashboard_widget( 'dashboard_custom_feed',
        'My Plugin Information', 'boj_dashboard_example_display' );

}

function boj_dashboard_example_display()
{
    echo '<p>Please contact support@example.com to report bugs.</p>';
}
?>

Code snippet boj-dashboard-widget.php

Now that you understand dashboard widgets, you can create a more advanced widget that stores an option value. Dashboard widgets can store options, making them easily customizable by the user. If a dashboard widget has any options, you see a Configure link display when you hover over the widget title.

The dashboard widget in this example enables you to set a custom RSS feed URL and display the contents of that feed.

<?php
add_action( 'wp_dashboard_setup', 'boj_dashboard_example_widgets' );

function boj_dashboard_example_widgets() {

//create a custom dashboard widget
    wp_add_dashboard_widget( 'dashboard_custom_feed',
        'My Plugin Information', 'boj_dashboard_example_display',
        'boj_dashboard_example_setup' );

}
?>

Notice the wp_add_dashboard_widget() function has the fourth parameter set, in this example boj_dashboard_example_setup(), which is the control callback. This is the function that displays your widget setting field and saves the data entered as an option for your widget. Next you need to create the boj_dashboard_example_display() function to display the custom RSS feed in your widget.

<?php
function boj_dashboard_example_display()
{
    //load our widget option
    $boj_option = get_option( 'boj_dashboard_widget_rss ');

    //if option is empty set a default
    $boj_rss_feed = ( $boj_option ) ? $boj_option : 'http://wordpress.org/news/feed/';

    //retrieve the RSS feed and display it
    echo '<div class="rss-widget">';

    wp_widget_rss_output( array(
        'url' => $boj_rss_feed,
        'title' => 'RSS Feed News',
        'items' => 2,
        'show_summary' => 1,
        'show_author' => 0,
        'show_date' => 1
    ) );

    echo '</div>';
}
?>

The first two lines load the RSS feed saved as an option in the widget. Chapter 7, "Plugin Settings," covers plugin settings and options in more detail. Next the widget uses the wp_widget_rss_output() function to retrieve the RSS feed and display it. This handy little function is great for retrieving and displaying RSS feeds in WordPress. The widget defines the RSS URL, sets the title to RSS Feed News, sets the number of posts to show to 2, and includes a few other options.

Now that you have the widget display, you need to create the control callback function boj_dashboard_example_setup(). This function adds the form field to your widget and can also save the value entered by the user.

<?php
function boj_dashboard_example_setup() {

    //check if option is set before saving
    if ( isset( $_POST['boj_rss_feed'] ) ) {
        //retrieve the option value from the form
        $boj_rss_feed = esc_url_raw( $_POST['boj_rss_feed'] );

        //save the value as an option
        update_option( 'boj_dashboard_widget_rss', $boj_rss_feed );
    }

    //load the saved feed if it exists
    $boj_rss_feed = get_option( 'boj_dashboard_widget_rss ');

    ?>
    <label for="feed">
        RSS Feed URL: <input type="text" name="boj_rss_feed" id="boj_rss_feed"
            value="<?php echo esc_url( $boj_rss_feed ); ?>" size="50" />
    </label>
    <?php
}
?>

The first task the function handles is saving the widget option. You should always check to verify the POST value exists prior to saving it using the isset() PHP function. Next you set the value of $_POST['boj_rss_feed'] to the $boj_rss_feed variable. Notice how the POST value is escaped using esc_url_raw(). This verifies the value is a properly formatted URL and free from any illegal characters prior to saving the data. Finally, the widget option is saved using update_option().

Now that the widget option is saved, you need to display the widget form field so that your users can enter in the RSS feed URL they want displayed. First, retrieve the widget option from the database if it exists, so you can display it in the form field. Next create a simple text input named boj_rss_feed. Notice the value is set to $boj_rss_feed, which is storing the RSS feed URL value entered by the user.

You now have a custom dashboard widget that stores a custom RSS feed URL and displays the latest two posts to the user, as shown in Figure 4-7!

Figure 4.7. FIGURE 4-7

Now look at the full source for the custom RSS feed dashboard widget:

<?php
/*
Plugin Name: RSS Dashboard Widget Example Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A plugin to create dashboard widgets in WordPress
Version: 1.0
Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2
*/

add_action( 'wp_dashboard_setup', 'boj_dashboard_example_widgets' );

function boj_dashboard_example_widgets() {

    //create a custom dashboard widget
    wp_add_dashboard_widget( 'dashboard_custom_feed', 'My Plugin Information',
                'boj_dashboard_example_display', 'boj_dashboard_example_setup' );

}

function boj_dashboard_example_setup() {

    //check if option is set before saving
    if ( isset( $_POST['boj_rss_feed'] ) ) {
        //retrieve the option value from the form
        $boj_rss_feed = esc_url_raw( $_POST['boj_rss_feed'] );

        //save the value as an option
        update_option( 'boj_dashboard_widget_rss', $boj_rss_feed );
    }

     //load the saved feed if it exists
    $boj_rss_feed = get_option( 'boj_dashboard_widget_rss ');

    ?>
    <label for="feed">
        RSS Feed URL: <input type="text" name="boj_rss_feed" id="boj_rss_feed"
            value="<?php echo esc_url( $boj_rss_feed ); ?>" size="50" />
    </label>
    <?php
}

function boj_dashboard_example_display()
{
    //load our widget option
    $boj_option = get_option( 'boj_dashboard_widget_rss ');

    //if option is empty set a default
    $boj_rss_feed = ( $boj_option ) ? $boj_option : 'http://wordpress.org/news/feed/';

    //retrieve the RSS feed and display it

echo '<div class="rss-widget">';

    wp_widget_rss_output( array(
        'url' => $boj_rss_feed,
        'title' => 'RSS Feed News',
        'items' => 2,
        'show_summary' => 1,
        'show_author' => 0,
        'show_date' => 1
    ) );

    echo '</div>';
}
?>

Code snippet boj-rss-dashboard-widget.php

To create a custom meta box in WordPress, you use the add_meta_box() function. This function enables you to define all aspects of your meta box. Following is how this function is used:

<?php add_meta_box( id, title, callback, page, context, priority,
            callback_args ); ?>

The add_meta_box() function accepts the following parameters:

Now you can build a custom meta box for the post screen.

<?php
add_action( 'add_meta_boxes', 'boj_mbe_create' );

function boj_mbe_create() {

    add_meta_box( 'boj-meta', 'My Custom Meta Box', 'boj_mbe_function', 'post',
        'normal', 'high' );

}

function boj_mbe_function() {

    echo 'Welcome to my meta box!';

}
?>

In this example, you create a meta box on the post screen. You use the add_meta_boxes action hook to trigger your boj_mbe_create() function to add a new meta box. The meta box title is set to My Custom Meta Box; it calls the boj_mbe_function() for display. Also notice you set the context parameter to normal and the priority to high. This displays your meta box directly below the visual editor on your post screen, as shown in Figure 4-8.

The real power of meta boxes is saving data to a post, page, or any type of content in WordPress. Any data saved against your content is called metadata. In the WordPress edit screens, the meta box for custom fields exists by default. Custom fields are just a quick way to save metadata against your content. Chapter 11, "Extending Posts," covers metadata in more detail, but you need understand the concept to save data in your meta box.

Figure 4.8. FIGURE 4-8

In this example, you create a meta box on the post screen to save two fields of data against your post.

<?php
add_action( 'add_meta_boxes', 'boj_mbe_create' );

function boj_mbe_create() {

    //create a custom meta box
    add_meta_box( 'boj-meta', 'My Custom Meta Box', 'boj_mbe_function', 'post',
        'normal', 'high' );


}
?>

You need to initialize and create your meta box just as you did before. Now create the function to display the form fields.

<?php
function boj_mbe_function( $post ) {

    //retrieve the metadata values if they exist
    $boj_mbe_name = get_post_meta( $post->ID, '_boj_mbe_name', true );
    $boj_mbe_costume = get_post_meta( $post->ID, '_boj_mbe_costume', true );

    echo 'Please fill out the information below';
    ?>
    <p>Name: <input type="text" name="boj_mbe_name" value="
        <?php echo esc_attr( $boj_mbe_name ); ?>" /></p>
    <p>Costume:
    <select name="boj_mbe_costume">
        <option value="vampire" <?php selected( $boj_mbe_costume, 'vampire' ); ?>>
            Vampire
        </option>
        <option value="zombie" <?php selected( $boj_mbe_costume, 'zombie' ); ?>>
            Zombie
        </option>
        <option value="smurf" <?php selected( $boj_mbe_costume, 'smurf' ); ?>>
            Smurf
        </option>
    </select>
    </p>
    <?php

}
?>

The first thing you should notice is the $post object passed as a parameter to your custom function. This gives you access to all the post data available in the object, in this case the post ID, to use in your meta box.

Now you need to retrieve the two metadata values from WordPress if they exist. To do this use the get_post_meta() function. This function accepts three parameters.

If you create a new post, the two metadata values would not exist because they haven't been created yet. Next in the code, the two form fields display. The first is a text field for a name. Notice the value of the text field is set to $boj_mbe_name, the variable that stores the metadata value you retrieve, and is escaped using the esc_attr() function for security.

The second field in the form is an HTML <select> form field. This field has three options to choose as your costume: Vampire, Zombie, or Smurf. In the example, you use the selected() function to determine if the item is selected. The meta box form is now complete, and as you can see there is no need to add a Submit button or form tags. Using use the save_post action hook, the values are passed to your boj_mbe_save_meta() function as shown here.

<?php

//hook to save the meta box data
add_action( 'save_post', 'boj_mbe_save_meta' );

function boj_mbe_save_meta( $post_id ) {

    //verify the metadata is set
    if ( isset( $_POST['boj_mbe_name'] ) ) {

        //save the metadata
        update_post_meta( $post_id, '_boj_mbe_name',
            strip_tags( $_POST['boj_mbe_name'] ) );
        update_post_meta( $post_id, '_boj_mbe_costume',
            strip_tags( $_POST['boj_mbe_costume'] ) );

    }

}
?>

First use the add_action() function to trigger the save_post action hook, which will call your boj_mbe_save_meta() function when a post is saved. This function saves the data entered by the user in your meta box. Notice you pass the $post_id variable to your function as a parameter. The post ID is used when saving your metadata. It's always a good idea to verify the form field you want to work with is set prior to doing so, as shown using the isset() PHP function. Finally, the update_post_meta() function adds or updates the post meta entered in your meta box. This function accepts four parameters.

In this example you use only the first three parameters because the fourth is optional. You set the post ID, name of the metadata field, and the value entered in your custom meta box. The form values are sanitized using the strip_tags() function.

You have just successfully created a custom meta box that stores data in WordPress! Now review the full code for your plugin.

<?php
/*
Plugin Name: Meta Box Example Plugin
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: A plugin to create meta boxes in WordPress
Version: 1.0
Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2
*/

add_action( 'add_meta_box', 'boj_mbe_create' );

function boj_mbe_create() {

    //create a custom meta box
    add_meta_box( 'boj-meta', 'My Custom Meta Box', 'boj_mbe_function',
                'post', 'normal', 'high' );


}

function boj_mbe_function( $post ) {

    //retrieve the metadata values if they exist
    $boj_mbe_name = get_post_meta( $post->ID, '_boj_mbe_name', true );
    $boj_mbe_costume = get_post_meta( $post->ID, '_boj_mbe_costume', true );

    echo 'Please fill out the information below';
    ?>
    <p>Name: <input type="text" name="boj_mbe_name" value="
            <?php echo esc_attr( $boj_mbe_name ); ?>" /></p>
    <p>Costume:
    <select name="boj_mbe_costume">
        <option value="vampire" <?php selected( $boj_mbe_costume, 'vampire' ); ?>>
            Vampire
        </ option>
        <option value="zombie" <?php selected( $boj_mbe_costume, 'zombie' ); ?>>
            Zombie

</option>
        <option value="smurf" <?php selected( $boj_mbe_costume, 'smurf' ); ?>>
            Smurf
        </option>
    </ select>
    </p>
       <?php
}

//hook to save the meta box data
add_action( 'save_post', 'boj_mbe_save_meta' );

function boj_mbe_save_meta( $post_id ) {

    //verify the metadata is set
    if ( isset( $_POST['boj_mbe_name'] ) ) {

        //save the metadata
        update_post_meta( $post_id, '_boj_mbe_name',
                        strip_tags( $_POST['boj_mbe_name'] ) );
        update_post_meta( $post_id, '_boj_mbe_costume',
                        strip_tags( $_POST['boj_mbe_costume'] ) );

    }

}
?>

Code snippet boj-meta-box.php

Now that you understand how meta boxes work, you can build a more complex one. In this example, you create a custom meta box that enables the user to select an image from the WordPress Media Library and save the URL in the meta box.

First, you use the add_meta_boxes action hook as before to execute the custom function to create your meta box.

<?php
add_action( 'add_meta_boxes', 'boj_mbe_image_create' );

function boj_mbe_image_create() {

    //create a custom meta box
    add_meta_box( 'boj-image-meta', 'Set Image', 'boj_mbe_image_function',
        'post', 'normal', 'high' );


}
?>

Using the add_meta_box() function, you can define the settings for your custom meta box. In this case the meta box is named Set Image and calls the custom boj_mbe_image_function() function.

Now that the meta box has been created, you need to create the function to display meta box content.

<?php
function boj_mbe_image_function( $post ) {

    //retrieve the metadata value if it exists
    $boj_mbe_image = get_post_meta( $post->ID, '_boj_mbe_image', true );
    ?>
    Image <input id="boj_mbe_image" type="text" size="75"
        name="boj_mbe_image" value="<?php echo esc_url( $boj_mbe_image ); ?>" />
    <input id="upload_image_button" type="button"
        value="Media Library Image" class="button-secondary"  />
    <br /> Enter an image URL or use an image from the Media Library
    <?php

}
?>

The first step is to load the metadata value if it exists to the $boj_mbe_image variable. If this meta value has not been saved, it will be empty. Next display the text form field to enter and display the image URL. You also create a button that enables the user to select an image from the Media Library, as shown in Figure 4-9.

Figure 4.9. FIGURE 4-9

Now call the save_post action hook to execute your custom boj_mbe_image_save_meta() function to save the meta box data.

<?php

//hook to save the meta box data
add_action( 'save_post', 'boj_mbe_image_save_meta' );

function boj_mbe_image_save_meta( $post_id ) {

    //verify the metadata is set
    if ( isset( $_POST['boj_mbe_image'] ) ) {

        //save the metadata
        update_post_meta( $post_id, '_boj_mbe_image',
            esc_url_raw( $_POST['boj_mbe_image'] ) );

    }

}
?>

It's a good practice to verify the form field is set prior to retrieving the form field value. If the field is set, your function can use the update_post_meta() function to save the metadata to the post. Notice you're using the esc_url_raw() function to sanitize the URL. This can eliminate invalid characters, remove dangerous characters, and verify the URL has a proper protocol set (http, https, ftp, and so on).

Up to this point this is a fairly standard meta box plugin. Now is where the fun begins! To prompt for the Media Library overlay, you need to use some JavaScript. Create a new file named boj-meta-image.js. This file can contain the JavaScript code that inserts the image URL into your meta box text field when selected from the Media Library. Now review the code.

jQuery(document).ready(function($) {

    var formfield = null;

    $('#upload_image_button').click(function() {
        $('html').addClass('Image');
        formfield = $('#boj_mbe_image').attr('name');
        tb_show('', 'media-upload.php?type=image&TB_iframe=true');
        return false;
    });


    // user inserts file into post.
    //only run custom if user started process using the above process
    // window.send_to_editor(html) is how wp normally handle the received data

    window.original_send_to_editor = window.send_to_editor;
    window.send_to_editor = function(html){
        var fileurl;

        if (formfield != null) {
            fileurl = $('img',html).attr('src');

            $('#boj_mbe_image').val(fileurl);

            tb_remove();

            $('html').removeClass('Image');
            formfield = null;
        } else {
            window.original_send_to_editor(html);
        }
    };

});

Remember this is JavaScript code and cannot be surrounded by <?php ?> tags. First, the code opens the Media overlay when the upload_image_button is clicked, which is the name of the Submit button in your meta box. The second part of the code takes the image URL and inserts it into the image URL text field in your form, named boj_mbe_image.

Now that the JavaScript file is in place, you need to call this file from your plugin.

<?php
//script actions with page detection
add_action('admin_print_scripts-post.php', 'boj_mbe_image_admin_scripts');
add_action('admin_print_scripts-post-new.php', 'boj_mbe_image_admin_scripts');

function boj_mbe_image_admin_scripts() {

    wp_enqueue_script( 'boj-image-upload',
        plugins_url( '/boj-meta-box/boj-meta-image.js' ),
        array( 'jquery','media-upload','thickbox' )
    );

}
?>

Use the admin_print_scripts action hook to execute the custom function for including your JavaScript file. Notice how the action hook has -post.php and -post-new.php appended to the hook name. This is called page detection, so the hook calls only the custom boj_mbe_image_admin_scripts() function when the user is on the post.php or post-new.php pages in WordPress.

To insert your JavaScript fill to the header of the page, use the wp_enqueue_script() function. This is the proper way to include JavaScript files in the header of WordPress, which Chapter 12, "JavaScript and Ajax," covers in more detail.

The final step is to add the thickbox style using the wp_enqueue_styles() function.

<?php

//style actions with page detection
add_action('admin_print_styles-post.php', 'boj_mbe_image_admin_styles');
add_action('admin_print_styles-post-new.php', 'boj_mbe_image_admin_styles');

function boj_mbe_image_admin_styles() {
    wp_enqueue_style( 'thickbox' );
}
?>

This includes the thickbox style in the header of the page.

To set an image in your meta box, just click the Media Library Image button. Next select an image from the Media Library, and click the Insert into Post button. This inserts the image URL into your meta box form field. This happens only if the user clicks the Media Library Image button in your meta box.

Now review the full plugin code.

BOJ-META-BOX-IMAGE.PHP
<?php
/*
Plugin Name: Meta Box Media Library Image Example
Plugin URI: http://example.com/wordpress-plugins/my-plugin
Description: Adds the ability to select an image from the media library
Version: 1.0

Author: Brad Williams
Author URI: http://wrox.com
License: GPLv2
*/

add_action( 'admin_init', 'boj_mbe_image_create' );

function boj_mbe_image_create() {

    //create a custom meta box
    add_meta_box( 'boj-image-meta', 'Set Image', 'boj_mbe_image_function', 'post',
        'normal', 'high' );

}

function boj_mbe_image_function( $post ) {

    //retrieve the metadata value if it exists
    $boj_mbe_image = get_post_meta( $post->ID, '_boj_mbe_image', true );
    ?>
    Image <input id="boj_mbe_image" type="text" size="75" name="boj_mbe_image"
        value="<?php echo esc_url( $boj_mbe_image ); ?>" />
           <input id="upload_image_button" type="button"
               value="Media Library Image" class="button-secondary"  />
     <p>Enter an image URL or use an image from the Media Library</p>
     <?php
}

//script actions with page detection
add_action('admin_print_scripts-post.php', 'boj_mbe_image_admin_scripts');
add_action('admin_print_scripts-post-new.php', 'boj_mbe_image_admin_scripts');

function boj_mbe_image_admin_scripts() {
    wp_enqueue_script( 'boj-image-upload',
        plugins_url( '/boj-meta-box/boj-meta-image.js' ),
        array( 'jquery','media-upload','thickbox' ) );
}

//style actions with page detection
add_action('admin_print_styles-post.php', 'boj_mbe_image_admin_styles');
add_action('admin_print_styles-post-new.php', 'boj_mbe_image_admin_styles');

function boj_mbe_image_admin_styles() {
    wp_enqueue_style( 'thickbox' );
}


//hook to save the meta box data
add_action( 'save_post', 'boj_mbe_image_save_meta' );


function boj_mbe_image_save_meta( $post_id ) {

    //verify the metadata is set

if ( isset( $_POST['boj_mbe_image'] ) ) {

        //save the metadata
        update_post_meta( $post_id, '_boj_mbe_image',
            esc_url( $_POST['boj_mbe_image'] ) );

    }

}
?>

Code snippet boj-meta-box-image.zip

BOJ-META-IMAGE.JS
jQuery(document).ready(function($) {

    var formfield = null;

    $('#upload_image_button').click(function() {
        $('html').addClass('Image');
        formfield = $('#boj_mbe_image').attr('name');
        tb_show('', 'media-upload.php?type=image&TB_iframe=true');
        return false;
    });


    // user inserts file into post.
    // only run custom if user started process using the above process
    // window.send_to_editor(html) is how wp normally handle the received data

    window.original_send_to_editor = window.send_to_editor;
    window.send_to_editor = function(html){
        var fileurl;

        if (formfield != null) {
            fileurl = $('img',html).attr('src');

            $('#boj_mbe_image').val(fileurl);

            tb_remove();

            $('html').removeClass('Image');
            formfield = null;
        } else {
            window.original_send_to_editor(html);
        }
    };

});

Code snippet boj-meta-box-image.zip

The most important part of using the WordPress styles is to wrap your plugin in the class wrap div.

<div class="wrap">
    Plugin Page
</div>

This class sets the stage for all admin styling.

WordPress has custom styles available for all heading tags. Now look at how those heading tags display:

<?php
function boj_styling_settings() {
    ?>
    <div class="wrap">
        <h2>My Plugin</h2>
        <h3>My Plugin</h3>
        <h4>My Plugin</h4>
        <h5>My Plugin</h5>
        <h6>My Plugin</h6>
    </div>
    <?php
}
?>

Each heading is slightly smaller than the previous, as shown in Figure 4-10. Notice there is no <h1> tag defined. The <h1> tag is reserved for the name of your website displayed at the top of the admin dashboard. Because of this you should always use the <h2> tag for your primary heading.

Figure 4.10. FIGURE 4-10

WordPress features many different icons for each section head. These icons are also available for use in your plugins. For example, the dashboard header icon is a house icon.

<div id="icon-index" class="icon32"></div>
<div id="icon-edit" class="icon32"></div>
<div id="icon-upload" class="icon32"></div>
<div id="icon-link-manager" class="icon32"></div>
<div id="icon-edit-pages" class="icon32"></div>
<div id="icon-edit-comments" class="icon32"></div>
<div id="icon-themes" class="icon32"></div>
<div id="icon-plugins" class="icon32"></div>
<div id="icon-users" class="icon32"></div>
<div id="icon-tools" class="icon32"></div>
<div id="icon-options-general" class="icon32"></div>

These divs generate the icons shown in Figure 4-11.

Figure 4.11. FIGURE 4-11

Rather than hardcoding these values, WordPress features a function to generate the icon divs called screen_icon(). This function accepts one parameter, and that is the screen icon you want to load.

Now modify your boj_styling_settings() function to display an icon and header.

<?php
function boj_styling_settings() {
    ?>
    <div class="wrap">
        <?php screen_icon( 'plugins' ); ?>
        <h2>My Plugin</h2>
    </div>
    <?php
}
?>
x

Now your plugin has a clean header and uses the Plug icon.

When an action occurs in your plugin, such as saving settings, it's important to display a message to the user verifying whether the update was successful. WordPress features some different styles for displaying these messages.

<?php
function boj_styling_settings() {
    ?>
    <div class="wrap">
        <h2>My Plugin</h2>
        <div id="message" class="updated">Settings saved successfully</div>
        <div id="message" class="error">Error saving settings</div>
    </div>
    <?php
}
?>

These styles will generate the messages shown in Figure 4-12.

Figure 4.12. FIGURE 4-12

When adding buttons to your form, you can take advantage of multiple classes. The first two you use are the button-primary and button-secondary classes. These classes style your buttons to match the WordPress UI.

<p>
<input type="submit" name="Save" value="Save Options" />
<input type="submit" name="Save" value="Save Options" class="button-primary" />
</p><p>
<input type="submit" name="Secondary" value="Secondary Button" />
<input type="submit" name="Secondary" value="Secondary Button"
    class="button-secondary" />
</p>

This example demonstrates a standard unstyled button as compared to the WordPress styled button. As you can tell, the WordPress-styled button looks familiar and uses the proper styling, as shown in Figure 4-13.

Figure 4.13. FIGURE 4-13

You can also use the button-highlighted class to put an emphasis on a particular button.

<input type="submit" name="secondary" value="Secondary Button"
    class="button-secondary" />
<input type="submit" name="highlighted" value="Button Highlighted"
    class="button-highlighted" />

The button is now bold and stands out more than a normal Secondary button, as shown in Figure 4-14. This is useful if you want to focus the users' attention on a button.

Links can also take the form of a button by using the appropriate class.

Figure 4.14. FIGURE 4-14

<a href="#">Search</a>
<a href='#' class='button-secondary'>Search</a>
<a href='#' class='button-highlighted'>Search</a>
<a href='#' class='button-primary'>Search</a>

This example shows how a standard <a href> link can be styled to look like a button, as shown in Figure 4-15. To normal users they would never know these are regular text links because they look just like a button.

Figure 4.15. FIGURE 4-15

Links inside the wrap class automatically assume the standard WordPress admin link style. However, you can modify the default styling in different ways.

<div class="wrap">
    <?php screen_icon( 'plugins' ); ?>     <h2>My Plugin</h2>
    <h2><a href="#">Testing Link</a></h2>
    <h3><a href="#">Testing Link</a></h3>
    <h4><a href="#">Testing Link</a></h4>
    <h5><a href="#">Testing Link</a></h5>
    <a href="#">Testing Link</a>
</div>

Wrapping any link in a heading tag enables you to adjust the size of the link, as shown in Figure 4-16.

Figure 4.16. FIGURE 4-16

WordPress has a special table class just for forms called form-table. This class is used on all WordPress admin dashboard forms, including every Settings page. This is a useful class when creating any type of options in your plugin.

<div class="wrap">
        <?php screen_icon( 'plugins' ); ?>
        <h2>My Plugin</h2>
        <form method="POST" action="">
        <table class="form-table">
        <tr valign="top">
            <th scope="row"><label for="fname">First Name</label></th>
            <td><input maxlength="45" size="25" name="fname" /></td>
        </tr>
        <tr valign="top">
            <th scope="row"><label for="lname">Last Name</label></th>
            <td><input id="lname" maxlength="45" size="25" name="lname" /></td>
        </tr>
        <tr valign="top">
            <th scope="row"><label for="color">Favorite Color</label></th>
            <td>
                <select name="color">
                    <option value="orange">Orange</option>
                    <option value="black">Black</option>
                </ select>
            </td>
        </tr>

<tr valign="top">
            <th scope="row"><label for="featured">Featured?</label></th>
            <td><input type="checkbox" name="favorite" /></td>
        </tr>
        <tr valign="top">
            <th scope="row"><label for="gender">Gender</label></th>
            <td>
                <input type="radio" name="gender" value="male" /> Male
                <input type="radio" name="gender" value="female" /> Female
            </td>
        </tr>
        <tr valign="top">
            <th scope="row"><label for="bio">Bio</label></th>
            <td><textarea name="bio"></textarea></td>
        </tr>
        <tr valign="top">
            <td>
            <input type="submit" name="save" value="Save Options"
                class="button-primary" />
            <input type="submit" name="reset" value="Reset"
                class="button-secondary" />
            </td>
        </tr>
        </table>
        </form>
    </div>

Using the form-table can give your options a familiar look to your plugin users. This makes for a better user experience, as shown in Figure 4-17.

Figure 4.17. FIGURE 4-17

HTML tables are a great way to display rows and columns of data in an easy-to-read layout. Tables can easily be styled in WordPress using the widefat class.

<table class="widefat">
<thead>
    <tr>
        <th>Name</th>
        <th>Favorite Holiday</th>
    </tr>
</thead>
<tfoot>
    <tr>
        <th>Name</th>
        <th>Favorite Holiday</th>
    </tr>
</tfoot>
<tbody>
    <tr>

<td>Brad Williams</td>
        <td>Halloween</td>
    </tr>
    <tr>
        <td>Ozh Richard</td>
        <td>Talk Like a Pirate</td>
    </tr>
    <tr>
        <td>Justin Tadlock</td>
        <td>Christmas</td>
    </tr>
</tbody>
</table>

The widefat class has specific styles set for the thead and tfoot HTML tags. This styles the header and footer of your table to match all other tables on the admin dashboard. The class can also style all table data, as shown in Figure 4-18.

Figure 4.18. FIGURE 4-18

If your plugin contains a list of records, you may have a need for pagination, which is the method to break lists of data into multiple pages and have links to load each individual page. This helps reduce the load times and makes it a much cleaner user experience to navigate through the data. Would you rather view 500 records on a page or 10 pages with 50 records on each page?

WordPress has a few different classes to style your pagination. Following is an example.

<div class="tablenav">
    <div class="tablenav-pages">
        <span class="displaying-num">Displaying 1-20 of 69</span>
        <span class="page-numbers current">1</span>
        <a href="#" class="page-numbers">2</a>
        <a href="#" class="page-numbers">3</a>
        <a href="#" class="page-numbers">4</a>
        <a href="#" class="next page-numbers">&raquo;</a>
    </div>
</div>

First, you need to wrap your pagination links in the tablenav and tablenav-pages div classes. The displaying-num class styles the records you view. The page-numbers class styles the page links in the familiar WordPress format. Adding current or next to the link class can add some unique styles to those elements, as shown in Figure 4-19.

Figure 4.19. FIGURE 4-19

Keeping your plugin design consistent with the WordPress user interface can reduce your plugins' learning curve because users will feel comfortable with the design and styles used. This can also make your plugins' design future-proof. If the WordPress core styles change down the road, your plugins' design will also change to match the new user interface, and you won't need to edit a single line of code!

Internationalizing your plugin can benefit both you and your plugin users. Compared to the more complex functionality you'll likely use when developing a plugin, internationalization will seem much easier after you follow the guidelines set out in this chapter.

Some plugin authors even develop relationships with translators of their plugins after working closely together to get a translation done. Forming relationships with new people is always a benefit of working on open source projects, and by internationalizing your plugin, you open the door for more possibilities than with plugins that aren't internationalized.

Generally, when preparing your plugin for translation, you would do so if it is intended for public release because many of your users may run sites in languages other than your own.

Not all plugins are for use by the public. When performing custom client development, it's not always necessary to follow the steps outlined in this chapter. If your client's site is only in a single language, there might not be a need for translation. However, some clients run multilingual sites and may use a multilingual plugin that enables their content to be read in several languages. In this case, your plugin should be internationalized. You should always check with your client to see if internationalization is a requirement.

Although it's not always necessary to internationalize text for client work, it is considered best practice to internationalize all text. It saves you from potentially having to recode it for translation later if the client changes their mind about needing translatable text, and it's always good to stick to best practices when coding.

Also, a potential benefit to learning the tools in this chapter is having an extra bullet point on your resume for clients in need of this skill.

The first step to make your plugin translatable is to use the load_plugin_textdomain() function. This function tells WordPress to load a translation file if it exists for the user's language.

<?php
load_plugin_textdomain( $domain, $abs_rel_path, $plugin_rel_path );
?>

If you were creating a plugin with a folder name of boj-plugin, your code would like this:

<?php
load_plugin_textdomain( 'boj-plugin', false, 'boj-plugin/languages' );
?>

Here, the $domain is boj-plugin to match the plugin folder name, the $abs_rel_path has a value of false because it's unneeded, and the $plugin_rel_path has a value of boj-plugin/languages because this is where you store translation files.

The last parameter is the directory of the plugin (boj-plugin) and a subdirectory of the plugin (languages). It's good practice to create an extra folder in your plugin called languages to house any translations for your plugin. If you ever get more than a handful of translations, you'll want this folder because placing all those files in the top directory of your plugin can get messy.

WordPress has many useful functions for making internationalization easy. Every time you add textual content in your plugin, you should wrap it in one of the WordPress translation functions.

Nearly each of these functions has at least one variable that you'll use: $domain. This is the unique variable used in the "Getting Your Plugin Ready for Translation" section: boj-plugin. The value of this variable enables WordPress to recognize it as a part of your plugin's translation files.

When viewing the core WordPress files, you'll likely notice that $domain is never set. WordPress uses the default, so your plugin should have a unique string to set it apart from the core.

<?php

$text = __( 'WordPress is a wonderful publishing platform.', 'boj-plugin' );

?>

<?php

/* Hook our message function to the footer. */
add_action( 'wp_footer', 'boj_footer_message' );

/* Function that outputs a message in the footer of the site. */
function boj_footer_message() {

    /* Output the translated text. */
    _e( 'This site runs off the coolest platform ever &mdash; WordPress.',
    'boj-plugin' );
}

?>

<?php

/* A function that returns a link to the site's terms of service page. */
function boj_terms_of_service_link() {
    return '<a href="http://example.com/tos" title="' .
    esc_attr__( 'Visit the Terms of Service page', 'boj-plugin' ) . '">' .
    __( 'Terms of Service', 'boj-plugin' ) . '</a>';
}

/* Display the output of the boj_terms_of_service_link() function. */
echo boj_terms_of_service_link();

?>

<a href="<?php echo admin_url( 'dashboard.php' ); ?>"
title="<?php esc_attr_e( 'Visit the WordPress dashboard', 'boj-plugin' ); ?>">
<?php _e( 'Dashboard', 'boj-plugin' ); ?></a>

<?php

function boj_get_text_message() {

    /* If the user input any text, escape it. */
    if ( !empty( $_POST['boj-text'] ) )
        $message = esc_html( $_POST['boj-text'] );

    /* If no text was input, use a default, translated message. */
    else
        $message = esc_html__( 'No message input by the user.', 'boj-plugin' );

    return $message;
}

?>

<textarea name="boj-text" id="boj-text">
    <?php esc_html_e( 'Please input a description.', 'boj-plugin' ); ?>
</textarea>

<?php

add_action( 'admin_menu', 'boj_add_seo_meta_box' );

function boj_add_seo_meta_box() {
    add_meta_box(
        'boj_seo_meta_box',
        _x( 'SEO', 'meta box, 'boj-plugin' ),
        'boj_seo_meta_box_callback',
        'post',
        'advanced'
    );
}

function boj_seo_meta_box_callback() {
    _e( 'An example meta box.', 'boj-plugin' );
}

?>

<?php

/* Displaying "Post" as a noun. */
_ex( 'Post', 'noun', 'boj-plugin' );

/* Displaying "Post" as a verb. */
_ex( 'Post', 'verb', 'boj-plugin' );

?>

<?php

_e( 'Select a post', 'boj-plugin' );

_e( 'Submit post', 'boj-plugin' );

?>

<?php

function boj_plugin_display_post_link( $post_id ) {

    /* The text for the link. */
    $boj_link_text = _x(
        'Admin',
        'admin link',
        'boj-plugin'
    );

/* The text for the "title" attribute of the link. */
    $boj_link_title = esc_attr_x(
        'Admin',
        'admin link',
        'boj-plugin'
    );

    /* Display the link on the screen. */
    echo '<a href="' . admin_url( 'dashboard.php' ) . '"
    title="' . $boj_link_title . '">' . $boj_link_text . '</a>';
}

?>

<?php

function boj_get_favorite_food() {

    /* If the user input a favorite food. */
    if ( !empty( $_POST['favorite-food'] ) )
        $boj_favorite_food = esc_html( $_POST['favorite-food'] );

    /* If no favorite food was chosen, set a default. */
    else {
        $boj_favorite_food = esc_html_x(
            'None',
            'favorite item',
            'boj-plugin'
        );
    }

    return $boj_favorite_food;
}

?>

<?php

function boj_count_published_posts() {

    /* Count the number of posts. */
    $boj_count_posts = wp_count_posts();

    /* Get the count for the number of posts with a post_status of 'publish'. */
    $count = $boj_count_posts->publish;

    /* Display a sentence, letting the user know how many posts are published. */
    printf( _n(
        'You have published %s post.', 'You have published %s posts.',
        $count,
        'boj-plugin' ),
    $count );
}

?>

<?php

function boj_list_post_tag_counts() {

    /* Get all post tags in an alphabetical list. */
    $tags = get_terms( 'post_tag', array( 'orderby' => 'name', 'order' => 'ASC' ) );

    /* Open unordered list. */
    echo '<ul>';

    /* Loop through each post tag and display its post count and name. */
    foreach ( $tags as $tag ) {
        echo '<li>';
        printf(
            _nx(
                '%s post',
                '%s posts',
                $tag->count,
                'post count',
                'boj-plugin'
            ),
            $tag->count
        );
        echo '</li>';
    }

    /* Close unordered list. */
    echo '</ul>';
}

?>

<?php

function boj_count_posts_of_cusboj_types( $post_type = 'video' ) {

    /* Get a count of all posts of the given post type. */
    $all_posts = wp_count_posts( $post_type );

/* Get the count of the published posts. */
    $count = $all_posts->publish;

    /* Prepare an array of messages. */
    $boj_messages = array(
        'video' => _n_noop( 'You have %s video.', 'You have %s videos.' ),
        'music' => _n_noop( 'You have %s music file.', 'You have %s music files.' )
    );

    /* Get the message for the custom post type given. */
    $boj_message = $boj_messages[$post_type];

    /* Print the message for the custom post type given and its count. */

    printf( _n(
        $boj_message['singular'],
        $boj_message['plural'],
        $count
    ), $count );
}

?>

<?php

function boj_count_posts_of_custom_types( $post_type = 'video' ) {

    /* Get a count of all posts of the given post type. */
    $all_posts = wp_count_posts( $post_type );

    /* Get the count of the published posts. */
    $count = $all_posts->publish;

    /* Prepare an array of messages. */
    $boj_messages = array(
        'video' => _n_noop(
            '%s video',
            '%s videos',
            'post count'
        ),

'music' => _n_noop(
            '%s music file',
            '%s music files',
            'post count'
        )
    );

    /* Get the message for the custom post type given. */
    $boj_message = $boj_messages[$post_type];

    /* Print the message for the custom post type given and its count. */
    printf( _n(
        $boj_message['singular'],
        $boj_message['plural'],
        $count
    ), $count );
}

?>

You may have noticed the use of symbols such as %s and %1$s in previous examples. These are placeholders for variables. Placeholders are useful because they enable you to translate strings without breaking them apart.

The translation functions in WordPress cannot output placeholders on their own. The placeholders are merely there for translators to properly set within the text of their translation files. Placeholders must be converted to a given variable in PHP.

The printf() and sprintf() PHP functions are useful when using placeholders. Both functions can replace the placeholder with a given variable. Use printf() to print text to the screen and sprintf() to return text. Each function takes in a first parameter of $text, which is the text you're translating. Both can then receive any number of extra parameters that represent the placeholders in the $text variable.

Now take a look at an example of a translated sentence that works in English but breaks in many other languages.

<?php
function boj_display_blog_name() {
    _e( 'The name of your blog is ', 'boj-plugin' );
    echo get_bloginfo( 'name' );
    _e( '.', 'boj-plugin' );
}
?>

Although the text in that function is internationalized, it's not done in a way that's easily translatable. This is where placeholders come in. They enable you to set a variable in the text and keep it as one sentence.

Now rewrite that function in a way that makes it easier for translators to translate. Use printf() to print the sentence to the screen and convert the placeholders.

<?php
function boj_display_blog_name() {
    printf(
        __( 'The name of your blog is %s.', 'boj-plugin' ),
        get_bloginfo( 'name' )
    );
}?>

Now create a function that returns the tagline of the site in a sentence using the sprintf() function.

<?php
function boj_get_blog_tagline() {
    return sprint(
        __( 'The tagline of your site is %s.', 'boj-plugin' ),
        get_bloginfo('description' )
    );
}
?>

Sometimes you need multiple placeholders in one text string. Luckily, both printf() and sprintf() handle this wonderfully. The big difference here is that you shouldn't use %s. It's best to use numbered placeholders instead because the order of words in other languages may be different than your own.

In the following example, you use multiple placeholders to display a sentence depending on the number of posts published on the blog, along with the blog title.

<?php

function boj_display_blog_name_and_post_count() {

    /* Get the number of posts. */
    $count_posts = wp_count_posts();

    /* Get the number of published posts. */
    $count = $count_posts->publish;

    /* Get the site name. */
    $site_name = get_bloginfo( 'name' );

    /* Display a sentence based on the number of posts published. */
    printf(
        _n(
            'There is %1$s post published on %2$s.',
            'There are %1$s posts published on %2$s.',
            $count,
            'boj-plugin'
        ),
        $count, $site_name
    );
}

?>

In the example function, the %1$s placeholder represents the $count variable, which returns the number of published posts. The %2$s placeholder represents the value of $site_name, which was set to the name of the site.

Some plugins require JavaScript to function properly (see Chapter 12, "JavaScript and AJAX"). Because the internationalization functions in WordPress are written in PHP, you can't use them inside of JavaScript files. This makes it a little tougher to translate but not impossible.

WordPress provides a function called wp_localize_script() that enables you to pass translated text to an external file. You can then use the translated strings within your JavaScript. Take a look at what this function looks like.

<?php
wp_localize_script( $handle, $object_name, $l10n );
?>

To understand how all this comes together, you need to create a plugin that uses JavaScript. You use a simple script here. To delve more into the process of using JavaScript, read the thorough explanation in Chapter 12. Your plugin will add two input buttons to the site's footer. When either of the buttons is clicked, a translated message appears.

The first step is to create a new plugin folder called boj-alert-box and place a new PHP file called boj-alert-box.php in this folder. In the boj-alert-box.php file, add your plugin information (Chapter 2, "Plugin Foundation").

<?php
/**
 * Plugin Name: BOJ Alert Box
 * Plugin URI: http://example.com
 * Description: A plugin example that places two input buttons in the blog footer
   that when clicked display an alert box.
 * Version: 0.1
 * Author: WROX
 * Author URI: http://wrox.com
 */

Code snippet boj-alert-box.php

Next, you need to load your translation as described in the "Getting Your Plugin Ready for Translation" section.

/* Add the translation function after the plugins loaded hook. */
add_action( 'plugins_loaded', 'boj_alert_box_load_translation' );

/**
 * Loads a translation file if the paged being viewed isn't in the admin.
 *
 * @since 0.1
 */
function boj_alert_box_load_translation() {

    /* If we're not in the admin, load any translation of our plugin. */
    if ( !is_admin() )
       load_plugin_textdomain( 'boj-alert-box', false, 'boj-alert-box/languages' );
}

Code snippet boj-alert-box.php

At this point, you need to load your script using the wp_enqueue_script() function. After calling that function, you can localize your script using the wp_localize_script() function. It is important that this function is called after the script has been registered because the $handle variable has to be set.

/* Add our script function to the print scripts action. */
add_action( 'wp_print_scripts', 'boj_alert_box_load_script' );

/**
 * Loads the alert box script and localizes text strings that need translation.
 *
 * @since 0.1
 */
function boj_alert_box_load_script() {

    /* If we're in the WordPress admin, don't go any farther. */
    if ( is_admin() )
        return;

    /* Get script path and file name. */
    $script = trailingslashit( plugins_url( 'boj-alert-box' ) ) .
    'boj-alert-box-script.js';

    /* Enqueue our script for use. */
    wp_enqueue_script( 'boj-alert-box', $script, false, 0.1 );

    /* Localize text strings used in the JavaScript file. */
    wp_localize_script( 'boj-alert-box', 'boj_alert_box_L10n', array(
        'boj_box_1' => __( 'Alert boxes are annoying!', 'boj-alert-box' ),
        'boj_box_2' => __( 'They are really annoying!', 'boj-alert-box' ),
    ) );
}

Code snippet boj-alert-box.php

Now you add a couple of fun input buttons to the footer of the site. Notice the use of the esc_attr__() function from earlier in the chapter to translate and escape the value attributes of the buttons.

/* Add our alert box buttons to the site footer. */
add_action( 'wp_footer', 'boj_alert_box_display_buttons' );

/**
 * Displays two input buttons with a paragraph.  Each button has an onClick()
 * event that loads a JavaScript alert box.
 *
 * @since 0.1
 */
function boj_alert_box_display_buttons() {

    /* Get the HTML for the first input button. */
    $boj_alert_box_buttons = '<input type="button" onclick="boj_show_alert_box_1()"
    value="' . esc_attr__( 'Press me!', 'boj-alert-box' ) . '" />';

    /* Get the HTML for the second input button. */
    $boj_alert_box_buttons .= '<input type="button" onclick="boj_show_alert_box_2()"
    value="' . esc_attr__( 'Now press me!', 'boj-alert-box' ) . '" />';

    /* Wrap the buttons in a paragraph tag. */
    echo '<p>' . $boj_alert_box_buttons . '</p>';
}

?>

Code snippet boj-alert-box.php

Your plugin's PHP file is complete. You now need to add a JavaScript file called boj-alert-box-script.js to your plugin folder. After it's created, you can add two functions for displaying the alert boxes on screen. Within the boj-alert-box-script.js file, add the JavaScript.

/**
 * Displays an alert box with our first translated message when called.
 */
function boj_show_alert_box_1() {
    alert( boj_alert_box_L10n.boj_box_1 );
}

/**
 * Displays an alert box with our second translated message when called.
 */
function boj_show_alert_box_2() {
    alert( boj_alert_box_L10n.boj_box_2 );
}

Code snippet boj-alert-box-script.js

Because you're working across multiple files, it may be hard to see how the files interact with one another.

The two most important parameters from the call to wp_localize_script() are the $object_name and $l10n parameters. In the example plugin, you specifically set $object_name to boj_alert_box_L10n and $l10n to an array of key/value pairs.

When needing a translation in the JavaScript file, you used $object_name.$l10n[$key]. In the JavaScript function for the first alert box, this looks like this:

alert( boj_alert_box_L10n.boj_box_2 );

When translators create translations of your plugin, they use your plugin's POT file to create two files: boj-alert-box-$locale.mo and boj-alert-box-$locale.po.

boj-alert-box is the $domain parameter used in the translation functions throughout the plugin. $locale is a variable that represents the language and regional dialect. For example, WordPress uses en_US as its default language. en represents English, and US represents the region.

The PO file is the file used by translation tools to allow for human-readable text. Translators work with this file to provide a translation. The PO file isn't necessary to run a translation of your plugin, but it's always nice to package it with your plugin download for use by other users that may want to update any text to suit their needs.

The MO file is created from the finished translation. WordPress uses it to translate internationalized text strings from your plugin.

WordPress users set their locale in their wp-config.php file. This tells WordPress to look for any translations with that locale and load them. If users set their locale to fr_FR (French), WordPress would load a file called boj-alert-box-fr_FR.mo if it existed in your plugin.

Many translation tools around the Web are open source and free to download. Each tool isn't covered in detail here because they all have different ways to create translations. However, there is a list of supported translation tools for WordPress.

Following are available tools for translation:

One of the most common tools for plugin developers is Poedit. It has a simple, point-and-click interface that enables developers to create a POT file from their plugin.

GlotPress is a new Web-based tool from the people behind the WordPress project that promises to enable a single person or a team to work on translating software. It is now being used to facilitate the translation process for the WordPress software at http://translate.wordpress.org.

Using Poedit from the "Translating Tools" section, you can create a POT file. You need to input only a few pieces of information, and Poedit does the rest for you.

Figure 5.1. FIGURE 5-1

After you complete this process, Poedit synchronizes your POT file with your plugin, and you will have completed the process of preparing your plugin for translation.

Many plugins add translation files in the top level of their plugin folder. Although translations will work when using this method, it can get a bit messy and is discouraged. If you have a plugin with many other files, it may become much too unorganized if you take this route.

For the cleanest, most organized system, create an extra directory in your plugin folder called languages. When you release your plugin, you can store your default translation files in this folder. When translators send you translation files for your plugin, you simply drop those files in the languages folder. Be sure to add both the PO file (for translators) and MO file (for WordPress) of the translation you're given.

Making your plugin secure is dealing with vulnerabilities and data integrity and reliability. It's both preventing malicious attacks and making sure legitimate use cannot produce unexpected behavior.

In WordPress' environment, securing your plugin is not a difficult task, nor is it cumbersome or time consuming: WordPress implements several functions to address the various potential issues.

The usage of current_user_can() is straightforward: You either check if a user has a capability or a role before proceeding to a sensitive action, or die with a meaningful message. For example:

<?php

// Capability:
if ( !current_user_can('install_plugins') )
    wp_die( 'Insufficient permissions' );

// Role:
if( !current_user_can('editor') )
    wp_die( 'You cannot edit this setting' );
?>

You can either use default roles and capabilities or create custom ones. You learn how to do this in Chapter 8, which is devoted to user management.

The function current_user_can() depends on get_currentuserinfo(), which has a particularity: It is a pluggable function. Pluggable functions can be replaced by plugins: They can be found in file wp-includes/pluggable.php, which is loaded after active plugins.

Because of this particularity you cannot check user permissions at plugin loading and instead will need to wait until WordPress has fully started and instantiated (for instance, after the action 'init').

For example, picture a plugin that outputs debug information when you append ?debug=1 to any URL of the blog, but only if the user is an administrator.

The debug output function here prints out all SQL queries that WordPress ran, provided that the constant SAVEQUERIES is set to true:

<?php
// Print debug information
function boj_debug_output() {
    global $wpdb;
    echo "<pre>";
    print_r($wpdb->queries);
    echo "</pre>";
}
?>

Now how can you make this function dependant on the query parameter debug=1?

The worst way to do so would be the following:

<?php
if( isset( $_GET['debug'] ) )
    boj_debug_output();
?>

This is bad practice because debug information can potentially reveal sensitive information such as physical paths or table names, and with such a conditional test, anyone would see them by simply adding ?debug=1 to any URL of the site.

Because you want to restrict the debug data to the administrator of the blog, you need to code a more evolved condition:

<?php
if( isset( $_GET['debug'] ) && current_user_can( 'manage_options' ) )
    boj_debug_output();
?>

But this won't work: Remember, when the plugin is loaded and the server parses and compiles its code, pluggable functions are not in memory yet. What you need to do is to hook this check to an action that occurs only when everything is loaded.

Following is the complete plugin:

<?php
/*
Plugin Name: Simple Debug
Plugin URI: http://example.com/
Description: Append ?debug=1 to display debug info if you are an admin
Author: WROX
Author URI: http://wrox.com
*/

add_action( 'init', 'boj_debug_check' );

function boj_debug_check() {
    if( isset( $_GET['debug'] ) && current_user_can( 'manage_options' ) ) {
        if( !defined( 'SAVEQUERIES' ) )
            define( 'SAVEQUERIES', true );
        add_action( 'wp_footer', 'boj_debug_output' );
    }
}

// Print debug information
function boj_debug_output() {
    global $wpdb;
    echo "<pre>";
    print_r($wpdb->queries);
    echo "</pre>";
}
?>

Code snippet plugin-simple-debug.php

When you are logged into your WordPress install, you can click links that perform various actions, such as delete a post, update plugin settings, or create a category. Before proceeding, all these operations should verify that you are actually logged in and have sufficient permission, using the function current_user_can(). They verify that you have authority.

Now imagine people maliciously crafting a link that would delete a post on your blog. They could not use it themselves, of course, because they have no admin account on your blog and thus, no authority. But what if they trick you into clicking on this link? Because you are logged in, the action would occur, and the post would be deleted. You had authority but no intention. The malicious users just completed a Cross Site Request Forgery, or CSRF.

Of course, WordPress has a built-in solution to prevent these attacks.

In computer language, a nonce, or cryptographic nonce, is the abbreviation of "number used once." In WordPress, it is a short and apparently random string such as a password, which is specific to the following:

For example, the link to delete the post #43 in your WordPress blog could be something such as http://example.com/wp-admin/post.php?post=43&action=trash&_wpnonce=83a08fcbc2. The nonce, here 83a08fcbc2, is valid for only 24 hours, only if used by you and only to delete post #43. When you click that link, WordPress verifies that this nonce meets all these specifications before actually deleting the link.

Figure 6.2. FIGURE 6-2

More important, a nonce cannot be guessed by a malicious user, and loading a link without the correct nonce goes nowhere, as shown in Figure 6-2, which shows the result of trying to activate a plugin without knowing the valid nonce.

WordPress employs two different functions to create nonces in forms, as hidden fields, or in URLs, as a GET parameter.

To become acquainted with nonces, you can code a useful plugin to enhance WordPress native tag management features. This plugin identifies post tags not used in any post and enables you to either rename or delete them. Call this plugin Unused Tags and use the prefix boj_utags.

<?php
$url = wp_nonce_url( $url, $action );
?>

<?php

$delete_url = add_query_arg( array('boj_action'=>'delete','id'=>$id) );
$nonced_url = wp_nonce_url( $delete_url, 'boj_utags-delete_tag'.$id );
?>
<a href="<?php echo $nonced_url; ?>">delete</a> this tag

<form action="" method="post">
    <?php wp_nonce_field( 'boj_utags-rename_tag'.$id ); ?>
    <input type="hidden" name="boj_action" value="rename" />
    <input type="hidden" name="id" value="<?php echo $id; ?>" />
    <input type="text" name="name" value="<?php echo esc_attr($name); ?>" />
    <input type="submit" value="Rename" />
</form>

<?php

if( !current_user_can( 'manage_options' ) )
    wp_die( 'Insufficient privileges!' );

$id     = $_REQUEST['id'];
$action = $_REQUEST['boj_action'];

check_admin_referer( 'boj_utags-'.$action.'_tag'.$id );

switch( $action ) {
    case 'rename':
        $newtag = array( 'name' => $_POST['name'], 'slug' => $_POST['name'] );
        wp_update_term( $id, 'post_tag', $newtag );
        break;
    case 'delete':
        wp_delete_term( $id, 'post_tag' );
        break;
}
?>

Wrapping It Up: The Entire "Unused Tags" Plugin

To be fully operational, your plugin now needs a proper plugin header, a complete administration page with a new entry in the menu, and of course the function that lists the unused tags.

<?php
/*
Plugin Name: Unused Tags
Plugin URI: http://example.com/
Description: Find unused tags and rename or delete them
Author: WROX
Author URI: http://wrox.com
*/

// Add an entry for our option page to the Posts menu
add_action('admin_menu', 'boj_utags_add_page');
function boj_utags_add_page() {
    add_posts_page( 'Unused Tags', 'Unused Tags', 'manage_options',
        'boj_utags', 'boj_utags_option_page' );
}

// Catch any boj_action parameter in query string
add_action( 'admin_init', 'boj_utags_do_action' );

// Proceed to requested boj_action if applicable
function boj_utags_do_action() {
    if( !isset( $_REQUEST['boj_action'] ) )
        return;

    if( !current_user_can( 'manage_options' ) )
        wp_die( 'Insufficient privileges!' );

    $id     = $_REQUEST['id'];
    $action = $_REQUEST['boj_action'];

    if( $action == 'done' ) {
        add_action( 'admin_notices', 'boj_utags_message' );
        return;
    }

    check_admin_referer( 'boj_utags-'.$action.'_tag'.$id );

    switch( $action ) {
        case 'rename':
            $newtag = array( 'name' => $_POST['name'], 'slug' => $_POST['name'] );
            wp_update_term( $id, 'post_tag', $newtag );
            break;
        case 'delete':
            wp_delete_term( $id, 'post_tag' );

break;
    }

    wp_redirect( add_query_arg( array( 'boj_action' => 'done' ) ) );

}

// Admin notice
function boj_utags_message() {
    echo "<div class='updated'><p>Action completed</p></div>";
}

// Draw the tag management page
function boj_utags_option_page() {
    ?>
    <div class="wrap">
        <?php screen_icon(); ?>
        <h2>Unused Tags</h2>

        <?php

        if( $tags = boj_utags_find_orphans() ):

        echo '<p>You currently have '.count( $tags ). ' unused tags:</p>';
        echo '<ol>';

        foreach( $tags as $tag ) {
            $id   = $tag->term_id;
            $name = esc_attr( $tag->name );

            $delete_url= add_query_arg( array('boj_action'=>'delete','id'=>$id) );
            $nonced_url= wp_nonce_url( $delete_url, 'boj_utags-delete_tag'.$id );
            ?>
            <li>
            <form action="" method="post">
            <?php wp_nonce_field( 'boj_utags-rename_tag'.$id ); ?>
            <input type="hidden" name="boj_action" value="rename" />
            <input type="hidden" name="id" value="<?php echo $id; ?>" />
            <input type="text" name="name" value="<?php echo $name; ?>" />
            <input type="submit" value="Rename" /> or
            <a href="<?php echo $nonced_url; ?>">delete</a> this tag
            </form>
            </li>

        <?php }

        else: ?>
        <p>You have no unused tags.</p>

        <?php endif; ?>

        </ol>
    </div>

<?php
}

// Find unused tags, return them in an array
function boj_utags_find_orphans() {
    global $wpdb;

    $sql = "SELECT terms.term_id, terms.name FROM {$wpdb->terms} terms
            INNER JOIN {$wpdb->term_taxonomy} taxo
            ON terms.term_id=taxo.term_id
            WHERE taxo.taxonomy = 'post_tag'
            AND taxo.count=0";

    return $wpdb->get_results( $sql );
}
?>

Code snippet plugin-unused-tags.php

Copy or download this plugin, activate it, and you can access a new page under the Posts menu that resembles Figure 6-3:

Figure 6.3. FIGURE 6-3

Spot a few more good practices in this plugin:

1. Function boj_utags_do_action(), which checks for the presence of a boj_action parameter in the query string or the POST data, is hooked to action admin_init. This way, the plugin actually does something only when the user is in the admin area. When viewing the public part (the blog itself), no event is triggered. The gain here is negligible because the plugin is simple, but this technique applied to complex plugins does speed up execution.

2. When a tag has been deleted or renamed, the plugin redirects the user to the current page with the additional query parameter 'boj_action=done'. Doing so, you prevent any unwanted repeated action if the user accidentally reloads the page and resubmits data. The function hooks into 'admin_notices' to display an informational message.

Ajax scripts are particular types of JavaScripts that enable updating a part of the browser's screen without reloading the entire page. Ajax scripts can consist of forms or links and as such need to be protected with nonces as well.

You learn how to add such nonces in Chapter 12, "JavaScript and Ajax," which is entirely about JavaScript and Ajax.

Consider a few lines of simple and innocent looking HTML and PHP code:

<?php $name = $_POST['fullname']; ?>

<form action="" method="POST">
    Full name:
    <input type="text" name="fullname" value="<?php echo $name; ?>" />
    <input type="submit" value="Save" />
</form>

Code snippet bad_form.php

This minimal form has just one field, named fullname, which is prepopulated with any previously entered value. For future reference, name this form Bad Form.

For instance, if you enter Ozh RICHARD as a full name and press Save, everything seems fine with this form (see Figure 6-4).

Figure 6.4. FIGURE 6-4

So, what could possibly go wrong with such a simple form?

The potential problem here is that inputs are not validated, and outputs are not sanitized. In other words, consider the following:

To illustrate this trivial lack in security, input the following full names and see the results (see Figure 6-5):

Figure 6.5. FIGURE 6-5

What just happened?

Case 1 is an example of a legit, nonmalicious, yet form-breaking example: Although the data entered is a valid full name, the lack of sanitization at output breaks the input field because of the quotation marks. A correct way to render the form in that case would have been to convert these quotation marks into HTML entities.

In case 2, the user has joined the Dark Side and deliberately tries to exploit the form. Again, the quotation mark breaks the input field, so the output shows another field that would be actually submitted if the user pressed Save again. Not only is the output not sanitized (by encoding quotation marks before printing the value of the field) but the input is also questionable and should have been validated first, for instance by removing all nonalphanumeric characters and stripping HTML tags.

Case 3 is a variation on the same principle: Instead of adding arbitrary content to the form, the user here injects JavaScript that could, for instance, fetch a session cookie value from your site and send it to another one.

The third case is an example of Cross Site Scripting, or XSS: a vulnerability in web applications that enables malicious attackers to inject client-side script into web pages viewed by other users. Via XSS, an attacker can gain elevated access privileges to sensitive page content, session cookies, and a variety of other information maintained by the browser on behalf of the user.

These examples demonstrate how the lack of data validation measures can, at best, corrupt data or, at worst, exploit security holes in your web applications.

Imagine you are coding a plugin with an interface asking users to enter their age and to pick a color between red, green, or blue.

Consider the following code fragment:

<?php

$clean = array();

// Age: positive integer only
$clean['age'] = absint( $_POST['age'] );

// Color: red, green or blue only
switch( $_POST['color'] ) {
    case 'red':
    case 'green':
    case 'blue':
        $clean['color'] = $_POST['color'];
        break;
}

?>

Notice how this validating snippet makes use of an array named $clean. This illustrates a good practice that can help developers identify whether data is potentially unsanitary or can be considered safe. Because you cannot be sure of what the submitted array $_POST contains, don't validate it. Instead, select the expected part of it.

This snippet also introduces a WordPress function that is a convenient wrapper for PHP functions intval() and abs(), used to return a positive integer.

Initializing variables, such as $clean at the beginning of the snippet here, is another good practice because you make sure the result of your validating procedure contains only what you expect.

Using PHP's error_reporting and setting WordPress constant WP_DEBUG to true can help to enforce the initialization of variables because a reference to an undefined variable generates a notice on the screen. For more details about debugging, see Chapter 16.

The previous snippet validated only data: User input is accepted if it is valid and ignored otherwise. It does not sanitize, or "fix," the input: If incorrect data is submitted (such as the user entering a string instead of their age), the resulting array $clean simply ignores the item.

You can write a similar code block to sanitize data instead of simply validating it:

<?php

$clean = array();

// Age: positive integer only
$clean['age'] = absint( $_POST['age'] );

// Color: red, green or blue only. Default is blue.
switch( $_POST['color'] ) {
    case 'red':
    case 'green':
        $clean['color'] = $_POST['color'];
        break;
    case 'blue':
        default:
        $clean['color'] = 'blue';
        break;
}

?>

Now, if users enter an invalid age, such as abc, the result will be 0. If they enter an invalid color (for instance purple), the result will be blue because of the default statement.

The validation philosophy applied here is called white listing: You accept data only from a finite list of known and trusted values. The opposite, reject data from a finite list of untrusted values, is called black listing, which is rarely a good idea. White listing is not always possible, but whenever you can enforce this policy, you should.

Whether you want to validate or sanitize user input is a design decision and depends mostly on the kind of data expected. Imagine a form containing a field to receive an integer (age for instance), an email address, and a longer paragraph for raw text with no HTML tags (such as a short bio).

Before you decide that you will just validate or also sanitize data, the first thing to consider is the potential inconvenience of simply validating and rejecting invalid data submitted:

A second decisive factor to consider is your ability to interpret and guess what a sanitized value would be:

A third characteristic to reflect on is what you will do right away with the input data if you sanitize, hence possibly modify it:

You now learn how to validate and sanitize various types of data, and what WordPress functions exist to do so.

<?php
$data = 43;

// validate integers
return( intval( $data ) == $data );

// sanitize integers
return( intval( $data ) );
?>

<?php
$num = '100000000000000000';

// Validate large integers
return( ctype_digit( $num ) );
?>

<?php
// Validate alphabetic strings
return( ctype_alpha( $num ) );
?>

<?php
// Validate alphanumeric strings
return( ctype_alnum( $num ) );
?>

<?php

var_dump( sanitize_text_field( "I am nice.\n Very <em>nice</em>!  " ) );

// result:
// string(21) "I am nice. Very nice!"

?>

<?php

$test = '<a href="xx">site</a> <b>bold<b> <script>alert("fail")</script>';

// PHP's strip_tags()
var_dump( htmlentities( strip_tags( $test ) ) );
// result: string(33) "site bold alert("fail")"

// WordPress' wp_strip_all_tags()
var_dump( htmlentities( wp_strip_all_tags( $test ) ) );
// result: string(9) "site bold"
?>

Internal Identifier Strings

WordPress comes with a function named sanitize_key() used to sanitize internal identifiers, such as option names, which accepts lowercase characters, dashes, and underscores.

<?php
$data = 'option_43;';

// Validate:
return( preg_match('/^[a-z0-9-_]+$/', $data ) );

// Sanitize:
return( sanitize_key( $data ) );
?>

The validating line introduces a powerful tool: regular expression pattern matching. Basically, this line says "return true if $data matches the pattern". This seemingly cryptic pattern is constructed as shown in Figure 6-6:

Figure 6.6. FIGURE 6-6

The four parts of this regular expression follow:

1. The pattern delimiters. It can be any character and is usually a forward slash /.

2. When used as the first character after the opening pattern delimiter, the caret ∧ identifies the beginning of the string. Similarly, when used as the last character before the closing delimiter, a dollar sign $ means "end of the string."

3. The plus sign + means "one or more of the preceding pattern."

4. And finally the pattern itself, between square brackets: any character from lowercase a to lowercase z, from 0 to 9, or a dash -, or an underscore _.

You will use more complex regular expressions in the following examples.

<?php
// Validate phone numbers like 123-456-7890
function boj_validate_phone( $num ) {
    return preg_match( '/^\d{3}-\d{3}-\d{4}$/', $num );
}

// Test your function:

var_dump( boj_validate_phone( '132-456-7890' ) );
// echoes: int(1)

var_dump( boj_validate_phone( '555-8882' ) );
// echoes: int(0)
?>

<?php

// Validate product serial number like A145-B3D5-KK43
function boj_validate_serial( $string ) {
    return preg_match( '/^[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/', $string );
}
?>

<?php

// Validate future dates like mm/dd/yyyy.
// Returns true or an error message
function boj_validate_date( $date ) {
    // first test: pattern matching
    if( !preg_match( '!\d{2}/\d{2}/\d{4}!', $date ) )
        return 'wrong pattern';

    // second test: is date valid?
    $timestamp = strtotime( $date );
    if( !$ timestamp )
        return 'date invalid';

    // third test: is the date from the past?
    if( $timestamp <= time() )
        return 'past date';

    // So far, so good
    return true;
}

// Test it:

var_dump( boj_validate_date( '12/12/99' ) );
// string(12) "wrong pattern"

var_dump( boj_validate_date( '35/30/1980' ) );
// string(12) "date invalid"

var_dump( boj_validate_date( '03/30/1980' ) );
// string(9) "past date"

var_dump( boj_validate_date( '03/30/2020' ) );
// bool(true)

?>

<?php

$date = '30/30/3030';

if( boj_validate_date( $date ) === true ) {

// date is valid
} else {
    // date is invalid
}
?>

<?php

$email = 'wrox@example.com';

// Validate:
return( is_email( $email ) );

// Sanitize:
return( sanitize_email( $email ) );
?>

<?php

var_dump( is_email( 'wrox@example' ) );
// bool(false)

var_dump( is_email( 'wrox@example.com' ) );
// string(11) "wrox@example.com"
?>

<?php

if( is_email( $email ) === email ) {
    // email seems valid
} else {
    // email is invalid
}
?>

<?php

var_dump( sanitize_email( 'ozh@ozh' ) );
// string(0) ""

var_dump( sanitize_email( 'ozh@ozh..org' ) );
// string(0) ""

var_dump( sanitize_email( '(ozh)@(ozh).org' ) );
// string(11) "ozh@ozh.org"

var_dump( sanitize_email( 'ozh@ozh.org' ) );
// string(11) "ozh@ozh.org"
?>

HTML (or XML)

HTML in this section can either be a full HTML fragment (a comment on a blog post, for instance), or single nodes, that is, an HTML element with text and attributes.

HTML Fragments

HTML fragments can be sanitized at input with WordPress function force_balance_tags(), although this cannot be considered as an HTML validator but more a helper function to achieve validity. This function finds incorrectly nested or missing closing tags and fixes the markup:

<?php

// 1. Fixing missing closing tags:

$html = '<p>Please close my <strong>tags!';
var_dump( force_balance_tags( $html ) );

// string(45) "<p>Please close my <strong>tags!</strong></p>"

// 2. Fixing incorrectly nested tags:

$html = '<p>Please <strong><em>fix</strong></em> nesting!</p>';
var_dump( force_balance_tags( $html ) );
// string(52) "<p>Please <strong><em>fix</em></strong> nesting!</p>"

?>

WordPress ships with a script named KSES (a recursive acronym: KSES Strips Evil Scripts) that should process and sanitize all untrusted HTML, both at input and output. The wrapper function, wp_kses() enables advanced filtering of HTML snippets, for instance with a custom set of authorized tags.

You can now write a function to strip all HTML tags except <strong> and <a href='' title=''>. All other tags (<em>, <b>...) or attributes (class='', style='',...) need to be taken out.

First, define an array of allowed tags and attributes:

<?php

$allowed = array(
    'strong' => array(),
    'a'      => array(
        'href'  => array(),
        'title' => array()
    )
);
?>

You are now ready to filter and sanitize HTML fragments:

<?php

$html = '<a href="#" class="external">site</a>
         <b>bold?</b> <strong>bold!</strong>';

var_dump( wp_kses( $html, $allowed ) );
// string(58) "<a href="#">site</a> bold? <strong>bold!</strong>"
?>

Notice how selective this function is in removing tags and attributes as you have defined them. This function is used for instance to filter comments and enable only a minimal common set of HTML tags.

Note that the KSES library in WordPress defines default sets of HTML tags and attributes, as you can see at the beginning of the file wp-includes/kses.php. The global variable $allowedtags contains a rather restrictive set of tags that are typically what you will want to accept in comments or user input.

Using the function wp_kses_data() and passing as a single argument the chunk of HTML you want to sanitize, you will make use of this default list:

<?php

$html = '<a href="http://site.com">site</a>
    <script src="script.js"></script>
    <img src="image.png" />
    <junk>random</junk>';

var_dump( wp_kses_data( $html ) );
// string(41) "<a href="http://site.com">site</a> random"
?>

HTML Nodes

A node is a part of an HTML (or, again, XML) document. It consists of three parts, as shown in Figure 6-7.

Figure 6.7. FIGURE 6-7

1. The element node (span, h1, em... or any custom XML element)

2. The attribute node (class, style, title, alt...)

3. The text node (any text found outside attributes and elements)

What you need to sanitize are the attribute and the text nodes at output to make sure they are valid and cannot break the display.

Consider the following code block, and try to spot its weaknesses before you read more:

<h1><?php echo $page_title; ?></h1>
<a href="#anchor" title="<?php echo $link_title; ?>" >link</a>

In a similar manner to how the previous example Bad Form was breakable, the problem here is that the text node $page_title and the attribute node $link_title are not sanitized for display, which can produce unexpected and potentially dreadful results with values such as the following:

<?php

$page_title = 'break</h1><h1>the tag';
$link_title = '" onmouseover="alert(\'XSS\');';

?>

WordPress contains two functions specifically designed to sanitize HTML attributes and text nodes, escape illegal characters, and convert to HTML entities when needed: esc_attr() and esc_html(). The same code block, now bullet proof, would be the following:

<h1><?php echo esc_html( $page_title; ) ?></h1>
<a href="#anchor" title="<?php echo esc_attr( $link_title; ) ?>" >link</a>

In a localized environment, functions esc_html() and esc_attr() have variations that can translate and escape at the same time (such as esc_html_e() for example). Chapter 5, "Internationalization," has a detailed description of these functions.

<?php
// dangerous URL
$url = 'javascript:alert("XSS");';
?>

<a href="<?php echo esc_url( $url ); ?> ">Link Text</a>

<?php

$url1 = 'http://example.com/"<script>alert(\'XSS\')</script>';
var_dump( esc_url( $url1 ) );
// string(54) "http://example.com/scriptalert('XSS')/script"

$url2 = 'http://example.com/"&lt;script&gt;alert(\'XSS\')&lt;/script&gt;';
var_dump( esc_url( $url2 ) );
// string(90) "http://example.com/&lt;script&gt;alert('XSS')&lt;/script&gt;"

$url3 = 'onmouseover="alert(\'XSS\')';
var_dump( esc_url( $url3 ) );
// string(41) "http://onmouseover=alert('XSS')"

$url4 = 'c:\dir\dir\dir\dir';
var_dump( esc_url( $url4 ) );
// string(0) ""

$url5 = 'http://ex[]amp[]le.co[]m/';
var_dump( esc_url( $url5 ) );
// string(19) "http://example.com/"
?>

<?php

$allowed = array( 'http', 'https', 'ftp' );

$url1 = 'https://example.com';
var_dump( esc_url( $url1, $allowed ) );
// string(19) "https://example.com"

$url2 = 'irc://example.com';
var_dump( esc_url( $url2, $allowed ) );
// string(0) ""

$url3 = 'xyz123://example.com';
var_dump( esc_url( $url3, $allowed ) );
// string(0) ""
?>

<?php

$url = "http://ex[a]mple.com/?q=1&s=2'";

var_dump( esc_url( $url ) );
// string(38) "http://example.com/?q=1&#038;s=2&#039;"

var_dump( esc_url_raw( $url ) );
// string(28) "http://example.com/?q=1&s=2'"
?>

<?php
header( "Location: http://example.com/profile.php?user=$user" );
?>

<?php
wp_redirect( "http://example.com/profile.php?user=$user" );
?>

<?php
$user = 'Joe';
?>

<script type="text/javascript">
var user = '<?php echo esc_js( $user ); ?>';

function confirm_delete() {
    return confirm('Really delete user '+user+'?');
}
</script>

<a href="<?php echo esc_url( "delete.php?user=$user" ); ?>"
   onclick="javascript:return( confirm_delete() )"
   title="Delete">Delete user <?php echo esc_html( $user ) ?></a>

Server or Environment Variables

The superglobal array $_SERVER, as its name may not imply, contains information received by the server from the client, that is, a user's browser. As such, consider its values unsafe. Depending on what server variable you need, be sure to always sanitize it with the appropriate functions.

For instance, if you want to display on a page the referring URL that presumably sent a visitor to your site, don't use the following:

<?php if( isset( $_SERVER['HTTP_REFERER'] ) ) { ?>
Welcome visitor from <?php echo $_SERVER['HTTP_REFERER']; ?> !
<?php } ?>

Because the referrer URL is extremely easy to spoof and may contain anything a malicious user can imagine, let esc_url() handle it for you:

<?php if( isset( $_SERVER['HTTP_REFERER'] ) ) { ?>
Welcome visitor from <?php echo esc_url( $_SERVER['HTTP_REFERER'] ); ?> !
<?php } ?>

In the same way, don't trust the user-agent signature stored in $_SERVER['HTTP_USER_AGENT']. If you want to display this data, you should treat it as unsafe HTML and sanitize it with wp_kses() first.

Other often-used server variables are $_SERVER['REQUEST_URI'] or $_SERVER['PHP_SELF'], containing the location of the currently loaded page or executed script. When not sanitized, these server variables are easily exploitable. For example, craft the following form that will point to itself in its action parameter:

<form action="<?php echo $_SERVER['PHP_SELF']; ?>" method="post" >
<input type="text" name="fullname" />
<input type="submit" value="Save" />
</form>

Save this form as self_form.php, and then point your browser to http://localhost/self_form.php/"><script>alert(1337)</script> and see what happens in Figure 6-8.

Figure 6.8. FIGURE 6-8

The best option is to always hardcode form action parameters, or to leave the form action empty (<form action="" method="post">) to send data back to the same place. If you need to make it dynamic and use a server variable, sanitize it with esc_url().

<?php

// sanitize the whole $_POST array
$_POST = array_map( 'absint', $_POST );

// extract only expected values
$clean = array();
$clean['age'] = $_POST['age'];
$clean['numchild'] = $_POST['numchild'];
$clean['income'] = $_POST['income'];
?>

<?php

$clean_urls = array();

// Split the textarea value into an array of URLs
$urls = split( "\n", $_POST['urls'] );

// Sanitize the whole array
$clean_urls = array_map( 'esc_url', $urls );
?>

Data from a Defined Set

Even when your form seems to lock down the number of possible values of a given field, such as a radio button being only Yes or No, always validate the submitted value. Indeed, it's trivial to post arbitrary data to any form, as the following example demonstrates.

Figure 6.9. FIGURE 6-9

First, create a script showing a simple form with radio buttons, check boxes, and a drop-down, similar to Figure 6-9. To mimic storing information, the script can also save any submitted information to a local text file.

<?php

if( $_POST ) {
    $post = print_r( $_POST, true );
    error_log( $post, 3, dirname( __FILE__ ).'/post.log' );
}

?>

<form action="" method="post">

    Gender:
    <input type="radio" name="gender" value="male" />male
    <input type="radio" name="gender" value="female" />female

    Food dislikes:
    <input type="checkbox" name="food[]" value="spinach"/>spinach
    <input type="checkbox" name="food[]" value="anchovy"/>anchovy
    <input type="checkbox" name="food[]" value="liver"/>liver

    Country of residence:
    <select name="country">
        <option value="usa">USA</option>
        <option value="canada">Canada</option>
        <option value="uk">United Kingdom</option>
        <option value="other">Other</option>
    </select>

    <input type="submit" />

</form>

Code snippet locked_form.php

At the beginning of the script, if array $_POST is defined, its content is sent to a file named 'log.txt' in the same directory. You can learn more about error and message logging in Chapter 16, which is about debugging and code optimization.

This form looks pretty much locked down: Every field value belongs to a limited set, and at first you would probably confidently think that the submitted data will always be along the lines of the following array as read in log.txt:

Array
(
    [gender] => male
    [food] => Array
        (
            [0] => anchovy
            [1] => liver
        )
    [country] => usa
)

Just because the input fields seem to enforce values does not mean you cannot post anything to the form. You can now take the role of a malicious user and try to abuse this seemingly locked-down form with a script that posts random data to it:

<form action="locked_form.php" method="post">
    <input name="gender" value="hello" />
    <input name="food[]" value="<script>alert('hello');</script>" />
    <input name="country" value="bleh" />
    <input name="random" value="1337" />
    <input type="submit" />
</form>

Code snippet locked_form_abuse.php

Notice how values passed to the script referenced in the action attribute contain totally random values that could not be generated by the legitimate form.

Note

All it takes is a plain HTML file, hosted anywhere including a desktop computer with no web server, to submit any information to a script. Never take for granted that all users will always post only what you expect.

Back to the first form, locked_form.php: You can now make it secure and sanitize submitted values before storing them. Because you know the different values every field can take, you can code efficient and straightforward filters, using a white list principle. The storing code block will now be the following:

<?php

if( $_POST ) {

    $clean = array();

    // Gender: 2 possible values, default to 'male'
    $clean['gender'] = ( $_POST['gender'] == 'female' ? 'female' : 'male' );

    // Food: arbitrary number of possible values, no default
    $foods = array( 'spinach', 'anchovy', 'liver' );
    if( in_array( $_POST['food'], $foods ) )
        $clean['food'] = $_POST['food'];

    // Country: arbitrary number of possible values, default to 'other'
    switch( $_POST['country'] ) {
        case 'canada':
        case 'uk':
        case 'usa':
            $clean['country'] = $_POST['country'];
            break;

default:
            $clean['country'] = 'other';
    }

    $post = print_r( $clean, true );
    error_log( $post, 3, dirname( __FILE__ ).'/post.log' );

}

?>

Code snippet locked_form_secure.php

Notice how different test syntaxes are involved. The first comparison and sanitization, for gender, uses PHP's ternary operator. This compact line means, Is $_POST['gender'] female? Then $clean['gender'] equals female, otherwise it will equal male.

Database Queries

Database queries are obviously crucial strings regarding security. Consider for instance a web application in which the following query would authenticate users after they submit their login and password:

<?php
$sql = "SELECT * FROM users
        WHERE ''user_login' = '$login' AND 'user_pass'= '$password'";
?>

Because that SQL statement is not escaped and not sanitized, a malicious user could log in with the following credentials:

<?php
$login = 'anything';
$password = "123456' OR 1='1";
?>

Indeed, setting these variables, the SQL statement becomes a simple 1=1 condition, which is obviously always true:

SELECT * FROM users
WHERE 'user_login' = 'adminzzz'
AND 'user_pass'= '123456'
OR 1='1'

This would be a successful SQL injection attack: A user manipulates the statement performed on the database, as humorously depicted in Figure 6-10, a strip by Randall Munroe, titled "Exploits of a Mom" and reproduced here with permission (original URL: http://xkcd.com/327/).

Figure 6.10. FIGURE 6-10

Opportunely, WordPress comes with functions to help you sanitize your queries properly.

Function esc_sql() escapes content for inclusion into the database, which means it adds backslashes before characters that need to be quoted in queries (quotes and backslashes). The particularity of esc_sql() is that it can process indifferently a query string or an array of query strings.

<?php

$login = 'back\slash';
$sql = 'SELECT * FROM 'users' WHERE 'login' = "'. esc_sql( $login ) .'"';
var_dump( $sql );
// string(55) "SELECT * FROM 'users' WHERE 'login' = "back\\slash""
?>

Function like_escape() takes care of escaping text used in LIKE clauses, where special characters percent % and ampersand _ are used:

<?php

$pattern = 'joe';

$like = like_escape( 'LIKE "%'.$pattern.'%"' );

$sql = 'SELECT * FROM 'users' WHERE 'username' '.$like;

var_dump( $sql );
// string(53) "SELECT * FROM 'users' WHERE 'username' LIKE "\%joe\%""
?>

Function sanitize_sql_orderby() sanitizes ORDER BY clauses before they are included into an SQL string:

<?php

$order_by   = 'last_name';
$order_sort = 'DESC';

$order = sanitize_sql_orderby( "$order_by $order_sort" );

$sql = 'SELECT * FROM 'users' ORDER BY '. $order;

var_dump( $sql );
// string(45) "SELECT * FROM 'users' ORDER BY last_name DESC"
?>

WordPress provides much more than simple escaping functions to sanitize queries: It has a complete set of functions designed to help you securely format your SQL statements.

All database interactions within WordPress can be done through a class called wpdb, which (if you have some PHP background) you will see derives from the popular ezSQL class.

You should not run SQL queries using PHP's functions such as mysql_query() or mysql_fetch_array() for two reasons:

Methods from this class, which you learn to use in this section, should not be called directly: Instead, always use the $wpdb object WordPress instantiates on every page load.

The $wpdb object can be used to access data from any table in the database used by WordPress: All the standard tables created upon installation or upgrade of your blog, but also any custom table created by a plugin, for example. In Chapter 7, "Plugin Settings," you learn when and how to create such a custom table.

The $wpdb object contains several methods you can use to read, insert, update, or delete information from tables. The following examples would produce the same results, but notice how readable and foolproof it gets:

<?php

// Example 1
mysql_connect( DB_HOST, DB_USER, DB_PASSWORD ) or
   die("Could not connect: " . mysql_error());
mysql_select_db( DB_NAME );
mysql_query( "UPDATE wp_posts SET post_title= '$newtitle' WHERE ID= $id" );

// Example 2
$newtitle = esc_sql( $newtitle );
$my_id = absint( $my_id );
$wpdb->query( "UPDATE $wpdb->posts SET post_title='$newtitle' WHERE ID=$id");

// Example 3
$new_values = array( 'post_title' => $newtitle );
$where = array( 'ID' => $my_id );
$wpdb->update( $wpdb->posts, $new_values, $where );
?>

What do these three examples tell you?

As in the previous example #3, all-in-one methods are foolproof functions that exempt you from memorizing the boring parts (SQL syntax, sanitization functions) and manage everything for you. Count on update() and insert().

<?php


$values = array(
    'column1' => 'some string',
    'column2' => 43
);

$where = array(

'ID' => 1
);

$formats_values = array( '%s', '%d' );

$formats_where = array( '%d' );

$wpdb->update( $wpdb->custom, $values, $where, $formats_values, $formats_where );
?>

<?php

$values = array(
    'column1' => 'new string',
    'column2' => 44
);

$formats_values = array( '%s', '%d' );

$wpdb->insert( $wpdb->custom, $values, $formats_values );
?>

Not all the queries you'll run will be simple UPDATE or INSERT, so the wpdb class provides numerous other methods you'll peruse now, for instance to fetch a single value or an entire row, or perform custom complex statements.

<?php

$sql = "SELECT COUNT(ID) FROM {$wpdb->posts}
        WHERE post_status = 'publish' AND post_type = 'post'";

$num_of_posts = $wpdb->get_var( $sql );
?>

<?php
$wpdb->get_row( $sql, $output_type, $row_offset );
?>

<?php
$sql = "SELECT 'user_email', 'user_url'
        FROM $wpdb->users
        WHERE user_login = 'admin'";

$object  = $wpdb->get_row( $sql, OBJECT );
$array_a = $wpdb->get_row( $sql, ARRAY_A );
$array_n = $wpdb->get_row( $sql, ARRAY_N );
?>

<?php

var_dump( $object );
/*
object(stdClass)#824 (2) {
  ["user_email"] => string(17) "ozh@ozh.org"
  ["user_url"] => string(21) "http://ozh.org/"
}
*/

var_dump( $array_a );
/*
array(2) {
  ["user_email"] => string(17) "ozh@ozh.org"
  ["user_url"] => string(21) "http://ozh.org/"
}
*/

var_dump( $array_n );
/*
array(2) {
  [0] => string(17) "ozh@ozh.org"
  [1] => string(21) "http://ozh.org/"
}
*/
?>

<?php
$email = $object->user_email;

$email = $array_a['user_email'];

$email = $array_n[0];
?>

<?php

$sql = "SELECT 'user_email' FROM $wpdb->users";

$emails = $wpdb->get_col( $sql );
?>

<?php

$subject = 'Blog maintenance';
$message = 'Dear user, the blog will be offline for 15 minutes.';

foreach( $emails as $email ) {
    wp_mail( $email, $subject, $message );
}
?>

<?php

$sql = "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";

$results = $wpdb->get_results( $sql, ARRAY_A );
?>

Array (
    [0] => Array (
            [year] => 2010
            [posts] => 13
        )
    [1] => Array (
            [year] => 2009
            [posts] => 37
        )
    [2] => Array (
            [year] => 2008
            [posts] => 9
        )
)

<?php

foreach( $results as $sum ) {
    $year  = $sum['year'];
    $count = $sum['posts'];
    echo "<p>Posts published in $year: $count</p>";
}
?>

<?php

$sql = "DELETE from wp_comments
        WHERE comment_author_url
        LIKE '%evil.example.com%'";

$deleted = $wpdb->query( $sql );
?>

<?php

$sql = "UPDATE $wpdb->posts
        SET comment_status = 'closed'
        WHERE post_date < DATE_SUB( NOW(), INTERVAL 90 DAY )
        AND post_status = 'publish'";

$wpdb->query( $sql );
?>

<?php

$sql = "UPDATE $wpdb->comments
        SET comment_author_url =
        REPLACE( comment_author_url, 'http://oldsite/', 'http://newsite/' )";

$wpdb->query( $sql );
?>

You may have noticed that the previous queries are not sanitized. This was indeed not needed because they are completely hardcoded and do not contain any dynamic and potentially unsanitary or malformed data.

If you need to create a dynamic custom query where you cannot hardcode every component, you already know that you need to sanitize and escape it with function esc_sql() before your run it. This preparation step can be handily done with the prepare() method, which enables the same kind of format strict validation as insert() or update().

The process becomes twofold:

For instance, how can you fetch the titles of all posts written by an author with a given user ID during a particular month? The SQL query for such a request is similar to the following:

SELECT 'post_title'
    FROM $wpdb->posts
    WHERE 'post_author' = 1
    AND post_status = 'publish'
    AND post_type = 'post'
    AND DATE_FORMAT( 'post_date', '%Y-%m' ) = '2010-11'

From this example, define a generic SQL query with format placeholders:

<?php
$sql = "SELECT 'post_title'
        FROM $wpdb->posts
        WHERE 'post_author' = %d
        AND post_status = 'publish'
        AND post_type = 'post'
        AND DATE_FORMAT( 'post_date', '%%Y-%%m') = %s ";

?>

Think of it as a template query, where %d will be an integer and %s a string. Notice how percent signs % are double-escaped as %% and how you don't need quotes around these placeholders.

Now you can "prepare" the query and then process it. Get all posts titles from author ID 1 from the month of November 2010:

<?php

$id = 1;
$month = '2010-11'

$safe_sql = $wpdb->prepare( $sql, $id, $month );

$posts = $wpdb->get_results( $safe_sql );
?>

The prepare() method takes an arbitrary number of parameters: first the SQL template with its placeholders and then as many values as there are placeholders, either one by one or grouped in an array. What is important here is to pass these values in the same order as their placeholders in the query, much like you would use PHP's function printf().

If you var_dump() the resulting $posts variable, you get something like the following:

array(3) {
  [0]=>
  object(stdClass)#251 (1) {

["post_title"] => string(30) "Halloween over, Christmas soon"
  }
  [1]=>
  object(stdClass)#250 (1) {
    ["post_title"] => string(25) "Happy Birthday Mike Muir"
  }
  [2]=>
  object(stdClass)#249 (1) {
    ["post_title"] => string(27) "Ditched My Mac, Bought a PC"
  }

The $wpdb object contains a few methods and properties you might use, particularly for debugging purposes.

<?php

// On:
$wpdb->show_errors();

// Off:
$wpdb->hide_errors();
?>

<?php
echo $wpdb->last_error;

$wpdb->print_error();
?>

You start by saving your first plugin option, which will be named boj_myplugin_color and have a value of red. The function call to do so is the following:

<?php
add_option( 'boj_myplugin_color', 'red' );
?>

The first parameter is your option name. It is crucial that you make it unique and self-explanatory.

The second parameter is the option value that can be practically anything a variable can hold: string, integer, float number, Boolean, object, or array.

Updating an option value is a similar function call:

<?php
update_option( 'boj_myplugin_color', 'blue' );
?>

The difference between add_option() and update_option() is that the first function does nothing if the option name already exists, whereas update_option() checks if the option already exists before updating its value and creates it if needed.

Every option saved adds a new record in WordPress' option table. You can simply store several options at once, in one array: This avoids cluttering the database and updates the values in one single MySQL query for greater efficiency and speed.

<?php
$options = array(
    'color'    => 'red',
    'fontsize' => '120%',

'border'   => '2px solid red'
);
update_option( 'boj_myplugin_options', $options );
?>

Saving your plugin options in one array rather than individual records can have a huge impact on WordPress' loading time, especially if you save or update many options. Most of the time, PHP code executes fast, but SQL queries usually hinder performance, so save them whenever possible.

To fetch an option value from the database, use the function get_option():

<?php
$myplugin_color = get_option( 'boj_myplugin_color' );
?>

The first thing to know about get_option() is that if the option does not exist, it will return false. The second thing is that if you store Booleans, you might get integers in return.

As an illustration of this behavior, consider the following code block that creates a couple of new options with various variable types:

<?php
update_option( 'test_bool_true',  true );
update_option( 'test_bool_false', false );
?>

You can now retrieve these options, along with another one that does not exist, and see what variable types are returned, shown as an inline comment below each get_option() call:

<?php
var_dump( get_option( 'nonexistent_option' ) );
// bool(false)

var_dump( get_option( 'test_bool_true' ) );
// string(1) "1"

var_dump( get_option( 'test_bool_false' ) );
// bool(false)
?>

To avoid an error when checking option values, you should store true and false as 1 and 0. This means also that you need to strictly compare the return of get_option() with Boolean false to check if the option exists:

<?php
if( get_option( 'boj_myplugin_someoption' ) === false ) {
    // option has not been defined yet
    // ...

} else {
    // option exists
    // ...
}
?>

You can also specify what value you want to be returned if the option is not found in the database, with a second option parameter to get_option(), like in the following example:

<?php
$option = get_option( 'boj_myplugin_option', 'option not found' );
?>

You have seen that saving multiple options in a single array is best practice. A complete example of saving and then getting values from one array would be as follows:

<?php
// To store all of them in a single function call:
$myplugin_options = array(
    'color'    => 'red',
    'fontsize' => '120%',
    'border'   => '2px solid red'
);
update_option( 'boj_myplugin_options', $myplugin_options ) ;

// Now to fetch individual values from one single call:
$options  = get_option( 'boj_myplugin_options' );
$color    = $options[ 'color' ];
$fontsize = $options[ 'fontsize' ];
$border   = $options[ 'border' ];
?>

Saving and retrieving options enclosed in an array has another advantage: Variable Boolean types within the array are preserved. Consider the following example:

<?php
add_option( 'test_bool', array(
    'booltrue'  => true,
    'boolfalse' => false
    )
);
?>

Now get the option value from the database with var_dump( get_option( 'test_bool' ) ). See how Boolean types are retained, contrary to the previous example:

// output result of var_dump(get_option('test_bool'))
array(2) {
  ["booltrue"] => bool(true)
  ["boolfalse"]=> bool(false)
}

Deleting an option needs a self-explanatory function call:

<?php
delete_option( 'boj_myplugin_options' );
?>

This function call returns false if the option to delete cannot be found and returns true otherwise. You will mostly delete options when writing uninstall functions or files (see Chapter 2).

By default, all the options stored in the database are fetched by a single SQL query when WordPress initializes and then caches. This applies to internal WordPress core settings and options created and stored by plugins.

This is efficient behavior: No matter how many get_option() calls you issue in your plugins, they won't generate extra SQL queries and slow down the whole site. Still, the potential drawback of this autoload technique is that rarely used options are always loaded in memory, even when not needed. For instance, there is no point in fetching backend options when a reader accesses a blog post.

To address this issue when saving an option for the first time, you can specify its autoload behavior, as in the following example:

<?php
add_option( 'boj_myplugin_option', $value, '', $autoload );
?>

Note the empty third parameter: This is a parameter that was deprecated several WordPress versions ago and is not needed any more. Any value passed to it will do; just be sure not to omit it.

The fourth parameter is what matters here. If $autoload is anything but 'no' (or simply not specified), option boj_myplugin_option will be read when WordPress starts, and subsequent get_option() function calls will not issue any supplemental SQL query. Setting $autoload to 'no' can invert this: This option will not be fetched during startup of WordPress, saving memory and execution time, but it will trigger an extra SQL query the first time your code fetches its value.

Of course, specifying the autoload parameter upon creation of an option does not change the way you fetch, update, or delete its value.

<?php
function boj_myplugin_create_options() {
    // front-end options: autoloaded
    add_option( 'boj_myplugin_options', array(
        'color'    => 'red',
        'fontsize' => '120%',
        'border'   => '2px solid red'
    );

    // back-end options: loaded only if explicitly needed
    add_option( 'boj_myplugin_admin_options', array(
        'version'    => '1.0',
        'donate_url' => 'http://x.y/z/',
        'advanced_options' => '1'
    ), '', 'no' );
}
?>

<?php
function boj_myplugin_recreate_options() {
    // get old value
    $old = get_option( 'boj_myplugin_admin_options' );

    // delete then recreate without autoload
    delete_option( 'boj_myplugin_admin_options' );
    add_option( 'boj_myplugin_admin_options', $old, '', 'no' );
}
?>

Dealing with user inputs introduces new constraints in the option process: You need to design a user interface, monitor form submissions, handle security checks, and validate user inputs. To easily manage these common tasks, WordPress wraps the option functions into a comprehensive Settings API.

The Settings API enables you to handle the simple tasks:

... and let WordPress transparently manage for you the cumbersome and repetitive parts:

Now dissect the Settings API: you learn to use it through a step-by-step example.

The Settings API functions consist of three steps:

But first, you create a setting management page for your plugin.

Creating the Plugin Administration Page

The plugin page will be located at /wp-admin/options-general.php?page=boj_myplugin:

<?php
// Add the admin options page
add_action('admin_menu', 'boj_myplugin_add_page');
function boj_myplugin_add_page() {
    add_options_page( 'My Plugin', 'My Plugin', 'manage_options',
        'boj_myplugin', 'boj_myplugin_options_page' );
}

// Draw the options page
function boj_myplugin_options_page() {
    ?>
    <div class="wrap">
    <?php screen_icon(); ?>
    <h2>My plugin</h2>
    <form action="options.php" method="post">
    </form></div>
    <?php
}
?>

This page is empty for now (see Figure 7-1). You will add form inputs later.

Figure 7.1. FIGURE 7-1

Creating pages for plugins is covered in detail in Chapter 4, "Integrating in WordPress," so refer to it for more explanation about this code.

<?php
register_setting(
    'boj_myplugin_options',
    'boj_myplugin_options',
    'boj_myplugin_validate_options'
);
?>

<?php
add_settings_section(
    'boj_myplugin_main',
    'My Plugin Settings',
    'boj_myplugin_section_text',
    'boj_myplugin'
);

add_settings_field(
    'boj_myplugin_text_string',
    'Enter text here',
    'boj_myplugin_setting_input',
    'boj_myplugin',
    'boj_myplugin_main'
);
?>

<?php
// Explanations about this section
function boj_myplugin_section_text() {
    echo '<p>Enter your settings here.</p>';
}

// Display and fill the form field
function boj_myplugin_setting_input() {
    // get option 'text_string' value from the database
    $options = get_option( 'boj_myplugin_options' );
    $text_string = $options['text_string'];
    // echo the field
    echo "<input id='text_string' name='boj_myplugin_options[text_string]'
        type='text' value='{$options['text_string']}' />";
}
?>

<?php
function boj_myplugin_validate_options( $input ) {
    $valid = array();
    $valid['text_string'] = preg_replace(
        '/[^a-zA-Z]/',
        '',
        $input['text_string'] );
    return $valid;
}?>

<?php
// Draw the options page
function boj_myplugin_options_page() {
    ?>

    <div class="wrap">
    <?php screen_icon(); ?>
    <h2>My plugin</h2>
    <form action="options.php" method="post">

    <?php
    settings_fields('boj_myplugin_options');
    do_settings_sections('boj_myplugin');
    ?>

    <input name="Submit" type="submit" value="Save Changes" />
    </form></div>

    <?php
}?>

Some of the function calls used here need to be hooked into WordPress actions such as 'admin_init'. Now recapitulate all the steps covered bit by bit into a full-fledged plugin.

<?php
/*
Plugin Name: Settings API example
Plugin URI: http://example.com/
Description: A complete and practical example of use of the Settings API
Author: WROX
Author URI: http://wrox.com
*/

// Add a menu for our option page
add_action('admin_menu', 'boj_myplugin_add_page');
function boj_myplugin_add_page() {
    add_options_page( 'My Plugin', 'My Plugin', 'manage_options',
        'boj_myplugin', 'boj_myplugin_option_page'
    );
}

// Draw the option page
function boj_myplugin_option_page() {
    ?>
    <div class="wrap">
    <?php screen_icon(); ?>
    <h2>My plugin</h2>

<form action="options.php" method="post">
    <?php settings_fields('boj_myplugin_options'); ?>
    <?php do_settings_sections('boj_myplugin'); ?>
    <input name="Submit" type="submit" value="Save Changes" />
    </form></div>
    <?php
}

// Register and define the settings
add_action('admin_init', 'boj_myplugin_admin_init');
function boj_myplugin_admin_init(){
    register_setting( 'boj_myplugin_options', 'boj_myplugin_options',
        'boj_myplugin_validate_options' );
    add_settings_section( 'boj_myplugin_main', 'My Plugin Settings',
        'boj_myplugin_section_text', 'boj_myplugin' );
    add_settings_field( 'boj_myplugin_text_string', 'Enter text here',
        'boj_myplugin_setting_input', 'boj_myplugin', 'boj_myplugin_main' );
}
// Draw the section header
function boj_myplugin_section_text() {
    echo '<p>Enter your settings here.</p>';
}

// Display and fill the form field
function boj_myplugin_setting_input() {
    // get option 'text_string' value from the database
    $options = get_option( 'boj_myplugin_options' );
    $text_string = $options['text_string'];
    // echo the field
    echo "<input id='text_string' name='boj_myplugin_options[text_string]'
        type='text' value='$text_string' />";
}

// Validate user input (we want text only)
function boj_myplugin_validate_options( $input ) {
    $valid = array();
    $valid['text_string'] = preg_replace(
        '/[^a-zA-Z]/',
        '',
        $input['text_string'] );
    return $valid;
}?>

Code snippet plugin1-standalone-page.php

Activate this plugin and head to /wp-admin/options-general.php?page=boj_myplugin. You see a similar interface to the one shown in Figure 7-2.

Figure 7.2. FIGURE 7-2

The validation function you've previously defined could be slightly improved by letting the users know they have entered an unexpected value and that it has been modified so that they can pay attention to it and maybe amend their input.

The relatively unknown function add_settings_error() of the Settings API can handle this case. Here's how it is used:

<?php
add_settings_error(
   'boj_myplugin_text_string',
   'boj_myplugin_texterror',
   'Incorrect value entered!',
   'error'
);
?>

This function call registers an error message that displays to the user. The first parameter is the title of the setting to which this error applies. The second parameter is an HTML ID tag. Then comes the error message itself, which WordPress encloses in appropriate <div> and <p> tags. The last parameter is the HTML class and can be either 'error' or 'update'.

You can improve the validating function with a user notice if applicable:

<?php
function boj_myplugin_validate_options( $input ) {
    $valid['text_string'] = preg_replace(

'/[^a-zA-Z]/',
        '',
        $input['text_string'] );

    if( $valid['text_string'] != $input['text_string'] ) {
        add_settings_error(
            'boj_myplugin_text_string',
            'boj_myplugin_texterror',
            'Incorrect value entered!',
            'error'
        );
    }

    return $valid;
}
?>

The function now compares the validated data with the original input and displays an error message if they differ (see Figure 7-3).

Figure 7.3. FIGURE 7-3

You have seen how to create a complete settings page for a plugin and its associated entry in the administration menus. Doing so makes sense if your plugin features a lot of settings and its administration page shows a lot of content.

Sometimes though, it is not worth adding a new menu entry for just one or a few plugin options. Here again the Settings API will prove to be useful, allowing plugin setting fields to easily be added to the existing WordPress setting pages.

Adding a Section to an Existing Page

Your previous plugin was adding a whole new section and its input field on a standalone page: You now modify it to insert this content into WordPress' Privacy Settings page.

<?php
function boj_myplugin_admin_init(){
    register_setting(
        'privacy',
        'boj_myplugin_options',

'boj_myplugin_validate_options'
    );

    add_settings_section(
        'boj_myplugin_options',
        'My Plugin Settings',
        'boj_myplugin_section_text',
        'privacy'
    );

    add_settings_field(
        'boj_myplugin_text_string',
        'Enter text here',
        'boj_myplugin_setting_input',
        'privacy',
        'boj_myplugin_options'
    );
}?>

This function now adds your custom section into the 'privacy' section, which is located within the Privacy Settings page, as shown in Figure 7-4. Replace all 'privacy' instances with 'media', and your section will be appended at the end of the Media Settings page.

You still need to whitelist this setting, with register_setting(). Omitting this step would make WordPress ignore the setting when submitting the form.

Figure 7.4. FIGURE 7-4

Adding Only Fields

Of course, it can even make sense to add just one field and no section header to an existing page. Now modify the function in the previous example:

<?php
function boj_myplugin_admin_init(){
    register_setting(
        'privacy',
        'boj_myplugin_options',
        'boj_myplugin_validate_options'
    );

    add_settings_field(
        'boj_myplugin_text_string',
        'Enter text here',
        'boj_myplugin_setting_input',
        'privacy',
        'default'
    );
}?>

Code snippet plugin2-add-to-page.php

Your singular field will be added to the 'default' field set of the 'privacy' section, as seen in Figure 7-5.

Figure 7.5. FIGURE 7-5

Imagine that your plugin has determined the current song on the online radio to be "I Heart WordPress" by the famous fictional band WROX Hackers. You are going to save this information, stating that it will be valid for 3 minutes:

<?php
set_transient( 'boj_myplugin_song', 'I Heart WordPress', 180 );
?>

As you can see, the analogy with add_option() is obvious: first a transient name and then its value. The novelty here is a number of seconds as a third parameter, which indicates the duration of the transient validity.

On every page request, your plugin would now get this transient value:

<?php
$song = get_transient( 'boj_myplugin_song' );
?>

The behavior of function get_transient() is as follows:

To manually delete a transient, use function delete_transient():

<?php
delete_transient( 'boj_myplugin_song' );
?>

This function returns true if successful, false otherwise, for the instance when the transient cannot be found in the database.

Using transients does not clutter the database because expired ones are automatically deleted when you attempt to get their value. Typically, you will not have to use this function, except during an uninstall procedure.

Now see what your plugin would look like.

<?php

// Fetches from an online radio a song title currently on air
function boj_myplugin_fetch_song_title_from_radio() {
    // ... code to fetch data from the remote website
    return $title;
}

// Get song title from database, using a 3 minute transient, and return it
function boj_myplugin_get_song_title() {
    // Get transient value
    $title = get_transient( 'boj_myplugin_song' );

    // If the transient does not exists or has expired, refresh it
    if( false === $title ) {
        $title = boj_myplugin_fetch_song_title_from_radio();
        set_transient( 'boj_myplugin_song', $title, 180 );
    }

    return $title;
}?>

Code snippet plugin3-transients.php

The boj_myplugin_fetch_song_title_from_radio() function would do the following:

Such tasks are beyond the scope of this chapter, but you learn how to do them in Chapter 9, which deals with HTTP requests.

Function boj_myplugin_get_song_title() is a complete example of how to use transient functions: Get a transient, and if it's false then refresh its value and restore it.

Due to their volatile nature, transients benefit from caching plugins, where normal options don't. For example, on server setups using memcached (a memory caching system) and a memcached plugin, WordPress stores transient values in fast memory instead of in the database. For this reason, never assume transients live in the database because they may not be stored there at all.

Any time you want to store data with a short time to live, you should probably use the transients. Following are a few examples of tasks or plugin features that would be a perfect application of the Transient API:

Imagine your newest client being a corporation with both English and Spanish employees. Your job, while working on its corporate intranet CMS (based on WordPress, of course), is to allow employees to select the language in which the interface of WordPress' backend will display.

As per your naming conventions, you can name this plugin BOJ's Admin Lang and use boj_adminlang as a prefix. While learning how to use functions needed to save and get per-user settings, you can build this plugin.

Data about users are kept in two places in WordPress' database:

The user metadata table has been designed to store anything related to a user and to be easily extensible. To do so, a set of functions enables easy access to these records: add_user_meta(), update_user_meta(), get_user_meta(), and delete_user_meta().

These four functions are similar to the ones from the Options API, with an interesting twist: They enable duplicate data.

The function call to save user metadata has the following syntax:

<?php
add_user_meta( $user_id, $meta_key, $meta_value, $unique );
?>

Its parameters follow:

The various option types previously covered have to be unique, but several metadata for a given user can have the same key. This can make sense to store, for instance, multiple book titles a user would own:

<?php
add_user_meta( 3, 'books', 'Professional WordPress', false);
add_user_meta( 3, 'books', 'I Love WP', false);
?>

Depending on the context, it also can make sense to state that a particular metadata key needs to be unique. Back to BOJ's Admin Lang: Storing a user's choice for an interface language is an example of a setting that cannot have multiple values:

<?php
add_user_meta( 3, 'boj_adminlang_lang', 'es_ES', true );
?>

This says that user #3 will want the interface to be translated using locale es_ES (see Chapter 5, "Internationalization," for more details on locales).

The syntax of function update_user_meta() follows:

<?php
update_user_meta( $user_id, $meta_key, $meta_value, $prev_value );
?>

The first three parameters are obvious by now. The fourth parameter, if specified, states which metadata key should be updated. If omitted, all the user's metadata with this $meta_key will be updated.

In a previous example, you have saved two book titles for user #3. Now update the second title to replace WP with WordPress:

<?php
update_user_meta( 3, 'books', 'I Love WordPress', 'I Love WP' );
?>

Omitting the fourth parameter would have updated all the book titles. Back to your polyglot plugin: Because this metadata key is unique, you don't need to pass a fourth parameter. Now set user #3's interface language to empty:

<?php
update_user_meta( 3, 'boj_adminlang_lang', '' );
?>

Prior to displaying WordPress' backend interface when a user loads it, your bilingual plugin can check if that particular user has a metadata stating a locale preference. Now see what user #3 prefers:

<?php
$lang = get_user_meta( 3, 'boj_adminlang_lang', true );
?>

The first and second parameters are the user ID and the metadata key. The third parameter is a bit less obvious: It's a Boolean stating whether you want the return value to be a single value (true) or an array (false).

Your dashboard language plugin stores unique metadata with the name boj_adminlang_lang, so you want that unique value as a string. To fetch the list of books from the previous example, set this third parameter to false to get the following array. (The results are shown as a comment below the function call.)

<?php
$book = get_user_meta( 3, 'books', false );
// array( 'Professional WordPress', 'I Love WordPress' );
?>

The last function you will learn to use is delete_user_meta(), which returns true if successful and false otherwise (for instance, when the metadata key could not be found in the database). Its syntax follows:

<?php
delete_user_meta( $user_id, $meta_key, $meta_value )
?>

You can match records based on key only, or on key and value, to deal with duplicate metadata keys. When you know the metadata key is unique, you can omit the third parameter:

<?php
delete_user_meta( 3, 'boj_adminlang_lang' );
?>

If the metadata key is not unique, as in the example with the book title, you can specify which record to delete or simply delete all records with that key:

<?php
// Delete one record:
delete_user_meta( 3, 'books', 'I Love WordPress' );

// Delete all records:
delete_user_meta( 3, 'books' );
?>

You have been reading about user IDs and have been using 3 in previous examples, but how do you get the current user ID?

Some actions and filters in WordPress pass the current user ID as an argument, as you see when you build your bilingual plugin from the ground up. If the current user ID is not known, use the following code:

<?php
$user = wp_get_current_user();
$userid = $user->ID;
?>

In this code, $user becomes an object containing all known data about the current user: login name, email, privileges in the admin area, Visual Editor preference, metadata, and so on. One of the properties of this object is ID, which is the integer you are looking for.

Because you are going to store per-user settings, it would not make sense to make a global plugin option page. Instead, you can add an input field to every user's Profile page. Profile pages trigger several actions to which you can hook if you want to add content to the page:

Now you can add a simple drop-down list from which to choose between English or Español in the "Personal Options" section:

<?php
// Add and fill an extra input field to user's profile
function boj_adminlang_display_field( $user ) {
    $userid = $user->ID;
    $lang = get_user_meta( $userid, 'boj_adminlang_lang', true );
    ?>

    <tr>
        <th scope="row">Language</th>
        <td>
        <select name="boj_adminlang_lang">
        <option value=""
            <?php selected( '', $lang); ?> >English</option>
        <option value="es_ES"
            <?php selected( 'es_ES', $lang); ?> >Spanish</option>
        </select>
        </td>
    </tr>

    <?php
}
// Trigger this function on 'personal_options' action
add_action( 'personal_options', 'boj_adminlang_display_field' );
?>

The action 'personal_options' passes to your custom function boj_adminlang_display_field() the user object. Your function gets the user ID, the language preference from the user's metadata, and then outputs the HTML that adds the select input field, as shown in Figure 7-6.

The input field uses WordPress' function selected() to automatically select the appropriate option, as per user choice if previously saved.

Figure 7.6. FIGURE 7-6

On profile pages, you need to monitor form submissions and verify if the user entered any custom metadata. To do so, you can rely on action 'personal_options_update' and check the $_POST data:

<?php
// Monitor form submits and update user's setting if applicable
function boj_adminlang_update_field( $userid ) {
    if( isset( $_POST['boj_adminlang_lang'] ) ) {
        $lang = $_POST['boj_adminlang_lang'] == 'es_ES' ? 'es_ES' : '';
        update_user_meta( $userid, 'boj_adminlang_lang', $lang );
    }
}
add_action( 'personal_options_update', 'boj_adminlang_update_field' );
?>

The plugin is now finished in its visible part: A custom field on every user's Profile page asks for and saves a preference setting.

Notice how you used a ternary operator for shorter code. The following single line:

<?php
$lang = $_POST['boj_adminlang_lang'] == 'es_ES' ? 'es_ES' : '';
?>

is equivalent to the longer structure:

<?php
if( $_POST['boj_adminlang_lang'] == 'es_ES' ) {
    $lang = 'es_ES';
} else {
    $lang = '';
}?>

Now you just need to make sure the admin area is actually translated as the user wants. Whenever WordPress needs to know what language to use, its internal function get_locale() returns the locale, after applying a filter. From WordPress' source, file wp-includes/l10n.php:

<?php
return apply_filters( 'locale', $locale );
?>

What you need to do is hook into this filter and return the locale as stored in the user's metadata. The entire plugin, complete with this function and its header, will look like this:

<?php
/*
Plugin Name: Per User Setting example
Plugin URI: http://example.com/

Description: Allow choosing either English or Spanish in the admin area
Author: WROX
Author URI: http://wrox.com
*/

// Return user's locale
function boj_adminlang_set_user_locale() {
    $user = wp_get_current_user();
    $userid = $user->ID;
    $locale = get_user_meta( $userid, 'boj_adminlang_lang', true );
    return $locale;
}
// Trigger this function every time WP checks the locale value
add_filter( 'locale', 'boj_adminlang_set_user_locale' );

// Add and fill an extra input field to user's profile
function boj_adminlang_display_field( $user ) {
    $userid = $user->ID;
    $lang = get_user_meta( $userid, 'boj_adminlang_lang', true );
    ?>

    <tr>
    <th scope="row">Language</th>
        <td>
        <select name="boj_adminlang_lang">
        <option value=""
            <?php selected( '', $lang); ?> >English</option>
        <option value="es_ES"
            <?php selected( 'es_ES', $lang); ?> >Spanish</option>
        </select>
        </td>
    </tr>

    <?php
}
add_action( 'personal_options', 'boj_adminlang_display_field' );
// Monitor form submits and update user's setting if applicable
function boj_adminlang_update_field( $userid ) {
    if( isset( $_POST['boj_adminlang_lang'] ) ) {
        $lang = $_POST['boj_adminlang_lang'] == 'es_ES' ? 'es_ES' : '';
        update_user_meta( $userid, 'boj_adminlang_lang', $lang );
    }
}
add_action( 'personal_options_update', 'boj_adminlang_update_field' );
?>

Code snippet plugin4-per-user-option.php

Now activate the plugin, pick the Spanish option and... ¡ole!, your blog now speaks Spanish, as shown in Figure 7-7.

Figure 7.7. FIGURE 7-7

If you want a plugin to store per-user settings, make sure it includes the following attributes:

Visual integration — Because you add content to Profile pages, such content must match the look and feel of the original WordPress interface. Use proper HTML and classes, as in the plugin example. More than ever your plugin settings will look like core settings because you won't create an extra administration page, so make it integrate impeccably.

Wise implementation — Sometimes it makes more sense to have a standalone plugin option page, or to add a few options to the WordPress Settings page, with global settings instead of per-user settings. Most WordPress blogs are single-user blogs, where people may not head to their Profile to check for new settings.

Following are two types of records you can store:

Setup information is typically plugin options: Users configure and save some settings the first time they install a plugin; they might modify these settings in the future, but the number of records won't grow. This is typically what needs to be stored in the Options table.

Collected data is information added as the users continue to use their blog. This data might be related to posts, comments, or any WordPress component. Data expanding over time might be appropriate candidates for a custom table.

WordPress installs 11 tables, and specifically tables that are more likely to store a lot of custom data; default names are as follows:

Not only can these tables store practically everything you need to store, but they all also have convenient API functions to save and get data. Try to make a connection between information you want to store and a metadata table.

Sometimes you need to think outside of the box to realize that a particular table will be just fine for your data. Consider for instance the wp_post table with stored custom menus, which at first you probably wouldn't have considered a particular post type.

This cannot be emphasized enough: In 99% of the cases, these tables will suffice, and most of the time you will store data in the options table.

Imagine a statistics plugin that can store the IP address and timestamp of every visitor on your blog. This plugin would need a custom table with three fields, as shown in Table 7-2.

The SQL statement to create such a table structure follows:

CREATE TABLE 'wp_hits' (
    'hit_id' INT( 11 ) NOT NULL AUTO_INCREMENT,
    'chitin' VARCHAR( 100 ) NOT NULL ,
    'hit_date' DATETIME
);

You now can use a powerful built-in WordPress tool: function dbDelta(). This function is not loaded by default, so you need to manually include it in your plugin. Now create your custom table:

<?php
$tablename = $wpdb->prefix . "hits";

$sql = "CREATE TABLE '$tablename' (
    'hit_id' INT( 11 ) NOT NULL AUTO_INCREMENT,
    'hit_ip' VARCHAR( 100 ) NOT NULL ,
    'hit_date' DATETIME
);";

require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

dbDelta($sql);
?>

What you have just done follows:

<?php
$tablename = $wpdb->prefix . "hits";

if( $wpdb->get_var("SHOW TABLES LIKE '$tablename'") != $tablename ) {
    // table does not exist!
}
?>

The power of function dbDelta() resides in its capability to update a table with the same syntax used to create it: It examines the current table structure if found, compares it to the desired table structure, and either adds or modifies the table as required.

This can make your code much easier to maintain: The install and the upgrade functions actually share this one function call.

Back to your statistics plugin: You can now add a fourth field to hold the WordPress post ID that has been visited. You can also improve the table structure with a primary key on first field hit_id.

Following is a complete create and upgrade function:

<?php
// Create / Update the custom table
function boj_hits_create_table() {
    global $wpdb;


    $tablename = $wpdb->prefix . "hits";

    $sql = "CREATE TABLE '$tablename' (
          'hit_id' int(11) NOT NULL AUTO_INCREMENT,
          'hit_ip' varchar(100) NOT NULL,
          'hit_date' datetime,
          'post_id' int(11) NOT NULL,
          PRIMARY KEY ('hit_id')
        );";

    require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

    dbDelta($sql);
}?>

Function dbDelta() can be tricky to use. MySQL's tolerance for syntax errors or approximations is limited, and so is dbDelta(), which is basically a wrapper function. It takes a single space (missing or extra) to fail the function call and sometimes to fail silently.

Watching Your SQL Syntax and Style

dbDelta() is touchy and needs the SQL statement to be formatted with care:

• Put each field on its own line in your SQL statement.

• Use the key word KEY rather than its synonym INDEX.

• Don't use extra spaces between MySQL keywords.

The simplest way to make sure your SQL statement is cleanly formatted is to design your table in a tool such as phpMyAdmin (see Chapter 18, "The Developer Toolbox") and then export your table structure, as shown in Figure 7-8. The SQL generated will generally be formatted and indented in a suitable way for dbDelta().

Figure 7.8. FIGURE 7-8

<?php
require('./wp-load.php');
?>
<pre>
<?php
$wpdb->show_errors();

$tablename = $wpdb->prefix . "hits";

$sql = "CREATE TABLE '$tablename' (
    'hit_id' int(11) NOT NULL AUTO_INCREMENT,
    'hit_ip' varchar(100) NOT NULL,
    'hit_date' datetime,
    'post_id' int(11) NOT NULL,
    PRIMARY KEY ('hit_id')
);";
require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

var_dump( dbDelta($sql) );

$wpdb->print_error();
?>
</pre>

Array
(
    ['wpb_hits'] => Created table 'wpb_hits'
)

<?php
// Execute statement and print execution result
var_dump( dbDelta( $sql ) );

// Test-run statement without executing it, and print result
var_dump( dbDelta( $sql, false ) );
?>

Now that your custom table is created, you can access it using the global $wpdb object. The following code snippet shows standard SQL queries:

<?php

$tablename = $wpdb->prefix . "hits";

// Insert a record
$newdata = array(
    'hit_ip' => '127.0.0.1',
    'hit_date' => current_time( 'mysql' ),
    'post_id' => '123'
);
$wpdb->insert(
    $tablename,
    $newdata
);

// Update a record
$newdata = array( 'post_id' => '456' );
$where   = array( 'post_id' => '123', 'hit_id' => 1 );
$wpdb->update( $tablename, $newdata, $where );


?>

Refer to Chapter 6 to learn how to use the wpdb class in detail.

WordPress has many functions for working with users. In this section, you learn how to use some of these basic functions.

<?php

add_action( 'wp_footer', 'boj_footer_user_logged_in' );

function boj_footer_user_logged_in() {

    if ( is_user_logged_in() )

echo 'You are currently logged into this site.';

    else
        echo 'You are not logged into the site.';
}

?>

<?php
get_users( $args );
?>

<?php
/*
Plugin Name: User Avatars
Plugin URI: http://example.com
Description: Displays user avatars based on role.
Author: WROX
Author URI: http://wrox.com
*/

function boj_user_avatars( $role = 'subscriber' ) {

    /* Get the users based on role. */
    $users = get_users(
        array(
            'role' => $role
        )
    );

    /* Check if any users were returned. */
    if ( is_array( $users ) ) {

        /* Loop through each user. */
        foreach ( $users as $user ) {

            /* Display the user's avatar. */
            echo get_avatar( $user );
        }
    }
}

?>

<?php
boj_user_avatars( 'editor' );
?>

<?php
get_users_of_blog( $id );
?>

<?php

function boj_list_users_of_blog() {

    /* Get the users of the current blog. */
    $users = get_users_of_blog();

    /* Check if users are returned. */
    if ( !empty( $users ) ) {

        /* Open the users list. */
        echo '<ul class="users-list">';

        /* Loop through each user returned. */
        foreach ( $users as $user ) {

            /* Create a list item linking to the user archive page. */
            echo '<li><a href="' . get_author_posts_url( $user->ID ) . '">';
            echo get_the_author_meta( 'display_name', $user->ID );
            echo '</a></li>';
        }

        /* Close the users list. */
        echo '</ul>';
    }
}

?>

<?php boj_list_users_of_blog(); ?>

<?php

/* Get the user counts. */
$user_count = count_users();

/* Open an unordered list. */
echo '<ul class="user-counts">';

/* List the total number of users. */
echo '<li>Total users: ' . $user_count['total_users'] . '</li>';

/* Loop through each of the roles. */
foreach ( $user_count['avail_roles'] as $role => $count ) {

    /* List the role and its number of users. */
    echo '<li>' . $role . ': ' . $count . '</li>';
}

/* Close the unordered list. */
echo '</ul>';

?>

WordPress has a built-in user interface for creating, updating, and deleting users that most people will use. However, you may find yourself in a situation where you would need to create a plugin that handles these things outside of the normal WordPress interface.

Following are some examples of reasons why you need to code a plugin to handle this:

As you should see by now, there can be many reasons for stepping outside of the standard WordPress interface for handling users. Although you won't be using the standard interface, you will be using standard functions that WordPress has conveniently provided for doing these types of things.

<?php
wp_insert_user( $userdata );
?>

<?php
/*
Plugin Name: Insert User
Plugin URI: http://example.com
Description: Plugin that inserts a user.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Insert the new user on the 'init' hook. */
add_action( 'init', 'boj_insert_user' );

/* Inserts a new user. */
function boj_insert_user() {

    /* Do nothing if the 'wrox' username exists. */
    if ( username_exists( 'wrox' ) )
        return;

    /* Set up the user data. */
    $userdata = array(
        'user_login' => 'wrox',
        'user_email' => 'wrox@example.com',
        'user_pass' => '123456789',
        'user_url' => 'http://example.com',
        'display_name' => 'Wrox',
        'description' => 'Loves to publish awesome books on WordPress!',
        'role' => 'editor'
    );

    /* Create the user. */
    $user = wp_insert_user( $userdata );

    /* If the user wasn't created, display the error message. */
    if ( is_wp_error( $user ) )
        echo $result->get_error_message();
}

?>

<?php
wp_create_user( $username, $password, $email );
?>

<?php
/*
Plugin Name: Create User
Plugin URI: http://example.com
Description: Plugin that creates a user.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Create the new user on the 'init' hook. */
add_action( 'init', 'boj_create_user' );

/* Creates a new user. */
function boj_create_user() {

    /* Do nothing if the 'wrox2' username exists. */
    if ( username_exists( 'wrox2' ) )
        return;

    /* Create the 'wrox2' user. */
    wp_create_user(
        'wrox2',
        '123456789',
        'wrox2@example.com'
    );
}

?>

<?php
wp_update_user( $userdata );
?>

<?php
/*
Plugin Name: Force Admin Color
Plugin URI: http://example.com
Description: Forces the 'fresh' admin color scheme.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Only load change the color scheme in the admin. */
add_action( 'admin_init', 'boj_force_admin_color' );

/* Forces the current user to use the 'fresh' admin color. */
function boj_force_admin_color() {

    /* Get the current user object. */
    $user = wp_get_current_user();

    /* If the $user variable is not empty, continue. */
    if ( !empty( $user ) ) {

        /* Get the user's admin color scheme. */
        $admin_color = get_user_meta( $user->ID, 'admin_color', true );

        /* If the admin color is not 'fresh', change it. */
        if ( $admin_color !== 'fresh' ) {

            /* Set up the user data. */
            $userdata = array(
                'ID' => $user->ID,
                'admin_color' => 'fresh'
            );

            /* Update the user. */

wp_update_user( $userdata );
        }
    }
}

?>

<?php
wp_delete_user( $user_id, $reassign );
?>

<?php

/* Delete user 100 and assign posts to user 1. */
wp_delete_user( 100, 1 );

?>

User data in WordPress is saved in two different tables in the database: $wpdb->users and $wpdb->usermeta. The users table saves information about the user that WordPress needs to function. The usermeta table is for storing additional metadata about users. You sometimes need to load, create, update, and delete this data within your plugins.

When working with user data from the users table, you work with a few different values set for every user on the site.

<?php
function boj_display_user_website( $user_id ) {

    /* Get the user data. */
    $data = get_userdata( $user_id );

    /* Check if data was returned. */
    if ( !empty( $data ) ) {

        /* Check if a URL has been given. */
        if ( !empty( $data->user_url ) ) {

            /* Display the user display name and URL. */
            echo $data->display_name . ': ' . $data->user_url;
        }
}

?>

<?php
boj_display_user_website( 100 );
?>

<?php

/* Display user welcome message in the admin footer. */
add_action( 'in_admin_footer', 'boj_user_welcome_message' );

function boj_user_welcome_message() {

    /* Get the current user's data. */
    $data = wp_get_current_user();

    /* Display a message for the user. */
    echo "Hello, {$data->display_name}.<br />";
}

?>

<?php
/*
Plugin Name: User Registration Date
Plugin URI: http://example.com
Description: Displays user's registration date in admin footer.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Display user registration date in the admin footer. */

add_action( 'in_admin_footer', 'boj_display_user_registration_date' );

function boj_display_user_registration_date() {

    /* Globalize the $current_user variable. */
    global $current_user;

    /* Call the current user function. */
    get_currentuserinfo();

    /* Format user registration date. */
    $date = mysql2date( 'F j, Y', $current_user->user_registered );

    /* Display the user's registration date. */
    echo "You registered on {$date}.<br />";
}

?>

<?php
/*
Plugin Name: User Ratings
Plugin URI: http://example.com
Description: Updates user rating based on number of posts.
Version: 0.1
Author: WROX
Author URI: http://wrox.com
*/

/* Only update the user rating when a post is saved. */
add_action( 'save_post', 'boj_add_user_rating' );

function boj_add_user_rating() {

    /* Get the current user. */

$user = wp_get_current_user();

    /* Get the current user rating. */
    $rating = get_user_meta( $user->ID, 'user_rating', true );

    /* If user already has 'gold' rating, do nothing. */
    if ( 'gold' == $rating )
        return;

    /* Get the user's post count. */
    $posts = count_user_posts( $user->ID );

    /* Check if the number of posts is equal to or greater than 50. */
    if ( 50 <= $posts ) {

        /* Give the user a 'gold' rating. */
        update_user_meta( $user->ID, 'user_rating', 'gold' );
    }

    /* Check if the number of posts is equal to or greater than 25. */
    elseif ( 25 <= $posts ) {

        /* Give the user a 'silver' rating. */
        update_user_meta( $user->ID, 'user_rating', 'silver' );
    }
}

?>

<?php

function boj_list_users_posts_counts( $user_ids = array() ) {

    /* Make sure user IDs were given. */
    if ( empty( $user_ids ) )

return '';

    /* Get the post counts for the users. */
    $users_counts = count_many_users_posts( $user_ids );

    /* Open an unordered list. */
    echo '<ul class="users-posts-counts">';

    /* Loop through each of the user counts. */
    foreach ( $users_counts as $user => $count ) {

        /* Display a message with user ID and post count. */
        echo "<li>The user with an ID of {$user} has {$count} posts.</li>";
    }

    /* Close the unordered list. */
    echo '</ul>';
}

?>

<?php boj_list_users_posts_counts( array( 100, 200, 300 ) ); ?>

User metadata is data about the user that is saved in the $wpdb->usermeta table in the database. This is additional data that plugins can add about the user outside of the predefined WordPress fields in the $wpdb->users table.

This type of data can be anything you need to develop user-based settings for your plugin. This data is saved in key/value pairs; however, a single key may have multiple values. Meta keys are a way to represent the information provided by the meta values. Think of them as a human-readable ID that represents the information you're working with. Meta values are the pieces of data you retrieved based on the given meta key.

Metadata can literally be any type of data you want to save for the user. Some examples include the following:

This section focuses on adding, displaying, updating, and deleting specific data for a user. This can enable you to see how the user meta functions work when manipulating data.

You work with a user ID of 100 and a meta key of favorite_books. This meta key saves the values of the user's three favorite books.

<?php
add_user_meta( $user_id, $meta_key, $meta_value, $unique );
?>

<?php

add_user_meta( 100, 'favorite_books', 'WordPress Dev Champ', false );
add_user_meta( 100, 'favorite_books', 'WordPress Lazy Coder', false );
add_user_meta( 100, 'favorite_books', 'WordPress The Hard Way', false );

?>

<?php
get_user_meta( $user_id, $meta_key, $single );
?>

<?php

/* Get the user's favorite books. */
$favorite_books = get_user_meta( 100, 'favorite_books', false );

/* Check if there are any favorite books. */
if ( !empty( $favorite_books ) ) {

    /* Open an unordered list. */
    echo '<ul class="favorite-books">';

    /* Loop through each of the books. */
    foreach ( $favorite_books as $book ) {

        /* Display the book name. */
        echo '<li>' . $book . '</li>';
    }
}

?>

<?php

/* Get the user's favorite book (single book). */
$favorite_book = get_user_meta( 100, 'favorite_books', true );

/* Display the favorite book. */
echo $favorite_book;

?>

<?php
update_user_meta( $user_id, $meta_key, $meta_value, $prev_value );
?>

<?php

update_user_meta(
    100,
    'favorite_books',
    'WordPress Design Champ',
    'WordPress Dev Champ'
);

?>

<?php

update_user_meta( 100, 'favorite_books', 'WordPress Design Champ' );

?>

<?php
delete_user_meta( $user_id, $meta_key, $meta_value = '' );
?>

<?php

delete_user_meta( 100, 'favorite_books', 'WordPress Lazy Coder' );

?>

<?php

delete_user_meta( 100, 'favorite_books' );

?>

user_contactmethods

user_contactmethods is a hook (Chapter 3, "Hooks"), not a function like what this chapter has focused on. It is important because it's a quick method for adding user metadata for alternative contact methods such as a Twitter username, Facebook profile, or phone numbers.

It enables you to create additional fields on the user edit screen with a few lines of code. By default, WordPress adds five methods. The last three are metadata as covered in this section of the chapter:

• Email

• Website

• AIM

• Yahoo IM

• Jabber/Google Talk

The user_contactmethods filter hook returns an array of meta keys and labels for these label keys. To add new meta keys, you need to add new values to the array, as shown in the next code.

<?php
/*
Plugin Name: User Contact Methods
Plugin URI: http://example.com
Description: Additional user contact methods.
Author: WROX
Author URI: http://wrox.com
*/

/* Add a filter to the hook. */
add_filter( 'user_contactmethods', 'boj_user_contactmethods' );

/* Function for adding new contact methods. */
function boj_user_contactmethods( $user_contactmethods ) {

    /* Add the Twitter contact method. */
    $user_contactmethods['twitter'] = 'Twitter Username';

    /* Add the phone number contact method. */

$user_contactmethods['phone'] = 'Phone Number';

    /* Return the array with the new values added. */
    return $user_contactmethods;
}

?>

Code snippet boj-user-contact-methods.php

This adds the extra fields to the contact info section of the user profile screen, as shown in Figure 8-1.

Figure 8.1. FIGURE 8-1

WordPress handles all the heavy lifting of adding, updating, and deleting the metadata in the admin. To retrieve these values, use the get_user_meta() function covered earlier in this section.

Creating a Plugin with User Metadata

Now that you've learned how to manipulate user metadata, it's time to use that knowledge for a practical test. In many cases, custom user metadata your plugin might use needs to be set by the user from the user's profile page.

What you will do is build a plugin that adds an extra section to the user edit screen in the WordPress admin. This form will have a select box of the site's blog posts. The users can select one of these posts as their favorite.

The first step would be to create a new file in your plugin directory with a filename boj-user-favorite-post.php. You would then need to create the plugin header and add the form to the user edit page.

<?php
/*
Plugin Name: User Favorite Post
Plugin URI: http://example.com
Description: Allows users to select their favorite post from the site.
Version: 0.1

Author: WROX
Author URI: http://wrox.com
*/

/* Add the post form to the user/profile edit page in the admin. */
add_action( 'show_user_profile', 'boj_user_favorite_post_form' );
add_action( 'edit_user_profile', 'boj_user_favorite_post_form' );

/* Function for displaying an extra form on the user edit page. */
function boj_user_favorite_post_form( $user ) {

    /* Get the current user's favorite post. */
    $favorite_post = get_user_meta( $user->ID, 'favorite_post', true );

    /* Get a list of all the posts. */
    $posts = get_posts( array( 'numberposts' => −1 ) );
    ?>

    <h3>Favorites</h3>

    <table class="form-table">

        <tr>
            <th><label for="favorite_post">Favorite Post</label></th>

            <td>
                <select name="favorite_post" id="favorite_post">
                    <option value=""></option>

                <?php foreach ( $posts as $post ) { ?>
                    <option value="<?php echo esc_attr( $post->ID ); ?>"
                    <?php selected( $favorite_post, $post->ID ); ?>>
                        <?php echo esc_html( $post->post_title ); ?>
                    </option>
                <?php } ?>

                </select>
                <br />
                <span class="description">Select your favorite post.</span>
            </td>
        </tr>

    </table>
<?php }

Code snippet boj-user-favorite-post.php

This gives you an extra section on the user edit page, as shown in Figure 8-2.

Figure 8.2. FIGURE 8-2

The form is only displayed at this point. The next step would be to save the user's favorite post as metadata.

/* Add the update function to the user update hooks. */
add_action( 'personal_options_update', 'boj_user_favorite_post_update' );
add_action( 'edit_user_profile_update', 'boj_user_favorite_post_update' );

/* Function for updating the user's favorite post. */
function boj_user_favorite_post_update( $user_id ) {

    /* Check if the current user has permission to edit the user. */
    if ( !current_user_can( 'edit_user', $user_id ) )
        return false;

    /* Only accept numbers 0-9 since it's a post ID. */
    $favorite_post = preg_replace( "/[^0-9]/", '', $_POST['favorite_post'] );

    /* Update the user's favorite post. */
    update_user_meta( $user_id, 'favorite_post', $favorite_post );
}

?>

Code snippet boj-user-favorite-post.php

The plugin is complete at this point. However, this information is saved only in the database and shown on the user's profile screen in the admin. If you want to show the user's favorite post, you need to use the get_user_meta() function to pull the information from the database.

With the following code, you get the favorite post selected by a user with the ID of 100 and display its title. Because the post ID is the saved meta value, you need to use the get_post() function to retrieve additional information about the post, such as the post title.

<?php

/* Get the user's favorite post (ID). */
$favorite_post = get_user_meta( 100, 'favorite_post', true );

/* Check if the favorite post is set. */
if ( !empty( $favorite_post ) ) {

    /* Get the post object based on the post ID. */
    $post = get_post( $favorite_post );

    /* Display the post title. */
    echo $post->post_title;
}

?>

Roles are what users are grouped by in WordPress. They're a way of giving a label to various sets of users. One of the most important things to note is that roles are not hierarchical. For example, an administrator is not necessarily "higher" than an editor. Roles are merely defined by what the role can and can't do. It's a permissions system.

Capabilities are that permissions system. Roles are assigned capabilities that define what that role can or can't do. These can be set up with the WordPress defaults or be completely custom, depending on the site. As a plugin developer, you can't make too many assumptions about what certain roles have permission to do.

Imagine having to define what individual users could do on a site with thousands of users, each user having a custom set of permissions. It'd be nearly impossible to maintain. Roles enable you to group users into distinguishable sets, each group with its own permissions.

Understanding how users, roles, and capabilities work and their relationship to one another is an important aspect of plugin development.

In general, most plugins won't need to know what roles users have. Most plugins work directly with capabilities because they are what define whether a user has permission to perform a task within the site.

WordPress ships with five default roles, which work well for most installs. Although roles are not hierarchical, the default roles do set up what appears to be a hierarchical system.

This list is a general overview of the default roles. Even though these are the defaults, plugin users can install role management plugins that enable them to change what each role can do.

WordPress allows custom roles, which can be created by plugins and themes. There is no user interface in WordPress for creating custom roles; however, several role management plugins exist that enable users to create new roles for their site.

Therefore, as a plugin developer, you can never know exactly what roles exist or might exist for a site unless you have direct access to the install, such as when doing client work. Keep this in mind when developing your plugins.

You may be faced with the task of creating custom roles in your plugins as well. Imagine that you were creating a plugin that implemented a forum within a WordPress install. Because WordPress wouldn't know how to manage a forum, you would have to define these custom roles within your plugin. Some example roles for a forum might include the following:

See the "Customizing Roles" section later in this chapter for more details on creating custom roles.

When you check a user's permissions, you're checking if a user's role has been granted a specific capability or if the user is given a meta capability for a specific object. Plugins won't need to deal with meta capabilities in most cases, but there are instances in which meta capabilities are needed.

<?php
current_user_can( $capability, $args );
?>

<?php

/* Check if the current user can edit posts. */
if ( current_user_can( 'edit_posts' ) ) {

    /* Link to the edit posts page in the admin. */
    echo '<a href="' . admin_url( 'edit.php' ) . '">Edit Posts</a>';
}

?>

<?php

/* Check if the current user can edit the specific post. */
if ( current_user_can( 'edit_post', 100 ) {

    /* Update the post meta. */
    update_post_meta( 100, 'boj_example_meta', 'Example' );
}

?>

<?php
current_user_can_for_blog( $blog_id, $capability );
?>

<?php
author_can( $post, $capability );
?>