get_posts() – Function | Developer.WordPress.org

Retrieves an array of the latest posts, or posts matching the given criteria.

Description

For more information on the accepted arguments, see the WP_Query documentation in the Developer Handbook.

The $ignore_sticky_posts and $no_found_rows arguments are ignored by this function and both are set to true.

The defaults are as follows:

Parameters

$argsarrayoptional

Arguments to retrieve posts. See WP_Query::parse_query() for all available arguments.

numberposts int
Total number of posts to retrieve. Is an alias of $posts_per_page in WP_Query. Accepts -1 for all. Default 5.
category int|string
Category ID or comma-separated list of IDs (this or any children).
Is an alias of $cat in WP_Query. Default 0.
include int[]
An array of post IDs to retrieve, sticky posts will be included.
Is an alias of $post__in in WP_Query. Default empty array.
exclude int[]
An array of post IDs not to retrieve. Default empty array.
suppress_filters bool
Whether to suppress filters. Default true.

Default:null

Return

WP_Post[]|int[] Array of post objects or post IDs.

The most appropriate use for get_posts is to create an array of posts based on a set of parameters. It retrieves a list of recent posts or posts matching this criteria. get_posts can also be used to create Multiple Loops, though a more direct reference to WP_Query using new WP_Query is preferred in this case.

The parameters of get_posts are similar to those of get_pages but are implemented quite differently, and should be used in appropriate scenarios. get_posts uses WP_Query, whereas get_pages queries the database more directly. Each have parameters that reflect this difference in implementation.

query_posts also uses WP_Query, but is not recommended because it directly alters the main loop by changing the variables of the global variable $wp_query. get_posts, on the other hand, simply references a new WP_Query object, and therefore does not affect or alter the main loop.

If you would like to alter the main query before it is executed, you can hook into it using pre_get_posts. If you would just like to call an array of posts based on a small and simple set of parameters within a page, then get_posts is your best option.

Source

function get_posts( $args = null ) {
	$defaults = array(
		'numberposts'      => 5,
		'category'         => 0,
		'orderby'          => 'date',
		'order'            => 'DESC',
		'include'          => array(),
		'exclude'          => array(),
		'meta_key'         => '',
		'meta_value'       => '',
		'post_type'        => 'post',
		'suppress_filters' => true,
	);

	$parsed_args = wp_parse_args( $args, $defaults );
	if ( empty( $parsed_args['post_status'] ) ) {
		$parsed_args['post_status'] = ( 'attachment' === $parsed_args['post_type'] ) ? 'inherit' : 'publish';
	}
	if ( ! empty( $parsed_args['numberposts'] ) && empty( $parsed_args['posts_per_page'] ) ) {
		$parsed_args['posts_per_page'] = $parsed_args['numberposts'];
	}
	if ( ! empty( $parsed_args['category'] ) ) {
		$parsed_args['cat'] = $parsed_args['category'];
	}
	if ( ! empty( $parsed_args['include'] ) ) {
		$incposts                      = wp_parse_id_list( $parsed_args['include'] );
		$parsed_args['posts_per_page'] = count( $incposts );  // Only the number of posts included.
		$parsed_args['post__in']       = $incposts;
	} elseif ( ! empty( $parsed_args['exclude'] ) ) {
		$parsed_args['post__not_in'] = wp_parse_id_list( $parsed_args['exclude'] );
	}

	$parsed_args['ignore_sticky_posts'] = true;
	$parsed_args['no_found_rows']       = true;

	$get_posts = new WP_Query();
	return $get_posts->query( $parsed_args );
}

View all references View on Trac View on GitHub

Uses	Description
WP_Query::__construct()`wp-includes/class-wp-query.php`	Constructor.
wp_parse_id_list()`wp-includes/functions.php`	Cleans up an array, comma- or space-separated list of IDs.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.

Show 1 more Show less

Used by	Description
do_all_trackbacks()`wp-includes/comment.php`	Performs all trackbacks.
do_all_enclosures()`wp-includes/comment.php`	Performs all enclosures.
do_all_pingbacks()`wp-includes/comment.php`	Performs all pingbacks.
WP_Customize_Manager::get_changeset_posts()`wp-includes/class-wp-customize-manager.php`	Gets changeset posts.
wp_add_trashed_suffix_to_post_name_for_trashed_posts()`wp-includes/post.php`	Adds a suffix if any trashed posts have a given slug.
WP_Customize_Nav_Menus::load_available_items_query()`wp-includes/class-wp-customize-nav-menus.php`	Performs the post_type and taxonomy queries for loading available menu items.
get_children()`wp-includes/post.php`	Retrieves all children of the post parent ID.
wp_generate_attachment_metadata()`wp-admin/includes/image.php`	Generates attachment meta data and create image sub-sizes for images.
wp_dashboard_recent_drafts()`wp-admin/includes/dashboard.php`	Show recent drafts of the user on the dashboard.
wp_ajax_find_posts()`wp-admin/includes/ajax-actions.php`	Handles querying posts for the Find Posts modal via AJAX.
wp_nav_menu_item_post_type_meta_box()`wp-admin/includes/nav-menu.php`	Displays a meta box for a post type menu item.
get_uploaded_header_images()`wp-includes/theme.php`	Gets the header images uploaded for the active theme.
WP_Query::get_posts()`wp-includes/class-wp-query.php`	Retrieves an array of posts based on query variables.
get_boundary_post()`wp-includes/link-template.php`	Retrieves the boundary post.
wp_get_recent_posts()`wp-includes/post.php`	Retrieves a number of recent posts.
wp_get_nav_menu_items()`wp-includes/nav-menu.php`	Retrieves all menu items of a navigation menu.
wp_xmlrpc_server::wp_getMediaLibrary()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves a collection of media library items (or attachments).
wp_xmlrpc_server::wp_getPages()`wp-includes/class-wp-xmlrpc-server.php`	Retrieves Pages.

Show 13 more Show less

Changelog

Version	Description
1.2.0	Introduced.

User Contributed Notes

Aurovrata Venet 8 years ago

Returns an array of WP_Post objects with attributes,

WP_Post Object
(
    [ID] =>
    [post_author] =>
    [post_date] => 
    [post_date_gmt] => 
    [post_content] => 
    [post_title] => 
    [post_excerpt] => 
    [post_status] =>
    [comment_status] =>
    [ping_status] => 
    [post_password] => 
    [post_name] =>
    [to_ping] => 
    [pinged] => 
    [post_modified] => 
    [post_modified_gmt] =>
    [post_content_filtered] => 
    [post_parent] => 
    [guid] => 
    [menu_order] =>
    [post_type] =>
    [post_mime_type] => 
    [comment_count] =>
    [filter] =>
)

Skip to note 24 content

swedish boy 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 14You must log in to vote on the helpfulness of this note
Array of post IDs

To return ids instead of post objects use the fields argument.
```
$args = array('fields' => 'ids');
$posts = get_posts($args);
// if any posts are found $posts will be an array with their ids
```
The fields argument can be set to 'ids', 'all' (default) or 'id=>parent'. The last two (arguments) will return an array of stdClass objects.

Source:
https://developer.wordpress.org/reference/classes/wp_query/#return-fields-parameter
Log in to add feedback
Skip to note 25 content

Nico 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
Example to get the latest 10 posts in the blog:
```
$args = array(
  'numberposts' => 10
);

$latest_posts = get_posts( $args );
```
You can also pass the post_type argument if you want to get posts from a Custom Post Type, like:
```
$args = array(
  'numberposts' => 10,
  'post_type'   => 'book'
);

$latest_books = get_posts( $args );
```
Log in to add feedback
Skip to note 26 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note
Custom Field Parameters

Show posts associated with a certain custom field. Following example displays posts from the ‘product’ post type that have meta key ‘featured’ with value ‘yes’, using ‘meta_query’:
```
$args = array(
	'post_type'  => 'product',
	'meta_query' => array(
		array(
			'key'   => 'featured',
			'value' => 'yes',
		)
	)
);
$postslist = get_posts( $args );
```
Refer to the custom fields parameters section of the WP_Query documentation for more examples.
Log in to add feedback

Codex 9 years ago

Posts with Previous Next Navigation

You can also using the custom queries to make the post with Previous and Next Post Navigation. Here is the following method to make it workable.

<?php
$post_list = get_posts( array(
	'orderby'    => 'menu_order',
	'sort_order' => 'asc'
) );

$posts = array();

foreach ( $post_list as $post ) {
   $posts[] += $post->ID;
}

$current = array_search( get_the_ID(), $posts );

$prevID = $posts[ $current-1 ];
$nextID = $posts[ $current+1 ];
?>

<div class="navigation">
<?php if ( ! empty( $prevID ) ): ?>
	<div class="alignleft">
		<a href="<?php echo get_permalink( $prevID ); ?>" alt="<?php echo get_the_title( $prevID ); ?>">
			<?php _e( 'Previous', 'textdomain' ); ?>
		</a>
	</div>
<?php endif;

if ( ! empty( $nextID ) ) : ?>
	<div class="alignright">
		<a href="<?php echo get_permalink( $nextID ); ?>" alt="<?php echo get_the_title( $nextID ); ?>">
			<?php _e( 'Next', 'textdomain' ); ?>
		</a>
	</div>
<?php endif; ?>
</div><!-- .navigation -->

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;

	$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>
		<?php
		endforeach;
		wp_reset_postdata();
	}
	?>
</ul>

Skip to note 28 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
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
$lastposts = get_posts( array(
	'posts_per_page' => 3
) );

if ( $lastposts ) {
	foreach ( $lastposts as $post ) :
		setup_postdata( $post ); ?>
		<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
		<?php the_content(); ?>
	<?php
	endforeach; 
	wp_reset_postdata();
}
```
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; ?>
```
Log in to add feedback
Skip to note 29 content

Codex 9 years ago

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

Show posts associated with certain taxonomy. If specifying a taxonomy registered to a custom post type then instead of using ‘category’ you would use ‘{custom_taxonomy_name}’. For instance, if you had a custom taxonomy called “genre” and wanted to only show posts from the “jazz” genre you would use the below code.
```
$show_albums = get_posts( array(
	 'posts_per_page' => 8,
	 'orderby'        => 'rand',
	 'post_type'      => 'albums',
	 'genre'          => 'jazz',
	 'post_status'    => 'publish'
) );
```
Following example displays posts tagged with ‘jazz’, under ‘genre’ custom taxonomy, using ‘tax_query’:
```
$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'genre',
			'field'    => 'slug',
			'terms'    => 'jazz'
		)
	)
);
$postslist = get_posts( $args );
```
Refer to the taxonomy parameters section of the WP_Query documentation for more examples.
Log in to add feedback
Skip to note 30 content

Jules Colle 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
Get all published posts of ANY post type:
```
$posts = get_posts( array(
  'post_type' => get_post_types(),
  'post_status' => 'publish',
  'numberposts' => -1,
) );
```
Log in to add feedback

Codex 9 years ago

Get a post by its slug

Allows you to get a post ID by post slug.

<?php
$the_slug = 'my-slug';
$args=array(
	'name'           => $the_slug,
	'post_type'      => 'post',
	'post_status'    => 'publish',
	'posts_per_page' => 1
);
$my_posts = get_posts( $args );

if ( $my_posts ) {
	printf( __( 'ID on the first post found %s', 'textdomain' ), esc_html( $my_posts[0]->ID ) );
}

Skip to note 32 content

Toao.net 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
orderby also accepts the value post__in. (Note two underscores between post and in.) If you used include to retrieve specific posts, the posts will be supplied in the order you supplied to include. For example:
```
$posts = get_posts( array(
	'include'   => '3,8,1,17',
	'post_type' => 'attachment',
	'orderby'   => 'post__in',
) );
```
Log in to add feedback
Skip to note 33 content

Juan C. (PotterSys) 9 years ago

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

You can check all the parameters that can be used on get_posts on https://codex.wordpress.org/Class_Reference/WP_Query#Parameters

Log in to add feedback

Codex 9 years ago

Show all attachments

Do this outside any Loops in your template.

<?php
$attachments = get_posts( array(
	'post_type'      => 'attachment',
	'posts_per_page' => 500,
	'post_status'    => 'any',
	'post_parent'    => null
) );

if ( $attachments ) {
	foreach ( $attachments as $post ) {
		setup_postdata( $post );
		the_title();
		the_attachment_link( $post->ID, false );
		the_excerpt();
	}
	wp_reset_postdata();
}
?>

Skip to note 35 content

adiant 8 years ago

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

It is not considered an error condition if no posts are found based on the specified and default parameter values. Instead, an empty array (“array()“) is returned by the function.

Log in to add feedback
Skip to note 36 content

Rolf Allard van Hagen 7 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Example to display posts or post type ‘album’, tagged with ‘jazz’ or ‘improv’ under the ‘genre’ custom taxonomy:
```
$args = array(
    'post_type' => 'album',
    'post_status' => 'publish',
    'tax_query' => array(
        array(
            'taxonomy' => 'genre',
            'field'    => 'slug',
            'terms'    => array( 'jazz', 'improv' )
        )
    )
);
$postslist = get_posts( $args );
```
Note that the simple '{custom_taxonomy_name}' => 'jazz' has been deprecated in favor of tax_query. More complex examples can be found on https://codex.wordpress.org/Class_Reference/WP_Query#Taxonomy_Parameters
Log in to add feedback
Skip to note 37 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
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:
```
$postslist = get_posts( array(
	'posts_per_page' => 10,
	'order'          => 'ASC',
	'orderby'        => 'title'
) );

if ( $postslist ) {
	foreach ( $postslist as $post ) :
		setup_postdata( $post );
		?>
		<div>
			<?php the_date(); ?>
			<br />
			<?php the_title(); ?>   
			<?php the_excerpt(); ?>
		</div>
	<?php
	endforeach; 
	wp_reset_postdata();
}
```
Log in to add feedback

Codex 9 years ago

Random posts

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

<ul>
	<?php
	$rand_posts = get_posts( array(
		'posts_per_page' => 5,
		'orderby'        => 'rand'
	) );
	
	if ( $rand_posts ) {
	foreach ( $rand_posts as $post ) : 
		setup_postdata( $post );
		?>
		<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
		<?php
	endforeach; 
	wp_reset_postdata();
	}
	?>
</ul>

Codex 9 years ago

Show attachments for the current post

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

$attachments = get_posts( array(
	'post_type'      => 'attachment',
	'posts_per_page' => -1,
	'post_status'    => 'any',
	'post_parent'    => $post->ID
) );

if ( $attachments ) {
	foreach ( $attachments as $attachment ) {
		echo apply_filters( 'the_title' , $attachment->post_title );
		the_attachment_link( $attachment->ID , false );
	}
}

Skip to note 40 content

u22 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Order results by post types names

If you have an array of custom post types you can also order the results by post_type name, this works if you need to “group” the results.
```
<?php
		$args = array(
			'posts_per_page' => 10,
			'post_type'      => array('page','post'),
			'post_status'    => 'publish',
			'offset'	 => 0,
			's'    		 => 'Lorem',
			'orderby'        => 'post_type',
        		'order'          => 'ASC'
		);
		 $posts = get_posts( $args );
?>
```
Log in to add feedback
Skip to note 41 content

Amy 3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
To Find Post By Title

To find a post by its title the array key is ‘title’, NOT ‘post_title’:
```
$post_array = get_posts( array(
  'post_status' => 'publish',
  'title' => 'my_post_title',
) );
```
Log in to add feedback
Skip to note 42 content

Amy 1 year ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
Only Published Posts Will Be Found Unless Status Specified

If you are searching for a post that is in draft, private, etc status and not in publish status, get_posts will not find your post unless you include the post_status in the array.
```
$post_array = get_posts( array(
	'post_status' => get_post_stasuses(),
	'title'       => 'my_post_title'
) );
```
Log in to add feedback
Skip to note 43 content

Benjamin Intal 1 year ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
If you use any as the post_status, it will return all post_status except for trash and auto-draft.
```
// Returns any post status except trash and auto-draft
$posts = get_posts( array( 'post_status' => 'any' ) );
```
Log in to add feedback
Skip to note 44 content

Codex 9 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
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
	$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>
		<?php
		endforeach; 
		wp_reset_postdata();
	}
	?>
</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.
Log in to add feedback

get_posts( array $args = null ): WP_Post[]|int[]

In this article

Description

See also

Parameters

Return

More Information

Source

Changelog

User Contributed Notes