media_handle_sideload( string[] $file_array, int $post_id, string $desc = null, array $post_data = array() ): int|WP_Error

Handles a side-loaded file in the same way as an uploaded file is handled by media_handle_upload() .

Parameters

$file_arraystring[]required
Array that represents a $_FILES upload array.
$post_idintoptional
The post ID the media is associated with.
$descstringoptional
Description of the side-loaded file.

Default:null

$post_dataarrayoptional
Post data to override.

Default:array()

Return

int|WP_Error The ID of the attachment or a WP_Error on failure.

Source

function media_handle_sideload( $file_array, $post_id = 0, $desc = null, $post_data = array() ) {
	$overrides = array( 'test_form' => false );

	if ( isset( $post_data['post_date'] ) && substr( $post_data['post_date'], 0, 4 ) > 0 ) {
		$time = $post_data['post_date'];
	} else {
		$post = get_post( $post_id );
		if ( $post && substr( $post->post_date, 0, 4 ) > 0 ) {
			$time = $post->post_date;
		} else {
			$time = current_time( 'mysql' );
		}
	}

	$file = wp_handle_sideload( $file_array, $overrides, $time );

	if ( isset( $file['error'] ) ) {
		return new WP_Error( 'upload_error', $file['error'] );
	}

	$url     = $file['url'];
	$type    = $file['type'];
	$file    = $file['file'];
	$title   = preg_replace( '/\.[^.]+$/', '', wp_basename( $file ) );
	$content = '';

	// Use image exif/iptc data for title and caption defaults if possible.
	$image_meta = wp_read_image_metadata( $file );

	if ( $image_meta ) {
		if ( trim( $image_meta['title'] ) && ! is_numeric( sanitize_title( $image_meta['title'] ) ) ) {
			$title = $image_meta['title'];
		}

		if ( trim( $image_meta['caption'] ) ) {
			$content = $image_meta['caption'];
		}
	}

	if ( isset( $desc ) ) {
		$title = $desc;
	}

	// Construct the attachment array.
	$attachment = array_merge(
		array(
			'post_mime_type' => $type,
			'guid'           => $url,
			'post_parent'    => $post_id,
			'post_title'     => $title,
			'post_content'   => $content,
		),
		$post_data
	);

	// This should never be set as it would then overwrite an existing attachment.
	unset( $attachment['ID'] );

	// Save the attachment metadata.
	$attachment_id = wp_insert_attachment( $attachment, $file, $post_id, true );

	if ( ! is_wp_error( $attachment_id ) ) {
		wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) );
	}

	return $attachment_id;
}

Changelog

VersionDescription
5.3.0The $post_id parameter was made optional.
2.6.0Introduced.

User Contributed Notes

  1. Skip to note 5 content

    Example

    <?php
    
    /*
     * Build the $file_array with
     * $url = the url of the image
     * $temp = storing the image in wordpress
     */
    
    $url = 'https://s.w.org/about/images/logos/wordpress-logo-stacked-rgb.png';
    
    $tmp = download_url( $url );
    
    $file_array = array(
        'name' => basename( $url ),
        'tmp_name' => $tmp
    );
    
    /**
     * Check for download errors
     * if there are error unlink the temp file name
     */
    if ( is_wp_error( $tmp ) ) {
        @unlink( $file_array[ 'tmp_name' ] );
        return $tmp;
    }
    
    /**
     * now we can actually use media_handle_sideload
     * we pass it the file array of the file to handle
     * and the post id of the post to attach it to
     * $post_id can be set to '0' to not attach it to any particular post
     */
    $post_id = '0';
    
    $id = media_handle_sideload( $file_array, $post_id );
    
    /**
     * We don't want to pass something to $id
     * if there were upload errors.
     * So this checks for errors
     */
    if ( is_wp_error( $id ) ) {
        @unlink( $file_array['tmp_name'] );
        return $id;
    }
    
    /**
     * 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)
  2. Skip to note 6 content

    For those wondering about the difference between media_handle_sideload() and media_handle_upload():

    media_handle_upload() is used to handle file uploads that come from a form submission ($_FILES array, typically from an HTML form). It expects a form’s file input field’s name and the ID of the post to attach the uploaded media to.

    On the other hand, media_handle_sideload() is used when you have a file that exists on the server’s file system (or accessible by URL) and you want to add it to the Media Library and generate the appropriate sizes and metadata for it. You would use this when you’re fetching images from another server or handling images that you’ve created or manipulated on the server.

You must log in before being able to contribute a note or feedback.