WordPress at a glance

get_pages() WP 1.5.0

Retrieve a list of pages (or hierarchical post type items) as an array of posts objects. Analog of get_posts().

The received array of posts objects should be custom processed via foreach.

If you specify the post_type parameter, the funcion, as well as get_posts(), can output regular posts (post, attachment).

Although the function is identical to get_posts(), some of the parameters and their values are different.

To display page titles in a tree view, use wp_list_pages().

  • Global. wpdb. $wpdb WordPress database abstraction object.
Is the basis for: wp_list_pages()
✈ 1 time = 0.004261s = very slow | 50000 times = 6.05s = fast PHP 7.1.2, WP 4.7.3
Hooks from function:
Return

Array/false. List of pages matching defaults or $args.

Usage

get_pages( $args );

Usage template

$args = array(
	'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',
); 

$pages = get_pages( $args );
foreach( $pages as $post ){
	setup_postdata( $post );
	// output format
}  
wp_reset_postdata();
$args(array/string)
Array or string of arguments to retrieve pages.
Default: array()

Arguments to the $args parameter

child_of(int)

Page ID to return child and grandchild pages of. 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.

Note: The $hierarchical parameter has no any affects on whether $child_of returns hierarchical results.

Default: 0 - all pages

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'

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.

  • menu_order - by the number specified in the admin panel. Do not confuse this parameter with the post ID.
  • rand - randomly shuffle the output.
  • ID - by identification number (post ID).
  • comment_count - by comment count.
  • post_title - by title.
  • post_date - by page creation date.
  • post_modified - by page modification date.
  • post_author - by the author of the page creation.
  • post_name - by slug (alternative name, which is specified in the URL) of the page.

Note: fields with post_ prefix can be specified without this prefix, for example post_title can be title.

The sorting direction specified in the parameter sort_order

Default: 'post_title'

menu
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.

If false in conjunction with $child_of also being false, both arguments will be disregarded.

Note: the default value of this parameter will interfere (conflict) with the parameters meta_key and parent - they will be applied only to the upper, main level of the tree. For these parameters to work properly, set this parameter to 0 ('hierarchical' => 0).

Default: true

exclude(array/string)
Array of page IDs to exclude. Can be specified as string: exclude=3,7,31.
Default: empty array
include(array/string)
Array of page IDs to include. Cannot be used with $child_of, $parent, $exclude, $meta_key, $meta_value, or $hierarchical. Can be specified as string: include=45,63,78,94,128,140.
Default: empty array
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: ''
authors(string)

A comma-separated list of author IDs.

Note: get_posts() uses the parameter author instead of authors.

Default: ''

parent(int)

Page ID to return direct children of. Displays the pages with the parent specified in this parameter ID. Default: -1 (displays all pages regardless of parents).

It is important to set hierarchical=false (which is true by default). If dont do it we will get wrong result by using this parameter.

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)

exclude_tree(string/array)
Comma-separated string or array 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
number(int)

The number of pages to return.

Note: get_posts() uses the numberposts parameter instead of number.

Default: 0, or all pages

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.
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. Ex: 'publish,private'
Default: 'publish'

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().

Code of get_pages: wp-includes/post.php VER 4.9.8

<?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";
	if ( $cache = wp_cache_get( $cache_key, 'posts' ) ) {
		// 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 = preg_split( '/[\s,]+/', $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) ) {
		/** 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 );
}

Related Functions

From tag: query

More from category: Pages

No comments
    Hello, !     Log In . Register