WP_Filesystem fixes and phpdoc, props hakre dd32, see #10304

git-svn-id: http://svn.automattic.com/wordpress/trunk@11831 1a063a9b-81f0-0310-95a4-ce76da25c4cd

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

@@ -15,24 +15,51 @@
  * @uses WP_Filesystem_Base Extends class
  */
 class WP_Filesystem_Direct extends WP_Filesystem_Base {
-	var $permission = null;
 	var $errors = null;
+	/**
+	 * constructor
+	 * 
+	 * @param $arg mixed ingored argument
+	 */
 	function WP_Filesystem_Direct($arg) {
 		$this->method = 'direct';
 		$this->errors = new WP_Error();
 	}
+	/**
+	 * connect filesystem.
+	 * 
+	 * @return bool Returns true on success or false on failure (always true for WP_Filesystem_Direct).
+	 */
 	function connect() {
 		return true;
 	}
-	function setDefaultPermissions($perm) {
+	/**
-		$this->permission = $perm;
+	 * Reads entire file into a string
-	}
+	 * 
+	 * @param $file string Name of the file to read.
+	 * @return string|bool The function returns the read data or false on failure. 
+	 */
 	function get_contents($file) {
 		return @file_get_contents($file);
 	}
+	/**
+	 * Reads entire file into an array
+	 * 
+	 * @param $file string Path to the file. 
+	 * @return array|bool the file contents in an array or false on failure. 
+	 */
 	function get_contents_array($file) {
 		return @file($file);
 	}
+	/**
+	 * Write a string to a file
+	 * 
+	 * @param $file string Path to the file where to write the data. 
+	 * @param $contents string The data to write.
+	 * @param $mode int (optional) The file permissions as octal number, usually 0644.
+	 * @param $type string (optional) Specifies additional type of access you require to the file.
+	 * @return bool False upon failure.
+	 */
 	function put_contents($file, $contents, $mode = false, $type = '') {
 		if ( ! ($fp = @fopen($file, 'w' . $type)) )
 			return false;
@@ -41,12 +68,31 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		$this->chmod($file, $mode);
 		return true;
 	}
+	/**
+	 * Gets the current working directory
+	 * 
+	 * @return string|bool the current working directory on success, or false on failure. 
+	 */
 	function cwd() {
 		return @getcwd();
 	}
+	/**
+	 * Change directory
+	 *
+	 * @param $dir string The new current directory. 
+	 * @return bool Returns true on success or false on failure.
+	 */
 	function chdir($dir) {
 		return @chdir($dir);
 	}
+	/**
+	 * Changes file group
+	 * 
+	 * @param $file string Path to the file. 
+	 * @param $group mixed A group name or number.
+	 * @param $recursive bool (optional) If set True changes file group recursivly. Defaults to False. 
+	 * @return bool Returns true on success or false on failure.
+	 */
 	function chgrp($file, $group, $recursive = false) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -62,14 +108,20 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 
 		return true;
 	}
+	/**
+	 * Changes filesystem permissions
+	 * 
+	 * @param $file string Path to the file.
+	 * @param $mode int (optional) The permissions as octal number, usually 0644 for files, 0755 for dirs.
+	 * @param $recursive bool (optional) If set True changes file group recursivly. Defaults to False. 
+	 * @return bool Returns true on success or false on failure.
+	 */
 	function chmod($file, $mode = false, $recursive = false) {
 		if ( ! $this->exists($file) )
 			return false;
 
 		if ( ! $mode ) {
-			if ( $this->permission )
+			if ( $this->is_file($file) )
-				$mode = $this->permission;
-			elseif ( $this->is_file($file) )
 				$mode = FS_CHMOD_FILE;
 			elseif ( $this->is_dir($file) )
 				$mode = FS_CHMOD_DIR;
@@ -89,6 +141,14 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 
 		return true;
 	}
+	/**
+	 * Changes file owner
+	 * 
+	 * @param $file string Path to the file. 
+	 * @param $owner mixed A user name or number.
+	 * @param $recursive bool (optional) If set True changes file owner recursivly. Defaults to False. 
+	 * @return bool Returns true on success or false on failure.
+	 */
 	function chown($file, $owner, $recursive = false) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -103,6 +163,12 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		}
 		return true;
 	}
+	/**
+	 * Gets file owner
+	 * 
+	 * @param $file string Path to the file. 
+	 * @return string Username of the user.
+	 */
 	function owner($file) {
 		$owneruid = @fileowner($file);
 		if ( ! $owneruid )
@@ -112,6 +178,14 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 		$ownerarray = posix_getpwuid($owneruid);
 		return $ownerarray['name'];
 	}
+	/**
+	 * Gets file permissions
+	 * 
+	 * FIXME does not handle errors in fileperms()
+	 * 
+	 * @param $file string Path to the file. 
+	 * @return string Mode of the file (last 4 digits).
+	 */
 	function getchmod($file) {
 		return substr(decoct(@fileperms($file)),3);
 	}
@@ -206,6 +280,9 @@ class WP_Filesystem_Direct extends WP_Filesystem_Base {
 	}
 
 	function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
+		if ( ! $chmod )
+			$chmod = FS_CHMOD_DIR;
+
 		if ( ! @mkdir($path) )
 			return false;
 		$this->chmod($path, $chmod);

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

@@ -19,8 +19,6 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 	var $errors = null;
 	var $options = array();
 
-	var $permission = null;
-
 	function WP_Filesystem_FTPext($opt='') {
 		$this->method = 'ftpext';
 		$this->errors = new WP_Error();
@@ -90,10 +88,6 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return true;
 	}
 
-	function setDefaultPermissions($perm) {
-		$this->permission = $perm;
-	}
-
 	function get_contents($file, $type = '', $resumepos = 0 ) {
 		if ( empty($type) )
 			$type = FTP_BINARY;
@@ -146,12 +140,18 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 		return false;
 	}
 	function chmod($file, $mode = false, $recursive = false) {
-		if( ! $mode )
-			$mode = $this->permission;
-		if( ! $mode )
-			return false;
 		if ( ! $this->exists($file) && ! $this->is_dir($file) )
 			return false;
+
+		if ( ! $mode ) {
+			if ( $this->is_file($file) )
+				$mode = FS_CHMOD_FILE;
+			elseif ( $this->is_dir($file) )
+				$mode = FS_CHMOD_DIR;
+			else
+				return false;	
+		}
+
 		if ( ! $recursive || ! $this->is_dir($file) ) {
 			if ( ! function_exists('ftp_chmod') )
 				return @ftp_site($this->link, sprintf('CHMOD %o %s', $mode, $file));
@@ -245,7 +245,8 @@ class WP_Filesystem_FTPext extends WP_Filesystem_Base {
 	function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
 		if  ( !ftp_mkdir($this->link, $path) )
 			return false;
-		if( $chmod )
+		if ( ! $chmod )
+			$chmod = FS_CHMOD_DIR;
 		$this->chmod($path, $chmod);
 		if ( $chown )
 			$this->chown($path, $chown);

wp-admin/includes/class-wp-filesystem-ftpsockets.php

@@ -19,8 +19,6 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	var $errors = null;
 	var $options = array();
 
-	var $permission = null;
-
 	function WP_Filesystem_ftpsockets($opt = '') {
 		$this->method = 'ftpsockets';
 		$this->errors = new WP_Error();
@@ -83,10 +81,6 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 		return true;
 	}
 
-	function setDefaultPermissions($perm) {
-		$this->permission = $perm;
-	}
-
 	function get_contents($file, $type = '', $resumepos = 0) {
 		if ( ! $this->exists($file) )
 			return false;
@@ -159,12 +153,16 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	}
 
 	function chmod($file, $mode = false, $recursive = false ) {
-		if( ! $mode )
+
-			$mode = $this->permission;
+		if ( ! $mode ) {
-		if( ! $mode )
+			if ( $this->is_file($file) )
+				$mode = FS_CHMOD_FILE;
+			elseif ( $this->is_dir($file) )
+				$mode = FS_CHMOD_DIR;
+			else
 				return false;	
-		//if( ! $this->exists($file) )
+		}
-		//	return false;
+
 		if ( ! $recursive || ! $this->is_dir($file) ) {
 			return $this->ftp->chmod($file, $mode);
 		}
@@ -267,7 +265,8 @@ class WP_Filesystem_ftpsockets extends WP_Filesystem_Base {
 	function mkdir($path, $chmod = false, $chown = false, $chgrp = false ) {
 		if ( ! $this->ftp->mkdir($path) )
 			return false;
-		if( $chmod )
+		if ( ! $chmod )
+			$chmod = FS_CHMOD_DIR;
 		$this->chmod($path, $chmod);
 		if ( $chown )
 			$this->chown($path, $chown);

wp-admin/includes/class-wp-filesystem-ssh2.php

@@ -48,8 +48,6 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	var $errors = array();
 	var $options = array();
 
-	var $permission = 0644;
-
 	function WP_Filesystem_SSH2($opt='') {
 		$this->method = 'ssh2';
 		$this->errors = new WP_Error();
@@ -152,12 +150,6 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		return false;
 	}
 
-	function setDefaultPermissions($perm) {
-		$this->debug("setDefaultPermissions();");
-		if ( $perm )
-			$this->permission = $perm;
-	}
-
 	function get_contents($file, $type = '', $resumepos = 0 ) {
 		$file = ltrim($file, '/');
 		return file_get_contents('ssh2.sftp://' . $this->sftp_link . '/' . $file);
@@ -193,12 +185,18 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 	}
 
 	function chmod($file, $mode = false, $recursive = false) {
-		if( ! $mode )
-			$mode = $this->permission;
-		if( ! $mode )
-			return false;
 		if ( ! $this->exists($file) )
 			return false;
+
+		if ( ! $mode ) {
+			if ( $this->is_file($file) )
+				$mode = FS_CHMOD_FILE;
+			elseif ( $this->is_dir($file) )
+				$mode = FS_CHMOD_DIR;
+			else
+				return false;	
+		}
+
 		if ( ! $recursive || ! $this->is_dir($file) )
 			return $this->run_command(sprintf('chmod %o %s', $mode, escapeshellarg($file)), true);
 		return $this->run_command(sprintf('chmod -R %o %s', $mode, escapeshellarg($file)), true);
@@ -307,9 +305,10 @@ class WP_Filesystem_SSH2 extends WP_Filesystem_Base {
 		//Not implmented.
 	}
 
-	function mkdir($path, $chmod = null, $chown = false, $chgrp = false) {
+	function mkdir($path, $chmod = false, $chown = false, $chgrp = false) {
 		$path = untrailingslashit($path);
-		$chmod = !empty($chmod) ? $chmod : $this->permission;
+		if ( ! $chmod )
+			$chmod = FS_CHMOD_DIR;
 		if ( ! ssh2_sftp_mkdir($this->sftp_link, $path, $chmod, true) )
 			return false;
 		if ( $chown )