get_pages( array|string $args = array() )

Retrieve a list of pages (or hierarchical post type items).

Description
- Parameters
- Return
- Source
- Changelog
Related
- Uses
- Used By
User Contributed Notes

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 $hierarchical has no bearing on whether $child_of returns 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_of also 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()

Top ↑

Return Return

(array|false) List of pages matching defaults or $args.

Top ↑

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

Top ↑

Changelog Changelog

Changelog
Version	Description
1.5.0	Introduced.

Top ↑

Uses Uses

Uses
Uses	Description
wp-includes/functions.php: wp_parse_list()	Cleans up an array, comma- or space-separated list of scalar values.
wp-includes/functions.php: wp_cache_get_last_changed()	Get last changed date for the specified cache group.
wp-includes/cache.php: wp_cache_get()	Retrieves the cache contents from the cache by key and group.
wp-includes/cache.php: wp_cache_set()	Saves the data to the cache.
wp-includes/formatting.php: wp_unslash()	Remove slashes from a string or array of strings.
wp-includes/pluggable.php: get_user_by()	Retrieve user info by a given field
wp-includes/functions.php: wp_parse_args()	Merge user defined arguments into defaults array.
wp-includes/functions.php: wp_array_slice_assoc()	Extract a slice of an array, given a list of keys.
wp-includes/functions.php: wp_parse_id_list()	Clean up an array, comma- or space-separated list of IDs.
wp-includes/plugin.php: apply_filters()	Call the functions added to a filter hook.
wp-includes/post.php: update_post_cache()	Updates posts in cache.
wp-includes/post.php: get_page_children()	Identify descendants of a given page ID in a list of page objects.
wp-includes/post.php: get_pages	Filters the retrieved list of pages.
wp-includes/post.php: sanitize_post()	Sanitize every post field.
wp-includes/post.php: get_post_types()	Get a list of all registered post type objects.
wp-includes/post.php: get_post_stati()	Get a list of post statuses.
wp-includes/wp-db.php: wpdb::get_results()	Retrieve an entire SQL result set from the database (i.e., many rows)
wp-includes/wp-db.php: wpdb::prepare()	Prepares a SQL query for safe execution. Uses sprintf()-like syntax.

Show 13 more uses Hide more uses

Top ↑

Used By Used By

Used By
Used By	Description
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::has_published_pages()	Return whether there are published pages.
wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::_display_rows_hierarchical()
wp-includes/post-template.php: wp_dropdown_pages()	Retrieve or display a list of pages as a dropdown (select list).
wp-includes/post-template.php: wp_list_pages()	Retrieve or display a list of pages (or hierarchical post type items) in list (li) format.
wp-includes/post-template.php: get_body_class()	Retrieves an array of the class names for the body element.

Top ↑

User Contributed Notes User Contributed Notes

Contributed by Codex — 4 years ago

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_link passing 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 code Collapse full source code

Contributed by Codex — 4 years ago

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 code Collapse full source code

You must log in before being able to contribute a note or feedback.

WordPress.org

Code Reference

get_pages( array|string $args = array() )

Contents

Description Description

Parameters Parameters

Return Return

Source Source

Changelog Changelog

User Contributed Notes User Contributed Notes

WordPress.org

get_pages( array|string $args = array() )

Contents

Description #Description

Parameters #Parameters

Return #Return

Source #Source

Changelog #Changelog

Related #Related

Uses #Uses

Used By #Used By

User Contributed Notes #User Contributed Notes

Description Description

Parameters Parameters

Return Return

Source Source

Changelog Changelog

Related Related

Uses Uses

Used By Used By

User Contributed Notes User Contributed Notes