the_posts
the_posts is a filter that is run on the array of queried posts. At this point, it would be possible to remove posts, add posts, change posts, etc. This is a very powerful hook.
Your filter function should accept and return an array.
Context:
File: wp-includes/classes.php
// Check post status to determine if post should be displayed.
if ($this->is_single) {
if ('publish' != $this->posts[0]->post_status) {
if ( ! (isset($user_ID) && ('' != intval($user_ID))) ) {
// User must be logged in to view unpublished posts.
$this->posts = array();
} else {
if ('draft' == $this->posts[0]->post_status) {
// User must have edit permissions on the draft to preview.
if (! user_can_edit_post($user_ID, $this->posts[0]->ID))
$this->posts = array();
} elseif ('private' == $this->posts[0]->post_status) {
if ($this->posts[0]->post_author != $user_ID)
$this->posts = array();
}
}
}
}
$this->posts = apply_filters('the_posts', $this->posts);
This hook is a filter which means that information is passed through it, and then used by WordPress. Your function needs to accept that information, and return it. Using add_filter('the_posts', 'your_function'); helps you to remember this distinction. When you are passing an ID, it is assumed that you will return the ID as it was given to you. With filters that pass strings or arrays, you may manipulate the information before passing it along.