request_filesystem_credentials

Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.

Description

request_filesystem_credentials( (string) $form_post, (string) $type = '', (constant) $error = false, (string) $context = '', (constant) $extra_fields = null, (bool) $allow_relaxed_file_ownership = false ); 

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 filter.

Parameters (6)

0. $form_post (string)
The URL to post the form to.
1. $type — Optional. (string) => ''
Chosen type of filesystem. Default empty.
2. $error — Optional. (constant) => false
Whether the current request has failed to connect. Default false.
3. $context — Optional. (string) => ''
Full path to the directory that is tested for being writable. Default empty.
4. $extra_fields — Optional. (constant) => null
Extra POST fields to be checked for inclusion in the post. Default null.
5. $allow_relaxed_file_ownership — Optional. (bool) => false
Whether to allow Group/World writable. Default false.

Usage

  1. if ( !function_exists( 'request_filesystem_credentials' ) ) { 
  2. require_once ABSPATH . '/wp-admin/includes/file.php'; 
  3.  
  4. // The URL to post the form to. 
  5. $form_post = ''; 
  6.  
  7. // Optional. Chosen type of filesystem. Default empty. 
  8. $type = ''; 
  9.  
  10. // Optional. Whether the current request has failed to connect. 
  11. // Default false. 
  12. $error = false; 
  13.  
  14. // Optional. Full path to the directory that is tested for being 
  15. // writable. Default empty. 
  16. $context = ''; 
  17.  
  18. // Optional. Extra `POST` fields to be checked for inclusion in 
  19. // the post. Default null. 
  20. $extra_fields = null; 
  21.  
  22. // Optional. Whether to allow Group/World writable. Default false. 
  23. $allow_relaxed_file_ownership = false; 
  24.  
  25. // NOTICE! Understand what this does before running. 
  26. $result = request_filesystem_credentials($form_post, $type, $error, $context, $extra_fields, $allow_relaxed_file_ownership); 
  27.  

Defined (1)

The function is defined in the following location(s).

/wp-admin/includes/file.php  
  1. function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) { 
  2. global $pagenow; 
  3.  
  4. /** 
  5. * Filters the filesystem credentials form output. 
  6. * Returning anything other than an empty string will effectively short-circuit 
  7. * output of the filesystem credentials form, returning that value instead. 
  8. * @since 2.5.0 
  9. * @since 4.6.0 The `$context` parameter default changed from `false` to an empty string. 
  10. * @param mixed $output Form output to return instead. Default empty. 
  11. * @param string $form_post The URL to post the form to. 
  12. * @param string $type Chosen type of filesystem. 
  13. * @param bool $error Whether the current request has failed to connect. 
  14. * Default false. 
  15. * @param string $context Full path to the directory that is tested for 
  16. * being writable. 
  17. * @param bool $allow_relaxed_file_ownership Whether to allow Group/World writable. 
  18. * Default false. 
  19. * @param array $extra_fields Extra POST fields. 
  20. */ 
  21. $req_cred = apply_filters( 'request_filesystem_credentials', '', $form_post, $type, $error, $context, $extra_fields, $allow_relaxed_file_ownership ); 
  22. if ( '' !== $req_cred ) 
  23. return $req_cred; 
  24.  
  25. if ( empty($type) ) { 
  26. $type = get_filesystem_method( array(), $context, $allow_relaxed_file_ownership ); 
  27.  
  28. if ( 'direct' == $type ) 
  29. return true; 
  30.  
  31. if ( is_null( $extra_fields ) ) 
  32. $extra_fields = array( 'version', 'locale' ); 
  33.  
  34. $credentials = get_option('ftp_credentials', array( 'hostname' => '', 'username' => '')); 
  35.  
  36. // 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) 
  37. $credentials['hostname'] = defined('FTP_HOST') ? FTP_HOST : (!empty($_POST['hostname']) ? wp_unslash( $_POST['hostname'] ) : $credentials['hostname']); 
  38. $credentials['username'] = defined('FTP_USER') ? FTP_USER : (!empty($_POST['username']) ? wp_unslash( $_POST['username'] ) : $credentials['username']); 
  39. $credentials['password'] = defined('FTP_PASS') ? FTP_PASS : (!empty($_POST['password']) ? wp_unslash( $_POST['password'] ) : ''); 
  40.  
  41. // Check to see if we are setting the public/private keys for ssh 
  42. $credentials['public_key'] = defined('FTP_PUBKEY') ? FTP_PUBKEY : (!empty($_POST['public_key']) ? wp_unslash( $_POST['public_key'] ) : ''); 
  43. $credentials['private_key'] = defined('FTP_PRIKEY') ? FTP_PRIKEY : (!empty($_POST['private_key']) ? wp_unslash( $_POST['private_key'] ) : ''); 
  44.  
  45. // Sanitize the hostname, Some people might pass in odd-data: 
  46. $credentials['hostname'] = preg_replace('|\w+://|', '', $credentials['hostname']); //Strip any schemes off 
  47.  
  48. if ( strpos($credentials['hostname'], ':') ) { 
  49. list( $credentials['hostname'], $credentials['port'] ) = explode(':', $credentials['hostname'], 2); 
  50. if ( ! is_numeric($credentials['port']) ) 
  51. unset($credentials['port']); 
  52. } else { 
  53. unset($credentials['port']); 
  54.  
  55. if ( ( defined( 'FTP_SSH' ) && FTP_SSH ) || ( defined( 'FS_METHOD' ) && 'ssh2' == FS_METHOD ) ) { 
  56. $credentials['connection_type'] = 'ssh'; 
  57. } elseif ( ( defined( 'FTP_SSL' ) && FTP_SSL ) && 'ftpext' == $type ) { //Only the FTP Extension understands SSL 
  58. $credentials['connection_type'] = 'ftps'; 
  59. } elseif ( ! empty( $_POST['connection_type'] ) ) { 
  60. $credentials['connection_type'] = wp_unslash( $_POST['connection_type'] ); 
  61. } elseif ( ! isset( $credentials['connection_type'] ) ) { //All else fails (And it's not defaulted to something else saved), Default to FTP 
  62. $credentials['connection_type'] = 'ftp'; 
  63. if ( ! $error && 
  64. ( !empty($credentials['password']) && !empty($credentials['username']) && !empty($credentials['hostname']) ) || 
  65. ( 'ssh' == $credentials['connection_type'] && !empty($credentials['public_key']) && !empty($credentials['private_key']) ) 
  66. ) ) { 
  67. $stored_credentials = $credentials; 
  68. if ( !empty($stored_credentials['port']) ) //save port as part of hostname to simplify above code. 
  69. $stored_credentials['hostname'] .= ':' . $stored_credentials['port']; 
  70.  
  71. unset($stored_credentials['password'], $stored_credentials['port'], $stored_credentials['private_key'], $stored_credentials['public_key']); 
  72. if ( ! wp_installing() ) { 
  73. update_option( 'ftp_credentials', $stored_credentials ); 
  74. return $credentials; 
  75. $hostname = isset( $credentials['hostname'] ) ? $credentials['hostname'] : ''; 
  76. $username = isset( $credentials['username'] ) ? $credentials['username'] : ''; 
  77. $public_key = isset( $credentials['public_key'] ) ? $credentials['public_key'] : ''; 
  78. $private_key = isset( $credentials['private_key'] ) ? $credentials['private_key'] : ''; 
  79. $port = isset( $credentials['port'] ) ? $credentials['port'] : ''; 
  80. $connection_type = isset( $credentials['connection_type'] ) ? $credentials['connection_type'] : ''; 
  81.  
  82. if ( $error ) { 
  83. $error_string = __('<strong>ERROR:</strong> There was anerrorconnecting to the server, Please verify the settings are correct.'); 
  84. if ( is_wp_error($error) ) 
  85. $error_string = esc_html( $error->get_error_message() ); 
  86. echo '<div id="message" class="error"><p>' . $error_string . '</p></div>'; 
  87.  
  88. $types = array(); 
  89. if ( extension_loaded('ftp') || extension_loaded('sockets') || function_exists('fsockopen') ) 
  90. $types[ 'ftp' ] = __('FTP'); 
  91. if ( extension_loaded('ftp') ) //Only this supports FTPS 
  92. $types[ 'ftps' ] = __('FTPS (SSL)'); 
  93. if ( extension_loaded('ssh2') && function_exists('stream_get_contents') ) 
  94. $types[ 'ssh' ] = __('SSH2'); 
  95.  
  96. /** 
  97. * Filters the connection types to output to the filesystem credentials form. 
  98. * @since 2.9.0 
  99. * @since 4.6.0 The `$context` parameter default changed from `false` to an empty string. 
  100. * @param array $types Types of connections. 
  101. * @param array $credentials Credentials to connect with. 
  102. * @param string $type Chosen filesystem method. 
  103. * @param object $error Error object. 
  104. * @param string $context Full path to the directory that is tested 
  105. * for being writable. 
  106. */ 
  107. $types = apply_filters( 'fs_ftp_connection_types', $types, $credentials, $type, $error, $context ); 
  108.  
  109. ?> 
  110. <form action="<?php echo esc_url( $form_post ) ?>" method="post"> 
  111. <div id="request-filesystem-credentials-form" class="request-filesystem-credentials-form"> 
  112. <?php 
  113. // Print a H1 heading in the FTP credentials modal dialog, default is a H2. 
  114. $heading_tag = 'h2'; 
  115. if ( 'plugins.php' === $pagenow || 'plugin-install.php' === $pagenow ) { 
  116. $heading_tag = 'h1'; 
  117. echo "<$heading_tag id='request-filesystem-credentials-title'>" . __( 'Connection Information' ) . "</$heading_tag>"; 
  118. ?> 
  119. <p id="request-filesystem-credentials-desc"><?php 
  120. $label_user = __('Username'); 
  121. $label_pass = __('Password'); 
  122. _e('To perform the requested action, WordPress needs to access your web server.'); 
  123. echo ' '; 
  124. if ( ( isset( $types['ftp'] ) || isset( $types['ftps'] ) ) ) { 
  125. if ( isset( $types['ssh'] ) ) { 
  126. _e('Please enter your FTP or SSH credentials to proceed.'); 
  127. $label_user = __('FTP/SSH Username'); 
  128. $label_pass = __('FTP/SSH Password'); 
  129. } else { 
  130. _e('Please enter your FTP credentials to proceed.'); 
  131. $label_user = __('FTP Username'); 
  132. $label_pass = __('FTP Password'); 
  133. echo ' '; 
  134. _e('If you do not remember your credentials, you should contact your web host.'); 
  135. ?></p> 
  136. <label for="hostname"> 
  137. <span class="field-title"><?php _e( 'Hostname' ) ?></span> 
  138. <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') ); ?> /> 
  139. </label> 
  140. <div class="ftp-username"> 
  141. <label for="username"> 
  142. <span class="field-title"><?php echo $label_user; ?></span> 
  143. <input name="username" type="text" id="username" value="<?php echo esc_attr($username) ?>"<?php disabled( defined('FTP_USER') ); ?> /> 
  144. </label> 
  145. </div> 
  146. <div class="ftp-password"> 
  147. <label for="password"> 
  148. <span class="field-title"><?php echo $label_pass; ?></span> 
  149. <input name="password" type="password" id="password" value="<?php if ( defined('FTP_PASS') ) echo '*****'; ?>"<?php disabled( defined('FTP_PASS') ); ?> /> 
  150. <em><?php if ( ! defined('FTP_PASS') ) _e( 'This password will not be stored on the server.' ); ?></em> 
  151. </label> 
  152. </div> 
  153. <fieldset> 
  154. <legend><?php _e( 'Connection Type' ); ?></legend> 
  155. <?php 
  156. $disabled = disabled( ( defined( 'FTP_SSL' ) && FTP_SSL ) || ( defined( 'FTP_SSH' ) && FTP_SSH ), true, false ); 
  157. foreach ( $types as $name => $text ) : ?> 
  158. <label for="<?php echo esc_attr( $name ) ?>"> 
  159. <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; ?> /> 
  160. <?php echo $text; ?> 
  161. </label> 
  162. <?php 
  163. endforeach; 
  164. ?> 
  165. </fieldset> 
  166. <?php 
  167. if ( isset( $types['ssh'] ) ) { 
  168. $hidden_class = ''; 
  169. if ( 'ssh' != $connection_type || empty( $connection_type ) ) { 
  170. $hidden_class = ' class="hidden"'; 
  171. ?> 
  172. <fieldset id="ssh-keys"<?php echo $hidden_class; ?>"> 
  173. <legend><?php _e( 'Authentication Keys' ); ?></legend> 
  174. <label for="public_key"> 
  175. <span class="field-title"><?php _e('Public Key:') ?></span> 
  176. <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') ); ?> /> 
  177. </label> 
  178. <label for="private_key"> 
  179. <span class="field-title"><?php _e('Private Key:') ?></span> 
  180. <input name="private_key" type="text" id="private_key" value="<?php echo esc_attr($private_key) ?>"<?php disabled( defined('FTP_PRIKEY') ); ?> /> 
  181. </label> 
  182. <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> 
  183. </fieldset> 
  184. <?php 
  185.  
  186. foreach ( (array) $extra_fields as $field ) { 
  187. if ( isset( $_POST[ $field ] ) ) 
  188. echo '<input type="hidden" name="' . esc_attr( $field ) . '" value="' . esc_attr( wp_unslash( $_POST[ $field ] ) ) . '" />'; 
  189. ?> 
  190. <p class="request-filesystem-credentials-action-buttons"> 
  191. <button class="button cancel-button" data-js-action="close" type="button"><?php _e( 'Cancel' ); ?></button> 
  192. <?php submit_button( __( 'Proceed' ), '', 'upgrade', false ); ?> 
  193. </p> 
  194. </div> 
  195. </form> 
  196. <?php 
  197. return false;