How to Use get_posts to Retrieve the Posts You Need

I can’t think of many functions that I use more often than get_posts. As a wrapper for WP_Query, get_posts provides a convenient way to retrieve just the posts you need. In this guide, I’m going to dive into all the different options you can use to retrieve the posts you need.

In this article:

Basic Usage
Retrieve Posts With a Search Query
Retrieve Posts by Title
Retrieving All Posts
In Conclusion

Basic Usage

In it’s most basic form, get_posts calls WP_Query behind the scenes and returns an array of posts as WP_Post instances. The function provides WP_Query with the following default arguments by default:

$defaults = array(
	'numberposts'      => 5,
	'category'         => 0,
	'orderby'          => 'date',
	'order'            => 'DESC',
	'include'          => array(),
	'exclude'          => array(),
	'meta_key'         => '',
	'meta_value'       => '',
	'post_type'        => 'post',
	'suppress_filters' => true,
);
Code language: PHP (php)

What do these arguments mean?

numberposts: The number of posts to retrieve. The default value is 5.
category: A category ID or array of category IDs. The default value is 0.
orderby: Field to order the resulting posts by. The default value is 'date'.
order: Whether results should be in ascending or descending order. It accepts 'ASC' or ‘DESC’ for ascending and descending order, respectively. The default value is 'DESC'.
include: An array of post IDs to retrieve. The default value is an empty array.
exclude: An array of post IDs to exclude. The default value is an empty array.
meta_key: A meta key to filter by. The default value is an empty string.
meta_value: A meta value to filter by. The default value is an empty string.
post_type: A post type to filter by. The default value is 'post'.
suppress_filters: Determines if filters should be suppressed. The default value is true.

Here’s the result of a get_posts call with no arguments given:

I realize it may be hard to see each of the dumped WP_Post instances in the screenshot. Here’s the data of a single WP_Post:

WP_Post::__set_state(array(
     'ID' => 14,
     'post_author' => '1',
     'post_date' => '2022-12-31 19:47:03',
     'post_date_gmt' => '2022-12-31 19:47:03',
     'post_content' => '
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam justo justo, feugiat ut quam vitae, dapibus consequat augue. Nulla facilisi. Ut condimentum dignissim efficitur. Phasellus vitae metus a tellus sollicitudin aliquet. Proin aliquam sapien ac semper tempus. Aliquam et sapien sit amet leo venenatis bibendum. Vestibulum egestas sem sit amet est egestas mattis. Aliquam pharetra orci dictum, tempus quam aliquam, vestibulum leo.





Curabitur lobortis sapien dictum mi feugiat, ac convallis purus pellentesque. Pellentesque iaculis congue mi ut malesuada. Duis quam nulla, convallis eget accumsan faucibus, imperdiet sit amet urna. Duis ac rhoncus metus. Cras placerat vehicula ante, eget venenatis lectus hendrerit nec. Pellentesque pulvinar dictum nibh, nec posuere est imperdiet sit amet. Nunc pellentesque tempus dui, nec ullamcorper velit mattis a. Proin eget mattis quam, a hendrerit nisl. In hac habitasse platea dictumst. Nulla viverra laoreet ante, eu accumsan urna tincidunt quis. Mauris et volutpat nulla. Quisque eget mauris a mi dictum elementum sed a erat.


',
     'post_title' => 'A Neat Post',
     'post_excerpt' => '',
     'post_status' => 'publish',
     'comment_status' => 'open',
     'ping_status' => 'open',
     'post_password' => '',
     'post_name' => 'a-neat-post',
     'to_ping' => '',
     'pinged' => '',
     'post_modified' => '2022-12-31 19:47:20',
     'post_modified_gmt' => '2022-12-31 19:47:20',
     'post_content_filtered' => '',
     'post_parent' => 0,
     'guid' => 'http://tutorials.local/?p=14',
     'menu_order' => 0,
     'post_type' => 'post',
     'post_mime_type' => '',
     'comment_count' => '0',
     'filter' => 'raw',
  ))
Code language: PHP (php)

From here, it’s all a matter of using your collected posts. You could output the title of each post. Here’s how you can do this:

foreach ( $posts as $post ) {
    echo $post->post_title;
}
Code language: PHP (php)

Which displays the following:

Retrieve Posts With a Search Query

Posts can also be retrieved similar to a search query using the 's' argument. Here’s an example tweaking the example above:

$posts = get_posts( array(
    's' => 'Test'
) );
Code language: PHP (php)

Which returns an array with a single post, “A Test Post”.

Retrieving Posts by Title

Posts can be retrieved by a specific title as well, using the 'post_title' argument.

$posts = get_posts( array(
    'post_title' => 'An Interesting Post'
) );
Code language: PHP (php)

Which returns an array containing a WP_Post instance entitled, “An Interesting Post”.

Retrieving All Posts

Most of the time, using get_posts with the default arguments isn’t that useful. There are many times I find retrieve all posts to be more helpful. To do so, just call get_posts with numberposts set to -1:

$posts = get_posts( array(
    'numberposts' => -1
) );
Code language: PHP (php)

In Conclusion

The get_posts function is incredibly useful and is used everywhere in the WordPress ecosystem.