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

Description

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

string|WP_Error

Filename on success, WP_Error on failure.

Hooks 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

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 ) ) {

History

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.