Question

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

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

---

description

---

参数

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

---

返回值

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

---

源代码

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";
	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 );
}

---

更新日志

Version	description
1.5.0	Introduced.

---

相关函数

Uses

• wp-includes/functions.php: wp_cache_get_last_changed()
• wp-includes/cache.php: wp_cache_get()
• wp-includes/cache.php: wp_cache_set()
• wp-includes/formatting.php: wp_unslash()
• wp-includes/pluggable.php: get_user_by()
• wp-includes/functions.php: wp_parse_args()
• wp-includes/functions.php: wp_array_slice_assoc()
• wp-includes/functions.php: wp_parse_id_list()
• wp-includes/plugin.php: apply_filters()
• wp-includes/post.php: update_post_cache()
• wp-includes/post.php: get_page_children()
• wp-includes/post.php: get_pages
• wp-includes/post.php: sanitize_post()
• wp-includes/post.php: get_post_types()
• wp-includes/post.php: get_post_stati()
• wp-includes/wp-db.php: wpdb::get_results()
• wp-includes/wp-db.php: wpdb::prepare()
Show 12 more uses Hide more uses

---

Used By

• wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::has_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()
• wp-includes/post-template.php: wp_list_pages()
• wp-includes/post-template.php: get_body_class()

---

User Contributed Notes

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

   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>
   

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