get_pages()
Retrieve pages data (or hierarchical post type data) as an array of posts objects. Caches the result in object cache.
The received data should be custom processed via foreach.
Specify the post_type parameter to get data of custom post types.
The function works only with hierarchical post types. So the function returns false if post_type = post
would be specified.
Use get_posts() to get the same posts data for non-hierarchical post types.
Use wp_list_pages() to display page titles in a tree view.
Hooks from the function
Return
WP_Post[]|false
. Array of pages (or hierarchical post type items). Boolean false if the specified post type is not hierarchical or the specified status is not supported by the post type.
Usage template
$pages = get_pages( [ 'sort_order' => 'ASC', 'sort_column' => 'post_title', 'hierarchical' => 1, 'exclude' => '', 'include' => '', 'meta_key' => '', 'meta_value' => '', 'authors' => '', 'child_of' => 0, 'parent' => -1, 'exclude_tree' => '', 'number' => '', 'offset' => 0, 'post_type' => 'page', 'post_status' => 'publish', ] ); foreach( $pages as $post ){ setup_postdata( $post ); // output format } wp_reset_postdata();
Usage
$pages = get_pages( $args );
- $args(array/string)
- Array or string of arguments to retrieve pages.
Default: array() (preset)
$args parameter arguments
- post_type(string)
- The post type to query.
Default: 'page' - post_status(string/array)
- Array or comma-separated list or of post statuses to include. Ex:
'publish,private'
Default: 'publish' - exclude(string/array)
- Array of page IDs to exclude. Can be specified as string:
exclude=3,7,31
.
Default: empty array - exclude_tree(string/array)
- Array or comma-separated string of page IDs to exclude. This is the opposite of
child_of
parameter. It cuts the entire pages branch starting with the one specified in this parameter, cuts it and all levels of child pages. Here we need to specify the ID of the "top-level" page.
Default: empty array - include(array/string)
Array of page IDs to include. Can be specified as string:
include=45,63,78,94,128,140
.Important: specifying of this parameter cancels the following parameters:
child_of
,parent
,exclude
,meta_key
,meta_value
and sethierarchical = false
.Default: empty array
- child_of(int)
Page ID child and grandchild of which we want to get. For example, if specify 10 we get all child pages of page 10 and all child pages of child pages, i.e not only the first level, but also the second, third, etc. We get the entire hierarchy.
Important: this parameter cancels if the
include
parameter is specified.Important: we can't use
number
parameter together with this one. Because this function makes SQL query for getting data of all pages of the specified post_type and only then the appropriate ones are selected as a childs using the function get_page_children( $child_of, $pages ).Default: 0 (not set)
- parent(int/array)
ID of a parent page. Many ID can be specified as an array. Retrieves the pages which has
post_parent = this parameter
in the DB.If this parameter is specified, then
hierarchical=false
is sets forcibly (it true by default).The difference with the
child_of
parameter is that this parameter returns only child pages, without any nested pages, i.e. returns one level.Default: -1 (no restriction)
- hierarchical(true/false)
Whether to return pages hierarchically.
- true (or 1) - children indented from the parent (default).
- false (or 0) - print all in one row.
Important:
hierarchical = false
is sets forcibly if any of the following parameters are specified:parent
,include
. This is done because these parameters are mutually exclusive (if you think about it).Default: true
- meta_key(string)
- Only include pages with this meta key.
Default: '' - meta_value(string)
- Only include pages with this meta value. Requires $meta_key.
Default: '' A comma-separated list of author IDs.
Note: get_posts() uses the parameter
author
instead ofauthors
.Default: ''
- number(int)
The number of pages to return. Specify LIMIT in the SQL query.
Note: this parameter can't be used together with the
child_of
.Note: get_posts() uses the
numberposts
parameter instead ofnumber
.Default: -1 (no limit)
- offset(int)
- The number of pages to skip before returning. Requires $number.
Specify how many pages you would like to skip from the specified selection, i.e. specify 5 and 5 top pages will be cut. - sort_column(string)
What columns to sort pages by, comma-separated. In this parameter, you can use any field from the table wp_posts.
You can specify multiple fields separated by commas:
menu_order, post_title
. Possible values:'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'
Note: fields with
post_
prefix can be specified without this prefix, for examplepost_title
can betitle
.Default: 'post_title'
- sort_order(string)
In which direction to arrange field specified in the $orderby parameter:
ASC
- from smaller to larger abs.DESC
- In reverse order (from larger to smaller, sba).
Note: get_posts() uses the parameter order instead of sort_order.
Default: 'ASC'
Examples
#1 Show pages in the drop-down list
In this example, we will create a drop-down list with all pages. We get the page link with get_page_link() in which we pass the page ID:
<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 ){ echo '<option value="' . get_page_link( $page->ID ) . '">'. esc_html($page->post_title) .'</option>'; } ?> </select>
#2 Show child pages
Output a dynamic list of child pages. If we place following code at the end of the article, we will get something like categories, where all child pages will go under the main content of the page:
<?php $mypages = get_pages( array( 'child_of' => $post->ID, 'sort_column' => 'post_date', 'sort_order' => 'desc' ) ); foreach( $mypages as $page ) { $content = $page->post_content; // skip pages without content if ( ! $content ) 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 }
#3 Pages with the specified template
This example shows how to get the pages which page-tpl.php
template file. This template file specified in admin page and stored in post metadata under _wp_page_template
key. So we need all the pages whith have such metafield.
$pages = get_pages( array( 'meta_key' => '_wp_page_template', 'meta_value' => 'page-tpl.php', 'hierarchical' => 0 )); foreach( $pages as $page ){ echo "$page->post_title <br>"; }
You can also use get_posts() instead of get_pages().
Changelog
Since 1.5.0 | Introduced. |
Since 6.3.0 | Use WP_Query internally. |