wp_list_pages( array|string $args = '' ): void|string

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$argsarray|stringoptional

Array or string of arguments to generate a list of pages. See get_pages() for additional arguments.Default: ''

• $child_ofintdefault: 0 (all pages)

  Display only the sub-pages of a single page by ID.

• $authorsstringdefault: empty (all authors)

  Comma-separated list of author IDs.

• $date_formatstringdefault: is the value of 'date_format' option

  PHP date format to use for the listed pages. Relies on the 'show_date' parameter.

• $depthintdefault: 0

  Number of levels in the hierarchy of pages to include in the generated list. Accepts -1 (any depth), 0 (all pages), 1 (top-level pages only), and n (pages to the given n depth).

• $echobooldefault: true

  Whether or not to echo the list of pages.

• $excludestringdefault: empty

  Comma-separated list of page IDs to exclude.

• $includearraydefault: empty

  Comma-separated list of page IDs to include.

• $link_afterstringdefault: null

  Text or HTML to follow the page link label.

• $link_beforestringdefault: null

  Text or HTML to precede the page link label.

• $post_typestringdefault: 'page'

  Post type to query for.

• $post_statusstring|arraydefault: 'publish'

  Comma-separated list or array of post statuses to include.

• $show_datestringdefault: empty

  Whether to display the page publish or modified date for each page. Accepts 'modified' or any other value. An empty value hides the date.

• $sort_columnstringdefault: 'post_title'

  Comma-separated list of column names to sort the pages by. Accepts 'post_author', 'post_date', 'post_title', 'post_name', 'post_modified', 'post_modified_gmt', 'menu_order', 'post_parent', 'ID', 'rand', or 'comment_count'.

• $title_listringdefault: 'Pages'

  List heading. Passing a null or empty value will result in no heading, and the list will not be wrapped with unordered list <ul> tags.

• $item_spacingstringdefault: 'preserve'

  Whether to preserve whitespace within the menu's HTML. Accepts 'preserve' or 'discard'.

• $walkerWalkerdefault: empty which results in a Walker_Page instance being used

  Walker instance to use for listing pages.

Return value

void|string

Void if 'echo' argument is true, HTML list of pages if 'echo' is false.

Performance profile

How much work a call to wp_list_pages() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via get_pages().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

65–115

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 121.

Plugin surface

2 hooks

Third-party callbacks on 'wp_list_pages_excludes', 'wp_list_pages' run inside this call, and their cost is not bounded by anything here.

Called by

2

2 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• optionoption read or writeget_option()called directly
• hookthird-party callbacksapply_filters()called directly
• querycontent queryget_pages()called directly
• cacheobject cachewp_cache_get()one call below wp_list_pages()
• serializeserialisationmaybe_unserialize()one call below wp_list_pages()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 10 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_list_pages() can have, taken from its control-flow graph on PHP 8.5.

Hooks and filters fired · 2

2 hooks fire while wp_list_pages() runs, in this order:

1. 1
   apply_filters( wp_list_pages_excludes )filterline 1343 (+40 into the body)

   Filters the array of pages to exclude from the pages list.

2. 2
   apply_filters( wp_list_pages )filterline 1384 (+81 into the body)

   Filters the HTML output of the pages to list.

Uses · 12

• get_option()Retrieves an option value based on an option name.
• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_pages()Retrieves an array of pages (or hierarchical post type items).
• is_page()Determines whether the query is for an existing single page.
• is_attachment()Determines whether the query is for an existing attachment page.
• get_queried_object_id()Retrieves the ID of the currently queried object.
• is_singular()Determines whether the query is for an existing single post of any post type (post, attachment, page, custom post types).
• get_queried_object()Retrieves the currently queried object.
• is_post_type_hierarchical()Determines whether the post type is hierarchical.
• walk_page_tree()Retrieves HTML list content for page list.

Used by · 2

• WP_Widget_Pages::widget()Outputs the content for the current Pages widget instance.
• wp_page_menu()Displays or retrieves a list of pages with an optional home link.

Source code

View on Trac ↗View on GitHub ↗

1303function wp_list_pages( $args = '' ) {1304	$defaults = array(1305		'depth'        => 0,1306		'show_date'    => '',1307		'date_format'  => get_option( 'date_format' ),1308		'child_of'     => 0,1309		'exclude'      => '',1310		'title_li'     => __( 'Pages' ),1311		'echo'         => 1,1312		'authors'      => '',1313		'sort_column'  => 'menu_order, post_title',1314		'link_before'  => '',1315		'link_after'   => '',1316		'item_spacing' => 'preserve',1317		'walker'       => '',1318	);1319 1320	$parsed_args = wp_parse_args( $args, $defaults );1321 1322	if ( ! in_array( $parsed_args['item_spacing'], array( 'preserve', 'discard' ), true ) ) {1323		// Invalid value, fall back to default.1324		$parsed_args['item_spacing'] = $defaults['item_spacing'];1325	}1326 1327	$output       = '';1328	$current_page = 0;1329 1330	// Sanitize, mostly to keep spaces out.1331	$parsed_args['exclude'] = preg_replace( '/[^0-9,]/', '', $parsed_args['exclude'] );1332 1333	// Allow plugins to filter an array of excluded pages (but don't put a nullstring into the array).1334	$exclude_array = ( $parsed_args['exclude'] ) ? explode( ',', $parsed_args['exclude'] ) : array();1335 1336	/**1337	 * Filters the array of pages to exclude from the pages list.1338	 *1339	 * @since 2.1.01340	 *1341	 * @param string[] $exclude_array An array of page IDs to exclude.1342	 */1343	$parsed_args['exclude'] = implode( ',', apply_filters( 'wp_list_pages_excludes', $exclude_array ) );1344 1345	$parsed_args['hierarchical'] = 0;1346 1347	// Query pages.1348	$pages = get_pages( $parsed_args );1349 1350	if ( ! empty( $pages ) ) {1351		if ( $parsed_args['title_li'] ) {1352			$output .= '<li class="pagenav">' . $parsed_args['title_li'] . '<ul>';1353		}1354		global $wp_query;1355		if ( is_page() || is_attachment() || $wp_query->is_posts_page ) {1356			$current_page = get_queried_object_id();1357		} elseif ( is_singular() ) {1358			$queried_object = get_queried_object();1359			if ( is_post_type_hierarchical( $queried_object->post_type ) ) {1360				$current_page = $queried_object->ID;1361			}1362		}1363 1364		$output .= walk_page_tree( $pages, $parsed_args['depth'], $current_page, $parsed_args );1365 1366		if ( $parsed_args['title_li'] ) {1367			$output .= '</ul></li>';1368		}1369	}1370 1371	/**1372	 * Filters the HTML output of the pages to list.1373	 *1374	 * @since 1.5.11375	 * @since 4.4.0 `$pages` added as arguments.1376	 *1377	 * @see wp_list_pages()1378	 *1379	 * @param string    $output      HTML output of the pages list.1380	 * @param array     $parsed_args An array of page-listing arguments. See wp_list_pages()1381	 *                               for information on accepted arguments.1382	 * @param WP_Post[] $pages       Array of the page objects.

Changelog

Introduced in 1.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 tag, from src/wp-includes/post-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.