To create and add a nonce to a URL, just like in the previous example with links deleting a post, use function wp_nonce_url() as follows:

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

The first parameter $url is a string of the URL address to which you want to append a nonce in the query string. The links in the Unused Tags plugin to delete a link will be of the form http://example.com/wp-admin/edit.php?page=boj_utags&boj_action=delete&id=6; in this URL notice the parameter boj_action and the tag ID.

The second parameter $action is the string with which you make the nonce specific to one action and one object. The link you want to protect with a nonce here is tied to the action "delete" and the tag id 6, so the $action parameter could be 'boj_utags-delete_tag6'.

To sum it up, in your plugin, given a tag ID $id, the code to generate a nonce protected URL to delete this tag will be the following:

<?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

To craft the delete link, you have used the handy function add_query_arg(), which adds to the current URL the query parameters defined in its array parameter. In other words, it adds ?boj_action=delete&id=6, or &boj_action=delete&id=6 if the current URL already has a query string.

Nonces also protect forms, with function wp_nonce_field(). This function needs a single string parameter, the nonce action plugin-action_object.

Given the $name and $id of a post tag, the proper form to allow renaming it follows:

<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>

Notice how you used a new function named esc_attr() here: It is to ensure that, should $name contain quotes, it will not break the display and the form. You learn all about this in the next section about data sanitization.

Adding nonces to URLs or forms is only the first part of the job: On the other end, the function that executes the expected operation needs to verify before that the nonce is valid and tied to that operation.

The function you use is named check_admin_referer(): It authenticates the nonce, silently does nothing if valid, or dies with an "Are you sure" error screen, as shown in Figure 6-2. This function must be called before any output is sent to the screen.

In your plugin, parameters such as the action or the tag ID are either passed via GET (the URL query string) or POST (the submitted form): Instead of checking both arrays $_GET and $_POST, you simply examine $_REQUEST to get the parameter values.

The complete code block to check nonces and then rename or delete a post tag follows:

<?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;
}
?>

Notice how you first check user permissions: Nonces check a user's intention, but you still need to validate their authority.

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:

Most of the time, PHP functions such as intval() or is_int() can do the job:

<?php
$data = 43;

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

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

WordPress's function absint() is also applicable whenever you want a positive integer, such as an age.

The possible problem you may run into is when dealing with large numbers: 32-bit systems have a maximum signed integer range of −2147483648 to 2147483647. So for example on such a system, intval('1000000000000') will return 2147483647. On the same principle, the maximum signed integer value for 64-bit systems is 9223372036854775807.

If you have to deal with large numbers, your best bet is to consider the data a string instead of an integer, and make sure it consists only of digits:

<?php
$num = '100000000000000000';

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

Note that the ctype library may not be available on all servers. Before using it for a particular client, check that their server supports it.

You often need to validate text strings of arbitrary length, such as a username or a country of birth. PHP functions of the ctype_ family are fine for validating them. They return Boolean true or false.

If you are expecting only letters:

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

If you are expecting alphanumeric strings, such as for a nickname (for example, "Bob43"):

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

Text strings can also consist of special characters such as punctuation. WordPress offers a function that is handy to sanitize general text strings from user input: sanitize_text_field(). This function removes invalid UTF-8 characters, converts single < into HTML entities, and removes all HTML tags, line breaks, and extra white space.

<?php

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

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

?>

In a less destructive manner, you may want to simply strip HTML tags but keep other formatting such as line breaks. WordPress provides wp_strip_all_tags() because PHP's built-in strip_tags() does not properly filter out complex markup such as <script></script> as you can see in the following example:

<?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"
?>

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:

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

Occasionally you need to validate or sanitize text strings that adhere to a predefined and known pattern, such as dates of birth, credit card numbers, ZIP codes, or telephone numbers.

<?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
}
?>

Emails are a type of pattern text string that is easy to validate or sanitize within WordPress, thanks to functions is_email() and sanitize_email():

<?php

$email = 'wrox@example.com';

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

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

Function is_email() returns either false or the email address if valid. Consider the following examples:

<?php

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

var_dump( is_email( 'wrox@example.com' ) );
// string(11) "wrox@example.com"
?>

To use this function, you need to strictly compare an email and the result of is_email():

<?php

if( is_email( $email ) === email ) {
    // email seems valid
} else {
    // email is invalid
}
?>

Be aware that in a LAN environment and some corporate networks, possibly functional email addresses such as admin@localhost or webmaster@server will not be considered valid. In such a case, you can simply check for the presence of the @ character, or maybe if possible test against a finite list of valid email addresses.

Function sanitize_email() either returns an empty string or a sanitized email address, depending on how malformed the input was. Consider the following sample outputs:

<?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"
?>

In any case, you should compare the sanitized emails with the original input, and if different ask the users to confirm their address.

Note that these functions do not check whether the email is actually an existing address, but only whether the pattern looks correct: one or more allowed characters, an at sign @, more characters, a dot, and again a few characters for the top-level domain. A blatantly fake email address such as kk@kk.kk will pass the test.

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.

<?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>"

?>

<?php

$allowed = array(
    'strong' => array(),
    'a'      => array(
        'href'  => array(),
        'title' => array()
    )
);
?>

<?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>"
?>

<?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.

Whether they are used as output in an HTML attribute node (<a href="">) or as standalone information (for example a field asking for a site URL in a form), URLs should be sanitized for input and output using WordPress' function esc_url(). This function checks and cleans a URL by removing unacceptable characters and optionally filtering protocols.

For output, use the function as following:

<?php
// dangerous URL
$url = 'javascript:alert("XSS");';
?>

<a href="<?php echo esc_url( $url ); ?> ">Link Text</a>

In this example, the link would be safely displayed with an empty href attribute. For input, pass either one parameter (the URL) or two parameters (the URL and an array of allowed protocols) to sanitize data before storing or returning it.

In the following example, see how various URLs are sanitized:

<?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/"
?>

As you can see, the purpose of function esc_url() is not to make sure a URL is valid (for instance, http://onmouseover=alert('XSS') does not look like one) but to sanitize it drastically so that it is harmless when used.

With a second array parameter, this function is also great at limiting the protocols you want to authorize:

<?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" );
?>

Inline JavaScript (such as onclick="doSomething();" for example) is another type of HTML node attribute that gets particular treatment and its own sanitization function: esc_js().

You can use this function to ensure that JavaScript snippets using dynamic variables from PHP will not break, as in the following example:

<?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>

Notice how this neat example uses different esc_ functions to sanitize the various parts of the "delete" link.

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().

Just as you must not trust $_GET or $_POST, be suspicious toward the $_COOKIE array. Indeed, cookies are simple text files stored on the client's computer and as such easy to edit with tools such as Firebug for Firefox. Give cookies the same treatment as data from a submitted form: Validate and sanitize values.

You can easily validate or sanitize an array of similar data using PHP's function array_map().

Imagine for instance a form where a user has to enter several positive integers (age, number of children, and household income). To sanitize this information, you need absint(). You can process each data one by one, or use this more compact and efficient code:

<?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'];
?>

This technique is particularly useful when you don't know how many values you need to sanitize. Picture a form textarea field in which you would ask users to enter a list of URLs, such as their favorite sites, one per line.

To sanitize such a list, you can split it into individual URLs and pass the resulting array to esc_url() all at once:

<?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 );
?>

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.

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 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.

This method needs three parameters:

You can optionally pass two other parameters:

To exemplify the usage of this function, imagine a table named wp_custom with a simple structure, as in Table 6-1:

You can now update a row of table wp_custom, where the ID is 1, the value in the second column is a string, and the value in the third column is an integer:

<?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 );
?>

As you can see, this method grants a structured way to declare the SQL query, in particular the format of the data to sanitize. The method returns either false on error, or an integer with the number of rows affected by the update.

You can use this method to insert data in a similar operation, with three parameters:

Use this method to insert in a row in the same $wpdb->custom table, the first field being a string and the second one being an integer:

<?php

$values = array(
    'column1' => 'new string',
    'column2' => 44
);

$formats_values = array( '%s', '%d' );

$wpdb->insert( $wpdb->custom, $values, $formats_values );
?>

Similarly to the update() method, this function also returns false on error or an integer for the number of rows inserted.

The get_var() method returns a single variable from WordPress' database (or NULL if no value is found).

For instance, to fetch the number of posts you have published on your blog, you can use the following query:

<?php

$sql = "SELECT COUNT(ID) FROM {$wpdb->posts}
        WHERE post_status = 'publish' AND post_type = 'post'";

$num_of_posts = $wpdb->get_var( $sql );
?>

To fetch an entire row (or parts of a row), use method get_row(), which can return results as an object, an associative array, or a numerically indexed array. The syntax of this method follows:

<?php
$wpdb->get_row( $sql, $output_type, $row_offset );
?>

This methods requires the following parameters:

For example, fetch from the users table the email and URL of user 'admin' and compare different output types. The SQL statement for such a query follows:

<?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 );
?>

Examine now with var_dump() the nature of each result, depending on the output type selected:

<?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/"
}
*/
?>

The nature of the result can affect how you now access individual records. For instance, to get the email address of the selected user, you can use one of the three following syntax constructions:

<?php
$email = $object->user_email;

$email = $array_a['user_email'];

$email = $array_n[0];
?>

Notice how the first two syntaxes refer to 'user_email', which is the name of the column in the database.

This method can select an entire column, or part of a column, and return a dimensional array. It needs a query as first parameter and an optional column offset as second parameter, used if more than one column is returned. (The default value is zero.)

Imagine you want to send an email to all registered users of your WordPress setup, telling them the site will go temporarily offline for maintenance.

First, query the $wpdb->users table and get column 'user_email':

<?php

$sql = "SELECT 'user_email' FROM $wpdb->users";

$emails = $wpdb->get_col( $sql );
?>

Now, send the short email notice to each of these registered users:

<?php

$subject = 'Blog maintenance';
$message = 'Dear user, the blog will be offline for 15 minutes.';

foreach( $emails as $email ) {
    wp_mail( $email, $subject, $message );
}
?>

If you need to fetch generic multiple row results, you can use method get_results(). This function needs a SQL statement parameter of course, and like get_row() an optional output format between OBJECT, ARRAY_N or ARRAY_A (as discussed earlier in the "Select a Row" section).

As an example of a more complex query, use this method to get the number of posts you have published each year on your blog:

<?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 );
?>

If you use print_r( $results ), the resulting associative array will be something like the following:

Array (
    [0] => Array (
            [year] => 2010
            [posts] => 13
        )
    [1] => Array (
            [year] => 2009
            [posts] => 37
        )
    [2] => Array (
            [year] => 2008
            [posts] => 9
        )
)

To display a human readable summary of your yearly activity, you can loop over each subarray of $results, like the following:

<?php

foreach( $results as $sum ) {
    $year  = $sum['year'];
    $count = $sum['posts'];
    echo "<p>Posts published in $year: $count</p>";
}
?>

This is especially crucial in shared host environments, where hundreds of other processes may be polling data from or writing to the database at the same time. Learning how to minimize hits against the database will ensure that your plugin will not be the one blamed for abuse of resources.

Of course, common methods of the $wpdb object are not limited to SELECT statements. Any query can be processed by method query(), which returns an integer corresponding to the number of rows affected or selected, or false if an error occurred.

For illustration, you can delete all comments from your blog if they point to an unwanted website:

<?php

$sql = "DELETE from wp_comments
        WHERE comment_author_url
        LIKE '%evil.example.com%'";

$deleted = $wpdb->query( $sql );
?>

Now the variable $deleted is either false if there were an error (for instance if the table prefix is not 'wp_' and thus table 'wp_comments' does not exist) or an integer of the number of records deleted.

You can also use the query() method in place of any other method when you need more flexibility in the syntax and parameters. In this practical example, you can disable comments on all posts older than 90 days:

<?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 );
?>

As a last example, imagine a friend of yours who is also a frequent commentator on your site just moved his personal blog to another URL. You can hopefully update all comment author URLs with a single query:

<?php

$sql = "UPDATE $wpdb->comments
        SET comment_author_url =
        REPLACE( comment_author_url, 'http://oldsite/', 'http://newsite/' )";

$wpdb->query( $sql );
?>

You can turn error echoing on and off:

<?php

// On:
$wpdb->show_errors();

// Off:
$wpdb->hide_errors();
?>

You can also echo the error (if any occurred) generated by the most recent query using either the print_error() method or the last_error property:

<?php
echo $wpdb->last_error;

$wpdb->print_error();
?>

Refer to Chapter 16, which is about debugging, for more tips.

The wpdb class variable num_queries keeps record of the number of queries issued. You can also more simply use function get_num_queries(). Again, you learn more about this in Chapter 16, which is about debugging and optimizing.

Table 6-2 shows a list of other noteworthy class variables and what they contain: