函式描述

此函式的作用是插入文章（或頁面、自定義文章型別）到資料庫，插入之前，會淨化一些變數，做一些檢查，補全一些缺失的必需資料（如日期/時間）。此函式需要一個數組作為引數，插入成功後，返回插入文章的ID（插入失敗返回0）。

使用方法

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

引數

$post

(array) (必需) 代表一篇文章陣列，陣列元素和wp_posts資料表中的資料列是一對一關係。

預設: None

重要：為&post['ID']設定一個值將不會建立ID為該值的文章，而是更新ID為該值的文章，也就是說，要想插入一篇新文章，$post['ID']必須為空，或者壓根不設定。

文章陣列的內容取決於你對文章預設值的信任程度，下面是所有文章陣列元素的簡短描述。

$post = array(
  'ID'             => [ <post id> ] // 如果需要更新文章，設定id為需要更新文章的id，否則不要設定此值
  'post_content'   => [ <string> ] // 文章內容，也就是視覺化編輯器裡面的輸入的內容
  'post_name'      => [ <string> ] // 文章的別名，就是URL裡面的名稱
  'post_title'     => [ <string
 
> ] // 文章標題
  'post_status'    => [ 'draft' | 'publish' | 'pending'| 'future' | 'private' | custom registered status ] // 文章狀態，預設 'draft'.
  'post_type'      => [ 'post' | 'page' | 'link' | 'nav_menu_item' | custom post type ] // 文章型別，預設為'post'.
  'post_author'    => [ <user ID> ] // 文章作者的ID，預設為當前登入的使用者ID
 
  'ping_status'    => [ 'closed' | 'open' ] // 是否允許 Pingbacks 或 trackbacks allowed，預設為'default_ping_status' 設定的值。
  'post_parent'    => [ <post ID> ] // 文章的父級文章ID，預設為 0，頂級文章。
  'menu_order'     => [ <order> ] // 如果新文章為一個頁面，可以設定一個頁面序號，預設為0。
  'to_ping'        => // 空格或回車分隔的需要ping的url列表，預設為空字串。
  'pinged'         => // 空格或回車分隔的已經ping過的url列表，預設為空字串。
  'post_password'  => [ <string> ] // 文章密碼，預設為空字串。
  'guid'           => // 不要管這個，WordPress會自動處理。
  'post_content_filtered' => // 不要管這個，WordPress會自動處理。
  'post_excerpt'   => [ <string> ] // 文章摘要。
  'post_date'      => [ Y-m-d H:i:s ] // 文章釋出時間。
  'post_date_gmt'  => [ Y-m-d H:i:s ] // GMT格式的文章釋出時間。
  'comment_status' => [ 'closed' | 'open' ] // 是否允許評論，預設為 'default_comment_status'的值，或'closed'。
  'post_category'  => [ array(<category id>, ...) ] // 文章分類目錄，預設為空
  'tags_input'     => [ '<tag>, <tag>, ...' | array ] // 文章標籤，預設為空
  'tax_input'      => [ array( <taxonomy> => <array | string>, <taxonomy_other> => <array | string> ) ] // 文章的自定義分類法專案，預設為空。
  'page_template'  => [ <string> ] // 頁面模板檔案的名稱，如，template.php，預設為空。
);  

注意

• post_name, post_title, post_content, 和post_excerpt 為必需的元素。
• ‘post_status’：如果設定了post_status 為 ‘future’，你還必須指定 post_date 值，這樣WordPress才能知道什麼時候釋出你的文章，更多資訊參見 文章狀態轉換。
• ‘post_category’：等效於呼叫 wp_set_post_categories()。
• ‘tags_input’：等效於呼叫 wp_set_post_tags()。
• ‘tax_input：等效於為陣列中的每個自定義分類法呼叫 wp_set_post_terms()，如果當前使用者沒有設定自定義分類法的許可權，就必須使用 wp_set_object_terms() 代替了。
• ‘page_template’：如果 post_type 為 ‘page’，將嘗試設定頁面，如果設定失敗，此函式將返回一個 WP_Error 物件或 0，然後在最終操作之前停止。如果 post_type 不是 ‘page’，此引數將被忽略，你可以通過呼叫 update_post_meta() 設定 ‘_wp_page_template’ 的值為不是頁面的文章型別設定頁面模板。

$wp_error

(bool) (optional) 失敗時允許返回一個 WP_Error 物件。

Default: false

返回值

如果文章成功插入了資料庫，將返回插入的新文章ID，如果失敗，將返回0或一個WP_Error物件（如果$wp_error設定為true）。

使用示例

在呼叫 wp_insert_post() 之前，我們需要建立一個包含必要文章元素的陣列，wp_insert_post() 將會使用預設值自動填充一些文章元素，但是，使用者必須提供一個文章標題和內容，否則，將會出現資料庫錯誤導致插入文章失敗。

下面的例子中，我麼設定了 post title, content, status, author, 和 post categories，除了這些，我們可以根據上面的列表新增更多的文章元素鍵值對，以匹配wp_posts資料表中的資料列。

// 建立文章物件
$my_post = array(
  'post_title'    => '我的測試文章',
  'post_content'  => '這是一個測試文章。',
  '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'          => '',
  'import_id'             => 0
);

分類目錄

分類目錄應該以分類ID陣列的形式傳入，即使只需要設定一個分類目錄，該引數的值也必須為陣列。

更多資訊參見：wp_set_post_terms()

安全問題

在存入資料庫之前，wp_insert_post() 先把資料傳遞給 sanitize_post() 處理了，也就是說，該函式已經處理了所有的資料驗證和淨化，我們不需要再為這些問題操心了。

因為一些原因，你可能需要移除文章標題或其他欄位中的 HTML, JavaScript, 和 PHP 程式碼，奇怪的是， WordPress 竟然沒有自動處理這些事情，不過我們可以使用 wp_strip_all_tags() 函式（WordPress 2.9以後可用）輕鬆的搞定，這在提交前端表單的時候，特別有用。

// 建立文章物件
$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 );

轉自：https://www.wpzhiku.com/codex/wp_insert_post/