wp_insert_attachment() の使い方｜説明・引数・注意点

説明

基本構文

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

引数

• $args：post_title、post_mime_type などの配列
• $file：ファイルのパス
• $parent_post_id：親投稿のID
• $wp_error：失敗時に WP_Error を返すか

戻り値

添付ファイルのID。失敗時は 0 または WP_Error。

使い方（サンプル）

$id = wp_insert_attachment( array(
	'post_title'     => 'サンプル画像',
	'post_mime_type' => 'image/jpeg',
	'post_status'    => 'inherit',
), $file, 123 );

注意点

• 登録後に wp_generate_attachment_metadata() でメタデータを作ります。
• ファイルは事前にアップロードディレクトリに置く必要があります。

実務での使いどころ

• すでにアップロードフォルダにあるファイルを、メディアとして登録するとき。
• プログラムで作成した画像や、外部から取り込んだファイルを、メディアに追加するとき。

よくあるミスと対処

• ファイルが、アップロードフォルダの中にない。
• 登録しただけで、サムネイルが作られない。wp_generate_attachment_metadata() と wp_update_attachment_metadata() を続けて呼ぶ。
• post_mime_type を指定していない。
• 戻り値が 0 や WP_Error のときを、考えていない。

NG例

$id = wp_insert_attachment( array( 'post_title' => '画像' ), $file ); // MIMEタイプがない。サムネイルもない

OK例

$id = wp_insert_attachment( array(
	'post_mime_type' => 'image/jpeg',
	'post_title'     => '画像',
	'post_status'    => 'inherit',
), $file );
if ( $id ) {
	require_once ABSPATH . 'wp-admin/includes/image.php';
	wp_update_attachment_metadata( $id, wp_generate_attachment_metadata( $id, $file ) );
}

使い分け早見表

関連項目

wp_generate_attachment_metadata()、media_handle_upload()

公式リファレンス：wp_insert_attachment() | Function | WordPress Developer Resources