wp_insert_attachment()
Adds a media file (attachment) to the WordPress media library. The file is not physically added — the function creates a post in the wp_posts table in the database and returns the ID of the created post.
This function is one of the low-level API functions used in WordPress to insert attachments.
The function should be used in conjunction with the functions: wp_generate_attachment_metadata() and wp_update_attachment_metadata().
Use media_handle_upload() to physically upload the file and create a record of that file in the DB at once.
No Hooks.
Returns
Int|WP_Error
. The ID of the post in case of successful addition and 0 on failure. WP_Error object on failure if the $wp_error parameter is specified (since version 4.7).
Usage
wp_insert_attachment( $args, $file, $parent_post_id, $wp_error, $fire_after_hooks );
- $args(array) (required)
Array of data about the attachment being added, which will be recorded in the DB in the wp_posts table.
When adding, it must contain at least these data:
$args = [ 'guid' => $url_to_attachment, 'post_mime_type' => $headers['content-type'], 'post_title' => $file_basename, // optional 'post_excerpt' => $caption, 'post_content' => $description, ];
Where,
guid
— URL to the file. It is highly recommended to specify this field, as it will be used in functions that return the URL to the file.post_mime_type
— mime type of the attachment, for example,image/jpg
.post_title
— name of the file that will be displayed in the admin panel. Usually the last part of the URL.post_content
— usually used as a description of the image in thealt
attribute.post_excerpt
— usually used as a caption for the image.
- $file(string)
The location of the file on the server. Use the absolute path, not the URL. The path should point to the WordPress uploads directory -
uploads
. See wp_upload_dir().After adding data to wp_posts, this parameter is passed to the function update_attached_file().
Default: false
- $parent_post_id(int)
- The ID of the post (record) to which the added media file should relate. Here we specify the ID of the parent post.
Default: 0 - $wp_error(boolean)
- Set to true if an object WP_Error should be returned in case of an error.
Default: false - $fire_after_hooks(boolean) (WP 5.6)
- Whether to run the function wp_after_insert_post(), which triggers hooks at the end of the function's execution.
Default: true
Examples
#1 Add an attachment file to the WP database
Assuming that the file has already been physically uploaded to the uploads directory, we now need to add it to the WordPress database. Also, let's attach the post to the post 37:
// the file must be in the WP uploads directory. $filename = '/path/to/uploads/2013/03/filname.jpg'; // the ID of the post to which we are attaching. $parent_post_id = 37; // Check the post type that we use in the 'post_mime_type' field. $filetype = wp_check_filetype( basename( $filename ), null ); // Get the path to the uploads directory. $wp_upload_dir = wp_upload_dir(); // Prepare the array with the necessary data for the nesting. $attachment = array( 'guid' => $wp_upload_dir['url'] . '/' . basename( $filename ), 'post_mime_type' => $filetype['type'], 'post_title' => preg_replace( '/\.[^.]+$/', '', basename( $filename ) ), 'post_content' => '', 'post_status' => 'inherit' ); // Insert the attachment into the database. $attach_id = wp_insert_attachment( $attachment, $filename, $parent_post_id ); // Connect the desired file, if it is not already connected // wp_generate_attachment_metadata() depends on this file. require_once( ABSPATH . 'wp-admin/includes/image.php' ); // Create metadata for the attachment and update the post in the database. $attach_data = wp_generate_attachment_metadata( $attach_id, $filename ); wp_update_attachment_metadata( $attach_id, $attach_data );
#2 Attachment, caption and description
If you are trying to make a media attachment, caption and description are post_excerpt
and post_content
, respectively. Example:
$attach_id = wp_insert_attachment( array( 'guid' => $upload['url'], 'post_title' => sanitize_text_field( $title ), 'post_excerpt' => sanitize_text_field( $caption ), 'post_content' => sanitize_text_field( $description ), 'post_mime_type' => $response_headers['content-type'], ), $upload['file'], 0 ); // Connect the desired file, if it is not already connected // wp_generate_attachment_metadata() depends on this file. require_once( ABSPATH . 'wp-admin/includes/image.php' ); // Create metadata for the attachment and update the post in the database. $attach_data = wp_generate_attachment_metadata( $attach_id, $filename ); wp_update_attachment_metadata( $attach_id, $attach_data );
Notes
- See: wp_insert_post()
Changelog
Since 2.0.0 | Introduced. |
Since 4.7.0 | Added the $wp_error parameter to allow a WP_Error to be returned on failure. |
Since 5.6.0 | Added the $fire_after_hooks parameter. |
wp_insert_attachment() wp insert attachment code WP 6.8.1
function wp_insert_attachment( $args, $file = false, $parent_post_id = 0, $wp_error = false, $fire_after_hooks = true ) { $defaults = array( 'file' => $file, 'post_parent' => 0, ); $data = wp_parse_args( $args, $defaults ); if ( ! empty( $parent_post_id ) ) { $data['post_parent'] = $parent_post_id; } $data['post_type'] = 'attachment'; return wp_insert_post( $data, $wp_error, $fire_after_hooks ); }