get_posts() │ WP 1.2.0

Gets an array of posts (pages, attachments, custom post types) from the database. You can specify any criteria for getting the posts.

This function has preset parameters. Sometimes you need to change them so they don't get in the way. Preset parameters:

• post_type = post ― if we specify a taxonomy output for a post type other than post, the post_type parameter should be changed - it defaults to post.

• numberposts = 5 ― if we forget to change the numberposts parameter, we may wonder why we output only 5 entries instead of the required 20.

• suppress_filters = true ― this parameter disables some filters (hooks). Read more.

• ignore_sticky_posts = true ― can't be changed!
• no_found_rows = true ― can't be changed!

No Hooks.

Return

WP_Post[]|Int[].

• Empty array if no entries.

• Array of WP_Post objects. Each object in the array looks like this:

  array(
  	[0]=> object(WP_Post)#4692 (24) {
  		["ID"]                    => int(822)
  		["post_author"]           => string(1) "1"
  		["post_date"]             => string(19) "2016-07-07 10:28:57"
  		["post_date_gmt"]         => string(19) "2016-07-07 07:28:57"
  		["post_content"]          => string(6225) "Post content"
  		["post_title"]            => string(37) "Dead Sea (14 photos)"
  		["post_excerpt"]          => string(15) "Quote about the article"
  		["post_status"]           => string(7) "publish"
  		["comment_status"]        => string(4) "open"
  		["ping_status"]           => string(4) "open"
  		["post_password"]         => string(0) ""
  		["post_name"]             => string(95) "dead-sea-14-photos"
  		["to_ping"]               => string(0) ""
  		["pinged"]                => string(0) ""
  		["post_modified"]         => string(19) "2016-07-07 10:28:57"
  		["post_modified_gmt"]     => string(19) "2016-07-07 07:28:57"
  		["post_content_filtered"] => string(0) ""
  		["post_parent"]           => int(0)
  		["guid"]                  => string(0) ""
  		["menu_order"]            => int(0)
  		["post_type"]             => string(4) "post"
  		["post_mime_type"]        => string(0) ""
  		["comment_count"]         => string(1) "0"
  		["filter"]                => string(3) "raw"
  	}
  	[1] => object(WP_Post){
  		...
  	}
  	[2] => object(WP_Post){
  		...
  	}
  )

Usage Template

$my_posts = get_posts( [
	'numberposts' => 5,
	'category'    => 0,
	'orderby'     => 'date',
	'order'       => 'DESC',
	'include'     => array(),
	'exclude'     => array(),
	'meta_key'    => '',
	'meta_value'  =>'',
	'post_type'   => 'post',
	'suppress_filters' => true, // suppression of filters of SQL query change
] );

foreach( $my_posts as $post ){
	setup_postdata( $post );

	// output: the_title() ...
}

wp_reset_postdata(); // reset $post

Usage

get_posts( $args );

$args(строка/массив)

A list of arguments according to which the result will be obtained. See WP_Query::parse_query() for all available arguments.
Default: null - presets

Arguments of the $args parameter

• numberposts (int)
• posts_per_page (int)
• offset (int)
• category (int|string|array)
• category_name (string)
• tag (string)
• include (string|int|array)
• exclude (string|int)
• meta_key (string)
• meta_value (string)
• meta_query (array)
• date_query (array)
• post_type (string|array)
• post_mime_type (string|array)
• post_status (string)
• post_parent (int)
• nopaging (true|false)
• order (string)
• orderby (string/array)
• suppress_filters (true|false)

numberposts(int)

posts_per_page(int)

The number of output posts. Set to 0 to limit output to the maximum number of posts per page (set in WP settings) or set to -1 to remove output limitations (LIMIT).
Default: 5

offset(int)

Indent from the first post.

category(int|string|array)

Specify the ID of the category from which you want to retrieve posts. You can specify an ID with a minus sign -3, then this category will be excluded (all posts except category 3 will be retrieved). You can specify several IDs separated by commas as a string 3,5,12 or -3,-5,12).

In the value you should pass ID, not category name.

See also description of parameter cat in WP_Query.

Default: 0

category_name(string)

Show posts from this category only (specify category name or category slug).
Default: ''

tag(string)

Get posts that have specified tags. It is necessary to specify slug of the tag.

• tagname,tagname2 - if you specify more than one slug comma-separated, you will get the posts with any of specified slug.
• tagname tagname2 - if you specify more than one slug spaces-separated, you will get the posts that have all specified slugs.
  Default: ''

include(string|int|array)

The IDs of the posts to be retrieved. If a string is specified, the IDs must be separated by commas or spaces. Example, get 6 posts: '45,63,78,94,128,140'.

Important: Specifying this parameter the following parameters will be ignored: posts_per_page, offset, category, exclude, meta_key, meta_value, post_parent.
Default: ''

exclude(string|int)

The IDs of the posts that you want to exclude from the result. Separate ids with commas or a spaces.
Default: ''

meta_key(string)

meta_value(string)

Get posts which have a specified custom field (meta_key) with value (meta_value).

You can to specify meta_key and meta_value, then the posts which have the specified meta field and specified meta value will be retrieved.

Or you can specify only meta_key, then all posts will be retrieved which have this meta field, and it does not matter what value they have.

Default: ''

meta_query(array)

Selecting posts by custom fields. For more details see. WP_Query (meta_query).
Default: []

date_query(array)

Selecting posts by date. For more details see. WP_Query (date_query).
Default: []

post_type(string|array)

Posts of what type should be retrieved. Default: post. But if specify tax_query parameter, the default will be any.

Can be:

• any - include all types, except revision, and types with exclude_from_search=true parameter specified.
• attachment - by default WP_Query sets the status 'post_status'=>'publish'. But attachments has status 'post_status'=>'inherit', so to display attachments you need also to change post_status parameter to inherit or any.
• page
• post
• revision
• custom_type - name (slug) of any custom post type.
• [ 'post', 'page' ] - several types specified in array.

Default: 'post'

post_mime_type(string|array)

What type of attachment you want to get. You can use this parameter when the post_type = attachment and post_status = inherit only. I.e. only attachments have MIME-type.

You can specify several mime types in an array instead of just one. List of mime types:

• image/jpeg
• image/png
• image/gif
• image - для любых картинок
• audio/mpeg
• application/pdf
• application/zip
• See here for a complete list of mime types.

Default: ''

post_status(string)

The status of the post. You can pass multiple statuses, separated by commas.

Default is publish, and if user is authorized the private status is also added. If the request is launched from the admin part protected status types are added too: future, draft and pending.

All status types:

• publish - published post.
• pending - post on moderation.
• draft - draft posts.
• auto-draft - draft saved by WordPress (auto-save).
• future - scheduled post.
• private - personal post.
• inherit - revision or attachment.
• trash - removed post (in trash). Since 2.9.
• any - all statuses, except status with parameter exclude_from_search=true. See register_post_status() and get_post_stati().

Default: publish

post_parent(int)

Get only child posts to the specified ID.
Default: 0

nopaging(true|false)

Enable or disable pagination. If true the $numberposts parameter is ignored.
Default: false

order(string)

The sort direction for the orderby parameter. Can be:

• ASC - in order, from less to more (1, 2, 3 or a, b, c).
• DESC - in reverse order, from more to less (3, 2, 1 or c, b, a).
  Default: 'DESC'

orderby(string/array)

Fields on which you can sort posts. Can be:

• none — do not sort, output as is in the database. Equivalent to sorting by ID. Since 2.8.
• ID — sort by ID.
• author — sort by author ID.
• title — sort by title.
• name — by post name (post slug).
• date — sort by publication date.
• modified — sort by modification date.
• type — by post type (post_type). Since 4.0.
• parent — sort by the value of the post_parent field.
• rand — random order.
• RAND(x) — in a random order for numeric values. Here "x" is an integer.
• comment_count — sort by the number of comments. Since 2.9.
• relevance — by search terms (parameter s) in the following order: 1) whether the entire sentence is matched. 2) all search terms are in the post title. 3) any of the search terms appear in the post title. 4) the full sentence is found in the post content.
• menu_order — used for pages and attachments. The sequence number is specified on the edit-post admin page.

• meta_value — by the value of a custom field.

  Important: the meta_key parameter must also be defined. Note: the sorting will be alphabetical, and it's not logical if the values of custom field is a numbers (for example 1, 3, 34, 4, 56, 6 etc., not 1, 3, 4, 6, 34, 56).

• meta_value_num — sort by custom field whose values are numbers. Since 2.8.
• array key from meta_query — in this case, the sorting will be based on the value of custom field specified in the meta_query array.
• post__in — takes into account the order of ID specified in post__in parameter. order parameter is ignored
• post_name__in — takes into account the order of names specified in the post_name__in parameter. order parameter is ignored
• post_parent__in — takes into account the order of ID specified in post_parent__in parameter. order parameter is ignored.

The prefix post_ in table fields is omitted for convenience. For example, instead of date you can write post_date, instead of content post_content etc.

orderby = array() - since WP 4.0 you can specify the combination of orderby and order parameters as an array in orderby parameter. it is for sorting by several columns simultaneously. syntax is:

'orderby' => array( 'title' => 'DESC', 'menu_order' => 'ASC' )

Default: 'date'

suppress_filters(true|false)

When true (default) skips all SQL query change hooks. The following hooks will be skipped: posts_* and comment_feed_*.

Which filters are skipped see here.

In WP_Query and query_posts() functions this parameter is disabled by default (= false).

uppress_filters = true has no effect on the pre_get_posts filter.

Disabling filters like this by default can be confusing if there are plugins which affect output of posts via SQL query filters, e.g. WPML. In such cases suppress_filters should be disabled.

Default: true

Examples

$args = [
	'numberposts' => 10
];

$latest_posts = get_posts( $args );

$args = [
  'numberposts' => 10,
  'post_type'   => 'book'
];

$latest_books = get_posts( $args );

$args = [ 'fields' => 'ids' ];
$posts = get_posts( $args );
// if any posts are found $posts will be an array with their ids

$args = [
	'post_type'  => 'product',
	'meta_query' => [
		[
			'key'   => 'featured',
			'value' => 'yes',
		]
	],
];

$postslist = get_posts( $args );

<?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();
}

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

<?php
global $post;

$myposts = get_posts( [
	'posts_per_page' => 6,
	'category_name' => 'articles',
	'post_type' => 'post',
] );

foreach( $myposts as $post ){
	setup_postdata( $post );
	?>
	<div class="article-elem">
		<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
	</div>
	<?php
}
wp_reset_postdata();
?>

$show_albums = get_posts( [
	 'posts_per_page' => 8,
	 'orderby'        => 'rand',
	 'post_type'      => 'albums',
	 'genre'          => 'jazz',
	 'post_status'    => 'publish'
] );

$args = array(
	'tax_query' => array(
		array(
			'taxonomy' => 'genre',
			'field'    => 'slug',
			'terms'    => 'jazz'
		)
	)
);
$postslist = get_posts( $args );

$posts = get_posts( [
	'include'   => '3,8,1,17',
	'post_type' => 'attachment',
	'orderby'   => 'post__in',
] );

$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();
}

<?php
global $post;
$postslist = get_posts( [
	'posts_per_page' => 10,
	'order'=> 'ASC',
	'orderby' => 'title'
] );

foreach( $postslist as $post ){
	setup_postdata($post);
	?>
	<div>
		<?php the_date(); ?>
		<br />
		<?php the_title(); ?>
		<?php the_excerpt(); ?>
	   </div>
	<?php
}

wp_reset_postdata();

<ul>
<?php
$args = array( 'posts_per_page' => 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; ?>
<?php wp_reset_postdata() ?>
</ul>

<?php
$args = array(
	'post_type' => 'attachment',
	'posts_per_page' => -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 );
	}
}
wp_reset_postdata();
?>

<?php
$category = get_the_category();
rsort( $category );
$cat_add_id = $category[0]->term_id;

$posts = get_posts( array(
	'cat' => $cat_add_id,
	'posts_per_page' => 4,
	'exclude' => $GLOBALS['post']->ID,
) );

foreach( $posts as $post ){
	setup_postdata($post);
	?>
	<a href="<?php the_permalink(); ?>"><?php the_title(); ?></a>
	<?php
}
wp_reset_postdata();
?>

<ul>
	<?php
	global $post;
	$myposts = get_posts( [
		'posts_per_page' => 5,
		'offset' => 1,
		'category' => 1,
	] );

	foreach( $myposts as $post ){
		setup_postdata( $post );
		?>
		<li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
		<?php
	}

	wp_reset_postdata();
	?>
</ul>

Add Your Own Example