WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

get_pages()

get_pages( array|string $args = array() ): WP_Post[]|false

In this article

Back to top

Retrieves an array of pages (or hierarchical post type items).

Parameters

$argsarray|stringoptional
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 int[]
    Array of page IDs to exclude.
  • include int[]
    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|int[]
    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:array()

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.

Source

function get_pages( $args = array() ) {	$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',	);	$parsed_args = wp_parse_args( $args, $defaults );	$number = (int) $parsed_args['number'];	$offset = (int) $parsed_args['offset'];	$child_of = (int) $parsed_args['child_of'];	$hierarchical = $parsed_args['hierarchical'];	$exclude = $parsed_args['exclude'];	$meta_key = $parsed_args['meta_key'];	$meta_value = $parsed_args['meta_value'];	$parent = $parsed_args['parent'];	$post_status = $parsed_args['post_status'];	// Make sure the post type is hierarchical.	$hierarchical_post_types = get_post_types( array( 'hierarchical' => true ) );	if ( ! in_array( $parsed_args['post_type'], $hierarchical_post_types, true ) ) {	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;	}	$query_args = array(	'orderby' => 'post_title',	'order' => 'ASC',	'post__not_in' => wp_parse_id_list( $exclude ),	'meta_key' => $meta_key,	'meta_value' => $meta_value,	'posts_per_page' => -1,	'offset' => $offset,	'post_type' => $parsed_args['post_type'],	'post_status' => $post_status,	'update_post_term_cache' => false,	'update_post_meta_cache' => false,	'ignore_sticky_posts' => true,	'no_found_rows' => true,	);	if ( ! empty( $parsed_args['include'] ) ) {	$child_of = 0; // Ignore child_of, parent, exclude, meta_key, and meta_value params if using include.	$parent = -1;	unset( $query_args['post__not_in'], $query_args['meta_key'], $query_args['meta_value'] );	$hierarchical = false;	$query_args['post__in'] = wp_parse_id_list( $parsed_args['include'] );	}	if ( ! empty( $parsed_args['authors'] ) ) {	$post_authors = wp_parse_list( $parsed_args['authors'] );	if ( ! empty( $post_authors ) ) {	$query_args['author__in'] = array();	foreach ( $post_authors as $post_author ) {	// Do we have an author id or an author login?	if ( 0 === (int) $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;	}	$query_args['author__in'][] = (int) $post_author;	}	}	}	if ( is_array( $parent ) ) {	$post_parent__in = array_map( 'absint', (array) $parent );	if ( ! empty( $post_parent__in ) ) {	$query_args['post_parent__in'] = $post_parent__in;	}	} elseif ( $parent >= 0 ) {	$query_args['post_parent'] = $parent;	}	/* * Maintain backward compatibility for `sort_column` key. * Additionally to `WP_Query`, it has been supporting the `post_modified_gmt` field, so this logic will translate * it to `post_modified` which should result in the same order given the two dates in the fields match. */	$orderby = wp_parse_list( $parsed_args['sort_column'] );	$orderby = array_map(	static function ( $orderby_field ) {	$orderby_field = trim( $orderby_field );	if ( 'post_modified_gmt' === $orderby_field || 'modified_gmt' === $orderby_field ) {	$orderby_field = str_replace( '_gmt', '', $orderby_field );	}	return $orderby_field;	},	$orderby	);	if ( $orderby ) {	$query_args['orderby'] = array_fill_keys( $orderby, $parsed_args['sort_order'] );	}	$order = $parsed_args['sort_order'];	if ( $order ) {	$query_args['order'] = $order;	}	if ( ! empty( $number ) ) {	$query_args['posts_per_page'] = $number;	}	/** * Filters query arguments passed to WP_Query in get_pages. * * @since 6.3.0 * * @param array $query_args Array of arguments passed to WP_Query. * @param array $parsed_args Array of get_pages() arguments. */	$query_args = apply_filters( 'get_pages_query_args', $query_args, $parsed_args );	$pages = new WP_Query();	$pages = $pages->query( $query_args );	if ( $child_of || $hierarchical ) {	$pages = get_page_children( $child_of, $pages );	}	if ( ! empty( $parsed_args['exclude_tree'] ) ) {	$exclude = wp_parse_id_list( $parsed_args['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, true ) ) {	unset( $pages[ $i ] );	}	}	}	/** * Filters the retrieved list of pages. * * @since 2.1.0 * * @param WP_Post[] $pages Array of page objects. * @param array $parsed_args Array of get_pages() arguments. */	return apply_filters( 'get_pages', $pages, $parsed_args ); }

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_pages’, WP_Post[] $pages, array $parsed_args )

Filters the retrieved list of pages.

apply_filters( ‘get_pages_query_args’, array $query_args, array $parsed_args )

Filters query arguments passed to WP_Query in get_pages.

UsesDescription
wp_parse_list()wp-includes/functions.php

Converts a comma- or space-separated list of scalar values to an array.

get_user_by()wp-includes/pluggable.php

Retrieves user info by a given field.

WP_Query::__construct()wp-includes/class-wp-query.php

Constructor.

wp_parse_id_list()wp-includes/functions.php

Cleans up an array, comma- or space-separated list of IDs.

get_page_children()wp-includes/post.php

Identifies descendants of a given page ID in a list of page objects.

get_post_stati()wp-includes/post.php

Gets a list of post statuses.

wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

get_post_types()wp-includes/post.php

Gets a list of all registered post type objects.

Show 4 moreShow less
Used byDescription
WP_Customize_Manager::has_published_pages()wp-includes/class-wp-customize-manager.php

Returns whether there are published pages.

WP_Posts_List_Table::_display_rows_hierarchical()wp-admin/includes/class-wp-posts-list-table.php
wp_dropdown_pages()wp-includes/post-template.php

Retrieves or displays a list of pages as a dropdown (select list).

wp_list_pages()wp-includes/post-template.php

Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.

get_body_class()wp-includes/post-template.php

Retrieves an array of the class names for the body element.

Changelog

VersionDescription
6.3.0Use WP_Query internally.
1.5.0Introduced.

User Contributed Notes

  1. Skip to note 4 content
    Codex
    You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

    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>
  2. Skip to note 5 content
    Codex
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

    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	} ?>

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