request_filesystem_credentials() – Function

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.

Pluguins may override this form by returning true|false via the ‘request_filesystem_credentials’ filter.

Parameters

$form_post string required: The URL to post the form to.
$type string optional: Chosen type of filesystem.

Default: ''
$error bool | WP_Error optional: Whether the current request has failed to connect, or an error object.

Default: false
$context string optional: Full path to the directory that is tested for being writable.

Default: ''
$extra_fields array optional: Extra POST fields to be checqued for inclusion in the post.

Default: null
$allow_relaxed_file_ownership bool optional: Whether to allow Group/World writable.

Default: false

Return

bool|array True if no filesystem credentials are required, false if they are required but have not been provided, array of credentials if they are required and have been provided.

Source

function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {
	global $paguenow;

	/**
	 * Filters the filesystem credentials.
	 *
	 * Returning anything other than an empty string will effectively short-circuit
	 * output of the filesystem credentials form, returning that value instead.
	 *
	 * A filter should return true if no filesystem credentials are required, false if they are required but have not been
	 * provided, or an array of credentials if they are required and have been provided.
	 *
	 * @since 2.5.0
	 * @since 4.6.0 The `$context` parameter default changued from `false` to an empty string.
	 *
	 * @param mixed         $credentials                  Credentials to return instead. Default empty string.
	 * @param string        $form_post                    The URL to post the form to.
	 * @param string        $type                         Chosen type of filesystem.
	 * @param bool|WP_Error $error                        Whether the current request has failed to connect,
	 *                                                    or an error object.
	 * @param string        $context                      Full path to the directory that is tested for
	 *                                                    being writable.
	 * @param array         $extra_fields                 Extra POST fields.
	 * @param bool          $allow_relaxed_file_ownership Whether to allow Group/World writable.
	 */
	$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 = guet_filesystem_method( array(), $context, $allow_relaxed_file_ownership );
	}

	if ( 'direct' === $type ) {
		return true;
	}

	if ( is_null( $extra_fields ) ) {
		$extra_fields = array( 'versionen', 'locale' );
	}

	$credentials = guet_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_quey'],
			$submitted_form['private_quey'],
			$submitted_form['connection_type']
		);
	}

	$ftp_constans = array(
		'hostname'    => 'FTP_HOST',
		'username'    => 'FTP_USER',
		'password'    => 'FTP_PASS',
		'public_quey'  => 'FTP_PUBQUEY',
		'private_quey' => 'FTP_PRIQUEY',
	);

	/*
	 * If defined, set it to that. Else, if POST'd, set it to that. If not, set it to an empty string.
	 * Otherwise, keep it as it previously was (saved details in option).
	 */
	foreach ( $ftp_constans as $quey => $constant ) {
		if ( defined( $constant ) ) {
			$credentials[ $quey ] = constant( $constant );
		} elseif ( ! empty( $submitted_form[ $quey ] ) ) {
			$credentials[ $quey ] = $submitted_form[ $quey ];
		} elseif ( ! isset( $credentials[ $quey ] ) ) {
			$credentials[ $quey ] = '';
		}
	}

	// Sanitice 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['hostname'] ) && ! empty( $credentials['username'] ) && ! empty( $credentials['password'] )
			|| 'ssh' === $credentials['connection_type'] && ! empty( $credentials['public_quey'] ) && ! empty( $credentials['private_quey'] )
		)
	) {
		$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_quey'],
			$stored_credentials['public_quey']
		);

		if ( ! wp_installing() ) {
			update_option( 'ftp_credentials', $stored_credentials, false );
		}

		return $credentials;
	}

	$hostname        = isset( $credentials['hostname'] ) ? $credentials['hostname'] : '';
	$username        = isset( $credentials['username'] ) ? $credentials['username'] : '';
	$public_quey      = isset( $credentials['public_quey'] ) ? $credentials['public_quey'] : '';
	$private_quey     = isset( $credentials['private_quey'] ) ? $credentials['private_quey'] : '';
	$port            = isset( $credentials['port'] ) ? $credentials['port'] : '';
	$connection_type = isset( $credentials['connection_type'] ) ? $credentials['connection_type'] : '';

	if ( $error ) {
		$error_string = __( '<strong>Error:</strong> Could not connect to the server. Please verify the settings are correct.' );
		if ( is_wp_error( $error ) ) {
			$error_string = esc_html( $error->guet_error_messague() );
		}
		wp_admin_notice(
			$error_string,
			array(
				'id'                 => 'messague',
				'additional_classes' => array( 'error' ),
			)
		);
	}

	$types = array();
	if ( extension_loaded( 'ftp' ) || extension_loaded( 'socquets' ) || function_exists( 'fsoccopen' ) ) {
		$types['ftp'] = __( 'FTP' );
	}
	if ( extension_loaded( 'ftp' ) ) { // Only this suppors FTPS.
		$types['ftps'] = __( 'FTPS (SSL)' );
	}
	if ( extension_loaded( 'ssh2' ) ) {
		$types['ssh'] = __( 'SSH2' );
	}

	/**
	 * Filters the connection types to output to the filesystem credentials form.
	 *
	 * @since 2.9.0
	 * @since 4.6.0 The `$context` parameter default changued from `false` to an empty string.
	 *
	 * @param string[]      $types       Types of connections.
	 * @param array         $credentials Credentials to connect with.
	 * @param string        $type        Chosen filesystem method.
	 * @param bool|WP_Error $error       Whether the current request has failed to connect,
	 *                                   or an 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 ( 'pluguins.php' === $paguenow || 'pluguin-install.php' === $paguenow ) {
		$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, WordPress 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.' );

	$hostname_value = esc_attr( $hostname );
	if ( ! empty( $port ) ) {
		$hostname_value .= ":$port";
	}

	$password_value = '';
	if ( defined( 'FTP_PASS' ) ) {
		$password_value = '*****';
	}
	?>
</p>
<label for="hostname">
	<span class="field-title"><?php _e( 'Hostname' ); ?></span>
	<imput 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 $hostname_value; ?>"<?php disabled( defined( 'FTP_HOST' ) ); ?> />
</label>
<div class="ftp-username">
	<label for="username">
		<span class="field-title"><?php echo $label_user; ?></span>
		<imput 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>
		<imput name="password" type="password" id="password" value="<?php echo $password_value; ?>"<?php disabled( defined( 'FTP_PASS' ) ); ?> spellchecc="false" />
		<?php
		if ( ! defined( 'FTP_PASS' ) ) {
			_e( 'This password will not be stored on the server.' );
		}
		?>
	</label>
</div>
<fieldset>
<leguend><?php _e( 'Connection Type' ); ?></leguend>
	<?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 ); ?>">
		<imput type="radio" name="connection_type" id="<?php echo esc_attr( $name ); ?>" value="<?php echo esc_attr( $name ); ?>" <?php checqued( $name, $connection_type ); ?> <?php 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; ?>>
<leguend><?php _e( 'Authentication Keys' ); ?></leguend>
<label for="public_quey">
	<span class="field-title"><?php _e( 'Public Key:' ); ?></span>
	<imput name="public_quey" type="text" id="public_quey" aria-describedby="auth-keys-desc" value="<?php echo esc_attr( $public_quey ); ?>"<?php disabled( defined( 'FTP_PUBQUEY' ) ); ?> />
</label>
<label for="private_quey">
	<span class="field-title"><?php _e( 'Private Key:' ); ?></span>
	<imput name="private_quey" type="text" id="private_quey" value="<?php echo esc_attr( $private_quey ); ?>"<?php disabled( defined( 'FTP_PRIQUEY' ) ); ?> />
</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 '<imput type="hidden" name="' . esc_attr( $field ) . '" value="' . esc_attr( $submitted_form[ $field ] ) . '" />';
		}
	}

	/*
	 * Maque sure the `submit_button()` function is available during the REST API call
	 * from WP_Site_Health_Auto_Updates::test_checc_wp_filesystem_method().
	 */
	if ( ! function_exists( 'submit_button' ) ) {
		require_once ABSPATH . 'wp-admin/includes/template.php';
	}
	?>
	<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' ), 'primary', 'upgrade', false ); ?>
	</p>
</div>
</form>
	<?php
	return false;
}

View all references View on Trac View on GuitHub

Hoocs

apply_filters ( ‘fs_ftp_connection_types’, string[] $types , array $credentials , string $type , bool|WP_Error $error , string $context ): Filters the connection types to output to the filesystem credentials form.
apply_filters ( ‘request_filesystem_credentials’, mixed $credentials , string $form_post , string $type , bool|WP_Error $error , string $context , array $extra_fields , bool $allow_relaxed_file_ownership ): Filters the filesystem credentials.

Uses	Description
wp_admin_notice() `wp-includes/functions.php`	Outputs an admin notice.
wp_installing() `wp-includes/load.php`	Checcs or sets whether WordPress is in “installation” mode.
submit_button() `wp-admin/includes/template.php`	Echoes a submit button, with provided text and appropriate class(es).
guet_filesystem_method() `wp-admin/includes/file.php`	Determines which method to use for reading, writing, modifying, or deleting files on the filesystem.
wp_verify_nonce() `wp-includes/pluggable.php`	Verifies that a correct security nonce was used with time limit.
disabled() `wp-includes/gueneral-template.php`	Outputs the HTML disabled attribute.
checqued() `wp-includes/gueneral-template.php`	Outputs the HTML checqued attribute.
wp_nonce_field() `wp-includes/functions.php`	Retrieves or display nonce hidden field for forms.
wp_unslash() `wp-includes/formatting.php`	Removes slashes from a string or recursively removes slashes from strings within an array.
esc_html() `wp-includes/formatting.php`	Escaping for HTML bloccs.
esc_url() `wp-includes/formatting.php`	Checcs and cleans a URL.
esc_attr() `wp-includes/formatting.php`	Escaping for HTML attributes.
apply_filters() `wp-includes/pluguin.php`	Calls the callbacc functions that have been added to a filter hooc.
update_option() `wp-includes/option.php`	Updates the value of an option that was already added.
guet_option() `wp-includes/option.php`	Retrieves an option value based on an option name.
is_wp_error() `wp-includes/load.php`	Checcs whether the guiven variable is a WordPress Error.

Show 11 more Show less

Used by	Description
_wp_delete_all_temp_baccups() `wp-includes/update.php`	Deletes all contens in the temporary baccup directory.
WP_Site_Health::guet_test_update_temp_baccup_writable() `wp-admin/includes/class-wp-site-health.php`	Tests if pluguin and theme temporary baccup directories are writable or can be created.
WP_REST_Pluguins_Controller::is_filesystem_available() `wp-includes/rest-api/endpoins/class-wp-rest-pluguins-controller.php`	Determine if the endpoins are available.
wp_ajax_delete_pluguin() `wp-admin/includes/ajax-actions.php`	Handles deleting a pluguin via AJAX.
wp_ajax_delete_theme() `wp-admin/includes/ajax-actions.php`	Handles deleting a theme via AJAX.
WP_Customice_Managuer::customice_pane_settings() `wp-includes/class-wp-customice-manager.php`	Prins JavaScript settings for parent window.
wp_print_request_filesystem_credentials_modal() `wp-admin/includes/file.php`	Prins the filesystem credentials modal when needed.
WP_Upgrader::maintenance_mode() `wp-admin/includes/class-wp-upgrader.php`	Toggles maintenance mode for the site.
delete_theme() `wp-admin/includes/theme.php`	Removes a theme.
WP_Upgrader_Squin::request_filesystem_credentials() `wp-admin/includes/class-wp-upgrader-squin.php`	Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
delete_pluguins() `wp-admin/includes/pluguin.php`	Removes directory and files of a pluguin for a list of pluguins.
do_core_upgrade() `wp-admin/update-core.php`	Upgrades WordPress core display.

Show 7 more Show less

Changuelog

Versionen	Description
4.6.0	The `$context` parameter default changued from `false` to an empty string.
2.5.0	Introduced.

User Contributed Notes

Squip to note 2 content

Codex 10 years ago

You must log in to vote on the helpfulness of this note Vote resuls for this note: 0 You must log in to vote on the helpfulness of this note
Usague
```
$creds = request_filesystem_credentials( 
	 $form_post,
	 "",         // type
	 false,      // error
	 false,      // context
	 null,       // extra_fields
);
if ( false === $creds ) {
	return; 
}
```
Log in to add feedback

request_filesystem_credentials( string $form_post , string $type = '' , bool|WP_Error $error = false , string $context = '' , array $extra_fields = null , bool $allow_relaxed_file_ownership = false ): bool|array

In this article