When developing custom WordPress themes or plugins, you often need to handle media programmatically. Whether you’re importing data from an external source or building a custom upload flow, WordPress provides several powerful functions to insert images into the Media Library and associate them with specific posts. In this article, we’ll explore two primary methods: importing from a local file path and importing from a remote URL.
1. Using media_handle_sideload to Insert Images from a Local File Path
If the image file is already located on your server (for example, in a temporary directory or a custom uploads folder), you should use the media_handle_sideload function. This function mimics the behavior of a standard file upload, handling the file processing and database insertion in one go.
To use this function, you must first provide a $file_array that resembles the PHP $_FILES superglobal. Here is a basic implementation:
// Include the necessary files if running outside of the admin area
require_once(ABSPATH . 'wp-admin/includes/media.php');
require_once(ABSPATH . 'wp-admin/includes/file.php');
require_once(ABSPATH . 'wp-admin/includes/image.php');
$file_path = '/path/to/your/image.jpg';
$file_array = [
'name' => basename($file_path),
'tmp_name' => $file_path
];
// Sideload the file and get the attachment ID
$attach_id = media_handle_sideload($file_array);media_handle_sideload Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| $file_array | array | Yes | – | An array similar to the $_FILES global. |
| $post_id | int | No | 0 | The ID of the post to attach the image to. |
| $desc | string | No | null | Description text for the image. |
| $post_data | array | No | [] | Additional information for the attachment post. |
2. Using media_sideload_image to Insert Images from a URL
If the image is hosted on another server and you only have its URL, media_sideload_image is the function you need. This function downloads the image to your server’s temporary storage and then internally calls media_handle_sideload to complete the import.
$url = "https://wordpress.org/about/images/logos/wordpress-logo-stacked-rgb.png";
$post_id = 1; // Optional: ID of the post to attach it to
$desc = "The WordPress Logo";
// Downloads the image and inserts it into the media library
$image = media_sideload_image($url, $post_id, $desc);| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| $url | string | Yes | – | The URL of the image to download. |
| $post_id | int | No | 0 | The ID of the post to attach the image to. |
| $desc | string | No | null | Description of the image. |
| $return | string | No | html | What to return: ‘html’, ‘src’, or ‘id’. |
In addition to these two functions, WordPress also provides media_handle_upload for handling files sent via POST requests from a form. All of these high-level functions eventually rely on lower-level utilities like wp_handle_sideload and wp_handle_upload, which perform file sanitization, type checks, and directory management. Once the file is safely stored, WordPress uses wp_insert_attachment to record the metadata in the database, making the image available in both the admin dashboard and on the frontend.
