WordPress.org

Languages: English • 日本語 (Add your language)

Description

This function inserts an attachment into the media library. The function should be used in conjunction with wp_update_attachment_metadata() and wp_generate_attachment_metadata(). It returns the ID of the entry created in the wp_posts table.

This function is part of the low-level API used by WordPress for handling attachments. To perform the entire attachment upload and insertion process at once, you will want to use media_handle_upload() instead in most cases.

Usage

 <?php wp_insert_attachment( $attachment, $filename, $parent_post_id ); ?> 

Parameters

$attachment

(array) (required) Array of data about the attachment that will be written into the wp_posts table of the database. Must contain at a minimum the keys post_title, post_content (the value for this key should be the empty string), post_status and post_mime_type.

Default: None

$filename

(string) (optional) Location of the file on the server. Use absolute path and not the URI of the file. The file MUST be in the uploads directory. See wp_upload_dir()

Default: false

$parent_post_id

(int) (optional) Attachments may be associated with a parent post or page. Specify the parent's post ID, or 0 if unattached.

Default: 0

Return Values

Returns the resulting post ID (int) on success or 0 (int) on failure.

Example

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

Note

Using the _wp_relative_upload_path() to build the guid may not be reliable on some servers.

Source File

wp_insert_attachment() is located in wp-includes/post.php.

Related

wp_get_attachment_url(), wp_delete_attachment(), wp_insert_post()