[wp-trac] [WordPress Trac] #32774: Improve WP_Filesystem::dirlist() format consistency

[WordPress Trac]

#32774: Improve WP_Filesystem::dirlist() format consistency
----------------------------+-----------------------------
 Reporter:  dd32            |      Owner:
     Type:  defect (bug)    |     Status:  new
 Priority:  normal          |  Milestone:  Awaiting Review
Component:  Filesystem API  |    Version:
 Severity:  minor           |   Keywords:
  Focuses:                  |
----------------------------+-----------------------------
 At present the return values of dirlist() between the various methods are
 scattered between several different formats

 ||Field||Direct||FTP Ext||FTP Sockets||SSH2||
 ||name||Yes||Yes||Yes||Yes||
 ||perms||Yes||Yes||Yes||Yes||
 ||permsn||Yes||Yes||Yes||Yes||
 ||number||`false`||Yes||Yes||`false`||
 ||owner||Yes||Yes||Yes||Yes||
 ||group||Yes||Yes||Yes||Yes||
 ||size||Yes||Yes||Yes or `<DIR>`||Yes||
 ||lastmodunix||Unix Timestamp||No||No||Unix Timestamp||
 ||lastmod||`Nov 15`||No||No||`Nov 15`||
 ||time||`02:12:48`||Unix Timestamp||Unix Timestamp||`02:12:48`||
 ||year||No||Maybe||Maybe||No||
 ||month||No||`Nov`||`Nov`||No||
 ||day||No||`15`||`15`||No||
 ||hour||No||`02`||`02`||No||
 ||minute||No||`12`||`12`||No||
 ||type||`d` or `f`||`d`, `f`, or `l`||`d`, `f`, or `l`||`d` or `f`||
 ||isdir||No||Yes||Yes||No||
 ||islink||No||Yes||Yes||No||

 If the FTP Server was Windows, it'd complicate it further by not returning
 certain fields, using different data in them, or getting confused and not
 returning any data.

 The attached patch boils it down to a consistent result of `[
 'filename.ext' => [...], ...]` with the nested arrays of:
 ||Field||Value||
 ||name||Filename||
 ||time||Unix Timestamp of last modified||
 ||size||File size or false for Directories||
 ||type||`d`, `f`, or `l` for Directory, File, or Link respectively||
 ||perms||A formatted human-readable `drwxr-xr-x`||
 ||permsn||A octal as string `'0755'` for Back-compat purposes||
 ||owner||Owner ID or name||
 ||group||Group ID or name||
 ||files||If it's a recursive directory lookup, a nested array of files||

 A number of these are only got back-compat or to match the FTP output -
 most of these fields are not used by WordPress at all - Specifically
 `group`, `owner`, `perms`, `permsn`, and `time` are ignored 100% by
 WordPress (along with a lot of the methods)
 Changing this has some back-compat issues for any plugins doing anything
 special with the fields - however they've had to work around the fields
 returning random content already, so this shouldn't be a huge issue (or
 they were already broken)

--
Ticket URL: <https://core.trac.wordpress.org/ticket/32774>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform