get_pages

Retrieve a list of pages.

Description

(array|false) get_pages( (array) $args = array() ); 

Returns (array|false)

List of pages matching defaults or `$args`.

Parameters (1)

0. $args — Optional. (array) => array()
Array or string of arguments to retrieve pages.

Options

  • child_of (int) => 0, or no restriction

    Page ID to return child and grandchild pages of. Note: The value of $hierarchical has no bearing on whether $child_of returns hierarchical results.

  • sort_order (string) => 'ASC'

    How to sort retrieved pages. Accepts ASC,, DESC..

  • sort_column (string) => 'post_title'

    What columns to sort pages by, comma-separated. Accepts post_author,, post_date., post_title , post_name, post_modified, menu_order, post_modified_gmt, post_parent, ID, rand, comment_count. post_ can be omitted for any values that start with it.

  • hierarchical (bool) => true

    Whether to return pages hierarchically. If false in conjunction with $child_of also being false, both arguments will be disregarded.

  • exclude (array) => array()

    Array of page IDs to exclude.

  • include (array) => array()

    Array of page IDs to include. Cannot be used with $child_of,, $parent., $exclude, $meta_key, $meta_value, or $hierarchical.

  • meta_key (string) => ''

    Only include pages with this meta key.

  • meta_value (string) => ''

    Only include pages with this meta value. Requires $meta_key..

  • authors (string) => ''

    A comma-separated list of author IDs.

  • parent (int) => -1, or no restriction

    Page ID to return direct children of.

  • exclude_tree (string|array) => array()

    Comma-separated string or array of page IDs to exclude.

  • number (int) => 0, or all pages

    The number of pages to return.

  • offset (int) => 0

    The number of pages to skip before returning. Requires $number..

  • post_type (string) => 'page'

    The post type to query.

array(

    /**
     * Page ID to return child and grandchild pages of. Note: The value of `$hierarchical` has no
     * bearing on whether `$child_of` returns hierarchical results.
     *
     * @type int
     * @default 0, or no restriction
     */
    'child_of' => 0, or no restriction,

    /**
     * How to sort retrieved pages. Accepts 'ASC', 'DESC'.
     *
     * @type string
     * @default 'ASC'
     */
    'sort_order' => 'ASC',

    /**
     * What columns to sort pages by, comma-separated. Accepts 'post_author', 'post_date',
     * 'post_title', 'post_name', 'post_modified', 'menu_order', 'post_modified_gmt',
     * 'post_parent', 'ID', 'rand', 'comment_count'. 'post_' can be omitted for any values that
     * start with it.
     *
     * @type string
     * @default 'post_title'
     */
    'sort_column' => 'post_title',

    /**
     * Whether to return pages hierarchically. If false in conjunction with `$child_of` also being
     * false, both arguments will be disregarded.
     *
     * @type bool
     * @default true
     */
    'hierarchical' => true,

    /**
     * Array of page IDs to exclude.
     *
     * @type array
     * @default array()
     */
    'exclude' => array(),

    /**
     * Array of page IDs to include. Cannot be used with `$child_of`, `$parent`, `$exclude`,
     * `$meta_key`, `$meta_value`, or `$hierarchical`.
     *
     * @type array
     * @default array()
     */
    'include' => array(),

    /**
     * Only include pages with this meta key.
     *
     * @type string
     * @default ''
     */
    'meta_key' => '',

    /**
     * Only include pages with this meta value. Requires `$meta_key`.
     *
     * @type string
     * @default ''
     */
    'meta_value' => '',

    /**
     * A comma-separated list of author IDs.
     *
     * @type string
     * @default ''
     */
    'authors' => '',

    /**
     * Page ID to return direct children of.
     *
     * @type int
     * @default -1, or no restriction
     */
    'parent' => -1, or no restriction,

    /**
     * Comma-separated string or array of page IDs to exclude.
     *
     * @type string|array
     * @default array()
     */
    'exclude_tree' => array(),

    /**
     * The number of pages to return.
     *
     * @type int
     * @default 0, or all pages
     */
    'number' => 0, or all pages,

    /**
     * The number of pages to skip before returning. Requires `$number`.
     *
     * @type int
     */
    'offset' => 0,

    /**
     * The post type to query.
     *
     * @type string
     * @default 'page'
     */
    'post_type' => 'page'
);        


Usage

  1. if ( !function_exists( 'get_pages' ) ) { 
  2. require_once ABSPATH . WPINC . '/post.php'; 
  3.  
  4. // Optional. Array or string of arguments to retrieve pages. 
  5. $args = array( 
  6. 'child_of' => 0, or no restriction, 
  7. 'sort_order' => 'ASC', 
  8. 'sort_column' => 'post_title', 
  9. 'hierarchical' => true, 
  10. 'exclude' => array(), 
  11. 'include' => array(), 
  12. 'meta_key' => '', 
  13. 'meta_value' => '', 
  14. 'authors' => '', 
  15. 'parent' => -1, or no restriction, 
  16. 'exclude_tree' => array(), 
  17. 'number' => 0, or all pages, 
  18. 'offset' => 0, 
  19. 'post_type' => 'page' 
  20. ); 
  21.  
  22. // NOTICE! Understand what this does before running. 
  23. $result = get_pages($args); 
  24.  

Defined (1)

The function is defined in the following location(s).

/wp-includes/post.php  
  1. function get_pages( $args = array() ) { 
  2. global $wpdb; 
  3.  
  4. $defaults = array( 
  5. 'child_of' => 0,  
  6. 'sort_order' => 'ASC',  
  7. 'sort_column' => 'post_title',  
  8. 'hierarchical' => 1,  
  9. 'exclude' => array(),  
  10. 'include' => array(),  
  11. 'meta_key' => '',  
  12. 'meta_value' => '',  
  13. 'authors' => '',  
  14. 'parent' => -1,  
  15. 'exclude_tree' => array(),  
  16. 'number' => '',  
  17. 'offset' => 0,  
  18. 'post_type' => 'page',  
  19. 'post_status' => 'publish',  
  20. ); 
  21.  
  22. $r = wp_parse_args( $args, $defaults ); 
  23.  
  24. $number = (int) $r['number']; 
  25. $offset = (int) $r['offset']; 
  26. $child_of = (int) $r['child_of']; 
  27. $hierarchical = $r['hierarchical']; 
  28. $exclude = $r['exclude']; 
  29. $meta_key = $r['meta_key']; 
  30. $meta_value = $r['meta_value']; 
  31. $parent = $r['parent']; 
  32. $post_status = $r['post_status']; 
  33.  
  34. // Make sure the post type is hierarchical. 
  35. $hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) ); 
  36. if ( ! in_array( $r['post_type'], $hierarchical_post_types ) ) { 
  37. return false; 
  38.  
  39. if ( $parent > 0 && ! $child_of ) { 
  40. $hierarchical = false; 
  41.  
  42. // Make sure we have a valid post status. 
  43. if ( ! is_array( $post_status ) ) { 
  44. $post_status = explode( ', ', $post_status ); 
  45. if ( array_diff( $post_status, get_post_stati() ) ) { 
  46. return false; 
  47.  
  48. // $args can be whatever, only use the args defined in defaults to compute the key. 
  49. $key = md5( serialize( wp_array_slice_assoc( $r, array_keys( $defaults ) ) ) ); 
  50. $last_changed = wp_cache_get_last_changed( 'posts' ); 
  51.  
  52. $cache_key = "get_pages:$key:$last_changed"; 
  53. if ( $cache = wp_cache_get( $cache_key, 'posts' ) ) { 
  54. // Convert to WP_Post instances. 
  55. $pages = array_map( 'get_post', $cache ); 
  56. /** This filter is documented in wp-includes/post.php */ 
  57. $pages = apply_filters( 'get_pages', $pages, $r ); 
  58. return $pages; 
  59.  
  60. $inclusions = ''; 
  61. if ( ! empty( $r['include'] ) ) { 
  62. $child_of = 0; //ignore child_of, parent, exclude, meta_key, and meta_value params if using include 
  63. $parent = -1; 
  64. $exclude = ''; 
  65. $meta_key = ''; 
  66. $meta_value = ''; 
  67. $hierarchical = false; 
  68. $incpages = wp_parse_id_list( $r['include'] ); 
  69. if ( ! empty( $incpages ) ) { 
  70. $inclusions = ' AND ID IN (' . implode( ', ', $incpages ) . ')'; 
  71.  
  72. $exclusions = ''; 
  73. if ( ! empty( $exclude ) ) { 
  74. $expages = wp_parse_id_list( $exclude ); 
  75. if ( ! empty( $expages ) ) { 
  76. $exclusions = ' AND ID NOT IN (' . implode( ', ', $expages ) . ')'; 
  77.  
  78. $author_query = ''; 
  79. if ( ! empty( $r['authors'] ) ) { 
  80. $post_authors = preg_split( '/[\s, ]+/', $r['authors'] ); 
  81.  
  82. if ( ! empty( $post_authors ) ) { 
  83. foreach ( $post_authors as $post_author ) { 
  84. //Do we have an author id or an author login? 
  85. if ( 0 == intval($post_author) ) { 
  86. $post_author = get_user_by('login', $post_author); 
  87. if ( empty( $post_author ) ) { 
  88. continue; 
  89. if ( empty( $post_author->ID ) ) { 
  90. continue; 
  91. $post_author = $post_author->ID; 
  92.  
  93. if ( '' == $author_query ) { 
  94. $author_query = $wpdb->prepare(' post_author = %d ', $post_author); 
  95. } else { 
  96. $author_query .= $wpdb->prepare(' OR post_author = %d ', $post_author); 
  97. if ( '' != $author_query ) { 
  98. $author_query = " AND ($author_query)"; 
  99.  
  100. $join = ''; 
  101. $where = "$exclusions $inclusions "; 
  102. if ( '' !== $meta_key || '' !== $meta_value ) { 
  103. $join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )"; 
  104.  
  105. // meta_key and meta_value might be slashed 
  106. $meta_key = wp_unslash($meta_key); 
  107. $meta_value = wp_unslash($meta_value); 
  108. if ( '' !== $meta_key ) { 
  109. $where .= $wpdb->prepare(" AND $wpdb->postmeta.meta_key = %s", $meta_key); 
  110. if ( '' !== $meta_value ) { 
  111. $where .= $wpdb->prepare(" AND $wpdb->postmeta.meta_value = %s", $meta_value); 
  112.  
  113.  
  114. if ( is_array( $parent ) ) { 
  115. $post_parent__in = implode( ', ', array_map( 'absint', (array) $parent ) ); 
  116. if ( ! empty( $post_parent__in ) ) { 
  117. $where .= " AND post_parent IN ($post_parent__in)"; 
  118. } elseif ( $parent >= 0 ) { 
  119. $where .= $wpdb->prepare(' AND post_parent = %d ', $parent); 
  120.  
  121. if ( 1 == count( $post_status ) ) { 
  122. $where_post_type = $wpdb->prepare( "post_type = %s AND post_status = %s", $r['post_type'], reset( $post_status ) ); 
  123. } else { 
  124. $post_status = implode( "', '", $post_status ); 
  125. $where_post_type = $wpdb->prepare( "post_type = %s AND post_status IN ('$post_status')", $r['post_type'] ); 
  126.  
  127. $orderby_array = array(); 
  128. $allowed_keys = array( 'author', 'post_author', 'date', 'post_date', 'title', 'post_title', 'name', 'post_name', 'modified',  
  129. 'post_modified', 'modified_gmt', 'post_modified_gmt', 'menu_order', 'parent', 'post_parent',  
  130. 'ID', 'rand', 'comment_count' ); 
  131.  
  132. foreach ( explode( ', ', $r['sort_column'] ) as $orderby ) { 
  133. $orderby = trim( $orderby ); 
  134. if ( ! in_array( $orderby, $allowed_keys ) ) { 
  135. continue; 
  136.  
  137. switch ( $orderby ) { 
  138. case 'menu_order': 
  139. break; 
  140. case 'ID': 
  141. $orderby = "$wpdb->posts.ID"; 
  142. break; 
  143. case 'rand': 
  144. $orderby = 'RAND()'; 
  145. break; 
  146. case 'comment_count': 
  147. $orderby = "$wpdb->posts.comment_count"; 
  148. break; 
  149. default: 
  150. if ( 0 === strpos( $orderby, 'post_' ) ) { 
  151. $orderby = "$wpdb->posts." . $orderby; 
  152. } else { 
  153. $orderby = "$wpdb->posts.post_" . $orderby; 
  154.  
  155. $orderby_array[] = $orderby; 
  156.  
  157. $sort_column = ! empty( $orderby_array ) ? implode( ', ', $orderby_array ) : "$wpdb->posts.post_title"; 
  158.  
  159. $sort_order = strtoupper( $r['sort_order'] ); 
  160. if ( '' !== $sort_order && ! in_array( $sort_order, array( 'ASC', 'DESC' ) ) ) { 
  161. $sort_order = 'ASC'; 
  162.  
  163. $query = "SELECT * FROM $wpdb->posts $join WHERE ($where_post_type) $where "; 
  164. $query .= $author_query; 
  165. $query .= " ORDER BY " . $sort_column . " " . $sort_order ; 
  166.  
  167. if ( ! empty( $number ) ) { 
  168. $query .= ' LIMIT ' . $offset . ', ' . $number; 
  169.  
  170. $pages = $wpdb->get_results($query); 
  171.  
  172. if ( empty($pages) ) { 
  173. /** This filter is documented in wp-includes/post.php */ 
  174. $pages = apply_filters( 'get_pages', array(), $r ); 
  175. return $pages; 
  176.  
  177. // Sanitize before caching so it'll only get done once. 
  178. $num_pages = count($pages); 
  179. for ($i = 0; $i < $num_pages; $i++) { 
  180. $pages[$i] = sanitize_post($pages[$i], 'raw'); 
  181.  
  182. // Update cache. 
  183. update_post_cache( $pages ); 
  184.  
  185. if ( $child_of || $hierarchical ) { 
  186. $pages = get_page_children($child_of, $pages); 
  187.  
  188. if ( ! empty( $r['exclude_tree'] ) ) { 
  189. $exclude = wp_parse_id_list( $r['exclude_tree'] ); 
  190. foreach ( $exclude as $id ) { 
  191. $children = get_page_children( $id, $pages ); 
  192. foreach ( $children as $child ) { 
  193. $exclude[] = $child->ID; 
  194.  
  195. $num_pages = count( $pages ); 
  196. for ( $i = 0; $i < $num_pages; $i++ ) { 
  197. if ( in_array( $pages[$i]->ID, $exclude ) ) { 
  198. unset( $pages[$i] ); 
  199.  
  200. $page_structure = array(); 
  201. foreach ( $pages as $page ) { 
  202. $page_structure[] = $page->ID; 
  203.  
  204. wp_cache_set( $cache_key, $page_structure, 'posts' ); 
  205.  
  206. // Convert to WP_Post instances 
  207. $pages = array_map( 'get_post', $pages ); 
  208.  
  209. /** 
  210. * Filters the retrieved list of pages. 
  211. * @since 2.1.0 
  212. * @param array $pages List of pages to retrieve. 
  213. * @param array $r Array of get_pages() arguments. 
  214. */ 
  215. return apply_filters( 'get_pages', $pages, $r );