request_filesystem_credentials( string $form_post, string $type = '', bool $error = false, string $context = '', array $extra_fields = null, bool $allow_relaxed_file_ownership = false )
Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
Description
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 ‘request_filesystem_credentials’ filter.
Parameters
- $form_post
-
(Required) The URL to post the form to.
- $type
-
(Optional) Chosen type of filesystem.
Default value: ''
- $error
-
(Optional) Whether the current request has failed to connect.
Default value: false
- $context
-
(Optional) Full path to the directory that is tested for being writable.
Default value: ''
- $extra_fields
-
(Optional) Extra
POST
fields to be checked for inclusion in the post.Default value: null
- $allow_relaxed_file_ownership
-
(Optional) Whether to allow Group/World writable.
Default value: false
Return
(bool) False on failure, true on success.
Source
File: wp-admin/includes/file.php
function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
global $pagenow;
/**
* Filters the filesystem credentials form output.
*
* Returning anything other than an empty string will effectively short-circuit
* output of the filesystem credentials form, returning that value instead.
*
* @since WP-2.5.0
* @since WP-4.6.0 The `$context` parameter default changed from `false` to an empty string.
*
* @param mixed $output Form output to return instead. Default empty.
* @param string $form_post The URL to post the form to.
* @param string $type Chosen type of filesystem.
* @param bool $error Whether the current request has failed to connect.
* Default false.
* @param string $context Full path to the directory that is tested for
* being writable.
* @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable.
* Default false.
* @param array $extra_fields Extra POST fields.
*/
$req_cred = apply_filters( 'request_filesystem_credentials', '', $form_post, $type, $error, $context, $extra_fields, $allow_relaxed_file_ownership );
if ( '' !== $req_cred )
return $req_cred;
if ( empty($type) ) {
$type = get_filesystem_method( array(), $context, $allow_relaxed_file_ownership );
}
if ( 'direct' == $type )
return true;
if ( is_null( $extra_fields ) )
$extra_fields = array( 'version', 'locale' );
$credentials = get_option('ftp_credentials', array( 'hostname' => '', 'username' => ''));
$submitted_form = wp_unslash( $_POST );
// Verify nonce, or unset submitted form field values on failure
if ( ! isset( $_POST['_fs_nonce'] ) || ! wp_verify_nonce( $_POST['_fs_nonce'], 'filesystem-credentials' ) ) {
unset(
$submitted_form['hostname'],
$submitted_form['username'],
$submitted_form['password'],
$submitted_form['public_key'],
$submitted_form['private_key'],
$submitted_form['connection_type']
);
}
// If defined, set it to that, Else, If POST'd, set it to that, If not, Set it to whatever it previously was(saved details in option)
$credentials['hostname'] = defined('FTP_HOST') ? FTP_HOST : (!empty($submitted_form['hostname']) ? $submitted_form['hostname'] : $credentials['hostname']);
$credentials['username'] = defined('FTP_USER') ? FTP_USER : (!empty($submitted_form['username']) ? $submitted_form['username'] : $credentials['username']);
$credentials['password'] = defined('FTP_PASS') ? FTP_PASS : (!empty($submitted_form['password']) ? $submitted_form['password'] : '');
// Check to see if we are setting the public/private keys for ssh
$credentials['public_key'] = defined('FTP_PUBKEY') ? FTP_PUBKEY : (!empty($submitted_form['public_key']) ? $submitted_form['public_key'] : '');
$credentials['private_key'] = defined('FTP_PRIKEY') ? FTP_PRIKEY : (!empty($submitted_form['private_key']) ? $submitted_form['private_key'] : '');
// 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'], ':') ) {
list( $credentials['hostname'], $credentials['port'] ) = explode(':', $credentials['hostname'], 2);
if ( ! is_numeric($credentials['port']) )
unset($credentials['port']);
} else {
unset($credentials['port']);
}
if ( ( defined( 'FTP_SSH' ) && FTP_SSH ) || ( defined( 'FS_METHOD' ) && 'ssh2' == FS_METHOD ) ) {
$credentials['connection_type'] = 'ssh';
} elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { //Only the FTP Extension understands SSL
$credentials['connection_type'] = 'ftps';
} elseif ( ! empty( $submitted_form['connection_type'] ) ) {
$credentials['connection_type'] = $submitted_form['connection_type'];
} elseif ( ! isset( $credentials['connection_type'] ) ) { //All else fails (And it's not defaulted to something else saved), Default to FTP
$credentials['connection_type'] = 'ftp';
}
if ( ! $error &&
(
( !empty($credentials['password']) && !empty($credentials['username']) && !empty($credentials['hostname']) ) ||
( 'ssh' == $credentials['connection_type'] && !empty($credentials['public_key']) && !empty($credentials['private_key']) )
) ) {
$stored_credentials = $credentials;
if ( !empty($stored_credentials['port']) ) //save port as part of hostname to simplify above code.
$stored_credentials['hostname'] .= ':' . $stored_credentials['port'];
unset($stored_credentials['password'], $stored_credentials['port'], $stored_credentials['private_key'], $stored_credentials['public_key']);
if ( ! wp_installing() ) {
update_option( 'ftp_credentials', $stored_credentials );
}
return $credentials;
}
$hostname = isset( $credentials['hostname'] ) ? $credentials['hostname'] : '';
$username = isset( $credentials['username'] ) ? $credentials['username'] : '';
$public_key = isset( $credentials['public_key'] ) ? $credentials['public_key'] : '';
$private_key = isset( $credentials['private_key'] ) ? $credentials['private_key'] : '';
$port = isset( $credentials['port'] ) ? $credentials['port'] : '';
$connection_type = isset( $credentials['connection_type'] ) ? $credentials['connection_type'] : '';
if ( $error ) {
$error_string = __('<strong>ERROR:</strong> There was an error connecting to the server, Please verify the settings are correct.');
if ( is_wp_error($error) )
$error_string = esc_html( $error->get_error_message() );
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');
/**
* Filters the connection types to output to the filesystem credentials form.
*
* @since WP-2.9.0
* @since WP-4.6.0 The `$context` parameter default changed from `false` to an empty string.
*
* @param array $types Types of connections.
* @param array $credentials Credentials to connect with.
* @param string $type Chosen filesystem method.
* @param object $error Error object.
* @param string $context Full path to the directory that is tested
* for being writable.
*/
$types = apply_filters( 'fs_ftp_connection_types', $types, $credentials, $type, $error, $context );
?>
<form action="<?php echo esc_url( $form_post ) ?>" method="post">
<div id="request-filesystem-credentials-form" class="request-filesystem-credentials-form">
<?php
// Print a H1 heading in the FTP credentials modal dialog, default is a H2.
$heading_tag = 'h2';
if ( 'plugins.php' === $pagenow || 'plugin-install.php' === $pagenow ) {
$heading_tag = 'h1';
}
echo "<$heading_tag id='request-filesystem-credentials-title'>" . __( 'Connection Information' ) . "</$heading_tag>";
?>
<p id="request-filesystem-credentials-desc"><?php
$label_user = __('Username');
$label_pass = __('Password');
_e('To perform the requested action, ClassicPress needs to access your web server.');
echo ' ';
if ( ( isset( $types['ftp'] ) || isset( $types['ftps'] ) ) ) {
if ( isset( $types['ssh'] ) ) {
_e('Please enter your FTP or SSH credentials to proceed.');
$label_user = __('FTP/SSH Username');
$label_pass = __('FTP/SSH Password');
} else {
_e('Please enter your FTP credentials to proceed.');
$label_user = __('FTP Username');
$label_pass = __('FTP Password');
}
echo ' ';
}
_e('If you do not remember your credentials, you should contact your web host.');
?></p>
<label for="hostname">
<span class="field-title"><?php _e( 'Hostname' ) ?></span>
<input name="hostname" type="text" id="hostname" aria-describedby="request-filesystem-credentials-desc" class="code" placeholder="<?php esc_attr_e( 'example: www.wordpress.org' ) ?>" value="<?php echo esc_attr($hostname); if ( !empty($port) ) echo ":$port"; ?>"<?php disabled( defined('FTP_HOST') ); ?> />
</label>
<div class="ftp-username">
<label for="username">
<span class="field-title"><?php echo $label_user; ?></span>
<input name="username" type="text" id="username" value="<?php echo esc_attr($username) ?>"<?php disabled( defined('FTP_USER') ); ?> />
</label>
</div>
<div class="ftp-password">
<label for="password">
<span class="field-title"><?php echo $label_pass; ?></span>
<input name="password" type="password" id="password" value="<?php if ( defined('FTP_PASS') ) echo '*****'; ?>"<?php disabled( defined('FTP_PASS') ); ?> />
<em><?php if ( ! defined('FTP_PASS') ) _e( 'This password will not be stored on the server.' ); ?></em>
</label>
</div>
<fieldset>
<legend><?php _e( 'Connection Type' ); ?></legend>
<?php
$disabled = disabled( ( defined( 'FTP_SSL' ) && FTP_SSL ) || ( defined( 'FTP_SSH' ) && FTP_SSH ), true, false );
foreach ( $types as $name => $text ) : ?>
<label for="<?php echo esc_attr( $name ) ?>">
<input type="radio" name="connection_type" id="<?php echo esc_attr( $name ) ?>" value="<?php echo esc_attr( $name ) ?>"<?php checked( $name, $connection_type ); echo $disabled; ?> />
<?php echo $text; ?>
</label>
<?php
endforeach;
?>
</fieldset>
<?php
if ( isset( $types['ssh'] ) ) {
$hidden_class = '';
if ( 'ssh' != $connection_type || empty( $connection_type ) ) {
$hidden_class = ' class="hidden"';
}
?>
<fieldset id="ssh-keys"<?php echo $hidden_class; ?>>
<legend><?php _e( 'Authentication Keys' ); ?></legend>
<label for="public_key">
<span class="field-title"><?php _e('Public Key:') ?></span>
<input name="public_key" type="text" id="public_key" aria-describedby="auth-keys-desc" value="<?php echo esc_attr($public_key) ?>"<?php disabled( defined('FTP_PUBKEY') ); ?> />
</label>
<label for="private_key">
<span class="field-title"><?php _e('Private Key:') ?></span>
<input name="private_key" type="text" id="private_key" value="<?php echo esc_attr($private_key) ?>"<?php disabled( defined('FTP_PRIKEY') ); ?> />
</label>
<p id="auth-keys-desc"><?php _e( 'Enter the location on the server where the public and private keys are located. If a passphrase is needed, enter that in the password field above.' ) ?></p>
</fieldset>
<?php
}
foreach ( (array) $extra_fields as $field ) {
if ( isset( $submitted_form[ $field ] ) )
echo '<input type="hidden" name="' . esc_attr( $field ) . '" value="' . esc_attr( $submitted_form[ $field ] ) . '" />';
}
?>
<p class="request-filesystem-credentials-action-buttons">
<?php wp_nonce_field( 'filesystem-credentials', '_fs_nonce', false, true ); ?>
<button class="button cancel-button" data-js-action="close" type="button"><?php _e( 'Cancel' ); ?></button>
<?php submit_button( __( 'Proceed' ), '', 'upgrade', false ); ?>
</p>
</div>
</form>
<?php
return false;
}
Changelog
Version | Description |
---|---|
WP-4.6.0 | The $context parameter default changed from false to an empty string. |
WP-2.5.0 | Introduced. |