Title: media_handle_sideload Published: April 25, 2014 Last modified: April 28, 2025 --- # media_handle_sideload( string[] $file_array, int $post_id, string $desc = null, array $post_data = array() ): int|󠀁[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)󠁿 ## In this article * [Parameters](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#parameters) * [Return](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#return) * [Source](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#source) * [Related](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#related) * [Changelog](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#changelog) * [User Contributed Notes](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#user-contributed-notes) [ Back to top](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#wp--skip-link--target) Handles a side-loaded file in the same way as an uploaded file is handled by [media_handle_upload()](https://developer.wordpress.org/reference/functions/media_handle_upload/). ## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#parameters)󠁿 `$file_array`string[]required Array that represents a `$_FILES` upload array. `$post_id`intoptional The post ID the media is associated with. `$desc`stringoptional Description of the side-loaded file. Default:`null` `$post_data`arrayoptional Post data to override. Default:`array()` ## 󠀁[Return](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#return)󠁿 int|[WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) The ID of the attachment or a [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/) on failure. ## 󠀁[Source](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#source)󠁿 ```php 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](https://developer.wordpress.org/reference/files/wp-admin/includes/media.php/) [View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/media.php#L455) [View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/media.php#L455-L521) ## 󠀁[Related](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#related)󠁿 | Uses | Description | | [wp_read_image_metadata()](https://developer.wordpress.org/reference/functions/wp_read_image_metadata/)`wp-admin/includes/image.php` | Gets extended image metadata, exif or iptc as available. | | [wp_generate_attachment_metadata()](https://developer.wordpress.org/reference/functions/wp_generate_attachment_metadata/)`wp-admin/includes/image.php` | Generates attachment meta data and create image sub-sizes for images. | | [wp_handle_sideload()](https://developer.wordpress.org/reference/functions/wp_handle_sideload/)`wp-admin/includes/file.php` | Wrapper for [_wp_handle_upload()](https://developer.wordpress.org/reference/functions/_wp_handle_upload/) . | | [sanitize_title()](https://developer.wordpress.org/reference/functions/sanitize_title/)`wp-includes/formatting.php` | Sanitizes a string into a slug, which can be used in URLs or HTML attributes. | | [current_time()](https://developer.wordpress.org/reference/functions/current_time/)`wp-includes/functions.php` | Retrieves the current time based on specified type. | | [wp_insert_attachment()](https://developer.wordpress.org/reference/functions/wp_insert_attachment/)`wp-includes/post.php` | Inserts an attachment. | | [wp_update_attachment_metadata()](https://developer.wordpress.org/reference/functions/wp_update_attachment_metadata/)`wp-includes/post.php` | Updates metadata for an attachment. | | [wp_basename()](https://developer.wordpress.org/reference/functions/wp_basename/)`wp-includes/formatting.php` | i18n-friendly version of basename(). | | [get_post()](https://developer.wordpress.org/reference/functions/get_post/)`wp-includes/post.php` | Retrieves post data given a post ID or post object. | | [is_wp_error()](https://developer.wordpress.org/reference/functions/is_wp_error/)`wp-includes/load.php` | Checks whether the given variable is a WordPress Error. | | [WP_Error::__construct()](https://developer.wordpress.org/reference/classes/wp_error/__construct/)`wp-includes/class-wp-error.php` | Initializes the error. | [Show 6 more](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#) [Show less](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#) | Used by | Description | | [WP_Customize_Manager::import_theme_starter_content()](https://developer.wordpress.org/reference/classes/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()](https://developer.wordpress.org/reference/functions/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](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#changelog)󠁿 | Version | Description | | [5.3.0](https://developer.wordpress.org/reference/since/5.3.0/) | The `$post_id` parameter was made optional. | | [2.6.0](https://developer.wordpress.org/reference/since/2.6.0/) | Introduced. | ## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#user-contributed-notes)󠁿 1. [Skip to note 5 content](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#comment-content-983) 2. [Codex](https://profiles.wordpress.org/codex/) [ 10 years ago ](https://developer.wordpress.org/reference/functions/media_handle_sideload/#comment-983) 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-983) Vote results for this note: 9[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-983) 4. **Example** 5. ```php 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) ``` 6. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%3Freplytocom%3D983%23feedback-editor-983) 7. [Skip to note 6 content](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#comment-content-6505) 8. [Daniel Davis](https://profiles.wordpress.org/tagawa/) [ 3 years ago ](https://developer.wordpress.org/reference/functions/media_handle_sideload/#comment-6505) 9. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-6505) Vote results for this note: 4[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-6505) 10. For those wondering about the difference between `media_handle_sideload()` and` media_handle_upload()`: 11. `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. 12. 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. 13. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%3Freplytocom%3D6505%23feedback-editor-6505) 14. [Skip to note 7 content](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#comment-content-6663) 15. [Aurovrata Venet](https://profiles.wordpress.org/aurovrata/) [ 3 years ago ](https://developer.wordpress.org/reference/functions/media_handle_sideload/#comment-6663) 16. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-6663) Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-6663) 17. If you need to use this function in a plugin you will need to include the following core files, 18. ```php require_once ABSPATH . 'wp-admin/includes/media.php'; require_once ABSPATH . 'wp-admin/includes/file.php'; require_once ABSPATH . 'wp-admin/includes/image.php'; ``` 19. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%3Freplytocom%3D6663%23feedback-editor-6663) 20. [Skip to note 8 content](https://developer.wordpress.org/reference/functions/media_handle_sideload/?output_format=md#comment-content-982) 21. [Codex](https://profiles.wordpress.org/codex/) [ 10 years ago ](https://developer.wordpress.org/reference/functions/media_handle_sideload/#comment-982) 22. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-982) Vote results for this note: -2[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%23comment-982) 23. **Usage** 24. ```php ``` 25. [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F%3Freplytocom%3D982%23feedback-editor-982) You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fmedia_handle_sideload%2F) before being able to contribute a note or feedback.