Filesystem: Update constructor parameter default value to an empty array

composer.json

@@ -17,7 +17,9 @@
 	},
 	"suggest": {
 		"ext-dom": "*",
-		"ext-mysqli": "*"
+		"ext-ftp": "*",
+    "ext-mysqli": "*",
+		"ext-ssh2": "*"
 	},
 	"require-dev": {
 		"composer/ca-bundle": "1.5.12",

src/wp-admin/includes/class-wp-filesystem-base.php

@@ -10,6 +10,23 @@
  * Base WordPress Filesystem class which Filesystem implementations extend.
  *
  * @since 2.5.0
+ *
+ * @phpstan-type FileListing array{
+ *     name: string,
+ *     perms?: string,
+ *     permsn?: string,
+ *     number?: int|string|false,
+ *     owner?: string|int<1, max>|false,
+ *     group?: string|int<1, max>|false,
+ *     size: int|string|false,
+ *     lastmodunix?: int|string|false,
+ *     lastmod?: string|false,
+ *     time: int|string|false,
+ *     type: 'd'|'f'|'l',
+ *     islink?: bool,
+ *     isdir?: bool,
+ *     files?: mixed[]|false, // The mixed[] is actually FileListing[] but PHPStan does not support recursive or self-referencing array shapes.
+ * }
  */
 #[AllowDynamicProperties]
 class WP_Filesystem_Base {
@@ -26,7 +43,7 @@ class WP_Filesystem_Base {
 	 * Cached list of local filepaths to mapped remote filepaths.
 	 *
 	 * @since 2.7.0
-	 * @var array
+	 * @var array<string, string>
 	 */
 	public $cache = array();
 
@@ -44,6 +61,7 @@ class WP_Filesystem_Base {
 	public $errors = null;
 
 	/**
+	 * @var array<string, mixed>
 	 */
 	public $options = array();
 
@@ -52,7 +70,7 @@ class WP_Filesystem_Base {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function abspath() {
 		$folder = $this->find_folder( ABSPATH );
@@ -73,7 +91,7 @@ public function abspath() {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function wp_content_dir() {
 		return $this->find_folder( WP_CONTENT_DIR );
@@ -84,7 +102,7 @@ public function wp_content_dir() {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function wp_plugins_dir() {
 		return $this->find_folder( WP_PLUGIN_DIR );
@@ -97,10 +115,10 @@ public function wp_plugins_dir() {
 	 *
 	 * @param string|false $theme Optional. The theme stylesheet or template for the directory.
 	 *                            Default false.
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function wp_themes_dir( $theme = false ) {
-		$theme_root = get_theme_root( $theme );
+		$theme_root = get_theme_root( is_string( $theme ) ? $theme : '' );
 
 		// Account for relative theme roots.
 		if ( '/themes' === $theme_root || ! is_dir( $theme_root ) ) {
@@ -115,7 +133,7 @@ public function wp_themes_dir( $theme = false ) {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function wp_lang_dir() {
 		return $this->find_folder( WP_LANG_DIR );
@@ -134,7 +152,7 @@ public function wp_lang_dir() {
 	 *
 	 * @param string $base    Optional. The folder to start searching from. Default '.'.
 	 * @param bool   $verbose Optional. True to display debug information. Default false.
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function find_base_dir( $base = '.', $verbose = false ) {
 		_deprecated_function( __FUNCTION__, '2.7.0', 'WP_Filesystem_Base::abspath() or WP_Filesystem_Base::wp_*_dir()' );
@@ -155,7 +173,7 @@ public function find_base_dir( $base = '.', $verbose = false ) {
 	 *
 	 * @param string $base    Optional. The folder to start searching from. Default '.'.
 	 * @param bool   $verbose Optional. True to display debug information. Default false.
-	 * @return string The location of the remote path.
+	 * @return string|false The location of the remote path, or false on failure.
 	 */
 	public function get_base_dir( $base = '.', $verbose = false ) {
 		_deprecated_function( __FUNCTION__, '2.7.0', 'WP_Filesystem_Base::abspath() or WP_Filesystem_Base::wp_*_dir()' );
@@ -194,7 +212,9 @@ public function find_folder( $folder ) {
 				}
 
 				if ( $folder === $dir ) {
-					return trailingslashit( constant( $constant ) );
+					/** @var string $constant_value */
+					$constant_value = constant( $constant );
+					return trailingslashit( $constant_value );
 				}
 			}
 
@@ -205,7 +225,9 @@ public function find_folder( $folder ) {
 				}
 
 				if ( 0 === stripos( $folder, $dir ) ) { // $folder starts with $dir.
-					$potential_folder = preg_replace( '#^' . preg_quote( $dir, '#' ) . '/#i', trailingslashit( constant( $constant ) ), $folder );
+					/** @var string $constant_value */
+					$constant_value   = constant( $constant );
+					$potential_folder = (string) preg_replace( '#^' . preg_quote( $dir, '#' ) . '/#i', trailingslashit( $constant_value ), $folder );
 					$potential_folder = trailingslashit( $potential_folder );
 
 					if ( $this->is_dir( $potential_folder ) ) {
@@ -221,7 +243,7 @@ public function find_folder( $folder ) {
 			return trailingslashit( $folder );
 		}
 
-		$folder = preg_replace( '|^([a-z]{1}):|i', '', $folder ); // Strip out Windows drive letter if it's there.
+		$folder = (string) preg_replace( '|^([a-z]{1}):|i', '', $folder ); // Strip out Windows drive letter if it's there.
 		$folder = str_replace( '\\', '/', $folder ); // Windows path sanitization.
 
 		if ( isset( $this->cache[ $folder ] ) ) {
@@ -258,7 +280,8 @@ public function find_folder( $folder ) {
 	 */
 	public function search_for_folder( $folder, $base = '.', $loop = false ) {
 		if ( empty( $base ) || '.' === $base ) {
-			$base = trailingslashit( $this->cwd() );
+			$cwd  = $this->cwd();
+			$base = is_string( $cwd ) ? trailingslashit( $cwd ) : '/';
 		}
 
 		$folder = untrailingslashit( $folder );
@@ -420,7 +443,7 @@ public function getchmod( $file ) {
 	public function getnumchmodfromh( $mode ) {
 		$realmode = '';
 		$legal    = array( '', 'w', 'r', 'x', '-' );
-		$attarray = preg_split( '//', $mode );
+		$attarray = (array) preg_split( '//', $mode );
 
 		for ( $i = 0, $c = count( $attarray ); $i < $c; $i++ ) {
 			$key = array_search( $attarray[ $i ], $legal, true );
@@ -440,9 +463,9 @@ public function getnumchmodfromh( $mode ) {
 		$mode  = strtr( $mode, $trans );
 
 		$newmode  = $mode[0];
-		$newmode .= $mode[1] + $mode[2] + $mode[3];
-		$newmode .= $mode[4] + $mode[5] + $mode[6];
-		$newmode .= $mode[7] + $mode[8] + $mode[9];
+		$newmode .= (int) $mode[1] + (int) $mode[2] + (int) $mode[3];
+		$newmode .= (int) $mode[4] + (int) $mode[5] + (int) $mode[6];
+		$newmode .= (int) $mode[7] + (int) $mode[8] + (int) $mode[9];
 
 		return $newmode;
 	}
@@ -508,7 +531,7 @@ public function get_contents( $file ) {
 	 * @abstract
 	 *
 	 * @param string $file Path to the file.
-	 * @return array|false File contents in an array on success, false on failure.
+	 * @return string[]|false File contents in an array on success, false on failure.
 	 */
 	public function get_contents_array( $file ) {
 		return false;
@@ -851,12 +874,13 @@ public function rmdir( $path, $recursive = false ) {
 	 *                                             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 int|string|false $time        Last modified time. A Unix timestamp on FTP transports, 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.
 	 *     }
 	 * }
+	 * @phpstan-return array<string, FileListing>|false
 	 */
 	public function dirlist( $path, $include_hidden = true, $recursive = false ) {
 		return false;

src/wp-admin/includes/class-wp-filesystem-direct.php

@@ -12,6 +12,7 @@
  * @since 2.5.0
  *
  * @see WP_Filesystem_Base
+ * @phpstan-import-type FileListing from WP_Filesystem_Base
  */
 class WP_Filesystem_Direct extends WP_Filesystem_Base {
 
@@ -23,6 +24,7 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	 * @param mixed $arg Not used.
 	 */
 	public function __construct( $arg ) {
+		unset( $arg );
 		$this->method = 'direct';
 		$this->errors = new WP_Error();
 	}
@@ -45,7 +47,7 @@ public function get_contents( $file ) {
 	 * @since 2.5.0
 	 *
 	 * @param string $file Path to the file.
-	 * @return array|false File contents in an array on success, false on failure.
+	 * @return string[]|false File contents in an array on success, false on failure.
 	 */
 	public function get_contents_array( $file ) {
 		return @file( $file );
@@ -138,9 +140,12 @@ public function chgrp( $file, $group, $recursive = false ) {
 		// Is a directory, and we want recursive.
 		$file     = trailingslashit( $file );
 		$filelist = $this->dirlist( $file );
+		if ( false === $filelist ) {
+			return false;
+		}
 
-		foreach ( $filelist as $filename ) {
-			$this->chgrp( $file . $filename, $group, $recursive );
+		foreach ( $filelist as $file_listing ) {
+			$this->chgrp( $file . $file_listing['name'], $group, $recursive );
 		}
 
 		return true;
@@ -226,9 +231,12 @@ public function chown( $file, $owner, $recursive = false ) {
 
 		// Is a directory, and we want recursive.
 		$filelist = $this->dirlist( $file );
+		if ( false === $filelist ) {
+			return false;
+		}
 
-		foreach ( $filelist as $filename ) {
-			$this->chown( $file . '/' . $filename, $owner, $recursive );
+		foreach ( $filelist as $file_listing ) {
+			$this->chown( $file . '/' . $file_listing['name'], $owner, $recursive );
 		}
 
 		return true;
@@ -240,7 +248,7 @@ public function chown( $file, $owner, $recursive = false ) {
 	 * @since 2.5.0
 	 *
 	 * @param string $file Path to the file.
-	 * @return string|false Username of the owner on success, false on failure.
+	 * @return string|int<1, max>|false Username of the owner on success, or UID of file owner if not available; false on failure.
 	 */
 	public function owner( $file ) {
 		$owneruid = @fileowner( $file );
@@ -285,7 +293,7 @@ public function getchmod( $file ) {
 	 * @since 2.5.0
 	 *
 	 * @param string $file Path to the file.
-	 * @return string|false The group on success, false on failure.
+	 * @return string|int<1, max>|false Username of the owner on success, or group ID of file owner if not available; false on failure.
 	 */
 	public function group( $file ) {
 		$gid = @filegroup( $file );
@@ -639,6 +647,7 @@ public function rmdir( $path, $recursive = false ) {
 	 *                                             files. False if unable to list directory contents.
 	 *     }
 	 * }
+	 * @phpstan-return array<string, FileListing>|false
 	 */
 	public function dirlist( $path, $include_hidden = true, $recursive = false ) {
 		if ( $this->is_file( $path ) ) {
@@ -684,8 +693,8 @@ public function dirlist( $path, $include_hidden = true, $recursive = false ) {
 			$struc['group']       = $this->group( $path . $entry );
 			$struc['size']        = $this->size( $path . $entry );
 			$struc['lastmodunix'] = $this->mtime( $path . $entry );
-			$struc['lastmod']     = gmdate( 'M j', $struc['lastmodunix'] );
-			$struc['time']        = gmdate( 'h:i:s', $struc['lastmodunix'] );
+			$struc['lastmod']     = is_int( $struc['lastmodunix'] ) ? gmdate( 'M j', $struc['lastmodunix'] ) : false;
+			$struc['time']        = is_int( $struc['lastmodunix'] ) ? gmdate( 'h:i:s', $struc['lastmodunix'] ) : false;
 			$struc['type']        = $this->is_dir( $path . $entry ) ? 'd' : 'f';
 
 			if ( 'd' === $struc['type'] ) {