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_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.
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.
Alex (Viper007Bond)
June 12, 2009 at 12:43 am
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”
Lloyd Budd
June 12, 2009 at 12:45 am
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.
Alex (Viper007Bond)
June 12, 2009 at 12:48 am
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
).
mdawaffe
June 12, 2009 at 12:53 am
[...] See the original post: Escaping API updates for WordPress 2.8 « Mark on WordPress [...]
Escaping API updates for WordPress 2.8 « Mark on WordPress | bllogger
June 12, 2009 at 3:00 am
Great stuff.
John Bachir
June 12, 2009 at 3:23 am
[...] Escaping API updates for WordPress 2.8 [...]
WordPress 2.8: Features and tips — gunnerpress.com
June 12, 2009 at 3:35 am
Of course, these functions also accept a text domain in the second parameter for translation.
johnbillion
June 12, 2009 at 9:23 am
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 Anderson
June 12, 2009 at 12:55 pm
Will is right.
__( $input )won’t work. For the sake of the example, something like__( 'I am so translated' )would be better.Nikolay
June 12, 2009 at 1:26 pm
Updated to address concerns brought up. Thanks all!
Mark Jaquith
June 12, 2009 at 3:08 pm
[...] 3. Escaping API updates for WordPress 2.8 [...]
10 Cool WordPress 2.8 Hacks and Tutorials to tinker with - Daily SEO blog
June 12, 2009 at 4:20 pm
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.
Ryan A. Smith
June 13, 2009 at 12:01 am
Great stuff.
123tweak.com
June 13, 2009 at 7:43 pm
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
karinaliette
June 14, 2009 at 12:11 am
[...] 3. Escaping API updates for WordPress 2.8 [...]
10 Cool WordPress 2.8 Hacks and Tutorials to tinker with | rapid-DEV.net
June 15, 2009 at 2:13 am
Cool! This feature I didn’t know before. Thank you very much.
FreewareMatter
June 16, 2009 at 5:26 am
[...] 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. – By Mark on WordPress [...]
WordPress & Blogging Articles for june 16 2009 | WPStart.org - WordPress themes, plugins and news
June 16, 2009 at 2:36 pm
[...] ‘esc’ tab-expansion: with the help of Mark Jaquith’s great article Escaping API updates for WordPress 2.8, typing esc and then pressing tab now brings up a menu with options to choose the proper escaping [...]
Updates to the WordPress TextMate bundle
June 24, 2009 at 8:19 am
Cool! This feature
I didn’t know before.
Thank you very much.
linda
July 13, 2009 at 9:22 am
[...] 30.Escaping API updates for WordPress 2.8 [...]
New And Comprehensive Wordpress 2.8 Tutorial and Hack Toolbox | Graphic and Web Design Blog - Inspiration, Resources and Tools
July 20, 2009 at 2:34 pm
Escaping API updates for WordPress 2.8
erotik izle
July 24, 2009 at 6:29 pm
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
byron
July 26, 2009 at 5:57 pm
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
byron
July 26, 2009 at 6:20 pm
[...] 30.Escaping API updates for WordPress 2.8 [...]
New And Comprehensive Wordpress 2.8 Tutorial and Hack Toolbox - Programming Blog
August 3, 2009 at 7:22 pm
[...] from the database? Do you use nonces? If not, you really should. Mark has a great article about the new escaping functions and another one about using nonces [...]
(PLUGIN) Conversation Manager
November 21, 2009 at 10:29 pm