wp_insert_attachment() – Function | Developer.WordPress.org

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

Parameters

$argsstring|arrayrequired: Arguments for inserting an attachment.
$filestring|falseoptional: Filename.
Default:false
$parent_post_idintoptional: Parent post ID or 0 for no parent. Default 0.
$wp_errorbooloptional: Whether to return a WP_Error on failure.
Default:false
$fire_after_hooksbooloptional: Whether to fire the after insert hooks.
Default:true

Return

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

Source

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 );
}

View all references View on Trac View on GitHub

Uses	Description
wp_insert_post()`wp-includes/post.php`	Inserts or update a post.
wp_parse_args()`wp-includes/functions.php`	Merges user defined arguments into defaults array.

Used by	Description
WP_REST_Attachments_Controller::edit_media_item()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Applies edits to a media item and creates a new attachment record.
WP_REST_Attachments_Controller::insert_attachment()`wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php`	Inserts the attachment post in the database. Does not update the attachment meta.
WP_Site_Icon::insert_attachment()`wp-admin/includes/class-wp-site-icon.php`	Inserts an attachment.
wp_ajax_crop_image()`wp-admin/includes/ajax-actions.php`	Handles cropping an image via AJAX.
File_Upload_Upgrader::__construct()`wp-admin/includes/class-file-upload-upgrader.php`	Construct the upgrader for a form.
wp_generate_attachment_metadata()`wp-admin/includes/image.php`	Generates attachment meta data and create image sub-sizes for images.
media_handle_upload()`wp-admin/includes/media.php`	Saves a file submitted from a POST request and create an attachment post for it.
media_handle_sideload()`wp-admin/includes/media.php`	Handles a side-loaded file in the same way as an uploaded file is handled by media_handle_upload() .
wp_import_handle_upload()`wp-admin/includes/import.php`	Handles importer uploading and adds attachment.
Custom_Image_Header::insert_attachment()`wp-admin/includes/class-custom-image-header.php`	Inserts an attachment and its metadata.
Custom_Image_Header::step_2_manage_upload()`wp-admin/includes/class-custom-image-header.php`	Uploads the file to be cropped in the second step.
Custom_Background::handle_upload()`wp-admin/includes/class-custom-background.php`	Handles an Image upload for the background image.
wp_update_post()`wp-includes/post.php`	Updates a post with new post data.
wp_xmlrpc_server::mw_newMediaObject()`wp-includes/class-wp-xmlrpc-server.php`	Uploads a file, following your settings.

Show 9 more Show less

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.

User Contributed Notes

Codex 10 years ago

Example
Inserts an attachment to a parent with a post ID of 37:

<?php 
// $filename should be the path to a file in the upload directory.
$filename = '/path/to/uploads/2013/03/filename.jpg';

// The ID of the post this attachment is for.
$parent_post_id = 37;

// Check the type of file. We'll use this as the 'post_mime_type'.
$filetype = wp_check_filetype( basename( $filename ), null );

// Get the path to the upload directory.
$wp_upload_dir = wp_upload_dir();

// Prepare an array of post data for the attachment.
$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.
$attach_id = wp_insert_attachment( $attachment, $filename, $parent_post_id );

// Make sure that this file is included, as wp_generate_attachment_metadata() depends on it.
require_once( ABSPATH . 'wp-admin/includes/image.php' );

// Generate the metadata for the attachment, and update the database record.
$attach_data = wp_generate_attachment_metadata( $attach_id, $filename );
wp_update_attachment_metadata( $attach_id, $attach_data );

set_post_thumbnail( $parent_post_id, $attach_id );
?>

Skip to note 8 content

rmdundon 5 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
If you are trying to make a media attachment, caption and description are ‘post_excerpt’ and ‘post_content’, respectively. Example:
```
    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
	);
```
Log in to add feedback
Skip to note 9 content

jon 11 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

Returns int 0 on failure

Log in to add feedback
Skip to note 10 content

ahsynv 4 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

If you want to upload a file to the media library from php, you need to use this function: media_handle_upload()

Log in to add feedback
Skip to note 11 content

mreall 3 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

Once you attach an image to a post, you can make it the featured image for the post by using set_post_thumbnail().

Log in to add feedback
Skip to note 12 content

Codex 10 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: -6You must log in to vote on the helpfulness of this note
Usage
```
<?php wp_insert_attachment( $attachment, $filename, $parent_post_id ); ?>
```
Log in to add feedback

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

In this article