What's $object->filter for?

Question

I keep seeing this pattern, and wonder what it's for, how WP uses it internally:

if ( empty($post) ) {
        if ( isset($GLOBALS['post']) )
            $_post = & $GLOBALS['post'];
        else
            return $null;
    } elseif ( is_object($post) && empty($post->filter) ) {
        _get_post_ancestors($post);
        $_post = sanitize_post($post, 'raw');
        wp_cache_add($post->ID, $_post, 'posts');
    } else {
        if ( is_object($post) )
            $post_id = $post->ID;
        else
            $post_id = $post;

The specific line in question is is_object($post) && empty($post->filter). I've seen this filter property associated with other objects as well. Wondering what it does and how it can be used?

EDIT

I'm hoping to get more input on this! Unfortunately, a Google search with "filter" in it only turns up Filter hooks etc. This is a tough one to get independent info on. Buehler?

Answer 1

The $post->filter contains the context under which the contents of the post have been filtered. Context could be something like "display" indicating the post is meant to be displayed on the page.

This is done by the sanitization functions, to indicate under what context the post data was sanitized. Different contexts get different types of sanitization. "raw", for example, is unsanitized data. "display" has probably gone through the esc_html function, or whatever is relevant for that context. The sanitize_post() function uses this to check for pre-existing sanitizations, in order to prevent double escaping things and so forth.

One other use for the $post->filter is in the get_sample_permalink() function. You'll find that it sets the $post->filter = 'sample' before calling get_permalink(). The use of "sample" here indicates to the get_permalink function, and to code below it, that the purpose of this call is to create a sample permalink for displaying on the edit post screen. This will change the way some of the functions below it work.

Answer 2

@Shaan: I don't think that Tom was looking for a description about the WP Plugin API. He is looking for a description of the object property filter which you get as a result of WP_Query. For example if you use get_posts():

stdClass Object
(
    // other post properties
    [filter] => raw
)

I don't know whether and where this property is used inside WordPress. After looking around in the sourcecode, I think this isn't used anywhere at the moment.

Just speculating here. The default value is raw for all posts so far. It could be that the core developers wanted to add a filtering on per post base. For example, if you want to allow only certain HTML elements inside the post content, you could create a filter sanitizeHtml, attach it to the post and WordPress will do the rest for you.