wp_insert_attachment() │ WP 2.0.0

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.

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

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 the alt 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

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.8.1

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)