WordPress: How to add images to the media library with PHP

WordPress offers different ways to add images with PHP to the WordPress media library. Two variants I would like to introduce to you today, media_handle_sideload and wp_insert_attachment.

wp_insert_attachment #

The following example shows you how to insert images into the WordPress media library using PHP and wp_insert_attachment.

/**
 * Adding an image to the WordPress library and creating all associated image sizes
 * 
 * @param string $path_to_file    The absolute path to the image to be added to the media library, e.g.: /wp-content/uploads/bild1.jpg
 * @param string $post_title      The title for the image
 * @param int &$attachment_id     If specified, the ID of the image will be stored in this variable after successful creation.
 * 
 * @return bool Returns true if the image was successfully created. Otherwise false is returned. 
 */
function addImageToWordPressMediaLibrary(string $path_to_file, string $post_title, &$attachment_id = null): bool{

   /**
    * Let WordPress determine the mime type of the file
    */
    $filetype = wp_check_filetype(basename($path_to_file));

    $attachment = array(
      'post_mime_type' => $filetype['type'],
      'post_title' => sanitize_title($post_title),
      'post_content' => '',
      'post_status' => 'inherit'
    );

    /**
     * Create the Post
     */
    $attachment_id = wp_insert_attachment($attachment, $path_to_file);

    if(!is_numeric($attachment_id)){
       return false;
    }

    /**
     * Create additional image sizes and store them for the image
     */
    require_once( ABSPATH . 'wp-admin/includes/image.php' );

    $attach_data = wp_generate_attachment_metadata( $attachment_id, $path_to_file );
    wp_update_attachment_metadata( $attachment_id, $attach_data );
    return true;
}

Using wp_insert_attachment the actual image is added to the media library. Only if this was successful, the remaining image formats are generated via wp_generate_attachment_metadata and then added to the image (post) via wp_update_attachment_metadata.

media_handle_sideload #

Alternatively, images can also be added to the WordPress media library with media_handle_sideload. This variant is also used by the media library in the backend of your WordPress website. Here you have less options, but you can save a few lines of code.

/**
 * Adding an image to the WordPress library and creating all associated image sizes
 * 
 * @param string $path_to_file    The absolute path to the image to be added to the media library, e.g.: /wp-content/uploads/bild1.jpg
 * @param string $image           The filename of the image after copying, e.g. bild1.jpg
 * @param int &$attachment_id     If specified, the ID of the image will be stored in this variable after successful creation.
 * 
 * @return bool Returns true if the image was successfully created. Otherwise false is returned. 
 */
function addImageToWordPressMediaLibrary(string $path_to_file, string $image, &$attachment_id = null): bool{
   $file_array = ["name" => $image, "tmp_name" => $path_to_file];

   // Add image to Media Library
   $attachment_id = media_handle_sideload($file_array , 0, '');

   if(!is_numeric($attachment_id )){
     return false;
   }
                
   return true;
}

Both variants, if the additional image sizes are created, require some time to add an image.

Summary #

Both media_handle_sideload and wp_insert_attachment lead to the desired result. The wp_insert_attachment function allows to add images to the media library even without the predefined image sizes of the theme. Only by calling wp_generate_attachment_metadata and saving the data by wp_update_attachment_metadata the additional image sizes are created. This can be especially helpful if several images are to be added at once. The different image sizes can be added later via plugins like RegenerateThumbnails.