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() .

Contents

Parameters

$file_array string[] Required
Array that represents a $_FILES upload array.
$post_id int Optional
The post ID the media is associated with.
$desc string Optional
Description of the side-loaded file.

Default: null

$post_data array Optional
Post data to override.

Default: array()

Top ↑

Return

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

Top ↑

Source

File: wp-admin/includes/media.php. View all references 

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;
}

View on Trac View on GitHub

Top ↑

Top ↑

Uses

Uses
Uses Description
wp_read_image_metadata() wp-admin/includes/image.php

Gets extended image metadata, exif or iptc as available.
wp_generate_attachment_metadata() wp-admin/includes/image.php

Generates attachment meta data and create image sub-sizes for images.
wp_handle_sideload() wp-admin/includes/file.php

Wrapper for _wp_handle_upload() .
sanitize_title() wp-includes/formatting.php

Sanitizes a string into a slug, which can be used in URLs or HTML attributes.
current_time() wp-includes/functions.php

Retrieves the current time based on specified type.
wp_insert_attachment() wp-includes/post.php

Inserts an attachment.
wp_update_attachment_metadata() wp-includes/post.php

Updates metadata for an attachment.
wp_basename() wp-includes/formatting.php

i18n-friendly version of basename().
get_post() wp-includes/post.php

Retrieves post data given a post ID or post object.
is_wp_error() wp-includes/load.php

Checks whether the given variable is a WordPress Error.
WP_Error::__construct() wp-includes/class-wp-error.php

Initializes the error.
Show 6 more uses Hide more uses

Top ↑

Changelog

Changelog
Version Description
5.3.0 The $post_id parameter was made optional.
2.6.0 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 9You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Daniel Davis —

    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.