Enhancement: Add get_pages_args filter to allow full control over get_pages() arguments before parsing in get_pages()

[vincent06]

Currently, the get_pages() function provides the get_pages_query_args filter to modify the arguments passed to WP_Query. However, many core variables like child_of, number, parent, offset, and hierarchical are extracted from the original $args array before that filter is applied — meaning they cannot be altered using get_pages_query_args.

This limits extensibility in cases where developers want to programmatically change the pages being queried by modifying the original $args — such as dynamically altering child_of or parent, or injecting a number or offset value.

To resolve this, I propose adding a new filter get_pages_args just before the call to wp_parse_args():

<?php
$args = apply_filters( 'get_pages_args', $args, $defaults );
$parsed_args = wp_parse_args( $args, $defaults );

This small addition makes it possible to modify any parameter passed to get_pages() — including those that are later used directly, not via WP_Query.

This approach is:

Non-breaking and backward-compatible.

Consistent with existing WordPress patterns, like the wp_parse_args usage in other core functions.

More intuitive for developers who expect $args to be fully filterable.

Adding get_pages_args brings get_pages() in line with other WordPress functions that allow full control over inputs, and complements get_pages_query_args rather than replacing it.

[vincent06]

Introduces get_pages_args filter before wp_parse_args() in get_pages().

Adds a new get_pages_args filter before wp_parse_args() in get_pages().

This allows developers to modify values such as child_of, number, offset, parent, and others that are not handled via the get_pages_query_args filter.

[jorbin]

Hi @vincent06, thanks for opening your first ticket on WordPress Core Trac.

Can you explain the use cases that you think this solves that the existing get_pages_query_args filter doesn't?

[vincent06]

Replying to jorbin:

Hi @vincent06, thanks for opening your first ticket on WordPress Core Trac.

Can you explain the use cases that you think this solves that the existing get_pages_query_args filter doesn't?

Thanks for the follow-up!

The use case that prompted this enhancement is the need to modify arguments like child_of or parent when get_pages() is called by core or third-party plugins — for example, inside a wp_dropdown_pages() context — but before they are parsed and used to control hierarchical filtering.

While get_pages_query_args allows customization of the arguments passed to WP_Query, it does not affect how get_pages() itself uses values like child_of, number, offset, or parent, since those are extracted from the original $args array *before* the actual get_pages_query_args filter is applied. So any attempt to override them via get_pages_query_args has no effect on the behavior of get_page_children() or pagination or some others variable hardcoded before.

This becomes a problem in cases like:

• A plugin calls get_pages() with child_of => X
• A filter attempts to override child_of to a different page ID
• The override in get_pages_query_args doesn't work, because $child_of is already extracted and used before the filter is applied

Adding a get_pages_args filter (before wp_parse_args()) solves this cleanly and allows full control of all inputs, just like how wp_list_pages() and shortcode_atts() allow filtering the raw args before processing.

It's backward-compatible, and doesn’t interfere with existing usage — it simply opens up a new level of flexibility for developers working with hierarchical pages.

Happy to clarify further or provide additional examples if helpful!

[vincent06]

Hi @jorbin how are you?

Have I clarified the aspects related to the introduction of the filter in my previous comment? Is there something that still deserves to be explored in more depth?

I believe that the filter can only provide greater flexibility when working with third-party code and you want to modify the default flow in a simple way if the developer does not foresee other ways as in the specific case that led me to experience this inconsistency of expected result using only the filter on the WP_Query.

I hope that my contribution, even if minimal, but aimed at improving WordPress more and more, will still be appreciated.

I look forward to your further feedback to see if it can be considered. Thank you so much for the great work you and others do for the WordPress ecosystem.