Sanitising Input and Escaping Output in a Plugin

Two people report the same bug on the same afternoon. The first types a company name with an apostrophe into your settings form and it saves as O\'Brien. The second has a note in your plugin called O'Brien, types the same name into a search box, and gets no results, even though the note is sitting right there in the database. Both bugs start in the same place: the code sitting between a request and your own data.

WordPress does almost nothing to protect that gap. It does not validate the request for you, it does not sanitise it, and it adds one thing you did not ask for. That one thing is slashing, and it is the step plugin authors skip most often because nothing in the request looks wrong. The rest of this lesson is about which side of a request sanitising belongs on, and which side escaping belongs on.

Input reaches a plugin through more doors than $_POST

Superglobals are the obvious entry point and the least structured. A form handler reads $_POST, an export link reads $_GET, a REST route reads its own parameter array. Each of those needs a sanitise call before the value touches the database, an option, or a comparison.

The less obvious entries are the ones WordPress hands you already parsed, which can give you the false impression that parsing equals sanitising. A shortcode callback is called with an attribute array built by shortcode_parse_atts(). A dynamic block's render_callback is called with an attributes array that came from the saved post content, or from a REST request to the block renderer. A settings page hands your sanitize_callback whatever was posted, and the Settings API calls it for you. An admin_post_{action} handler receives nothing at all; you read the request yourself.

The rule that makes all of these tractable is to name the boundary and put sanitising exactly there. The shortcode callback is a boundary: treat its $atts as hostile even though the parser stripped whitespace for you. The REST sanitize_callback is a boundary. The admin_post_ handler is a boundary. Inside those functions a value is sanitised once; past them it is your data, and you do not sanitise it again on the way to the database.

WordPress slashes the request before your code sees it

Since 3.0, wp_magic_quotes() in wp-includes/load.php runs during startup and applies add_magic_quotes() to $_GET, $_POST, $_COOKIE and $_SERVER, then rebuilds $_REQUEST as $_GET + $_POST. Every quote, double quote and backslash in the request arrives escaped. This is not the PHP magic_quotes_gpc setting, which was removed in PHP 5.4; it is WordPress doing it deliberately so that a value can be passed to a query without further work.

That convenience is a trap for plugin code, because sanitize_text_field() does not remove the backslash. It strips tags, removes line breaks and extra whitespace, and returns the escaped string. Store that and you have stored O\'Brien. Compare it against your stored title and it will never match.

// What the plugin usually writes first.
$title = sanitize_text_field( $_POST['wpsifero_title'] ?? '' );

// What it has to write.
$title = sanitize_text_field( wp_unslash( $_POST['wpsifero_title'] ?? '' ) );

wp_unslash() is a wrapper around stripslashes_deep() and works on arrays as well as strings, so a whole $_POST array can be unslashed in one call when a handler needs many fields. Order matters: unslash first, sanitise second. Sanitising first and unslashing afterwards is worse than useless, because sanitising has already changed the string.

Some boundaries do not need it, and knowing which ones saves noise. WordPress's REST server passes wp_unslash( $_GET ) and wp_unslash( $_POST ) into the request object in class-wp-rest-server.php before any sanitize_callback runs, so a REST parameter arrives unslashed and calling wp_unslash() inside the callback is a no-op. check_admin_referer() reads $_REQUEST directly, which is why the nonce sometimes looks slashed and usually is not: nonces are hashes truncated to ten hex characters and contain no quotes. Any value you read from a superglobal yourself is slashed. The two places where that matters most in a plugin are loops over posted arrays and anything compared against stored data.

esc_html on stored data breaks the comparison that follows

This is the mistake that produces the search bug from the opening paragraph. Here is the whole of it, with the output from the plugin's own test suite underneath.

function wpsifero_notes_find_by_title( string $needle ): string {
    $notes = get_option( 'wpsifero_notes', array() );

    foreach ( $notes as $slug => $note ) {
        if ( $note['title'] === $needle ) {
            return (string) $slug;
        }
    }

    return '';
}

$posted = addslashes( "O'Brien" );   // what the request carries

wpsifero_notes_find_by_title( sanitize_text_field( $posted ) )            => ''
wpsifero_notes_find_by_title( sanitize_text_field( wp_unslash( $posted ) ) ) => 'obrien'

The escaped version compares O\'Brien against the stored O'Brien and returns nothing. There is no error, no log line and no exception: an empty result is a valid result, which is why this class of bug survives so long.

Escaping has the same property. esc_html() turns & into & and " into ", so a title escaped on the way into an option is a different string from the title the user typed, and every comparison, deduplication and sanitize_title() key computed from it is wrong in a way that only shows up on the rows containing those characters. The fix is not a better escape function. The fix is that escaping is an output operation and has no business on the write path.

The short version of the whole boundary: sanitize_* on the way in, esc_* at the moment of printing. A value that has been sanitised once and not escaped until the last possible moment is safe, comparable, and searchable. A value escaped on the way in is none of those things.

Each output context has exactly one escape function

Printing is not one operation. The function that makes a string safe inside a <div> is wrong inside an attribute, wrong inside a URL and dangerous inside a <script> block. The rule is to escape as late as possible and for the exact context the value will sit in.

The URL row is worth testing rather than remembering. esc_url() does not percent-encode a tag in a query string; it removes the angle brackets, so https://example.org/?a=1&b=<script>alert(1)</script> renders as https://example.org/?a=1&b=scriptalert(1)/script. That is safe and also not the URL the user typed, which is why a link the user pastes with a + or a bracket can come back changed. The alternative at a plugin boundary is esc_url_raw() on the way into the database and esc_url() on the way out, so the stored value is the one the user gave you.

For data going to a script, wp_localize_script() is not an escaping function and has one behaviour that ruins strings. It runs each scalar through html_entity_decode( (string) $value, ENT_QUOTES, 'UTF-8' ), so a value containing & or & arrives in JavaScript with those sequences decoded, and an array is encoded as JSON and left alone. Since 5.7, passing anything other than an array triggers a _doing_it_wrong() notice pointing at wp_add_inline_script(). The short answer for a plugin that needs a nonce and a few settings in the browser is wp_add_inline_script() with wp_json_encode( $data, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ), which is what core uses and what keeps a stored </script> from closing your tag.

wp_kses is for the subset of HTML you decided to allow

Sometimes escaping is the wrong answer because you want the user's markup to survive. A note body that may contain a link and bold text is a normal plugin requirement, and esc_html() flattens it. That is what wp_kses() is for: you pass the allowed tags and attributes, and everything else is removed.

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

$filtered = wp_kses( '<p>Read <a href="https://example.org/" onclick="steal()">this</a> now.</p>', $allowed );

// Read <a href="https://example.org/">this</a> now.

The onclick attribute disappears because it is not in the list, and the p is stripped along with any tag not named. wp_kses() also checks the protocol of every URL attribute against wp_allowed_protocols(), which is why javascript: never survives even when href is allowed. Passing the string 'post' instead of an array uses the same allowed set as a post body, and it is the right shortcut only if you actually want that set.

Two limits are worth stating plainly. wp_kses() is comparatively expensive, so do not run it on every request over a large body; filter once when the value is saved and treat the stored value as the sanitised one. And it is not a substitute for escaping the variables you print beside the filtered content. A hybrid is common and correct: wp_kses() for the body the user wrote, esc_html() for the title next to it.

function wpsifero_notes_handle_save(): void {
    $notes = get_option( 'wpsifero_notes', array() );

    foreach ( $_POST['wpsifero_notes'] as $note ) {
        $slug = sanitize_title( $note['title'] );

        $notes[ $slug ] = array(
            'title' => esc_html( $note['title'] ),
            'url'   => $note['url'],
        );
    }

    update_option( 'wpsifero_notes', $notes );

    echo '<p>Saved ' . count( $notes ) . ' notes.</p>';
}

function wpsifero_notes_handle_save(): void {
    $posted = wp_unslash( $_POST['wpsifero_notes'] ?? array() );
    $notes  = get_option( 'wpsifero_notes', array() );

    foreach ( (array) $posted as $note ) {
        $title = sanitize_text_field( $note['title'] ?? '' );

        if ( '' === $title ) {
            continue;
        }

        $notes[ sanitize_title( $title ) ] = array(
            'title' => $title,
            'url'   => esc_url_raw( $note['url'] ?? '' ),
        );
    }

    update_option( 'wpsifero_notes', $notes );
    wp_safe_redirect( admin_url( 'tools.php?page=wpsifero-notes' ) );
    exit;
}