get_pages( array|string $args = array() )
Retrieve a list of pages (or hierarchical post type items).
Description Description
Parameters Parameters
- $args
-
(array|string) (Optional) Array or string of arguments to retrieve pages.
- 'child_of'
(int) Page ID to return child and grandchild pages of. Note: The value of$hierarchicalhas no bearing on whether$child_ofreturns hierarchical results. Default 0, or no restriction. - 'sort_order'
(string) How to sort retrieved pages. Accepts 'ASC', 'DESC'. Default 'ASC'. - 'sort_column'
(string) 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. Default 'post_title'. - 'hierarchical'
(bool) Whether to return pages hierarchically. If false in conjunction with$child_ofalso being false, both arguments will be disregarded. Default true. - 'exclude'
(array) Array of page IDs to exclude. - 'include'
(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) Page ID to return direct children of. Default -1, or no restriction. - 'exclude_tree'
(string|array) Comma-separated string or array of page IDs to exclude. - 'number'
(int) The number of pages to return. Default 0, or all pages. - 'offset'
(int) The number of pages to skip before returning. Requires$number. Default 0. - 'post_type'
(string) The post type to query. Default 'page'. - 'post_status'
(string|array) A comma-separated list or array of post statuses to include. Default 'publish'.
Default value: array()
- 'child_of'
Return Return
(array|false) List of pages matching defaults or $args.
Source Source
File: wp-includes/post.php
function get_pages( $args = array() ) {
global $wpdb;
$defaults = array(
'child_of' => 0,
'sort_order' => 'ASC',
'sort_column' => 'post_title',
'hierarchical' => 1,
'exclude' => array(),
'include' => array(),
'meta_key' => '',
'meta_value' => '',
'authors' => '',
'parent' => -1,
'exclude_tree' => array(),
'number' => '',
'offset' => 0,
'post_type' => 'page',
'post_status' => 'publish',
);
$r = wp_parse_args( $args, $defaults );
$number = (int) $r['number'];
$offset = (int) $r['offset'];
$child_of = (int) $r['child_of'];
$hierarchical = $r['hierarchical'];
$exclude = $r['exclude'];
$meta_key = $r['meta_key'];
$meta_value = $r['meta_value'];
$parent = $r['parent'];
$post_status = $r['post_status'];
// Make sure the post type is hierarchical.
$hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) );
if ( ! in_array( $r['post_type'], $hierarchical_post_types ) ) {
return false;
}
if ( $parent > 0 && ! $child_of ) {
$hierarchical = false;
}
// Make sure we have a valid post status.
if ( ! is_array( $post_status ) ) {
$post_status = explode( ',', $post_status );
}
if ( array_diff( $post_status, get_post_stati() ) ) {
return false;
}
// $args can be whatever, only use the args defined in defaults to compute the key.
$key = md5( serialize( wp_array_slice_assoc( $r, array_keys( $defaults ) ) ) );
$last_changed = wp_cache_get_last_changed( 'posts' );
$cache_key = "get_pages:$key:$last_changed";
$cache = wp_cache_get( $cache_key, 'posts' );
if ( false !== $cache ) {
// Convert to WP_Post instances.
$pages = array_map( 'get_post', $cache );
/** This filter is documented in wp-includes/post.php */
$pages = apply_filters( 'get_pages', $pages, $r );
return $pages;
}
$inclusions = '';
if ( ! empty( $r['include'] ) ) {
$child_of = 0; //ignore child_of, parent, exclude, meta_key, and meta_value params if using include
$parent = -1;
$exclude = '';
$meta_key = '';
$meta_value = '';
$hierarchical = false;
$incpages = wp_parse_id_list( $r['include'] );
if ( ! empty( $incpages ) ) {
$inclusions = ' AND ID IN (' . implode( ',', $incpages ) . ')';
}
}
$exclusions = '';
if ( ! empty( $exclude ) ) {
$expages = wp_parse_id_list( $exclude );
if ( ! empty( $expages ) ) {
$exclusions = ' AND ID NOT IN (' . implode( ',', $expages ) . ')';
}
}
$author_query = '';
if ( ! empty( $r['authors'] ) ) {
$post_authors = wp_parse_list( $r['authors'] );
if ( ! empty( $post_authors ) ) {
foreach ( $post_authors as $post_author ) {
//Do we have an author id or an author login?
if ( 0 == intval( $post_author ) ) {
$post_author = get_user_by( 'login', $post_author );
if ( empty( $post_author ) ) {
continue;
}
if ( empty( $post_author->ID ) ) {
continue;
}
$post_author = $post_author->ID;
}
if ( '' == $author_query ) {
$author_query = $wpdb->prepare( ' post_author = %d ', $post_author );
} else {
$author_query .= $wpdb->prepare( ' OR post_author = %d ', $post_author );
}
}
if ( '' != $author_query ) {
$author_query = " AND ($author_query)";
}
}
}
$join = '';
$where = "$exclusions $inclusions ";
if ( '' !== $meta_key || '' !== $meta_value ) {
$join = " LEFT JOIN $wpdb->postmeta ON ( $wpdb->posts.ID = $wpdb->postmeta.post_id )";
// meta_key and meta_value might be slashed
$meta_key = wp_unslash( $meta_key );
$meta_value = wp_unslash( $meta_value );
if ( '' !== $meta_key ) {
$where .= $wpdb->prepare( " AND $wpdb->postmeta.meta_key = %s", $meta_key );
}
if ( '' !== $meta_value ) {
$where .= $wpdb->prepare( " AND $wpdb->postmeta.meta_value = %s", $meta_value );
}
}
if ( is_array( $parent ) ) {
$post_parent__in = implode( ',', array_map( 'absint', (array) $parent ) );
if ( ! empty( $post_parent__in ) ) {
$where .= " AND post_parent IN ($post_parent__in)";
}
} elseif ( $parent >= 0 ) {
$where .= $wpdb->prepare( ' AND post_parent = %d ', $parent );
}
if ( 1 == count( $post_status ) ) {
$where_post_type = $wpdb->prepare( 'post_type = %s AND post_status = %s', $r['post_type'], reset( $post_status ) );
} else {
$post_status = implode( "', '", $post_status );
$where_post_type = $wpdb->prepare( "post_type = %s AND post_status IN ('$post_status')", $r['post_type'] );
}
$orderby_array = array();
$allowed_keys = array(
'author',
'post_author',
'date',
'post_date',
'title',
'post_title',
'name',
'post_name',
'modified',
'post_modified',
'modified_gmt',
'post_modified_gmt',
'menu_order',
'parent',
'post_parent',
'ID',
'rand',
'comment_count',
);
foreach ( explode( ',', $r['sort_column'] ) as $orderby ) {
$orderby = trim( $orderby );
if ( ! in_array( $orderby, $allowed_keys ) ) {
continue;
}
switch ( $orderby ) {
case 'menu_order':
break;
case 'ID':
$orderby = "$wpdb->posts.ID";
break;
case 'rand':
$orderby = 'RAND()';
break;
case 'comment_count':
$orderby = "$wpdb->posts.comment_count";
break;
default:
if ( 0 === strpos( $orderby, 'post_' ) ) {
$orderby = "$wpdb->posts." . $orderby;
} else {
$orderby = "$wpdb->posts.post_" . $orderby;
}
}
$orderby_array[] = $orderby;
}
$sort_column = ! empty( $orderby_array ) ? implode( ',', $orderby_array ) : "$wpdb->posts.post_title";
$sort_order = strtoupper( $r['sort_order'] );
if ( '' !== $sort_order && ! in_array( $sort_order, array( 'ASC', 'DESC' ) ) ) {
$sort_order = 'ASC';
}
$query = "SELECT * FROM $wpdb->posts $join WHERE ($where_post_type) $where ";
$query .= $author_query;
$query .= ' ORDER BY ' . $sort_column . ' ' . $sort_order;
if ( ! empty( $number ) ) {
$query .= ' LIMIT ' . $offset . ',' . $number;
}
$pages = $wpdb->get_results( $query );
if ( empty( $pages ) ) {
wp_cache_set( $cache_key, array(), 'posts' );
/** This filter is documented in wp-includes/post.php */
$pages = apply_filters( 'get_pages', array(), $r );
return $pages;
}
// Sanitize before caching so it'll only get done once.
$num_pages = count( $pages );
for ( $i = 0; $i < $num_pages; $i++ ) {
$pages[ $i ] = sanitize_post( $pages[ $i ], 'raw' );
}
// Update cache.
update_post_cache( $pages );
if ( $child_of || $hierarchical ) {
$pages = get_page_children( $child_of, $pages );
}
if ( ! empty( $r['exclude_tree'] ) ) {
$exclude = wp_parse_id_list( $r['exclude_tree'] );
foreach ( $exclude as $id ) {
$children = get_page_children( $id, $pages );
foreach ( $children as $child ) {
$exclude[] = $child->ID;
}
}
$num_pages = count( $pages );
for ( $i = 0; $i < $num_pages; $i++ ) {
if ( in_array( $pages[ $i ]->ID, $exclude ) ) {
unset( $pages[ $i ] );
}
}
}
$page_structure = array();
foreach ( $pages as $page ) {
$page_structure[] = $page->ID;
}
wp_cache_set( $cache_key, $page_structure, 'posts' );
// Convert to WP_Post instances
$pages = array_map( 'get_post', $pages );
/**
* Filters the retrieved list of pages.
*
* @since 2.1.0
*
* @param array $pages List of pages to retrieve.
* @param array $r Array of get_pages() arguments.
*/
return apply_filters( 'get_pages', $pages, $r );
}
Expand full source code Collapse full source code View on Trac
Changelog Changelog
| Version | Description |
|---|---|
| 1.5.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Displaying pages in dropdown list
In this example a dropdown list with all the pages. Note how you can grab the link for the page with a simple call to the function
get_page_linkpassing the ID of the page.<select name="page-dropdown" onchange='document.location.href=this.options[this.selectedIndex].value;'> <option value=""> <?php echo esc_attr( __( 'Select page' ) ); ?></option> <?php $pages = get_pages(); foreach ( $pages as $page ) { $option = '<option value="' . get_page_link( $page->ID ) . '">'; $option .= $page->post_title; $option .= '</option>'; echo $option; } ?> </select>Expand full source codeCollapse full source code
Displaying child pages of the current page in post format
<?php $mypages = get_pages( array( 'child_of' => $post->ID, 'sort_column' => 'post_date', 'sort_order' => 'desc' ) ); foreach( $mypages as $page ) { $content = $page->post_content; if ( ! $content ) // Check for empty page continue; $content = apply_filters( 'the_content', $content ); ?> <h2><a href="<?php echo get_page_link( $page->ID ); ?>"><?php echo $page->post_title; ?></a></h2> <div class="entry"><?php echo $content; ?></div> <?php } ?>Expand full source codeCollapse full source code