<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" /><style type="text/css"><!--
#msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; }
#msg ul, pre { overflow: auto; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<title>[12151] trunk/wp-admin/includes/file.php:
Add phpdoc and extra filter to file.php, props dd32, fixes #11002</title>
</head>
<body>
<div id="msg">
<dl>
<dt>Revision</dt> <dd><a href="http://trac.wordpress.org/changeset/12151">12151</a></dd>
<dt>Author</dt> <dd>azaozz</dd>
<dt>Date</dt> <dd>2009-11-05 23:03:48 +0000 (Thu, 05 Nov 2009)</dd>
</dl>
<h3>Log Message</h3>
<pre>Add phpdoc and extra filter to file.php, props dd32, fixes <a href="http://trac.wordpress.org/ticket/11002">#11002</a></pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkwpadminincludesfilephp">trunk/wp-admin/includes/file.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkwpadminincludesfilephp"></a>
<div class="modfile"><h4>Modified: trunk/wp-admin/includes/file.php (12150 => 12151)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/wp-admin/includes/file.php 2009-11-05 22:53:31 UTC (rev 12150)
+++ trunk/wp-admin/includes/file.php 2009-11-05 23:03:48 UTC (rev 12151)
</span><span class="lines">@@ -99,13 +99,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * @since 2.6.0
</ins><span class="cx"> *
</span><del>- * @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
</del><ins>+ * @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
</ins><span class="cx"> */
</span><span class="cx"> function list_files( $folder = '', $levels = 100 ) {
</span><span class="cx"> if( empty($folder) )
</span><span class="lines">@@ -135,11 +136,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * 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/
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @return unknown
</del><ins>+ * @since 2.5.0
+ *
+ * @return string Writable temporary directory
</ins><span class="cx"> */
</span><span class="cx"> function get_temp_dir() {
</span><span class="cx"> if ( defined('WP_TEMP_DIR') )
</span><span class="lines">@@ -156,13 +160,17 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * Returns a filename of a Temporary unique file.
+ * Please note that the calling function must unlink() this itself.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @param unknown_type $filename
- * @param unknown_type $dir
- * @return unknown
</del><ins>+ * @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
</ins><span class="cx"> */
</span><span class="cx"> function wp_tempnam($filename = '', $dir = ''){
</span><span class="cx"> if ( empty($dir) )
</span><span class="lines">@@ -431,10 +439,10 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Downloads a url to a local file using the Snoopy HTTP Class.
</del><ins>+ * Downloads a url to a local temporary file using the WordPress HTTP Class.
+ * Please note, That the calling function must unlink() the file.
</ins><span class="cx"> *
</span><del>- * @since unknown
- * @todo Transition over to using the new HTTP Request API (jacob).
</del><ins>+ * @since 2.5.0
</ins><span class="cx"> *
</span><span class="cx"> * @param string $url the URL of the file to download
</span><span class="cx"> * @return mixed WP_Error on failure, string Filename on success.
</span><span class="lines">@@ -473,13 +481,17 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @param unknown_type $file
- * @param unknown_type $to
- * @return unknown
</del><ins>+ * @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
</ins><span class="cx"> */
</span><span class="cx"> function unzip_file($file, $to) {
</span><span class="cx"> global $wp_filesystem;
</span><span class="lines">@@ -487,7 +499,7 @@
</span><span class="cx"> if ( ! $wp_filesystem || !is_object($wp_filesystem) )
</span><span class="cx"> return new WP_Error('fs_unavailable', __('Could not access filesystem.'));
</span><span class="cx">
</span><del>- // Unzip uses a lot of memory
</del><ins>+ // Unzip uses a lot of memory, but not this much hopefully
</ins><span class="cx"> @ini_set('memory_limit', '256M');
</span><span class="cx">
</span><span class="cx"> $fs =& $wp_filesystem;
</span><span class="lines">@@ -545,13 +557,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * Copies a directory from one location to another via the WordPress Filesystem Abstraction.
+ * Assumes that WP_Filesystem() has already been called and setup.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * @since 2.5.0
</ins><span class="cx"> *
</span><del>- * @param unknown_type $from
- * @param unknown_type $to
- * @return unknown
</del><ins>+ * @param string $from source directory
+ * @param string $to destination directory
+ * @return mixed WP_Error on failure, True on success.
</ins><span class="cx"> */
</span><span class="cx"> function copy_dir($from, $to) {
</span><span class="cx"> global $wp_filesystem;
</span><span class="lines">@@ -580,15 +593,20 @@
</span><span class="cx"> return $result;
</span><span class="cx"> }
</span><span class="cx"> }
</span><ins>+ return true;
</ins><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * Initialises and connects the WordPress Filesystem Abstraction classes.
+ * This function will include the chosen transport and attempt connecting.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * Plugins may add extra transports, And force WordPress to use them by returning the filename via the 'filesystem_method_file' filter.
</ins><span class="cx"> *
</span><del>- * @param unknown_type $args
- * @return unknown
</del><ins>+ * @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
</ins><span class="cx"> */
</span><span class="cx"> function WP_Filesystem( $args = false, $context = false ) {
</span><span class="cx"> global $wp_filesystem;
</span><span class="lines">@@ -633,13 +651,20 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * Determines which Filesystem Method to use.
+ * The priority of the Transports are: Direct, SSH2, FTP PHP Extension, FTP Sockets (Via Sockets class, or fsoxkopen())
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @param unknown_type $args
</del><ins>+ * @since 2.5.0
+ *
+ * @param array $args Connection details.
</ins><span class="cx"> * @param string $context Full path to the directory that is tested for being writable.
</span><del>- * @return unknown
</del><ins>+ * @return string The transport to use, see description for valid return values.
</ins><span class="cx"> */
</span><span class="cx"> function get_filesystem_method($args = array(), $context = false) {
</span><span class="cx"> $method = defined('FS_METHOD') ? FS_METHOD : false; //Please ensure that this is either 'direct', 'ssh', 'ftpext' or 'ftpsockets'
</span><span class="lines">@@ -665,14 +690,20 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * {@internal Missing Short Description}}
</del><ins>+ * 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.
</ins><span class="cx"> *
</span><del>- * @since unknown
</del><ins>+ * Hostnames may be in the form of hostname:portnumber (eg: wordpress.org:2467) to specify an alternate FTP/SSH port.
</ins><span class="cx"> *
</span><del>- * @param unknown_type $form_post
- * @param unknown_type $type
- * @param unknown_type $error
- * @return unknown
</del><ins>+ * 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.
</ins><span class="cx"> */
</span><span class="cx"> function request_filesystem_credentials($form_post, $type = '', $error = false, $context = false) {
</span><span class="cx"> $req_cred = apply_filters('request_filesystem_credentials', '', $form_post, $type, $error, $context);
</span><span class="lines">@@ -699,10 +730,13 @@
</span><span class="cx"> //sanitize the hostname, Some people might pass in odd-data:
</span><span class="cx"> $credentials['hostname'] = preg_replace('|\w+://|', '', $credentials['hostname']); //Strip any schemes off
</span><span class="cx">
</span><del>- if ( strpos($credentials['hostname'], ':') )
</del><ins>+ if ( strpos($credentials['hostname'], ':') ) {
</ins><span class="cx"> list( $credentials['hostname'], $credentials['port'] ) = explode(':', $credentials['hostname'], 2);
</span><del>- else
</del><ins>+ if ( ! is_numeric($credentials['port']) )
+ unset($credentials['port']);
+ } else {
</ins><span class="cx"> unset($credentials['port']);
</span><ins>+ }
</ins><span class="cx">
</span><span class="cx"> if ( defined('FTP_SSH') || (defined('FS_METHOD') && 'ssh' == FS_METHOD) )
</span><span class="cx"> $credentials['connection_type'] = 'ssh';
</span><span class="lines">@@ -738,6 +772,17 @@
</span><span class="cx"> $error_string = $error->get_error_message();
</span><span class="cx"> echo '<div id="message" class="error"><p>' . $error_string . '</p></div>';
</span><span class="cx"> }
</span><ins>+
+ $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);
+
</ins><span class="cx"> ?>
</span><span class="cx"> <script type="text/javascript">
</span><span class="cx"> <!--
</span><span class="lines">@@ -774,7 +819,7 @@
</span><span class="cx"> <td><input name="password" type="password" id="password" value="<?php if ( defined('FTP_PASS') ) echo '*****'; ?>"<?php if ( defined('FTP_PASS') ) echo ' disabled="disabled"' ?> size="40" /></td>
</span><span class="cx"> </tr>
</span><span class="cx">
</span><del>-<?php if ( extension_loaded('ssh2') && function_exists('stream_get_contents') ) : ?>
</del><ins>+<?php if ( isset($types['ssh']) ) : ?>
</ins><span class="cx"> <tr id="ssh_keys" valign="top" style="<?php if ( 'ssh' != $connection_type ) echo 'display:none' ?>">
</span><span class="cx"> <th scope="row"><?php _e('Authentication Keys') ?>
</span><span class="cx"> <div class="key-labels textright">
</span><span class="lines">@@ -790,13 +835,16 @@
</span><span class="cx"> <th scope="row"><?php _e('Connection Type') ?></th>
</span><span class="cx"> <td>
</span><span class="cx"> <fieldset><legend class="screen-reader-text"><span><?php _e('Connection Type') ?></span></legend>
</span><del>-<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; ?>
</del><ins>+<?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; ?>
</ins><span class="cx"> </fieldset>
</span><span class="cx"> </td>
</span><span class="cx"> </tr>
</span></span></pre>
</div>
</div>
</body>
</html>