Codex

Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

User:Environnement-France/fr:get posts

Description

This is a simple tag for creating multiple loops.

Usage

 <?php get_posts('arguments'); ?> 

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;
 $myposts = get_posts('numberposts=5&offset=1&category=1');
 foreach($myposts as $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.

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('numberposts=3');
 foreach($lastposts as $post) :
    setup_postdata($post);
 ?>
 <h2><a href="<?php the_permalink(); ?>" id="post-<?php the_ID(); ?>"><?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
 $postslist = get_posts('numberposts=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 endforeach; ?>
 

Note: The orderby parameter was modified in Version 2.6. This code is using the new orderby format. See Parameters for details.

Random posts

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

 <ul><li><h2>A random selection of my writing</h2>
    <ul>
 <?php
 $rand_posts = get_posts('numberposts=5&orderby=rand');
 foreach( $rand_posts as $post ) :
 ?>
    <li><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></li>
 <?php endforeach; ?>
    </ul>
 </li></ul> 

Show all attachments

Do this outside any Loops in your template.

(Since Version 2.5, it may be easier to use get_children() instead.)

<?php

$args = array(
	'post_type' => 'attachment',
	'numberposts' => -1,
	'post_status' => null,
	'post_parent' => null, // any parent
	); 
$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);
	}
}

?>

Parameters: WordPress 2.6+

In addition to the parameters listed below under "WordPress 2.5 And Older", get_posts() can also take the parameters that query_posts() can since both functions now use the same database query code internally.

Note: Version 2.6 changed a number of the orderby options. Table fields that begin with post_ no longer have that part of the name. For example, post_title is now title and post_date is now date.

Parameters: WordPress 2.5 And Older

$numberposts
(integer) (optional) Number of posts to return. Set to 0 to use the max number of posts per page. Set to -1 to remove the limit.
Default: 5
$offset
(integer) (optional) Offset from latest post.
Default: 0
$category
(integer) (optional) Only show posts from this category ID. Making the category ID negative (-3 rather than 3) will show results not matching that category ID. Multiple category IDs can be specified by separating the category IDs with commas - but an array of IDs does not work.
Default: None
$category_name
(string) (optional) Only show posts from this category name or category slug.
Default: None
$tag
(string) (optional) Only show posts with this tag slug. If you specify multiple tag slugs separated by commas, all results matching any tag will be returned. If you specify multiple tag slugs separated by spaces, the results will match all the specified tag slugs.
Default: None
$orderby
(string) (optional) Sort posts by one of various values (separated by space), including:
  • 'author' - Sort by the numeric author IDs.
  • 'category' - Sort by the numeric category IDs.
  • 'content' - Sort by content.
  • 'date' - Sort by creation date.
  • 'ID' - Sort by numeric post ID.
  • 'menu_order' - Sort by the menu order. Only useful with pages.
  • 'mime_type' - Sort by MIME type. Only useful with attachments.
  • 'modified' - Sort by last modified date.
  • 'name' - Sort by stub.
  • 'parent' - Sort by parent ID.
  • 'password' - Sort by password.
  • 'rand' - Randomly sort results.
  • 'status' - Sort by status.
  • 'title' - Sort by title.
  • 'type' - Sort by type.

Notes:

  • Sorting by ID and rand is only available starting with Version 2.5.
Default: post_date
$order
(string) (optional) How to sort $orderby. Valid values:
  • 'ASC' - Ascending (lowest to highest).
  • 'DESC' - Descending (highest to lowest).
Default: DESC
$include
(string) (optional) The IDs of the posts you want to show, separated by commas and/or spaces. The following value would work in showing these six posts:
  • '45,63, 78 94 ,128 , 140'
Note: Using this parameter will override the numberposts, offset, category, exclude, meta_key, meta_value, and post_parent parameters.
Default: None
$exclude
(string) (optional) The IDs of any posts you want to exclude, separated by commas and/or spaces (see $include parameter).
Default: None
$meta_key and $meta_value
(string) (optional) Only show posts that contain a meta (custom) field with this key and value. Both parameters must be defined, or neither will work.
Default: None
$post_type
(string) (optional) The type of post to show. Available options are:
  • post - Default
  • page
  • attachment
  • any - all post types
Default: post
$post_status
(string) (optional) Show posts with a particular status. Available options are:
  • publish - Default
  • private
  • draft
  • future
  • inherit - Default if $post_type is set to attachment
  • (blank) - all statuses
Default: publish
$post_parent
(integer) (optional) Show only the children of the post with this ID
Default: None
$nopaging
(boolean) (optional) Enable or disable paging. If paging is disabled, the $numberposts option is ignored.
Default: None

Related

See also index of Function Reference and index of Template Tags.