wp_insert_attachment( string|array $args, string|false $file = false, int $parent, bool $wp_error = false, bool $fire_after_hooks = true )

Insert an attachment.

Description

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.

See also

Parameters

$args

(string|array) (Required) Arguments for inserting an attachment.

$file

(string|false) (Optional) Filename.

Default value: false

$parent

(int) (Optional) Parent post ID.

$wp_error

(bool) (Optional) Whether to return a WP_Error on failure.

Default value: false

$fire_after_hooks

(bool) (Optional) Whether to fire the after insert hooks.

Default value: true

Return

(int|WP_Error) The attachment ID on success. The value 0 or WP_Error on failure.

Source

File: wp-includes/post.php 

function wp_insert_attachment( $args, $file = false, $parent = 0, $wp_error = false, $fire_after_hooks = true ) {
	$defaults = array(
		'file'        => $file,
		'post_parent' => 0,
	);

	$data = wp_parse_args( $args, $defaults );

	if ( ! empty( $parent ) ) {
		$data['post_parent'] = $parent;
	}

	$data['post_type'] = 'attachment';

	return wp_insert_post( $data, $wp_error, $fire_after_hooks );
}

Uses

Uses Description
wp-includes/functions.php: wp_parse_args()

Merges user defined arguments into defaults array.
wp-includes/post.php: wp_insert_post()

Insert or update a post.

Used By

Used By Description
wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php: WP_REST_Attachments_Controller::edit_media_item()

Applies edits to a media item and creates a new attachment record.
wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php: WP_REST_Attachments_Controller::insert_attachment()

Inserts the attachment post in the database. Does not update the attachment meta.
wp-admin/includes/class-wp-site-icon.php: WP_Site_Icon::insert_attachment()

Inserts an attachment.
wp-admin/includes/ajax-actions.php: wp_ajax_crop_image()

Ajax handler for cropping an image.
wp-admin/includes/class-file-upload-upgrader.php: File_Upload_Upgrader::__construct()

Construct the upgrader for a form.
wp-admin/includes/image.php: wp_generate_attachment_metadata()

Generate attachment meta data and create image sub-sizes for images.
wp-admin/includes/media.php: media_handle_upload()

Saves a file submitted from a POST request and create an attachment post for it.
wp-admin/includes/media.php: media_handle_sideload()

Handles a side-loaded file in the same way as an uploaded file is handled by media_handle_upload().
wp-admin/includes/import.php: wp_import_handle_upload()

Handle importer uploading and add attachment.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::insert_attachment()

Insert an attachment and its metadata.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_2_manage_upload()

Upload the file to be cropped in the second step.
wp-admin/includes/class-custom-background.php: Custom_Background::handle_upload()

Handle an Image upload for the background image.
wp-includes/post.php: wp_update_post()

Update a post with new post data.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::mw_newMediaObject()

Uploads a file, following your settings.

Changelog

Version Description
5.6.0 Added the $fire_after_hooks parameter.
4.7.0 Added the $wp_error parameter to allow a WP_Error to be returned on failure.
2.0.0 Introduced.

© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/wp_insert_attachment