wp_insert_post

説明

mixed wp_insert_post( array $postarr [ , bool $wp_error = false [ , bool $fire_after_hooks = true ] ] )
投稿情報を登録する。

パラメータ

  • $postarr
    投稿情報を連想配列で指定。連想配列の内容(抜粋)は次の通り。
    キー名省略時の値内容
    'post_status''draft'投稿ステータス('draft'、'publish'、'private'、'future'など)
    'post_type''post'投稿タイプ('post'、'page'、カスタム投稿タイプ名など)
    'post_author' $user_ID投稿者ID
    'ping_status' get_option( 'default_ping_status' )デフォルトのピンステータス
    'post_parent'0親の投稿情報ID
    'menu_order'0メニューの表示順
    'to_ping'''
    'pinged'''
    'post_password'''パスワードによるアクセス制限時のパスワード
    'guid'''
    'post_content_filtered'''
    'post_excerpt'''抜粋
    'import_id'0新しい投稿情報ID(未使用のID)
    'post_content'''投稿記事
    'post_title'''タイトル
    'ID'投稿情報ID
    'post_category'カテゴリーIDの配列
    'tags_input'投稿タグの文字列(複数の場合は,(カンマ)区切り)
    'comment_status'コメントステータス('open'、'closed'など)
    'post_date'投稿日時
  • $wp_error
    登録失敗時にエラー内容を示す WP_Errorオブジェクトを返す場合はtrueを、0を返す場合はfalseを指定(省略時はfalse)
  • $fire_after_hooks
    [5.6.0]投稿情報とその関連情報の保存後に wp_after_insert_post関数を呼び出す場合はtrueを指定(省略時はtrue)。

返り値

正しく登録できた場合は投稿情報のIDを返す。登録できなかった場合は、パラメータ$wp_errorにしたがってWP_Errorオブジェクトまたは0を返す。

注意

'ID'プロパティで指定した投稿情報がすでに存在する場合は、追加は行わず、その投稿情報を更新する。なお、公開済みの投稿危記事を'post_status'プロパティを省略して更新すると、ステータスが「下書き('draft')」などに変わってしまう。また固定ページを'post_type'プロパティを省略して更新すると、投稿タイプが「投稿('post')」に変わってしまう。どちらも注意が必要だ。
'post_status'プロパティが'private'以外の場合、'post_password'プロパティを指定しても無効となる。
'post_type'プロパティが'post'で'post_status'プロパティが'auto-draft'以外の場合、'post_category'プロパティが省略されている場合はデフォルトのカテゴリーが適用される。
内部では、デフォルトのカテゴリーID、コメントステータス(「新しい投稿へのコメントを許可する」の値)、ピンステータス(「他のブログからの通知 (ピンバック・トラックバック) を受け付ける」の値)を取得している。
$post_category = array( get_option('default_category') );
$comment_status = get_option( 'default_comment_status' );
$ping_status = get_option( 'default_ping_status' );
[4.2.0]タイトル(post_titile)、本文(post_content)、抜粋(post_excerpt)については、カラムのcharsetが'utf8'の場合に wp_encode_emoji関数を使って絵文字の文字コードをHTMLエンティティに変換する。

使用例

  • 投稿情報としてタイトルと内容を登録する。
    <?php $post_id = wp_insert_post( array( 'post_title'=>'テスト投稿', 'post_content'=>'この投稿はテストです。' ) ); ?>
  • 投稿情報として$postarrを登録する。登録できなかった場合はエラー内容を取得する。
    <?php $post_id = wp_insert_post( $postarr, true ); ?>

フィルター

[3.9.0]更新する投稿情報の再構築後、投稿タイプが'attachment'の場合は'wp_insert_attachment_data'フィルターを呼び出す。パラメータ$dataには再構築された投稿情報が、$postarrには本関数が受け取った内容にデフォルト要素を補完後にサニタイズしたものが格納されている。[5.4.1]パラメータ$unsanitized_postarrが追加され、本関数が受け取り時の$postarrの内容が格納されている。[6.0.0]パラメータ$updateが追加され、投稿済み($postarr['ID']が空でない)の場合はtrueが格納されている。
$data = apply_filters( 'wp_insert_attachment_data', $data, $postarr, $unsanitized_postarr, $update );
[2.7.0]更新する投稿情報の再構築後、投稿タイプが'attachment'以外の場合は'wp_insert_post_data'フィルターを呼び出す。パラメータ$dataには再構築された投稿情報が、$postarrには本関数が受け取った内容にデフォルト要素を補完後にサニタイズしたものが格納されている。[5.4.1]パラメータ$unsanitized_postarrが追加され、本関数が受け取り時の$postarrの内容が格納されている。[6.0.0]パラメータ$updateが追加され、投稿済み($postarr['ID']が空でない)の場合はtrueが格納されている。
$data = apply_filters( 'wp_insert_post_data', $data, $postarr, $unsanitized_postarr, $update );
[3.3.0]指定された投稿情報が「空」か調べるため'wp_insert_post_empty_content'フィルターを呼び出す。$maybe_emptyにはタイトル、コンテント(記事内容)、抜粋のすべてが空の場合にtrueが格納されている。
if ( apply_filters( 'wp_insert_post_empty_content', $maybe_empty, $postarr ) ) {
[3.1.0]親記事のIDを指定する前に'wp_insert_post_parent'フィルターを呼び出す。
$post_parent = apply_filters( 'wp_insert_post_parent', $post_parent, $post_ID, compact( array_keys( $postarr ) ), $postarr );

アクション

[2.5.0]投稿情報を更新する前に'pre_post_update'アクションを呼び出す。
do_action( 'pre_post_update', $post_ID );
[5.1.0]すでに投稿情報が登録されている場合'edit_post'アクションの前に'edit_post_{投稿タイプ}'アクションを呼び出す。パラメータ$post_IDには投稿IDが、$postには更新する投稿情報が格納されている。
do_action( "edit_post_{$post->post_type}", $post_ID, $post );
[1.2.0]すでに投稿情報が登録されている場合'edit_post'アクションを呼び出す。パラメータ$post_IDには投稿IDが、$postには更新する投稿情報が格納されている。
do_action( 'edit_post', $post_ID, $post );
[3.0.0]すでに投稿情報が登録されている場合'edit_post'アクションの後に'post_updated'アクションを呼び出す。$post_afterには更新後の投稿情報が、$post_beforeには更新前の投稿情報が格納されている。
do_action( 'post_updated', $post_ID, $post_after, $post_before );
[3.7.0]'save_post'アクションを呼び出す前に'save_post_post'のような末尾に投稿タイプ名を含むアクションを呼び出す。$postには更新する投稿情報が格納されている。
do_action( "save_post_{$post->post_type}", $post_ID, $post, $update );
[1.5.0]'save_post'アクションを呼び出す。$postには更新する投稿情報が格納されている。
do_action( 'save_post', $post_ID, $post, $update );
[2.0.0]'wp_insert_post'アクションを呼び出す。$postには更新する投稿情報が格納されている。
do_action( 'wp_insert_post', $post_ID, $post, $update );

ソースファイル

/wp-includes/post.php

最終更新 : 2022年06月01日 12:29



お勧め

Contact Form 7に確認フェーズを(2012年12月16日 更新)

Contact Form 7はWordPressによるサイト製作でお世話になることが多いプラグインの1つ。ただ、クライアント様によっては、入力、確認、送信の3フェーズにしたいという要望があり、そんな時は別の方法を採用していたのですが、JavaScript(jQuery)を使ってページ遷移しなくてもいいなら確認フェーズは用意できるかなと思い、作り込んでみた。

投稿一覧に独自リンクを追加する(2013年10月16日 更新)

管理者ページの「投稿一覧」や「固定ページ一覧」の各投稿記事はマウスポインタを移動すると、「編集」や「クイック編集」といったリンクが表示される。このリンクに独自のリンクを追加する方法を調べてみた。

HTML編集モードに定型文ボタンを追加する(2011年6月1日 更新)

投稿編集ページにはビジュアル編集モードとHTML編集モードがあり、それらを拡張するプラグインも多数存在している。そういったプラグインを利用するのもいいのだが、仕組みを理解するのも悪くないはず。というわけで、ここではHTML編集モードのボタンの仕組みと定型文を挿入するボタンを追加する方法を紹介する。

投稿日の検索が自由自在に(2015年3月7日 更新)

WordPress 3.7.0ではWP_Date_Queryクラスが追加され、WP_Queryクラス(もちろん query_posts関数でも)で利用できるようになった。このWP_Date_Queryにより、○年○月○日以前や以降の投稿情報を取得したり、○年○月○日から○年○月○日の範囲の投稿情報を取得したりといったことが、容易に行えるようになった。

プラグインのヘッダー情報を国際化対応しよう(2018年5月27日 更新)

バージョン4.8がリリースされてひと段落。あらためてプラグイン一覧ページを見てみると「Akismet」が「Akismet Anti-Spam (アンチスパム)」と表示されていた。説明文だけじゃなくプラグイン名も国際化対応できたのね。