From bd393654cc8255e5096fd18b0e140ba77ef7c898 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 3 May 2023 21:30:19 +0000 Subject: [PATCH] Filesystem API: Correct and improve the return type documentation for the `dirlist()` method in `WP_Filesystem_Base` and its extending classes. Props mat-lipe, szepeviktor, costdev, audrasjb, johnbillion Fixes #58229 See #57840 Built from https://develop.svn.wordpress.org/trunk@55714 git-svn-id: http://core.svn.wordpress.org/trunk@55226 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- .../includes/class-wp-filesystem-base.php | 32 ++++++++---- .../includes/class-wp-filesystem-direct.php | 32 ++++++++---- .../includes/class-wp-filesystem-ftpext.php | 51 ++++++++++++++----- .../class-wp-filesystem-ftpsockets.php | 32 ++++++++---- .../includes/class-wp-filesystem-ssh2.php | 32 ++++++++---- wp-includes/version.php | 2 +- 6 files changed, 124 insertions(+), 57 deletions(-) diff --git a/wp-admin/includes/class-wp-filesystem-base.php b/wp-admin/includes/class-wp-filesystem-base.php index aae09e8dfa..fbe8b3cc60 100644 --- a/wp-admin/includes/class-wp-filesystem-base.php +++ b/wp-admin/includes/class-wp-filesystem-base.php @@ -827,18 +827,28 @@ class WP_Filesystem_Base { * @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. + * Array of arrays containing file information. 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. + * @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 ) { diff --git a/wp-admin/includes/class-wp-filesystem-direct.php b/wp-admin/includes/class-wp-filesystem-direct.php index f201def08f..9fdfeb95cb 100644 --- a/wp-admin/includes/class-wp-filesystem-direct.php +++ b/wp-admin/includes/class-wp-filesystem-direct.php @@ -597,18 +597,28 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base { * @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. + * Array of arrays containing file information. 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. + * @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 ) { diff --git a/wp-admin/includes/class-wp-filesystem-ftpext.php b/wp-admin/includes/class-wp-filesystem-ftpext.php index 3ce8b67996..7db0685fc5 100644 --- a/wp-admin/includes/class-wp-filesystem-ftpext.php +++ b/wp-admin/includes/class-wp-filesystem-ftpext.php @@ -602,7 +602,24 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base { /** * @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; @@ -712,18 +729,28 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base { * @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. + * Array of arrays containing file information. 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. + * @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 ) { diff --git a/wp-admin/includes/class-wp-filesystem-ftpsockets.php b/wp-admin/includes/class-wp-filesystem-ftpsockets.php index da578d0f2e..c69d8012ca 100644 --- a/wp-admin/includes/class-wp-filesystem-ftpsockets.php +++ b/wp-admin/includes/class-wp-filesystem-ftpsockets.php @@ -623,18 +623,28 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base { * @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. + * Array of arrays containing file information. 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. + * @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 ) { diff --git a/wp-admin/includes/class-wp-filesystem-ssh2.php b/wp-admin/includes/class-wp-filesystem-ssh2.php index 80fb81b971..2b3edf1adc 100644 --- a/wp-admin/includes/class-wp-filesystem-ssh2.php +++ b/wp-admin/includes/class-wp-filesystem-ssh2.php @@ -741,18 +741,28 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base { * @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. + * Array of arrays containing file information. 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. + * @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 ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index e2091affb3..3123adc9ee 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-alpha-55713'; +$wp_version = '6.3-alpha-55714'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.