media_handle_sideload() │ WP 2.6.0

This example shows how to work with the function. This code will download an image from an external source, add it to the WordPress media library, and attach it to the specified post:

// the frontend needs these files
//require_once ABSPATH . 'wp-admin/includes/image.php';
//require_once ABSPATH . 'wp-admin/includes/file.php';
//require_once ABSPATH . 'wp-admin/includes/media.php';

$url     = 'http://s.w.org/style/images/wp-header-logo.png';
$post_id = 3061;
$desc = "WordPress Logo";

// Load file
$tmp = download_url( $url );

/**
 * Check for download errors
 * if there are error unlink the temp file name
 */
if ( is_wp_error( $tmp ) ) {
	@unlink( $tmp );
	return $tmp;
}

//Set file data
$file_array = [
	'name'     => basename( $url ), // ex: wp-header-logo.png
	'tmp_name' => $tmp,
	'error'    => 0,
	'size'     => filesize($tmp),
];

// upload the file
$id = media_handle_sideload( $file_array, $post_id, $desc );

// if there is an error
if( is_wp_error( $id ) ) {
	@unlink($file_array['tmp_name']);
	return $id->get_error_messages();
}

// delete the temporary file
@unlink( $tmp );

// that's it, the file is loaded and should appear in the admin panel in the media files

No we can get the url of the sideloaded file $value now contains the file url in WordPress $id is the attachment id:

$value = wp_get_attachment_url( $id );

// Now you can do something with $value (or $id)

// the frontend needs these files
//require_once ABSPATH . 'wp-admin/includes/image.php';
//require_once ABSPATH . 'wp-admin/includes/file.php';
//require_once ABSPATH . 'wp-admin/includes/media.php';

$url = "http://s.w.org/style/images/wp-header-logo.png";
$desc = "WordPress Logo";

// load the file
$tmp = download_url( $url );

if ( ! is_wp_error( $tmp ) ) {

	// correct the filename in the query lines.
	$file_array = [
		'name'     => basename( $url ),
		'tmp_name' => $tmp
	];

	$id = media_handle_sideload( $file_array, 0 );

	// if there is an error
	if( is_wp_error( $id ) ){
		echo $id->get_error_messages();
	}

}

// delete the temporary file
@unlink( $tmp );

A function that will download an external image from a specified URL, save it to the uploads directory and attach it to the post as a thumbnail:

// initialize function
$post_id = 3061;
$file = 'http://s.w.org/style/images/wp-header-logo.png?1';

if( is_single( $post_id ) ){
	my_sideload_image( $post_id, $file, $desc = 'Image description' );
}

// function code
function my_sideload_image( $post_id, $file, $desc = null ){

	global $debug; // defined outside the function as true

	if( ! function_exists('media_handle_sideload') ) {
		require_once ABSPATH . 'wp-admin/includes/image.php';
		require_once ABSPATH . 'wp-admin/includes/file.php';
		require_once ABSPATH . 'wp-admin/includes/media.php';
	}

	// Load the file into a temporary directory
	$tmp = download_url( $file );

	// Set variables for placement
	$file_array = [
		'name'     => basename( $file ),
		'tmp_name' => $tmp
	];

	// Delete the temporary file, in case of an error
	if ( is_wp_error( $tmp ) ) {
		$file_array['tmp_name'] = '';
		if( $debug ) echo 'Error no temporary file! <br />';
	}

	// debug checks
	if( $debug ){
		echo 'File array: <br />';
		var_dump( $file_array );
		echo '<br /> Post id: ' . $post_id . '<br />';
	}

	$id = media_handle_sideload( $file_array, $post_id, $desc );

	// Check the function
	if ( is_wp_error( $id ) ) {
		var_dump( $id->get_error_messages() );
	} else {
		update_post_meta( $post_id, '_thumbnail_id', $id );
	}

	// delete the temporary file
	@unlink( $tmp );
}