wp_list_pages - exclude parameter changes behaviour depending on depth

[nosnurg]

Let's say I have four top level pages with IDs 1,2 and 3 and each has three children, say, (11,12,13), (21,22,23) and (31,32,33).

If I run

<?php wp_list_pages(); ?>

on that I'll get all the pages shown. So it'll be a list like:

1
    11
    12
    13
2
    21
    22
    23
3
    31
    32
    33

If I run

<?php wp_list_pages(exclude=3); ?>

then page 3 will not be shown and the hierarchy will collapse so 31,32,33 appear in the top level of the hierarchy. So what I'll get is:

1
    11
    12
    13
2
    21
    22
    23
31
32
33

Given the existence of a separate exclude_tree argument, that is pretty much what I'd expect to happen, after all it has to show the child pages somehow. If I now introduce a depth argument so it is:

<?php wp_list_pages(depth=3&exclude=3); ?>

I'd expect the same thing to happen as the depth shouldn't make any difference. What actually happens is that the

exclude now behaves similarly to exclude_tree. What I actually get is:

1
  11 12 13
2
  21 22 23

Now that to me doesn't make sense.

[nosnurg]

Apologies for somewhat untidy formatting, and please note I did mean to write:

1
    11
    12
    13
2
    21
    22
    23

for the last bit.

[nosnurg]

The bug, if that is what it is, would seem to remain in 3.9.0.

[MikeHansenMe]

Unit tests for wp_list_pages

[MikeHansenMe]

I was able to confirm this. I wrote some unit tests for wp_list_pages that test the arguments. The final test in the set is for this ticket.

[MikeHansenMe]

minor updates to tests and cleanup

[wonderboymusic]

In 28400:

Add unit tests for wp_list_pages().

Props MikeHansenMe.
See #27326.

[MikeHansenMe]

see #30284

[MikeHansenMe]

27326.diff​ still applies and has unit tests in 27326-unittests.diff​. These tests were added then removed during #30284 because they were failing. The test was for this bug and passes with the patch.

[SirLouen]

Reproduction Report

Description

✅ This report validates that the issue can be reproduced.

Reproduction Instructions

1. Add 3 parent pages
2. Add 3 child pages to each of the 3 parent pages (9 children in total). Will look ​like this
3. Add the code in supplemental artifacts to a plugin, functions.php or wherever you can execute such code. Remember to edit the ID of 'exclude' to the ID of the 3rd parent page you created
4. Add the shortcode [custom_pages_list] to a post
5. Check the post results
6. 🐞 The whole section of the parent excluded is removed.

Actual Results

1. ✅ Error condition occurs (reproduced).

Additional notes

It appears that the current bug is still valid in 2025. I've tried to apply this patch, seems not to be working (or I'm not applying as expected). Checking Unit tests, they seem to be correct, covering this bug. Wondering what happened with this report, general unit tests were added, but the report did not progress itself.

cc @MikeHansenMe

Anyway, just in case, given that the solution provided is almost done, including some tests, I believe this could be a suitable candidate for good-first-bug.

Supplemental artifacts

Code for testing

function custom_pages_list_shortcode($atts) {
    $atts = array(
            'exclude' => '11', // ID of the 3rd parent to exclude
            'depth'   => '3',
            'echo'    => 0,
    );
    return wp_list_pages($atts);
}
add_shortcode('custom_pages_list', 'custom_pages_list_shortcode');

Fixes unexpected behavior when using wp_list_pages() with both depth and exclude parameters.

Previously, excluded parent pages would also exclude their children if depth > 0, making exclude behave like exclude_tree. This change updates the walker logic to ensure orphaned children of excluded parents are still displayed when depth is limited, consistent with how exclude works without depth.

A follow-up commit will add unit test coverage for this behavior.

Trac ticket: #27326