download_url( string $url, int $timeout = 300, bool $signature_verification = false ): string|WP_Error

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

$urlstring

The URL of the file to download.

$timeoutintoptional

The timeout for the request to download the file.
Default 300 seconds.Default: 300

$signature_verificationbooloptional

Whether to perform Signature Verification.
Default false.Default: false

Return value

string|WP_Error

Filename on success, WP_Error on failure.

Performance profile

How much work a call to download_url() 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

Expensive

Reaches an outbound HTTP request via wp_safe_remote_get().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

25–184

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

Plugin surface

4 hooks

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

Called by

2

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

What it touches

• httpoutbound HTTP requestwp_safe_remote_get()called directly
• hookthird-party callbacksapply_filters()called directly
• filesystemfilesystem accessunlink()called directly

Further down the call graph this can also reach transient, option, cache, serialize 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 · 1005 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost download_url() 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 · 4

4 hooks fire while download_url() runs, in this order:

1. 1
   apply_filters( download_url_error_max_body_size )filterline 1206 (+51 into the body)

   Filters the maximum error response body size in `download_url()`.

2. 2
   apply_filters( wp_signature_hosts )filterline 1264 (+109 into the body)

   Filters the list of hosts which should have Signature Verification attempted on.

3. 3
   apply_filters( wp_signature_url )filterline 1293 (+138 into the body)

   Filters the URL where the signature for a file is located.

4. 4
   apply_filters( wp_signature_softfail )filterline 1325 (+170 into the body)

   Filters whether Signature Verification failures should be allowed to soft fail.

Uses · 16

• __()Retrieves the translation of $text.
• wp_tempnam()Returns a filename of a temporary unique file.
• wp_safe_remote_get()Retrieves the raw response from a safe HTTP request using the GET method.
• is_wp_error()Checks whether the given variable is a WordPress Error.
• wp_remote_retrieve_response_code()Retrieves only the response code from the raw response.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• wp_remote_retrieve_response_message()Retrieves only the response message from the raw response.
• wp_remote_retrieve_header()Retrieves a single header by name from the raw response.
• str_starts_with()Polyfill for `str_starts_with()` function added in PHP 8.0.
• sanitize_file_name()Sanitizes a filename, replacing whitespace with dashes.
• validate_file()Validates a file name and path against an allowed set of rules.
• verify_file_md5()Calculates and compares the MD5 of a file to its expected value.

Used by · 2

• WP_Upgrader::download_package()Downloads a package.
• media_sideload_image()Downloads an image from the specified URL, saves it as an attachment, and optionally attaches it to a post.

Source code

View on Trac ↗View on GitHub ↗

1155function download_url( $url, $timeout = 300, $signature_verification = false ) {1156	// WARNING: The file is not automatically deleted, the script must delete or move the file.1157	if ( ! $url ) {1158		return new WP_Error( 'http_no_url', __( 'No URL Provided.' ) );1159	}1160 1161	$url_path     = parse_url( $url, PHP_URL_PATH );1162	$url_filename = '';1163	if ( is_string( $url_path ) && '' !== $url_path ) {1164		$url_filename = basename( $url_path );1165	}1166 1167	$tmpfname = wp_tempnam( $url_filename );1168	if ( ! $tmpfname ) {1169		return new WP_Error( 'http_no_file', __( 'Could not create temporary file.' ) );1170	}1171 1172	$response = wp_safe_remote_get(1173		$url,1174		array(1175			'timeout'  => $timeout,1176			'stream'   => true,1177			'filename' => $tmpfname,1178		)1179	);1180 1181	if ( is_wp_error( $response ) ) {1182		unlink( $tmpfname );1183		return $response;1184	}1185 1186	$response_code = wp_remote_retrieve_response_code( $response );1187 1188	if ( 200 !== $response_code ) {1189		$data = array(1190			'code' => $response_code,1191		);1192 1193		// Retrieve a sample of the response body for debugging purposes.1194		$tmpf = fopen( $tmpfname, 'rb' );1195 1196		if ( $tmpf ) {1197			/**1198			 * Filters the maximum error response body size in `download_url()`.1199			 *1200			 * @since 5.1.01201			 *1202			 * @see download_url()1203			 *1204			 * @param int $size The maximum error response body size. Default 1 KB.1205			 */1206			$response_size = apply_filters( 'download_url_error_max_body_size', KB_IN_BYTES );1207 1208			$data['body'] = fread( $tmpf, $response_size );1209			fclose( $tmpf );1210		}1211 1212		unlink( $tmpfname );1213 1214		return new WP_Error( 'http_404', trim( wp_remote_retrieve_response_message( $response ) ), $data );1215	}1216 1217	$content_disposition = wp_remote_retrieve_header( $response, 'Content-Disposition' );1218 1219	if ( $content_disposition ) {1220		$content_disposition = strtolower( $content_disposition );1221 1222		if ( str_starts_with( $content_disposition, 'attachment; filename=' ) ) {1223			$tmpfname_disposition = sanitize_file_name( substr( $content_disposition, 21 ) );1224		} else {1225			$tmpfname_disposition = '';1226		}1227 1228		// Potential file name must be valid string.1229		if ( $tmpfname_disposition && is_string( $tmpfname_disposition )1230			&& ( 0 === validate_file( $tmpfname_disposition ) )1231		) {1232			$tmpfname_disposition = dirname( $tmpfname ) . '/' . $tmpfname_disposition;1233 1234			if ( rename( $tmpfname, $tmpfname_disposition ) ) {

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