Optional skipping of hidden files/folders in list_files

[yani.iliev]

The function always skips hidden files/folders that begin with a dot (.)
This allows for files like .htaccess and .git to be skipped when listing a folder.
This ticket is about allow to suppress this behavior in the function and return hidden files/folders that begin with a dot (.).
One possible solution is to add a new argument to the function so that the function is defined as such:
function list_files( $folder = '', $levels = 100, $exclusions = array(), $skip_dots = true )

This adds a new optional $include_hidden parameter to allow the inclusion of hidden ("." prefixed) files.

Defaults to false for backward compatibility.

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

[costdev]

• ​PR 4223 introduces the $include_hidden parameter to allow the inclusion of hidden ("." prefixed) files.
• The parameter name $include_hidden is used as this is consistent with the parameter name used in the ::dirlist() filesystem abstraction classes, which defaults to true.
• However, this new parameter in list_files() defaults to false for backward compatibility.

---

• Hidden file exclusion was introduced in [41806]. See this comment. Setting the Version property to 4.9.
• Milestoning this ticket for 6.3.

[rutviksavsani]

This ticket was discussed in the recent bug scrub.
It seems we need testing instructions/info and testing the PR.

[costdev]

Testing Instructions

Steps to Test

1. Create a directory with several files and subdirectories.
   • Make sure each directory and subdirectory has a file called .hidden-file and a file called .hidden-file-2.
   • The . denotes a hidden file.
2. Call list_files( $path_to_folder ).
3. Call list_files( $path_to_folder, 100, array(), true ).
4. Call list_files( $path_to_folder, 100, array( '.hidden-file-2' ), true ).

Expected Results

Before the patch:

2. The result should not contain the hidden files.
3. The result should not contain the hidden files.
4. The result should not contain the hidden files.

After the patch:

2. The result should not contain the hidden files.
3. The result should contain all of the hidden files.
4. The result should only contain .hidden-file entries for $path_to_folder, but should include .hidden-file and .hidden-file-2 entries for its sub-directories.

[zunaid321]

Test Report

This report validates that the indicated patch addresses the issue.

Patch tested: ​https://patch-diff.githubusercontent.com/raw/WordPress/wordpress-develop/pull/4223.diff

Environment

• OS: Windows 11 (22H2)
• Web Server: nginx/1.23.4
• PHP: 7.4.33
• WordPress: 6.3-alpha-55505-src
• Browser: Chrome Version 114.0.5735.110 (Official Build) (64-bit)
• Theme: Twenty Twenty-Three

Before Applying The Patch

• Followed the instructions of @costdev
• ❌ The hidden files did not show up in all three results

After Applying The Patch

• Followed the same instructions
• ✅ The hidden files appeared according to the calls made

Plugins Used

• Attached: test-53659.zip

[zunaid321]

File structure which includes the sub directories and the hidden files

[costdev]

Thanks for testing @zunaid321!

Adding for commit consideration so a committer can take a look and see if this is ready to go into Core.

[mikeschroder]

If there are no objections / the replies in the PR seem sufficient, @azaozz, I'm willing to do a bit of testing, and assuming things seem good, commit in my evening before Beta.

[mikeschroder]

In 56069:

Filesystem API: Allow optional inclusion of hidden files in list_files().

Adds a new optional $include_hidden parameter to allow the inclusion of hidden (. prefixed) files.
Defaults to false for backward compatibility.

Props yani.iliev, sabernhardt, costdev, rutviksavsani, zunaid321, azaozz.
Fixes #53659.

[mikeschroder]

This doesn't need its own post, but would be useful to mention as an enhancement for folks in the field guide.

Committed in https://core.trac.wordpress.org/changeset/56069.