• 赤色のリンクは、まだ日本語Codexに存在しないページ・画像です。英語版と併せてご覧ください。(詳細

このWikiはいつでも誰でも編集できます

関数リファレンス/wp insert post

提供: WordPress Codex 日本語版
移動先: 案内検索

説明

データベースへ投稿(および固定ページ)を追加します。無害化や値のチェック、デフォルト値の設定なども行います。投稿オブジェクト(配列)を引数に取り、作成された投稿の ID(失敗時は 0)を返します。

使い方

<?php wp_insert_post( $post, $wp_error ); ?>

パラメータ

$post
配列|オブジェクト) (必須) 投稿の要素を表す配列またはオブジェクト。キーの名前は wp_posts テーブルの各フィールド名に一致させます。
初期値: なし

重要$post['ID'] に値を入れても、その ID の投稿は作成されません。値を入れると、その ID を持つ投稿を、$post で与えられた残りの値を使って更新します。つまり、新規投稿を作成するには $post['ID'] を空文字列にするか、値を何も入れないでおく必要があります。

$post 配列の内容は、あなたがデフォルト値をどれだけ利用するかに応じて指定すればよいでしょう。下記は、一つの投稿に対してセットできるすべてのキーと短い説明のリストです:

$post = array(
  'ID'             => [ <投稿 ID> ] // 既存の投稿を更新する場合に指定。
  'post_content'   => [ <文字列> ] // 投稿の全文。
  'post_name'      => [ <文字列> ] // 投稿のスラッグ。
  'post_title'     => [ <文字列> ] // 投稿のタイトル。
  'post_status'    => [ 'draft' | 'publish' | 'pending'| 'future' | 'private' | 登録済みカスタムステータス ] // 公開ステータス。デフォルトは 'draft'。
  'post_type'      => [ 'post' | 'page' | 'link' | 'nav_menu_item' | カスタム投稿タイプ ] // 投稿タイプ。デフォルトは 'post'。
  'post_author'    => [ <ユーザー ID> ] // 作成者のユーザー ID。デフォルトはログイン中のユーザーの ID。
  'ping_status'    => [ 'closed' | 'open' ] // 'open' ならピンバック・トラックバックを許可。デフォルトはオプション 'default_ping_status' の値。
  'post_parent'    => [ <投稿 ID> ] // 親投稿の ID。デフォルトは 0。
  'menu_order'     => [ <順序値> ] // 固定ページを追加する場合、メニュー内の並び順を指定。デフォルトは 0。
  'to_ping'        => // スペースまたは改行で区切った、ピンを打つ予定の URL のリスト。デフォルトは空文字列。
  'pinged'         => // スペースまたは改行で区切った、ピンを打った URL のリスト。デフォルトは空文字列。
  'post_password'  => [ <文字列> ] // 投稿パスワード。デフォルトは空文字列。
  'guid'           => // 普通はこれを指定せず WordPress に任せてください。
  'post_content_filtered' => // 普通はこれを指定せず WordPress に任せてください。
  'post_excerpt'   => [ <文字列> ] // 投稿の抜粋。
  'post_date'      => [ Y-m-d H:i:s ] // 投稿の作成日時。
  'post_date_gmt'  => [ Y-m-d H:i:s ] // 投稿の作成日時(GMT)。
  'comment_status' => [ 'closed' | 'open' ] // 'open' ならコメントを許可。デフォルトはオプション 'default_comment_status' の値、または 'closed'。
  'post_category'  => [ array(<カテゴリー ID>, ...) ] // 投稿カテゴリー。デフォルトは空(カテゴリーなし)。
  'tags_input'     => [ '<tag>, <tag>, ...' | array ] // 投稿タグ。デフォルトは空(タグなし)。
  'tax_input'      => [ array( <タクソノミー> => <array | string>, ...) ] // カスタムタクソノミーとターム。デフォルトは空。
  'page_template'  => [ <文字列> ] // テンプレートファイルの名前、例えば template.php 等。デフォルトは空。
);  

注意事項

  • post_title と post_content が必要です。
  • 'post_status': 投稿ステータスに 'future' を設定するときは、WordPress が投稿をいつ公開すればよいか判るよう、未来の日付を post_date に設定してください。Post Status Transitions も見てください。
  • 'post_category': wp_set_post_categories() を呼び出すのと同じです。
  • 'tags_input': wp_set_post_tags() を呼び出すのと同じです。
  • 'tax_input': 配列の各要素(カスタムタクソノミーとターム)について wp_set_post_terms() を呼び出すのと同じです。ログイン中のユーザーがタクソノミーを扱う権限を持たない場合は代わりに wp_set_object_terms() を使う必要があります。
  • 'page_template': 投稿タイプが 'page' なら、ページテンプレートを設定します。失敗すると WP_Error または 0 を返し、この関数は最後のアクションを呼び出す前に終了します。投稿タイプが 'page' でなければ、このパラメータは無視されます。固定ページではないものにページテンプレートを設定するには、キー '_wp_page_template' を指定して update_post_meta() を呼び出します。
$wp_error
真偽値) (オプションtrue にすると、失敗したときに WP_Error オブジェクトを返します。
初期値: false

戻り値

投稿をデータベースに追加できた場合、投稿 ID を返します。失敗すると、$wp_error が false なら 0 を、true なら WP_Error オブジェクトを返します。

用例

wp_insert_post() を実行する前に、必要な投稿の要素を渡すための配列を作成する必要があります。wp_insert_post() は未指定の値にデフォルト値を設定しますが、タイトル・本文・抜粋の何れかを必ず指定してください。どれも未指定の場合は、追加に失敗します。

次の例は投稿のタイトル、本文、ステータス、作成者、カテゴリーを設定します。データベースの wp_posts テーブルにあるフィールドを配列のキーにして値を追加できます。

// 投稿オブジェクトを作成
$my_post = array(
  'post_title'    => 'My post',
  'post_content'  => 'This is my post.',
  'post_status'   => 'publish',
  'post_author'   => 1,
  'post_category' => array(8,39)
);

// 投稿をデータベースへ追加
wp_insert_post( $my_post );

新規投稿を追加して、その ID を返します。

$post_id = wp_insert_post( $post, $wp_error );
// $post_id を add_post_meta や update_post_meta に渡して利用できます

デフォルト値のリストは関数の本体で定義されていますが、次のようになっています:

$defaults = array(
  'post_status'           => 'draft',
  'post_type'             => 'post',
  'post_author'           => $user_id,
  'ping_status'           => get_option( 'default_ping_status' ),
  'post_parent'           => 0,
  'menu_order'            => 0,
  'to_ping'               => '',
  'pinged'                => '',
  'post_password'         => '',
  'guid'                  => '',
  'post_content_filtered' => '',
  'post_excerpt'          => '',
  'post_content'          => '',
  'post_title'            => ''
);

カテゴリー

カテゴリーはデータベースに登録済みのカテゴリー ID の配列で指定します。カテゴリーがひとつの場合でも配列にします。

wp_set_post_terms() も見てください。

セキュリティ

wp_insert_post() はデータを sanitize_post() に通します。これにより、必要な無害化と検証(KSES 等)を実行します。

従って、心配する必要はありません。

しかし、投稿タイトルや他のフィールドから、HTML や JavaScript や PHP タグを除去したいと思うかもしれません。驚くべきことに、WordPress はこれを自動的には行いませんが、wp_strip_all_tags() 関数を使えば簡単に実行できます。またフロントエンドに投稿入力フォームを作るときにとても役立ちます。

// 投稿オブジェクトを作成
$my_post = array(
  'post_title'    => wp_strip_all_tags( $_POST['post_title'] ),
  'post_content'  => $_POST['post_content'],
  'post_status'   => 'publish',
  'post_author'   => 1,
  'post_category' => array( 8,39 )
);

// 投稿をデータベースへ追加
wp_insert_post( $my_post );

変更履歴

  • 1.0 : 新規導入

変更履歴

wp_insert_post()wp-includes/post.php にあります。

関連項目

wp_update_post(), wp_delete_post(), wp_publish_post(), wp_delete_attachment()/en, wp_get_attachment_url(), wp_insert_attachment()/en

フィルター: wp_insert_post_data()/en


関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/wp insert post最新版との差分