Changeset 12151

Timestamp:

11/05/2009 11:03:48 PM (15 years ago)

Author:

azaozz

Message:

Add phpdoc and extra filter to file.php, props dd32, fixes #11002

File:

• trunk/wp-admin/includes/file.php (modified) (14 diffs)

trunk/wp-admin/includes/file.php

@@ -100 +100 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @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
+ * 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 2.6.0
+ *
+ * @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 ) {
@@ -136 +137 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @return unknown
+ * Determines a writable directory for temporary files.
+ * Function's preference is to WP_CONTENT_DIR followed by the return value of <code>sys_get_temp_dir()</code>, before finally defaulting to /tmp/
+ *
+ * In the event that this function does not find a writable location, It may be overridden by the <code>WP_TEMP_DIR</code> constant in your <code>wp-config.php</code> file.
+ *
+ * @since 2.5.0
+ *
+ * @return string Writable temporary directory
  */
 function get_temp_dir() {
@@ -157 +161 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $filename
- * @param unknown_type $dir
- * @return unknown
+ * Returns a filename of a Temporary unique file.
+ * Please note that the calling function must unlink() this itself.
+ *
+ * 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.
+ *
+ * @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 = ''){
@@ -432 +440 @@
 
 /**
- * Downloads a url to a local file using the Snoopy HTTP Class.
- *
- * @since unknown
- * @todo Transition over to using the new HTTP Request API (jacob).
+ * Downloads a url to a local temporary file using the WordPress HTTP Class.
+ * Please note, That the calling function must unlink() the  file.
+ *
+ * @since 2.5.0
  *
  * @param string $url the URL of the file to download
@@ -474 +482 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $file
- * @param unknown_type $to
- * @return unknown
+ * 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.
+ *
+ * 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.
+ *
+ * @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) {
@@ -488 +500 @@
         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');
 
@@ -546 +558 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $from
- * @param unknown_type $to
- * @return unknown
+ * Copies a directory from one location to another via the WordPress Filesystem Abstraction.
+ * Assumes that WP_Filesystem() has already been called and setup.
+ *
+ * @since 2.5.0
+ *
+ * @param string $from source directory
+ * @param string $to destination directory
+ * @return mixed WP_Error on failure, True on success.
  */
 function copy_dir($from, $to) {
@@ -581 +594 @@
         }
     }
-}
-
-/**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $args
- * @return unknown
+    return true;
+}
+
+/**
+ * Initialises and connects the WordPress Filesystem Abstraction classes.
+ * This function will include the chosen transport and attempt connecting.
+ *
+ * Plugins may add extra transports, And force WordPress to use them by returning the filename via the 'filesystem_method_file' filter.
+ *
+ * @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 ) {
@@ -634 +652 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $args
+ * Determines which Filesystem Method to use.
+ * The priority of the Transports are: Direct, SSH2, FTP PHP Extension, FTP Sockets (Via Sockets class, or fsoxkopen())
+ *
+ * Note that the return value of this function can be overridden in 2 ways
+ *  - By defining FS_METHOD in your <code>wp-config.php</code> 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.
+ *
+ * @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) {
@@ -666 +691 @@
 
 /**
- * {@internal Missing Short Description}}
- *
- * @since unknown
- *
- * @param unknown_type $form_post
- * @param unknown_type $type
- * @param unknown_type $error
- * @return unknown
+ * 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.
+ *
+ * Hostnames may be in the form of hostname:portnumber (eg: wordpress.org:2467) to specify an alternate FTP/SSH port.
+ *
+ * Plugins may override this form by returning true|false via the <code>request_filesystem_credentials</code> 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) {
@@ -700 +731 @@
     $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) )
@@ -739 +773 @@
         echo '<div id="message" class="error"><p>' . $error_string . '</p></div>';
     }
+
+    $types = array();
+    if ( extension_loaded('ftp') || extension_loaded('sockets') || function_exists('fsockopen') )
+        $types[ 'ftp' ] = __('FTP');
+    if ( extension_loaded('ftp') ) //Only this supports FTPS
+        $types[ 'ftps' ] = __('FTPS (SSL)');
+    if ( extension_loaded('ssh2') && function_exists('stream_get_contents') )
+        $types[ 'ssh' ] = __('SSH2');
+
+    $types = apply_filters('fs_ftp_connection_types', $types, $credentials, $type, $error, $context);
+
 ?>
 <script type="text/javascript">
@@ -775 +820 @@
 </tr>
 
-<?php if ( extension_loaded('ssh2') && function_exists('stream_get_contents') ) : ?>
+<?php if ( isset($types['ssh']) ) : ?>
 <tr id="ssh_keys" valign="top" style="<?php if ( 'ssh' != $connection_type ) echo 'display:none' ?>">
 <th scope="row"><?php _e('Authentication Keys') ?>
@@ -791 +836 @@
 <td>
 <fieldset><legend class="screen-reader-text"><span><?php _e('Connection Type') ?></span></legend>
-<label><input id="ftp" name="connection_type"  type="radio" value="ftp" <?php checked('ftp', $connection_type); if ( defined('FTP_SSL') || defined('FTP_SSH') ) echo ' disabled="disabled"'; ?>/> <?php _e('FTP') ?></label>
-<?php if ( 'ftpext' == $type ) : ?>
-<br /><label><input id="ftps" name="connection_type" type="radio" value="ftps" <?php checked('ftps', $connection_type); if ( defined('FTP_SSL') || defined('FTP_SSH') ) echo ' disabled="disabled"';  ?>/> <?php _e('FTPS (SSL)') ?></label>
-<?php endif; ?>
-<?php if ( extension_loaded('ssh2') && function_exists('stream_get_contents') ) : ?>
-<br /><label><input id="ssh" name="connection_type" type="radio" value="ssh" <?php checked('ssh', $connection_type);  if ( defined('FTP_SSL') || defined('FTP_SSH') ) echo ' disabled="disabled"'; ?>/> <?php _e('SSH') ?></label>
-<?php endif; ?>
+<?php
+
+    $disabled = defined('FTP_SSL') || defined('FTP_SSH') ? '' : ' disabled="disabled"';
+
+    foreach ( $types as $name => $text ) : ?>
+    <label for="<?php echo esc_atr($name) ?>">
+        <input type="radio" name="connection_type" id="<?php echo esc_atr($name) ?>" value="<?php echo esc_atr($name) ?>" <?php checked($name, $connection_type); echo $disabled; ?>/>
+        <?php echo $text ?>
+    </label>
+    <?php endforeach; ?>
 </fieldset>
 </td>