Changeset 55714 for trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php

Timestamp:

05/03/2023 09:28:11 PM (19 months ago)

Author:

johnbillion

Message:

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

File:

• trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php (modified) (2 diffs)

trunk/src/wp-admin/includes/class-wp-filesystem-ftpext.php

@@ -603 +603 @@
     /**
      * @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 ) {
@@ -713 +730 @@
      *                               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.
+     *     }
      * }
      */