Posts, Post Types: Accept an array of page IDs for wp_list_pages() exclude.

[Sabbir345]

Trac ticket: https://core.trac.wordpress.org/ticket/66052

wp_list_pages() cleaned its exclude argument with preg_replace() and then split it with explode(). Both functions expect a string, so passing an array of page IDs caused a fatal TypeError on PHP 8:

wp_list_pages( array( 'exclude' => array( 2, 5 ) ) ); // Fatal error on PHP 8.

Passing an array is a reasonable thing to do: get_pages(), which receives these arguments, accepts arrays. The include argument of wp_list_pages() is also already documented as an array.

Changes

• exclude is now parsed with wp_parse_id_list(), so it accepts an array of IDs (integers or numeric strings) as well as the existing comma-separated string.
• Backward compatible: the wp_list_pages_excludes filter still receives an array of numeric strings, as before. A @phpstan-param numeric-string[] tag now documents this.
• The exclude default changes from '' to array().
• Docs: exclude and include are now documented as int[] to match get_pages(). include was typed as array but described as a comma-separated list. Added a @since 7.2.0 note.

Testing

New PHPUnit tests in tests/phpunit/tests/post/wpListPages.php:

• exclude accepts an array of IDs, as integers or as numeric strings.
• include accepts an array of IDs, as integers or as numeric strings.
• The wp_list_pages_excludes filter still receives numeric strings when given a comma-separated string with extra spaces.

npm run test:php -- --filter Tests_Post_wpListPages

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props sabbir345, therssoftware.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[robelsust]

Test Report

Ticket: https://core.trac.wordpress.org/ticket/66052
PR: #13922

Environment

• WordPress: 7.2-alpha-63166-src (trunk)
• PHP: 8.3.33
• Server: macOS Darwin 24.6.0 (arm64)
• Database: MariaDB 10.11 / MySQL
• PHPUnit: 9.6.37

Steps to Test

1. On trunk (before patch):
   • Execute wp_list_pages() passing an array of page IDs to exclude:

     wp_list_pages( array( 'echo' => false, 'exclude' => array( 1, 2 ) ) );

   • Observe a fatal TypeError on PHP 8+:

     Fatal error: Uncaught TypeError: explode(): Argument #2 ($string) must be of type string, array given in src/wp-includes/post-template.php:1349
     

2. Apply PR Posts, Post Types: Accept an array of page IDs for wp_list_pages() exclude. #13922:
   • Execute the same call with an array of integer IDs:

     wp_list_pages( array( 'echo' => false, 'exclude' => array( 1, 2 ) ) );

   • Execute with an array of numeric strings:

     wp_list_pages( array( 'echo' => false, 'exclude' => array( '1', '2' ) ) );

   • Execute with legacy comma-separated string (with spaces):

     wp_list_pages( array( 'echo' => false, 'exclude' => ' 1, 2, 3 ' ) );

   • Verify that the wp_list_pages_excludes filter continues to receive an array of numeric strings.
3. Run automated test suite:

   vendor/bin/phpunit tests/phpunit/tests/post/wpListPages.php
   vendor/bin/phpcs src/wp-includes/post-template.php tests/phpunit/tests/post/wpListPages.php

Test Results

• Before Patch (trunk):
  • Reproducible fatal error:

    Fatal error: Uncaught TypeError: explode(): Argument #2 ($string) must be of type string, array given in src/wp-includes/post-template.php:1349
    Stack trace:
    #0 src/wp-includes/post-template.php(1349): explode(',', Array)
    #1 wp_list_pages(Array)
    

• After Patch (PR Posts, Post Types: Accept an array of page IDs for wp_list_pages() exclude. #13922):
  • Passing an array of IDs (both integers and numeric strings) to exclude works as expected without any error or notice.
  • Legacy comma-separated strings ('1, 2, 3') continue to exclude pages properly (verified via test_wp_list_pages_exclude).
  • The wp_list_pages_excludes filter receives array( '1', '2', '3' ) as expected for backward compatibility.
  • All 23 tests and 27 assertions in tests/phpunit/tests/post/wpListPages.php pass:
    • test_wp_list_pages_exclude_should_accept_an_array_of_ids with integers passed.
    • test_wp_list_pages_exclude_should_accept_an_array_of_ids with numeric strings passed.
    • test_wp_list_pages_include_should_accept_an_array_of_ids with integers passed.
    • test_wp_list_pages_include_should_accept_an_array_of_ids with numeric strings passed.
    • test_wp_list_pages_excludes_filter_should_receive_numeric_strings passed.
  • PHPCS analysis with WordPress-Core ruleset passes with 0 errors and 0 warnings on modified code.

The PR is complete, maintains backward compatibility, and is ready for commit.

Props therssoftware.

---

AI Disclosure: In accordance with the WordPress AI policy, I disclose that generative AI (Google Antigravity) was used in testing and drafting this test report. All test steps and assertions were run and verified in the local development environment.