"hierarchical" argument for get_pages() does nothing

[Viper007Bond]

The hierarchical argument for get_pages() is never actually used. It is in an if statement, but one that requires child_of to also be set:

if ( $child_of || $hierarchical )
	$pages = & get_page_children($child_of, $pages);

Props Vynce Montgomery for pointing this out to me.

[nacin]

Somewhat related, I've found afew times that it would be helpful for get_pages() to not enforce hierarchical-ness.

[DrewAPicture]

Took a look at this the other night.

The truly special part about the current state of get_pages() is that because $hierarchical is true and $child_of is 0|false by default, we actually end up with non-hierarchical results by default because $child_of translates to parent = 0 in get_page_children(). To maintain backward-compatibility, we would have to retain that default behavior

Running two rudimentary tests of current behavior, I got surprising results:

$hierarchical = get_pages( array( 'number' => 10 ) );
$hierarchical = wp_list_pluck( $hierarchical, 'post_parent' );
// 5 pages, all with parent 0

$non_hierarchical = get_pages( array( 'hierarchical' => false, 'number' => 10 ) );
$non_hierarchical = wp_list_pluck( $non_hierarchical, 'post_parent' );
// 10 pages, mixed parents

If we wanted to truly implement hierarchical results, there are a couple of things to consider:

• Like get_terms(), we should probably only set the LIMIT clause if $hierarchical, $child_of and $parent are falsey and $number is not empty. Currently it's always set if $number is not empty (default is empty)
• It should be documented what exactly "hierarchical" means in terms of returned results

I think the best starting place is to write tests for the current behavior and work outward.

[DrewAPicture]

In 34698:

Tests: Add two tests for the current 'hierarchical' argument behavior in get_pages().

See #18701.

[DrewAPicture]

In 34699:

Tests: Add two tests for the current behavior of the 'hierarchical' and 'child_of' arguments in get_pages().

See #18701.

[DrewAPicture]

In 34746:

Docs: Update the argument descriptions for $child_of and $hierarchical in get_pages() to more closely reflect expected behavior.

See #18701. See #32246.