media_handle_sideload() – Function | Developer.WordPress.org

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

View all references View on Trac View on GitHub

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() .
wp_basename()`wp-includes/formatting.php`	i18n-friendly version of basename().
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.
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 Show less

Used by	Description
WP_Customize_Manager::import_theme_starter_content()`wp-includes/class-wp-customize-manager.php`	Imports theme starter content into the customized state.
media_sideload_image()`wp-admin/includes/media.php`	Downloads an image from the specified URL, saves it as an attachment, and optionally attaches it to a post.

Changelog

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

User Contributed Notes

Codex 9 years ago

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)

Skip to note 6 content

Daniel Davis 2 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 3You must log in to vote on the helpfulness of this note

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.

Log in to add feedback
Skip to note 7 content

Aurovrata Venet 1 year ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
If you need to use this function in a plugin you will need to include the following core files,
```
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
```
Log in to add feedback
Skip to note 8 content

Codex 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -1You must log in to vote on the helpfulness of this note
Usage
```
<?php $media = media_handle_sideload( $file_array, $post_id, $desc, $post_data ); ?>
```
Log in to add feedback

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

In this article

Parameters

Return

Source

Changelog

User Contributed Notes

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

In this article

Parameters

Return

Source

Related

Changelog

User Contributed Notes