WP_Term_Query does not allow limiting results when descending family tree

[get_dave]

The Problem

Over in ​https://github.com/WordPress/gutenberg/pull/42424 we're working on a way to limit the number of Category taxonomy terms that are displayed in the UI.

This works well until you attempt to display top level terms only (i.e. those with a parent of 0). In this case the limit is not applied.

Here is the Gutenberg PHP code where we apply the parent argument:

​https://github.com/WordPress/gutenberg/blob/10f8542e26e83262f177cdcca30ca57ae516e644/packages/block-library/src/categories/index.php#L27

Why does this happen?

Digging into the Core code I noticed that WP_Term_Query->get_terms() method explicitly does not allow limiting when descending into the family tree of terms or when a parent is provided:

​https://github.com/WordPress/wordpress-develop/blob/6.0/src/wp-includes/class-wp-term-query.php#L628-L629

The code comment states:

Don't limit the query results when we have to descend the family tree.

There is no further information.

Further investigation reveals that this "feature" was present in the original commit which introduced this functionality:

​https://github.com/WordPress/wordpress-develop/commit/8220d04e6d12c4a139344117e02fef268df5f205#diff-7813f38c6b905b75c4b11bf2750c63ba0f5a1227ffc4f012deeeb22999cee68bR1338-R1339

Feature Request

I would like to display the top X categories but showing top level terms only. As it stands I don't believe this is possible.

Perhaps we could introduce a clause in the conditional which allows limiting if the $parent is 0?

[peterwilsoncc]

This was introduced in [10416] for #8832 and has followed various refactors since then.

[get_dave]

I just noticed this line which seems to suggest this should already work

​https://github.com/WordPress/wordpress-develop/blob/67023d0c66267420107bb565f887ae6a95b12666/src/wp-includes/class-wp-term-query.php#L856-L862