Skip to content

Commit

Permalink
Filesystem API: Correct and improve the return type documentation for…
Browse files Browse the repository at this point in the history 
… the `dirlist()` method in `WP_Filesystem_Base` and its extending classes.

Props mat-lipe, szepeviktor, costdev, audrasjb, johnbillion

Fixes #58229
See #57840


git-svn-id: https://develop.svn.wordpress.org/trunk@55714 602fd350-edb4-49c9-b593-d223f7449a82
  • Loading branch information
@johnbillion
johnbillion committed May 3, 2023
1 parent d73323e commit eb409e4
Show file tree
Hide file tree
Showing 5 changed files with 128 additions and 61 deletions.
34 changes: 22 additions & 12 deletions src/wp-admin/includes/class-wp-filesystem-base.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -827,18 +827,28 @@ public function rmdir( $path, $recursive = false ) {
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|false {
* Array of files. False if unable to list directory contents.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string $owner Owner name or ID.
* @type int $size Size of file in bytes.
* @type int $lastmodunix Last modified unix timestamp.
* @type mixed $lastmod Last modified month (3 letter) and day (without leading 0).
* @type int $time Last modified time.
* @type string $type Type of resource. 'f' for file, 'd' for directory.
* @type mixed $files If a directory and `$recursive` is true, contains another array of files.
* Array of arrays containing file information. False if unable to list directory contents.
*
* @type array $0... {
* Array of file information. Note that some elements may not be available on all filesystems.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type int|string|false $number File number. May be a numeric string. False if not available.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type int|string|false $size Size of file in bytes. May be a numeric string.
* False if not available.
* @type int|string|false $lastmodunix Last modified unix timestamp. May be a numeric string.
* False if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of
* files. False if unable to list directory contents.
* }
* }
*/
public function dirlist( $path, $include_hidden = true, $recursive = false ) {
Expand Down
34 changes: 22 additions & 12 deletions src/wp-admin/includes/class-wp-filesystem-direct.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -597,18 +597,28 @@ public function rmdir( $path, $recursive = false ) {
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|false {
* Array of files. False if unable to list directory contents.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string $owner Owner name or ID.
* @type int $size Size of file in bytes.
* @type int $lastmodunix Last modified unix timestamp.
* @type mixed $lastmod Last modified month (3 letter) and day (without leading 0).
* @type int $time Last modified time.
* @type string $type Type of resource. 'f' for file, 'd' for directory.
* @type mixed $files If a directory and `$recursive` is true, contains another array of files.
* Array of arrays containing file information. False if unable to list directory contents.
*
* @type array $0... {
* Array of file information. Note that some elements may not be available on all filesystems.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type false $number File number. Always false in this context.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type int|string|false $size Size of file in bytes. May be a numeric string.
* False if not available.
* @type int|string|false $lastmodunix Last modified unix timestamp. May be a numeric string.
* False if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of
* files. False if unable to list directory contents.
* }
* }
*/
public function dirlist( $path, $include_hidden = true, $recursive = false ) {
Expand Down
53 changes: 40 additions & 13 deletions src/wp-admin/includes/class-wp-filesystem-ftpext.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -602,7 +602,24 @@ public function rmdir( $path, $recursive = false ) {

/**
* @param string $line
* @return array
* @return array {
* Array of file information.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string|false $number File number as a string, or false if not available.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type string|false $size Size of file in bytes as a string, or false if not available.
* @type string|false $lastmodunix Last modified unix timestamp as a string, or false if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of files.
* False if unable to list directory contents.
* }
*/
public function parselisting( $line ) {
static $is_windows = null;
Expand Down Expand Up @@ -712,18 +729,28 @@ public function parselisting( $line ) {
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|false {
* Array of files. False if unable to list directory contents.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string $owner Owner name or ID.
* @type int $size Size of file in bytes.
* @type int $lastmodunix Last modified unix timestamp.
* @type mixed $lastmod Last modified month (3 letter) and day (without leading 0).
* @type int $time Last modified time.
* @type string $type Type of resource. 'f' for file, 'd' for directory.
* @type mixed $files If a directory and `$recursive` is true, contains another array of files.
* Array of arrays containing file information. False if unable to list directory contents.
*
* @type array $0... {
* Array of file information. Note that some elements may not be available on all filesystems.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type int|string|false $number File number. May be a numeric string. False if not available.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type int|string|false $size Size of file in bytes. May be a numeric string.
* False if not available.
* @type int|string|false $lastmodunix Last modified unix timestamp. May be a numeric string.
* False if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of
* files. False if unable to list directory contents.
* }
* }
*/
public function dirlist( $path = '.', $include_hidden = true, $recursive = false ) {
Expand Down
34 changes: 22 additions & 12 deletions src/wp-admin/includes/class-wp-filesystem-ftpsockets.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -623,18 +623,28 @@ public function rmdir( $path, $recursive = false ) {
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|false {
* Array of files. False if unable to list directory contents.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string $owner Owner name or ID.
* @type int $size Size of file in bytes.
* @type int $lastmodunix Last modified unix timestamp.
* @type mixed $lastmod Last modified month (3 letter) and day (without leading 0).
* @type int $time Last modified time.
* @type string $type Type of resource. 'f' for file, 'd' for directory.
* @type mixed $files If a directory and `$recursive` is true, contains another array of files.
* Array of arrays containing file information. False if unable to list directory contents.
*
* @type array $0... {
* Array of file information. Note that some elements may not be available on all filesystems.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type int|string|false $number File number. May be a numeric string. False if not available.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type int|string|false $size Size of file in bytes. May be a numeric string.
* False if not available.
* @type int|string|false $lastmodunix Last modified unix timestamp. May be a numeric string.
* False if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of
* files. False if unable to list directory contents.
* }
* }
*/
public function dirlist( $path = '.', $include_hidden = true, $recursive = false ) {
Expand Down
34 changes: 22 additions & 12 deletions src/wp-admin/includes/class-wp-filesystem-ssh2.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -741,18 +741,28 @@ public function rmdir( $path, $recursive = false ) {
* @param bool $recursive Optional. Whether to recursively include file details in nested directories.
* Default false.
* @return array|false {
* Array of files. False if unable to list directory contents.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type string $owner Owner name or ID.
* @type int $size Size of file in bytes.
* @type int $lastmodunix Last modified unix timestamp.
* @type mixed $lastmod Last modified month (3 letter) and day (without leading 0).
* @type int $time Last modified time.
* @type string $type Type of resource. 'f' for file, 'd' for directory.
* @type mixed $files If a directory and `$recursive` is true, contains another array of files.
* Array of arrays containing file information. False if unable to list directory contents.
*
* @type array $0... {
* Array of file information. Note that some elements may not be available on all filesystems.
*
* @type string $name Name of the file or directory.
* @type string $perms *nix representation of permissions.
* @type string $permsn Octal representation of permissions.
* @type false $number File number. Always false in this context.
* @type string|false $owner Owner name or ID, or false if not available.
* @type string|false $group File permissions group, or false if not available.
* @type int|string|false $size Size of file in bytes. May be a numeric string.
* False if not available.
* @type int|string|false $lastmodunix Last modified unix timestamp. May be a numeric string.
* False if not available.
* @type string|false $lastmod Last modified month (3 letters) and day (without leading 0), or
* false if not available.
* @type string|false $time Last modified time, or false if not available.
* @type string $type Type of resource. 'f' for file, 'd' for directory, 'l' for link.
* @type array|false $files If a directory and `$recursive` is true, contains another array of
* files. False if unable to list directory contents.
* }
* }
*/
public function dirlist( $path, $include_hidden = true, $recursive = false ) {
Expand Down

0 comments on commit eb409e4

Please sign in to comment.