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

Inserts an attachment.

Contents

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.

Top ↑

See also

Top ↑

Parameters

$args string|array Required
Arguments for inserting an attachment.
$file string|false Optional
Filename.

Default: false

$parent_post_id int Optional
Parent post ID.
$wp_error bool Optional
Whether to return a WP_Error on failure.

Default: false

$fire_after_hooks bool Optional
Whether to fire the after insert hooks.

Default: true

Top ↑

Return

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

Top ↑

Source

File: wp-includes/post.php. View all references 

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 on Trac View on GitHub

Top ↑

Top ↑

Used By

Used By
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

Ajax handler for cropping an image.
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

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

Upload 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 used by Hide more used by

Top ↑

Changelog

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.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    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
    Contributed by Codex —

    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 );
?>
  2. Skip to note 2 content
    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
    Contributed by rmdundon —

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

You must log in before being able to contribute a note or feedback.