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)

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