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_is the prefix for the new WP escaping functions.attris the context (in this case, attribute). The available contexts for 2.8 areattr,html,js,sql,url, andurl_raw._eis 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
attrmeans an HTML attribute.htmlmeans text within an HTML node, but not within an attributesqlis an alias to$wpdb->escape().urlmeans URLs for use in HTML attributes.url_rawmeans URLs for use in redirects or storage in the database (does not entity-encode).jsmeans 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._etranslates the string and echoes it.- The suffix is optional. A blank suffix will just return.
- Suffixes are currently only available for
htmlandattrcontexts.
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.
Mark on WordPress 
Thanks for writing this up! Good to be able to link this to people.
Also thought I’d reinforce that #3 is optional and only used if you want to translate at the same time.
Exactly the info I was looking for earlier today, and http://codex.wordpress.org/Data_Validation is a little sparce.
You don’t explain the most basic concept though, “escaping” 😉
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.
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<and>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 :)).
Great stuff.
Of course, these functions also accept a text domain in the second parameter for translation.
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!
Will is right.
__( $input )won’t work. For the sake of the example, something like__( 'I am so translated' )would be better.Updated to address concerns brought up. Thanks all!
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. 😦
Great stuff.
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
Cool! This feature I didn’t know before. Thank you very much.
Cool! This feature
I didn’t know before.
Thank you very much.
Escaping API updates for WordPress 2.8
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
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
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!
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 ?
How do I cleanup white space for a title in a URL?
I have a Twitter Share button and the W3 validator isn’t liking it.
<a href="http://twitter.com/share?url=&text=” class=”twitter-share-button”>Tweet
Thanks Mark. Great Tuts.
Too you have nice website.
This is a REAL dissapointment and I’m wondering like it.