Index: wp-admin/includes/file.php
===================================================================
--- wp-admin/includes/file.php (revision 11906)
+++ wp-admin/includes/file.php (working copy)
@@ -99,13 +99,14 @@
}
/**
- * {@internal Missing Short Description}}
+ * Returns a listing of all files in the specified folder and all subdirectories up to 100 levels deep.
+ * The depth of the recursiveness can be controlled by the $levels param.
*
- * @since unknown
+ * @since 2.6.0
*
- * @param string $folder Optional. Full path to folder
- * @param int $levels Optional. Levels of folders to follow, Default: 100 (PHP Loop limit).
- * @return bool|array
+ * @param string $folder Full path to folder
+ * @param int $levels (optional) Levels of folders to follow, Default: 100 (PHP Loop limit).
+ * @return bool|array False on failure, Else array of files
*/
function list_files( $folder = '', $levels = 100 ) {
if( empty($folder) )
@@ -135,11 +136,14 @@
}
/**
- * {@internal Missing Short Description}}
+ * Determines a writable directory for temporary files.
+ * Function's preference is to WP_CONTENT_DIR followed by the return value of sys_get_temp_dir(), before finally defaulting to /tmp/
*
- * @since unknown
+ * In the event that this function does not find a writable location, It may be overridden by the WP_TEMP_DIR constant in your wp-config.php file.
*
- * @return unknown
+ * @since 2.5.0
+ *
+ * @return string Writable temporary directory
*/
function get_temp_dir() {
if ( defined('WP_TEMP_DIR') )
@@ -156,13 +160,17 @@
}
/**
- * {@internal Missing Short Description}}
+ * Returns a filename of a Temporary unique file.
+ * Please note that the calling function must unlink() this itself.
*
- * @since unknown
+ * The filename is based off the passed parameter or defaults to the current unix timestamp,
+ * while the directory can either be passed as well, or by leaving it blank, default to a writable temporary directory.
*
- * @param unknown_type $filename
- * @param unknown_type $dir
- * @return unknown
+ * @since 2.6.0
+ *
+ * @param string $filename (optional) Filename to base the Unique file off
+ * @param string $dir (optional) Directory to store the file in
+ * @return string a writable filename
*/
function wp_tempnam($filename = '', $dir = ''){
if ( empty($dir) )
@@ -425,10 +433,10 @@
}
/**
- * Downloads a url to a local file using the Snoopy HTTP Class.
+ * Downloads a url to a local temporary file using the WordPress HTTP Class.
+ * Please note, That the calling function must unlink() the file.
*
- * @since unknown
- * @todo Transition over to using the new HTTP Request API (jacob).
+ * @since 2.5.0
*
* @param string $url the URL of the file to download
* @return mixed WP_Error on failure, string Filename on success.
@@ -467,13 +475,17 @@
}
/**
- * {@internal Missing Short Description}}
+ * Unzip's a specified ZIP file to a location on the Filesystem via the WordPress Filesystem Abstraction.
+ * Assumes that WP_Filesystem() has already been called and set up.
*
- * @since unknown
+ * Attempts to increase the PHP Memory limit to 256M before uncompressing,
+ * However, The most memory required shouldn't be much larger than the Archive itself.
*
- * @param unknown_type $file
- * @param unknown_type $to
- * @return unknown
+ * @since 2.5.0
+ *
+ * @param string $file Full path and filename of zip archive
+ * @param string $to Full path on the filesystem to extract archive to
+ * @return mixed WP_Error on failure, True on success
*/
function unzip_file($file, $to) {
global $wp_filesystem;
@@ -481,11 +493,9 @@
if ( ! $wp_filesystem || !is_object($wp_filesystem) )
return new WP_Error('fs_unavailable', __('Could not access filesystem.'));
- // Unzip uses a lot of memory
+ // Unzip uses a lot of memory, But not this much hopefully
@ini_set('memory_limit', '256M');
- $fs =& $wp_filesystem;
-
require_once(ABSPATH . 'wp-admin/includes/class-pclzip.php');
$archive = new PclZip($file);
@@ -497,55 +507,54 @@
if ( 0 == count($archive_files) )
return new WP_Error('empty_archive', __('Empty archive'));
- $path = explode('/', untrailingslashit($to));
- for ( $i = count($path); $i > 0; $i-- ) { //>0 = first element is empty allways for paths starting with '/'
- $tmppath = implode('/', array_slice($path, 0, $i) );
- if ( $fs->is_dir($tmppath) ) { //Found the highest folder that exists, Create from here(ie +1)
- for ( $i = $i + 1; $i <= count($path); $i++ ) {
- $tmppath = implode('/', array_slice($path, 0, $i) );
- if ( ! $fs->mkdir($tmppath, FS_CHMOD_DIR) )
- return new WP_Error('mkdir_failed', __('Could not create directory'), $tmppath);
- }
- break; //Exit main for loop
- }
- }
+ $needed_dirs = array();
+ $to = trailingslashit($to);
- $to = trailingslashit($to);
- foreach ($archive_files as $file) {
- $path = $file['folder'] ? $file['filename'] : dirname($file['filename']);
- $path = explode('/', $path);
- for ( $i = count($path); $i >= 0; $i-- ) { //>=0 as the first element contains data
+ // Determine any parent dir's needed
+ if ( ! $wp_filesystem->is_dir($to) ) { //Only do parents if no children exist
+ $path = preg_split('![/\\\]!', untrailingslashit($to));
+ for ( $i = count($path); $i >= 0; $i-- ) {
if ( empty($path[$i]) )
continue;
- $tmppath = $to . implode('/', array_slice($path, 0, $i) );
- if ( $fs->is_dir($tmppath) ) {//Found the highest folder that exists, Create from here
- for ( $i = $i + 1; $i <= count($path); $i++ ) { //< count() no file component please.
- $tmppath = $to . implode('/', array_slice($path, 0, $i) );
- if ( ! $fs->is_dir($tmppath) && ! $fs->mkdir($tmppath, FS_CHMOD_DIR) )
- return new WP_Error('mkdir_failed', __('Could not create directory'), $tmppath);
- }
- break; //Exit main for loop
- }
+ $dir = implode('/', array_slice($path, 0, $i+1) );
+ if ( preg_match('!^\w:$!i', $dir) ) //Win32 drive letter causes issues.
+ continue;
+ $needed_dirs[] = $dir;
}
+ }
- // We've made sure the folders are there, so let's extract the file now:
- if ( ! $file['folder'] ) {
- if ( !$fs->put_contents( $to . $file['filename'], $file['content']) )
- return new WP_Error('copy_failed', __('Could not copy file'), $to . $file['filename']);
- $fs->chmod($to . $file['filename'], FS_CHMOD_FILE);
- }
+ // Determine any children directories needed
+ foreach ( $archive_files as $file )
+ $needed_dirs[] = $to . untrailingslashit( $file['folder'] ? $file['filename'] : dirname($file['filename']) );
+
+ $needed_dirs = array_unique($needed_dirs);
+ asort($needed_dirs);
+
+ // Create those directories if need be:
+ for ( $i = 0; $i < count($needed_dirs); $i++ )
+ if ( ! $wp_filesystem->is_dir($needed_dirs[$i]) && ! $wp_filesystem->mkdir($needed_dirs[$i], FS_CHMOD_DIR) )
+ return new WP_Error('mkdir_failed', __('Could not create directory'), $needed_dirs[$i]);
+
+ // Extract the files from the zip
+ foreach ( $archive_files as $file ) {
+ if ( $file['folder'] )
+ continue;
+ if ( ! $wp_filesystem->put_contents( $to . $file['filename'], $file['content']) )
+ return new WP_Error('copy_failed', __('Could not copy file'), $to . $file['filename']);
+ $wp_filesystem->chmod($to . $file['filename'], FS_CHMOD_FILE);
}
return true;
}
/**
- * {@internal Missing Short Description}}
+ * Copies a directory from one location to another via the WordPress Filesystem Abstraction.
+ * Assumes that WP_Filesystem() has already been called and setup.
*
- * @since unknown
+ * @since 2.5.0
*
- * @param unknown_type $from
- * @param unknown_type $to
- * @return unknown
+ * @param string $from source directory
+ * @param string $to destination directory
+ * @return mixed WP_Error on failure, True on success.
*/
function copy_dir($from, $to) {
global $wp_filesystem;
@@ -574,15 +583,20 @@
return $result;
}
}
+ return true;
}
/**
- * {@internal Missing Short Description}}
+ * Initialises and connects the WordPress Filesystem Abstraction classes.
+ * This function will include the chosen transport and attempt connecting.
*
- * @since unknown
+ * Plugins may add extra transports, And force WordPress to use them by returning the filename via the 'filesystem_method_file' filter.
*
- * @param unknown_type $args
- * @return unknown
+ * @since 2.5.0
+ *
+ * @param array $args (optional) Connection args, These are passed directly to the WP_Filesystem_*() classes.
+ * @param string $context (optional) Context for get_filesystem_method(), See function declaration for more information.
+ * @return boolean false on failure, true on success
*/
function WP_Filesystem( $args = false, $context = false ) {
global $wp_filesystem;
@@ -627,13 +641,20 @@
}
/**
- * {@internal Missing Short Description}}
+ * Determines which Filesystem Method to use.
+ * The priority of the Transports are: Direct, SSH2, FTP PHP Extension, FTP Sockets (Via Sockets class, or fsoxkopen())
*
- * @since unknown
+ * Note that the return value of this function can be overridden in 2 ways
+ * - By defining FS_METHOD in your wp-config.php file
+ * - By using the filesystem_method filter
+ * Valid values for these are: 'direct', 'ssh', 'ftpext' or 'ftpsockets'
+ * Plugins may also define a custom transport handler, See the WP_Filesystem function for more information.
*
- * @param unknown_type $args
+ * @since 2.5.0
+ *
+ * @param array $args Connection details.
* @param string $context Full path to the directory that is tested for being writable.
- * @return unknown
+ * @return string The transport to use, see description for valid return values.
*/
function get_filesystem_method($args = array(), $context = false) {
$method = defined('FS_METHOD') ? FS_METHOD : false; //Please ensure that this is either 'direct', 'ssh', 'ftpext' or 'ftpsockets'
@@ -659,14 +680,20 @@
}
/**
- * {@internal Missing Short Description}}
+ * Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
+ * All chosen/entered details are saved, Excluding the Password.
*
- * @since unknown
+ * Hostnames may be in the form of hostname:portnumber (eg: wordpress.org:2467) to specify an alternate FTP/SSH port.
*
- * @param unknown_type $form_post
- * @param unknown_type $type
- * @param unknown_type $error
- * @return unknown
+ * Plugins may override this form by returning true|false via the request_filesystem_credentials filter.
+ *
+ * @since 2.5.0
+ *
+ * @param string $form_post the URL to post the form to
+ * @param string $type the chosen Filesystem method in use
+ * @param boolean $error if the current request has failed to connect
+ * @param string $context The directory which is needed access to, The write-test will be performed on this directory by get_filesystem_method()
+ * @return boolean False on failure. True on success.
*/
function request_filesystem_credentials($form_post, $type = '', $error = false, $context = false) {
$req_cred = apply_filters('request_filesystem_credentials', '', $form_post, $type, $error, $context);
@@ -693,10 +720,13 @@
//sanitize the hostname, Some people might pass in odd-data:
$credentials['hostname'] = preg_replace('|\w+://|', '', $credentials['hostname']); //Strip any schemes off
- if ( strpos($credentials['hostname'], ':') )
+ if ( strpos($credentials['hostname'], ':') ) {
list( $credentials['hostname'], $credentials['port'] ) = explode(':', $credentials['hostname'], 2);
- else
+ if ( ! is_numeric($credentials['port']) )
+ unset($credentials['port']);
+ } else {
unset($credentials['port']);
+ }
if ( defined('FTP_SSH') || (defined('FS_METHOD') && 'ssh' == FS_METHOD) )
$credentials['connection_type'] = 'ssh';