setup_postdata() – Function | Developer.WordPress.org

Set up global post data.

Parameters

$postWP_Post|object|intrequired: WP_Post instance or Post ID/object.

More Information

Sets up global post data. Helps to format custom query results for using Template tags.

setup_postdata() fills the global variables $id, $authordata, $currentday, $currentmonth, $page, $pages, $multipage, $more, $numpages, which help many Template Tags work in the current post context.

setup_postdata() does not assign the global $post variable so it’s important that you do this yourself. Failure to do so will cause problems with any hooks that use any of the above globals in conjunction with the $post global, as they will refer to separate entities.

Usage

<?php
global $post;

// modify the $post variable with the post data you want. Note that this variable must have this name!

setup_postdata( $post );
?>

Source

function setup_postdata( $post ) {
	global $wp_query;

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

	return false;
}

View all references View on Trac View on GitHub

Uses	Description
WP_Query::setup_postdata()`wp-includes/class-wp-query.php`	Sets up global post data.

Used by	Description
WP_REST_Block_Renderer_Controller::get_item()`wp-includes/rest-api/endpoints/class-wp-rest-block-renderer-controller.php`	Returns block output from block’s registered render_callback.
WP_REST_Revisions_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php`	Prepares the revision for the REST response.
WP_REST_Posts_Controller::prepare_item_for_response()`wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php`	Prepares a single post output for response.
wp_ajax_parse_embed()`wp-admin/includes/ajax-actions.php`	Applies Ajax handlers to a string.
wp_ajax_parse_media_shortcode()`wp-admin/includes/ajax-actions.php`
WP_Posts_List_Table::single_row()`wp-admin/includes/class-wp-posts-list-table.php`
start_wp()`wp-includes/deprecated.php`	Sets up the WordPress Loop.

Show 2 more Show less

Changelog

Version	Description
4.4.0	Added the ability to pass a post ID to `$post`.
1.5.0	Introduced.

User Contributed Notes

Skip to note 7 content

mslade 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 13You must log in to vote on the helpfulness of this note

An important note about setup_postdata and the $post global: setup_postdata( $new_post ) sets various globals related to the current post but it does not update the $post global. This disjoint can cause problems both in WP internals and in plugins/themes.

Therefore if you call setup_postdata( $new_post ), you should also assign it to the global $post object.

Log in to add feedback

Aurovrata Venet 3 years ago

<ul>
    <?php
    global $post;
     
    $myposts = get_posts( array(
        'posts_per_page' => 5,
        'offset'         => 1,
        'category'       => 1
    ) );
     
    if ( $myposts ) :
        foreach ( $myposts as $post ) :
          setup_postdata( $post ); ?>
            <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
        endforeach; 
        wp_reset_postdata();
    endif;
    ?>
</ul>

Ahmad Karim 3 years ago

Example of using setup_postdata in a custom query:

global $wpdb, $post;

$query = "SELECT * FROM `wp_posts` WHERE `post_type` = 'cpt_1' AND `post_status` = 'publish' AND `comment_count` > 0 LIMIT 5";
$result = $wpdb->get_results($query, OBJECT);

if ( $result && count($result) > 0 ):

  echo '<ol>';

  foreach ($result as $post):

    setup_postdata($post);

    echo '<li>';

    the_title();

    echo '</li>';

  endforeach;

  echo '</ol>';

  wp_reset_postdata();

endif;

stratboy 2 years ago

-1

Here’s a good simple working example that also assigns the global $post before passing it to setup_postdata.

// ... your custom query..., and then:

global $post; // Call global $post variable

foreach ( $your_posts as $current_post ) {
	$post = $current_post; // Set $post global variable to the current post object   
	setup_postdata( $post ); // Set up "environment" for template tags

	// Use template tags normally
	the_title();
	the_post_thumbnail( 'large' );
	the_excerpt();
	// Or the_content(), the_permalink(), etc.
}

wp_reset_postdata();

In general, you shouldn’t override the global $post, unless you know you need to.

crstauf 2 years ago

Codex 9 years ago

-2

Example 1

<ul>
	<?php
	global $post;
	
	$myposts = get_posts( array(
		'posts_per_page' => 5,
		'offset'         => 1,
		'category'       => 1
	) );
	
	if ( $myposts ) :
		foreach ( $myposts as $mypost ) :
		  setup_postdata( $mypost ); ?>
			<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
		endforeach; 
		wp_reset_postdata();
	endif;
	?>
</ul>

Skip to note 12 content

Zane Matthew 4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note
Note, it is probably best not to use this function, although it is neat, it goes against WordPress’ own coding standards.

Issue reported here, back in 2017.

If you use this function, and run PHPCS with WordPress standards you’ll see this error:
```
 24 | ERROR | [ ] Overriding WordPress globals is prohibited. Found assignment to $post
```
Log in to add feedback

setup_postdata( WP_Post|object|int $post ): bool

In this article