setup_postdata() WP 1.5.0

Set up the global post data. Useful for easy usage of Template Tags related to the design of the post: the_title(), the_permalink(), etc.

Fills global variables: $id, $authordata, $currentday, $currentmonth, $page, $pages, $multipage, $more, $numpages. This variables are needed for correct work of the Template Tags that should be used within the WordPress Loop.

The $post variable passed to the function must be global, i.e. the function expects the passed variable $post is already global. If the function is used within WordPress Loop, then the current $post object in the loop must be passed.

No Hooks.

Return

true/false. True when finished.

Usage

setup_postdata( $post );

$post(WP_Post/object/int) (required)

WP_Post instance or Post ID/object.

Examples

#1 How to pass the $post argument correctly

Let's say we get the post data into the $post_object variable, then we need to create a variable called $post and pass that data into it. setup_postdata() works only with the global variable $post.

global $post;

// Pass the received post data to the $post variable and not to any other.
$post = $post_object;

setup_postdata( $post );
// the_title();
// the_permalink();

A short record of the example above:

setup_postdata( $GLOBALS['post'] = & $post_object );

And here is a wrong variant:

global $post;

setup_postdata( $post_object ); // bad

#2 An example with get_posts() loop

Get posts from category 1 and display them as links:

<ul>
	<?php
	global $post;
	$myposts = get_posts( array( 'numberposts' => 5, 'offset'=> 1, 'category' => 1 ) );
	foreach( $myposts as $post ){
		setup_postdata($post);
		?>
		<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
		<?php 
	}
	wp_reset_postdata(); // important
	?>
</ul>

#3 Get posts directly from the database

<ul>
	<?php
	global $wpdb, $post;
	$result = $wpdb->get_results(
		"SELECT * FROM $wpdb->posts WHERE post_type = 'post' AND post_status = 'publish'"
	);
	foreach( $result as $post ){
		setup_postdata( $post );
		?>
		<li><a href="<?php the_permalink()?>"><?php the_title();?></a></li>
		<?php 
	}
	wp_reset_postdata(); // important
	?>
</ul>

#4 If not $post variable passed to the function argument

Demonstration of what happens if you pass not the global variable $post as an argument, but any other - the function will not work as it expected.

Let's pass $pst, but not $post:

global $post;

$posts = get_posts( "posts_per_page=2" );
foreach( $posts as $pst ){
	setup_postdata( $pst );
	echo the_title();
	echo '<br>';
}
echo '$post->post_title - '. $post->post_title . '<br>';

/*
Display:
current global post title
current global post title
$post->post_title - current global post title
*/

Now lets pass normal $post:

// repeat only with $post instead of $pst
$posts = get_posts("posts_per_page=2");
foreach( $posts as $post ){
	setup_postdata( $post );
	echo the_title();
	echo '<br>';
}
echo '$post->post_title - '. $post->post_title . '<br>';

/*
Display:
Received first post title
Received second post title
$post->post_title - Received second post title
*/

Code of setup postdata: wp-includes/query.php ^{VER 5.0.3}

<?php
function setup_postdata( $post ) {
	global $wp_query;

	if ( ! empty( $wp_query ) && $wp_query instanceof WP_Query ) {
		return $wp_query->setup_postdata( $post );
	}

	return false;
}

Related Functions

From tag: WP Loop

More from tag: query

More from category: Queries

More from Template Tags: Main Functions