get_posts()

You are here:

get_posts( array $args = null )

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

Description Description

The defaults are as follows:

See also See also

  • WP_Query::parse_query()

Top ↑

Parameters Parameters

$args

(array) (Optional) 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’
    (array) 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’
    (array) An array of post IDs not to retrieve. Default empty array.
  • ‘suppress_filters’
    (bool) Whether to suppress filters. Default true.

 

Default value: null


Top ↑

Return Return

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


Top ↑

More Information More Information

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.


Top ↑

Source Source

File: wp-includes/post.php

2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
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 );
 
}


Top ↑

Changelog Changelog

Changelog
VersionDescription
1.2.0Introduced.
Was this article helpful?
Dislike 0
Views: 1

Cart

Log in

Create an Account
Back to Top