WordPress.org

Template Tags/get posts

Languages: English • 日本語 • (Add your language)

Description

This is a simple function for creating multiple loops. It retrieves a list of latest posts or posts matching criteria.

Note that although the parameters are similar to get_pages, several have different names or take slightly different values.

Usage

<?php $posts_array = get_posts( $args ); ?>

Default Usage

<?php $args = array( 'numberposts' => 5, 'offset' => 0, 'category' => , 'orderby' => 'post_date', 'order' => 'DESC', 'include' => , 'exclude' => , 'meta_key' => , 'meta_value' => , 'post_type' => 'post', 'post_mime_type' => , 'post_parent' => , 'post_status' => 'publish' ); ?>

Parameters

get_posts() makes use of the WP_Query class to fetch posts. See the parameters section of the WP_Query documentation for a list of parameters that this function accepts.

Note: get_posts uses 'suppress_filters' => true as default, while query_posts() applies filters by default, this can be confusing when using query-modifying plugins, like WPML.

Note: The category parameter needs to be the ID of the category, and not the category name.

Return Value

(array): List of post objects. Check get_post() return values.

Examples

Posts list with offset

If you have your blog configured to show just one post on the front page, but also want to list links to the previous five posts in category ID 1, you can use this:

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

Note: With use of the offset, the above query should be used only on a category that has more than one post in it, otherwise there'll be no output.

Reset after Postlists with offset

If you need after the loop, the post you had before joining the foreach, you can use this:

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

Access all post data

Some post-related data is not available to get_posts by default, such as post content through the_content(), or the numeric ID. This is resolved by calling an internal function setup_postdata(), with the $post array as its argument:

<?php
$args = array( 'numberposts' => 3 );
$lastposts = get_posts( $args );
foreach($lastposts as $post) : setup_postdata($post); ?>
	<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
	<?php the_content(); ?>
<?php endforeach; ?>

To access a post's ID or content without calling setup_postdata(), or in fact any post-specific data (data retained in the posts table), you can use $post->COLUMN, where COLUMN is the table column name for the data. So $post->ID holds the ID, $post->post_content the content, and so on. To display or print this data on your page use the PHP echo command, like so:

<?php echo $post->ID; ?>

Latest posts ordered by title

To show the last ten posts sorted alphabetically in ascending order, the following will display their post date, title and excerpt:

<?php
$args = array( 'numberposts' => 10, 'order'=> 'ASC', 'orderby' => 'title' );
$postslist = get_posts( $args );
foreach ($postslist as $post) :  setup_postdata($post); ?> 
	<div>
		<?php the_date(); ?>
		<br />
		<?php the_title(); ?>   
		<?php the_excerpt(); ?>
	</div>
<?php endforeach; ?>

Random posts

Display a list of 5 posts selected randomly by using the MySQL RAND() function for the orderby parameter value:

<ul>
<?php
$args = array( 'numberposts' => 5, 'orderby' => 'rand' );
$rand_posts = get_posts( $args );
foreach( $rand_posts as $post ) : ?>
	<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
<?php endforeach; ?>
</ul>

Show all attachments

Do this outside any Loops in your template.

<?php
$args = array( 'post_type' => 'attachment', 'numberposts' => -1, 'post_status' => null, 'post_parent' => null ); 
$attachments = get_posts( $args );
if ($attachments) {
	foreach ( $attachments as $post ) {
		setup_postdata($post);
		the_title();
		the_attachment_link($post->ID, false);
		the_excerpt();
	}
}
?>

Show attachments for the current post

Do this inside The Loop (where $post->ID is available).

<?php
$args = array( 'post_type' => 'attachment', 'numberposts' => -1, 'post_status' => null, 'post_parent' => $post->ID ); 
$attachments = get_posts($args);
if ($attachments) {
	foreach ( $attachments as $attachment ) {
		echo apply_filters( 'the_title' , $attachment->post_title );
		the_attachment_link( $attachment->ID , false );
	}
}
?>

Get a post by its slug

Allows you to get a post ID by post slug. The caller_get_posts argument excludes sticky posts from this custom query.

<?php
$the_slug = 'my_slag';
$args=array(
  'name' => $the_slug,
  'post_type' => 'post',
  'post_status' => 'publish',
  'showposts' => 1,
  'caller_get_posts'=> 1
);
$my_posts = get_posts($args);
if( $my_posts ) {
echo 'ID on the first post found '.$my_posts[0]->ID;
}
?>

Custom Post Type Category (Taxonomy)

If specifying a category from a custom post type then instead of using 'category' you would use '{your_custom_post_type}_category'. For instance, if you had a custom post type called "dogfood" and wanted to only show posts from the category "brand" you would use the below code.

<?php
$args = array(
   'numberposts' => 8,
   'orderby' => 'rand',
   'post_type' => 'dogfood',
   'dogfood_category' => 'brand',
   'post_status' => 'publish'
);
$show_brands = get_posts ( $args );
?>

Change Log

Since: 1.2.0

Source File

get_posts() is located in wp-includes/post.php.