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

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:

• WP_Query
• WP_Query::parse_query()

$args array Optional

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

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

More Arguments from WP_Query::parse_query( ... $query )

Array or string of Query parameters.

• attachment_idint
  Attachment post ID. Used for 'attachment' post_type.
• authorint|string
  Author ID, or comma-separated list of IDs.
• author_namestring
  User 'user_nicename'.
• author__inint[]
  An array of author IDs to query from.
• author__not_inint[]
  An array of author IDs not to query from.
• cache_resultsbool
  Whether to cache post information. Default true.
• catint|string
  Category ID or comma-separated list of IDs (this or any children).
• category__andint[]
  An array of category IDs (AND in).
• category__inint[]
  An array of category IDs (OR in, no children).
• category__not_inint[]
  An array of category IDs (NOT in).
• category_namestring
  Use category slug (not name, this or any children).
• comment_countarray|int
  Filter results by comment count. Provide an integer to match comment count exactly. Provide an array with integer 'value' and 'compare' operator ('=', '!=', '>', '>=', '<', '<=' ) to compare against comment_count in a specific way.
• comment_statusstring
  Comment status.
• comments_per_pageint
  The number of comments to return per page.
  Default 'comments_per_page' option.
• date_queryarray
  An associative array of WP_Date_Query arguments.
  See WP_Date_Query::__construct().
• dayint
  Day of the month. Accepts numbers 1-31.
• exactbool
  Whether to search by exact keyword. Default false.
• fieldsstring
  Post fields to query for. Accepts:
  

  • '' Returns an array of complete post objects (WP_Post[]).
  • 'ids' Returns an array of post IDs (int[]).
  • 'id=>parent' Returns an associative array of parent post IDs, keyed by post ID (int[]).

  Default ''.
• hourint
  Hour of the day. Accepts numbers 0-23.
• ignore_sticky_postsint|bool
  Whether to ignore sticky posts or not. Setting this to false excludes stickies from 'post__in'. Accepts 1|true, 0|false.
  Default false.
• mint
  Combination YearMonth. Accepts any four-digit year and month numbers 01-12.
• meta_keystring|string[]
  Meta key or keys to filter by.
• meta_valuestring|string[]
  Meta value or values to filter by.
• meta_comparestring
  MySQL operator used for comparing the meta value.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_compare_keystring
  MySQL operator used for comparing the meta key.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_typestring
  MySQL data type that the meta_value column will be CAST to for comparisons.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_type_keystring
  MySQL data type that the meta_key column will be CAST to for comparisons.
  See WP_Meta_Query::__construct() for accepted values and default value.
• meta_queryarray
  An associative array of WP_Meta_Query arguments.
  See WP_Meta_Query::__construct() for accepted values.
• menu_orderint
  The menu order of the posts.
• minuteint
  Minute of the hour. Accepts numbers 0-59.
• monthnumint
  The two-digit month. Accepts numbers 1-12.
• namestring
  Post slug.
• nopagingbool
  Show all posts (true) or paginate (false). Default false.
• no_found_rowsbool
  Whether to skip counting the total rows found. Enabling can improve performance. Default false.
• offsetint
  The number of posts to offset before retrieval.
• orderstring
  Designates ascending or descending order of posts. Default 'DESC'.
  Accepts 'ASC', 'DESC'.
• orderbystring|array
  Sort retrieved posts by parameter. One or more options may be passed.
  To use 'meta_value', or 'meta_value_num', 'meta_key=keyname' must be also be defined. To sort by a specific $meta_query clause, use that clause's array key. Accepts:
  

  • 'none'
  • 'name'
  • 'author'
  • 'date'
  • 'title'
  • 'modified'
  • 'menu_order'
  • 'parent'
  • 'ID'
  • 'rand'
  • 'relevance'
  • 'RAND(x)' (where 'x' is an integer seed value)
  • 'comment_count'
  • 'meta_value'
  • 'meta_value_num'
  • 'post__in'
  • 'post_name__in'
  • 'post_parent__in'
  • The array keys of $meta_query.

  Default is 'date', except when a search is being performed, when the default is 'relevance'.
• pint
  Post ID.
• pageint
  Show the number of posts that would show up on page X of a static front page.
• pagedint
  The number of the current page.
• page_idint
  Page ID.
• pagenamestring
  Page slug.
• permstring
  Show posts if user has the appropriate capability.
• ping_statusstring
  Ping status.
• post__inint[]
  An array of post IDs to retrieve, sticky posts will be included.
• post__not_inint[]
  An array of post IDs not to retrieve. Note: a string of comma- separated IDs will NOT work.
• post_mime_typestring
  The mime type of the post. Used for 'attachment' post_type.
• post_name__instring[]
  An array of post slugs that results must match.
• post_parentint
  Page ID to retrieve child pages for. Use 0 to only retrieve top-level pages.
• post_parent__inint[]
  An array containing parent page IDs to query child pages from.
• post_parent__not_inint[]
  An array containing parent page IDs not to query child pages from.
• post_typestring|string[]
  A post type slug (string) or array of post type slugs.
  Default 'any' if using 'tax_query'.
• post_statusstring|string[]
  A post status (string) or array of post statuses.
• posts_per_pageint
  The number of posts to query for. Use -1 to request all posts.
• posts_per_archive_pageint
  The number of posts to query for by archive page. Overrides 'posts_per_page' when is_archive() , or is_search() are true.
• sstring
  Search keyword(s). Prepending a term with a hyphen will exclude posts matching that term. Eg, 'pillow -sofa' will return posts containing 'pillow' but not 'sofa'. The character used for exclusion can be modified using the the 'wp_query_search_exclusion_prefix' filter.
• secondint
  Second of the minute. Accepts numbers 0-59.
• sentencebool
  Whether to search by phrase. Default false.
• suppress_filtersbool
  Whether to suppress filters. Default false.
• tagstring
  Tag slug. Comma-separated (either), Plus-separated (all).
• tag__andint[]
  An array of tag IDs (AND in).
• tag__inint[]
  An array of tag IDs (OR in).
• tag__not_inint[]
  An array of tag IDs (NOT in).
• tag_idint
  Tag id or comma-separated list of IDs.
• tag_slug__andstring[]
  An array of tag slugs (AND in).
• tag_slug__instring[]
  An array of tag slugs (OR in). unless 'ignore_sticky_posts' is true. Note: a string of comma-separated IDs will NOT work.
• tax_queryarray
  An associative array of WP_Tax_Query arguments.
  See WP_Tax_Query::__construct().
• titlestring
  Post title.
• update_post_meta_cachebool
  Whether to update the post meta cache. Default true.
• update_post_term_cachebool
  Whether to update the post term cache. Default true.
• update_menu_item_cachebool
  Whether to update the menu item cache. Default false.
• lazy_load_term_metabool
  Whether to lazy-load term meta. Setting to false will disable cache priming for term meta, so that each get_term_meta() call will hit the database.
  Defaults to the value of $update_post_term_cache.
• wint
  The week number of the year. Accepts numbers 0-53.
• yearint
  The four-digit year. Accepts any four-digit year.

Default: null

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.

File: wp-includes/post.php. View all references

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 );

}