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



お勧め

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

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

更新ボタンの横にスピナーを実装する(2019年5月14日 更新)

WordPressの管理画面ではAJAXを使って何らかの処理を行う際、数秒間の空き時間にアイコンがクルクル回る「スピナー」を表示しているところがある。今作っているプラグインでこの「スピナー」を使いたくなったので、実装方法を調べてみた。

ブロックエディターをちょっとだけカスタマイズしてみる(2021年11月3日 更新)

ブロックエディターで投稿を編集していると「ここは〇〇だったらいいのにな」と思うところがある。今回は、そんな気になるところをいくつか(自分好みに)調整してみた。

Login rebuilder 2.3.0の新機能を紹介(2018年5月27日 更新)

プラグイン「Login rebuilder」はログイン時の履歴(ログ)や不正なログインページへのアクセス履歴を保存している。これらの履歴情報はダッシュボートで確認できるが、バージョン2.3.0においてそれぞれがダウンロードできるようになった。

メディア(attachment)を拡張してより便利に活用する(2014年5月22日 更新)

「メディア(attachment)」は、標準ではカテゴリもタグもカスタムフィールドもない。投稿と親子関係を作って利用することが前提だからともいえるが、メディアをもっと便利に活用するために、それらの付加情報を絞り込みの材料として利用できないか調べてみた。