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

説明

基本構文

wp_insert_post( array $postarr, bool $wp_error = false, bool $fire_after_hooks = true ): int|WP_Error

引数

• $postarr：投稿データの配列（post_title、post_content、post_status、post_type など）
• $wp_error：true にすると失敗時に WP_Error を返す
• $fire_after_hooks：保存後のフックを実行するか

戻り値

成功すると投稿ID。失敗時は 0 または WP_Error。

使い方（サンプル）

$id = wp_insert_post( array(
	'post_title'   => 'サンプル',
	'post_content' => '本文',
	'post_status'  => 'publish',
	'post_type'    => 'post',
), true );
if ( is_wp_error( $id ) ) {
	error_log( $id->get_error_message() );
}

注意点

• post_status を省略すると draft になります。
• データは内部でスラッシュ処理されます。$_POST 由来など、エスケープ済みの値には wp_slash() が必要な場合があります。
• post_author を省略すると、現在のユーザーが投稿者になります。

実務での使いどころ

• プログラムから、新しい投稿を作成するとき（インポートや、フォームからの投稿など）。
• カスタム投稿タイプの記事を、自動で登録するとき。
• post_title・post_content・post_status などを、配列で渡して登録するとき。

よくあるミスと対処

• post_status を省略している。既定は draft のため、公開されない。
• 失敗したときの戻り値を確認していない。$wp_error が false（既定）なら 0、true なら WP_Error が返る。
• フォームの入力値を、そのまま渡している。検証とサニタイズをしてから渡す。
• save_post フックの中で呼び、無限ループになる。

NG例

wp_insert_post( array( 'post_title' => 'タイトル' ) ); // 下書きとして保存される

OK例

$post_id = wp_insert_post( array(
	'post_title'   => 'タイトル',
	'post_content' => '本文',
	'post_status'  => 'publish',
	'post_type'    => 'post',
), true );

if ( is_wp_error( $post_id ) ) {
	return;
}

使い分け早見表

関連項目

wp_update_post()、wp_delete_post()、wp_set_post_terms()

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