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

Description

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$form_poststring

The URL to post the form to.

$typestringoptional

Chosen type of filesystem. Default empty.Default: ''

$errorbool|WP_Erroroptional

Whether the current request has failed to connect, or an error object. Default false.Default: false

$contextstringoptional

Full path to the directory that is tested for being writable. Default empty.Default: ''

$extra_fieldsarrayoptional

Extra POST fields to be checked for inclusion in the post. Default null.Default: null

$allow_relaxed_file_ownershipbooloptional

Whether to allow Group/World writable.
Default false.Default: false

Return value

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.

Performance profile

How much work a call to request_filesystem_credentials() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reads stored settings via get_option(), cached per request but not free on a cold cache.

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

267–323

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 533.

Plugin surface

2 hooks

Third-party callbacks on 'request_filesystem_credentials', 'fs_ftp_connection_types' run inside this call, and their cost is not bounded by anything here.

Called by

12

12 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksapply_filters()called directly
• optionoption read or writeget_option()called directly
• cacheobject cachewp_cache_get()one call below request_filesystem_credentials()
• serializeserialisationmaybe_unserialize()one call below request_filesystem_credentials()

Further down the call graph this can also reach transient and query. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 4 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost request_filesystem_credentials() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 2

2 hooks fire while request_filesystem_credentials() runs, in this order:

1. 1
   apply_filters( request_filesystem_credentials )filterline 2389 (+25 into the body)

   Filters the filesystem credentials.

2. 2
   apply_filters( fs_ftp_connection_types )filterline 2543 (+179 into the body)

   Filters the connection types to output to the filesystem credentials form.

Uses · 19

• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_filesystem_method()Determines which method to use for reading, writing, modifying, or deleting files on the filesystem.
• get_option()Retrieves an option value based on an option name.
• wp_unslash()Removes slashes from a string or recursively removes slashes from strings within an array.
• wp_verify_nonce()Verifies that a correct security nonce was used with time limit.
• wp_installing()Checks or sets whether WordPress is in "installation" mode.
• update_option()Updates the value of an option that was already added.
• __()Retrieves the translation of $text.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• esc_html()Escaping for HTML blocks.
• wp_admin_notice()Outputs an admin notice.
• esc_url()Checks and cleans a URL.

Used by · 12

• WP_Customize_Manager::customize_pane_settings()Prints JavaScript settings for parent window.
• WP_REST_Plugins_Controller::is_filesystem_available()Determine if the endpoints are available.
• WP_Site_Health::get_test_update_temp_backup_writable()Tests if plugin and theme temporary backup directories are writable or can be created.
• WP_Upgrader::maintenance_mode()Toggles maintenance mode for the site.
• WP_Upgrader_Skin::request_filesystem_credentials()Displays a form to the user to request for their FTP/SSH details in order to connect to the filesystem.
• _wp_delete_all_temp_backups()Deletes all contents in the temporary backup directory.
• delete_plugins()Removes directory and files of a plugin for a list of plugins.
• delete_theme()Removes a theme.
• do_core_upgrade()Upgrades WordPress core display.
• wp_ajax_delete_plugin()Handles deleting a plugin via AJAX.
• wp_ajax_delete_theme()Handles deleting a theme via AJAX.
• wp_print_request_filesystem_credentials_modal()Prints the filesystem credentials modal when needed.

Source code

View on Trac ↗View on GitHub ↗

2364function request_filesystem_credentials( $form_post, $type = '', $error = false, $context = '', $extra_fields = null, $allow_relaxed_file_ownership = false ) {2365	global $pagenow;2366 2367	/**2368	 * Filters the filesystem credentials.2369	 *2370	 * Returning anything other than an empty string will effectively short-circuit2371	 * output of the filesystem credentials form, returning that value instead.2372	 *2373	 * A filter should return true if no filesystem credentials are required, false if they are required but have not been2374	 * provided, or an array of credentials if they are required and have been provided.2375	 *2376	 * @since 2.5.02377	 * @since 4.6.0 The `$context` parameter default changed from `false` to an empty string.2378	 *2379	 * @param mixed         $credentials                  Credentials to return instead. Default empty string.2380	 * @param string        $form_post                    The URL to post the form to.2381	 * @param string        $type                         Chosen type of filesystem.2382	 * @param bool|WP_Error $error                        Whether the current request has failed to connect,2383	 *                                                    or an error object.2384	 * @param string        $context                      Full path to the directory that is tested for2385	 *                                                    being writable.2386	 * @param array         $extra_fields                 Extra POST fields.2387	 * @param bool          $allow_relaxed_file_ownership Whether to allow Group/World writable.2388	 */2389	$req_cred = apply_filters( 'request_filesystem_credentials', '', $form_post, $type, $error, $context, $extra_fields, $allow_relaxed_file_ownership );2390 2391	if ( '' !== $req_cred ) {2392		return $req_cred;2393	}2394 2395	if ( empty( $type ) ) {2396		$type = get_filesystem_method( array(), $context, $allow_relaxed_file_ownership );2397	}2398 2399	if ( 'direct' === $type ) {2400		return true;2401	}2402 2403	if ( is_null( $extra_fields ) ) {2404		$extra_fields = array( 'version', 'locale' );2405	}2406 2407	$credentials = get_option(2408		'ftp_credentials',2409		array(2410			'hostname' => '',2411			'username' => '',2412		)2413	);2414 2415	$submitted_form = wp_unslash( $_POST );2416 2417	// Verify nonce, or unset submitted form field values on failure.2418	if ( ! isset( $_POST['_fs_nonce'] ) || ! wp_verify_nonce( $_POST['_fs_nonce'], 'filesystem-credentials' ) ) {2419		unset(2420			$submitted_form['hostname'],2421			$submitted_form['username'],2422			$submitted_form['password'],2423			$submitted_form['public_key'],2424			$submitted_form['private_key'],2425			$submitted_form['connection_type']2426		);2427	}2428 2429	$ftp_constants = array(2430		'hostname'    => 'FTP_HOST',2431		'username'    => 'FTP_USER',2432		'password'    => 'FTP_PASS',2433		'public_key'  => 'FTP_PUBKEY',2434		'private_key' => 'FTP_PRIKEY',2435	);2436 2437	/*2438	 * If defined, set it to that. Else, if POST'd, set it to that. If not, set it to an empty string.2439	 * Otherwise, keep it as it previously was (saved details in option).2440	 */2441	foreach ( $ftp_constants as $key => $constant ) {2442		if ( defined( $constant ) ) {2443			$credentials[ $key ] = constant( $constant );

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-admin/includes/file.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.