Escaping API updates for WordPress 2.8

The WordPress escaping API functions have been updated. Escaping is a way of using untrusted text that “neuters” anything that could do damage. Escaping is used in WordPress to avoid SQL injection and cross-site scripting/script injection (XSS), among other things.

The old functions still work, so if you were using the old ones, you’re fine. The new ones just offer you an easier to remember, more concise, and more flexible way of securing your WordPress code.

Here’s an example. Say you wanted to translate a string, escape it for use in a quoted HTML attribute, and then echo it out. In WP 2.7, you’d have to do this:

<?php echo attribute_escape( __( 'Untranslated text' ) ); ?>

In WordPress 2.8, you can just do this:

<?php esc_attr_e( 'Untranslated text' ); ?>

Shorter, plus we killed the echo and the extra pair of parenthesis! But let’s break it down.

esc_ = 1, attr = 2, _e = 3

  1. esc_ is the prefix for the new WP escaping functions.
  2. attr is the context (in this case, attribute). The available contexts for 2.8 are attr, html, js, sql, url, and url_raw.
  3. _e is the optional translation suffix. The available suffixes for 2.8 are __, and _e. If you omit the suffix, no translation is performed, and your string is just returned.

More about contexts

  • attr means an HTML attribute.
  • html means text within an HTML node, but not within an attribute
  • sql is an alias to $wpdb->escape().
  • url means URLs for use in HTML attributes.
  • url_raw means URLs for use in redirects or storage in the database (does not entity-encode).
  • js means JS, for using PHP to populate a Javascript var.

More about suffixes

Suffixes work just like the function they’re named after.

  • __ translates the string and returns it.
  • _e translates the string and echoes it.
  • The suffix is optional. A blank suffix will just return.
  • Suffixes are currently only available for html and attr contexts.

Functions with translation suffixes also accept an option second parameter of a translation domain, for use in plugins.

Enjoy! Go forth and write more succinct code.

32 thoughts on “Escaping API updates for WordPress 2.8

  1. Oh, the “_e” and “__” suffixes are also only available for the ones you’d want to output — “attr” and “html”.

    All other combination don’t have translation suffixes and everything but “esc_attr_e()” and “esc_html_e()” returns the string. You still need to echo.

  2. To nitpick for precision: esc_html() is not for general HTML, but only for escaping data for use in text nodes in an XML/XHTML/HTML document. That is, it escapes < and > symbols to &lt; and &gt; entities, respectively.

    I wish it were called esc_text().

    To “escape” general HTML fragments, you still need to go through KSES.

    More information at http://codex.wordpress.org/Data_Validation (which is currently technical and terse, unlike the fantastically simple and easy to understand explanation in your post above :)).

  3. From what I understand, you would never actually translate a dynamic variable, like this: __( $input ) so I’m not sure the initial example is valid, but I didn’t know about the these combination functions. Definitely cool!

  4. Will is right.

    __( $input ) won’t work. For the sake of the example, something like __( 'I am so translated' )would be better.

  5. What are API functions? And why do you want to escape API?

    About API, how do you change API key assigned to a blog? Because I want to change API key for WordPress.com Stats plugin, but I couldn’t. :(

  6. karinaliette says:

    I don’t know HTML and am wondering is this why, now that I’ve updated, I am no longer able to type up my post in Microsoft word with the formatting I like, looking the way I want it to and the cut & paste into the ‘visual’??? This is a REAL dissapointment and I’m wondering how I can go back to the old version as I am not at all happy with this new change! Please, if you can explain how I can either get around this new BORING problem please email me karinaliette@shaw.ca

    Thank you to all you HTML literate bloggers who may offer assistance!!!
    K.Hunter

  7. Hi Mark,

    Out of curiosity, what is the purpose of esc_attr() – no suffix, if it just returns the string you put in?

    It would seem to me that this would invite a lot of misunderstanding and mistakes, but I may be missing part of the picture. I could see people using esc_attr(‘make me safe’), thinking they’re in the clear.

    Thanks,
    BB

  8. Mark,

    I think I may understand now…When you said “If you omit the suffix, no translation is performed, and your string is just returned” and “A blank suffix will just return,” I thought you meant that it would return the original string, no Escaping…doh!!!

    It’s still escaped, just not translated…I get it now.
    Thanks for the tut.
    BB

  9. Excellent posting , You hit the
    nail on the head, I just don’t think that people quite get what you’re saying.
    I’m not for sure how many people I’ve talked to about this very
    thing in the past few days, and they just don’t understand.

    , Excellent post!

  10. Nico says:

    I tried to work with the esc_url function and it’s not escaping unauthorized characters from my URL :

    $url = esc_url(‘http://www.url.c!!!om/$’);
    echo $url;

    Am I wrong in the uses of this function ?

Comments are closed.