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



お勧め

フィードにサムネイル画像を追加する(2022年11月1日 更新)

WordPressが出力するの標準のフィードには、各投稿のサムネイル画像の情報が含まれていない。ネットで検索してみるといくつかの方法があることがわかったので、その中から2つ試してみた。

投稿一覧に「投稿フォーマット」フィルターが追加される(2019年4月12日 更新)

WordPress 5.2 Beta2(以降5.2Beta2)のソースコードを眺めていると、投稿一覧ページのフィルター機能に「投稿フォーマット」(select要素)が追加されていた。

5.5の機能強化:コメントフォームのちょっとした改良(2020年8月12日 更新)

来月にリリースされるWordPress 5.5に向けてBeta 1、2、3と公開が続いている。「WordPress 5.5 Beta 3(以降Beta 3)」のソースコードを見ていくと、コメントフォームを表示する comment_form関数が機能拡張されていた。

Login rebuilderに「XML-RPC設定」を追加しました(2018年5月27日 更新)

公式サイトで公開しているプラグイン「Login rebuilder」をバージョンアップし、XML-RPCリクエストの管理機能を追加しました。Login rebuilderの主たる機能は、ログインページをサイト別にユニークなURLに変更し、ログインページへの不正アクセスを回避することです。WordPressのXML-RPCリクエストはピンバックや外部ツールやサイトなどとの連携に利用されていますが、今回追加した機能ではXML-RPCリクエストの処理に対していくつかの制限できるようにしています。

index.htmlでアーカイブページを表示させる(2011年10月14日 更新)

静的なサイトでは、各ディレクトリにindex.htmlファイルを置き、そのディレクトリの内容を紹介することが多い。WordPressで構築したサイトも同様にできないかと考え、試行錯誤してみた(こんなことを考えてるのは自分だけだろうか!?)。