wp_insert_attachment() │ WP 2.0.0

Insert an attachment.

If you set the 'ID' in the $args parameter, it will mean that you are updating and attempt to update the attachment. You can also set the attachment name or title by setting the key 'post_name' or 'post_title'.

You can set the dates for the attachment manually by setting the 'post_date' and 'post_date_gmt' keys' values.

By default, the comments will use the default settings for whether the comments are allowed. You can close them manually or keep them open by setting the value for the 'comment_status' key.

Uses: wp_insert_post()
Used By: media_handle_sideload(), media_handle_upload()

No Hooks.

Return

Int|WP_Error. The attachment ID on success. The value 0 or WP_Error on failure.

Usage

wp_insert_attachment( $args, $file, $parent_post_id, $wp_error, $fire_after_hooks );
$args(string|array) (required)
Arguments for inserting an attachment.
$file(string|false)
Filename.
Default: false
$parent_post_id(int)
Parent post ID or 0 for no parent.
$wp_error(true|false)
Whether to return a WP_Error on failure.
Default: false
$fire_after_hooks(true|false)
Whether to fire the after insert hooks.
Default: true

Examples

0

#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 );
0

#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

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() code WP 6.5.2

wp-includes/post.php 
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 );
}

wp_insert (insert in DB)

Attachments (Media files)