Function Reference/wp insert post

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

Description

This function inserts posts (and pages) in the database. It sanitizes variables, does some checks, fills in missing variables like date/time, etc. It takes an array as its argument and returns the post ID of the created post (or 0 if there is an error).

Usage

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

Parameters

tt$post/tt
(array) (required) An array representing the elements that make up a post. There is a one-to-one relationship between these elements and the names of columns in the wp_posts table in the database.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

IMPORTANT: Setting a value for $post['ID'] WILL NOT create a post with that ID number. Setting this value will cause the function to update the post with that ID number with the other values specified in $post. In short, to insert a new post, $post['ID'] must be blank or not set at all.

The contents of the post array can depend on how much (or little) you want to trust the defaults. Here is a list with a short description of all the keys you can set for a post:

$post = array(
  'ID'             => [ <post id> ] //Are you updating an existing post?
  'menu_order'     => [ <order> ] //If new post is a page, it sets the order in which it should appear in the tabs.
  'comment_status' => [ 'closed' | 'open' ] // 'closed' means no comments.
  'ping_status'    => [ 'closed' | 'open' ] // 'closed' means pingbacks or trackbacks turned off
  'pinged'         => [ ? ] //?
  'post_author'    => [ <user ID> ] //The user ID number of the author.
  'post_category'  => [ array(<category id>, <...>) ] //post_category no longer exists, try wp_set_post_terms() for setting a post's categories
  'post_content'   => [ <the text of the post> ] //The full text of the post.
  'post_date'      => [ Y-m-d H:i:s ] //The time post was made.
  'post_date_gmt'  => [ Y-m-d H:i:s ] //The time post was made, in GMT.
  'post_excerpt'   => [ <an excerpt> ] //For all your post excerpt needs.
  'post_name'      => [ <the name> ] // The name (slug) for your post
  'post_parent'    => [ <post ID> ] //Sets the parent of the new post.
  'post_password'  => [ ? ] //password for post?
  'post_status'    => [ 'draft' | 'publish' | 'pending'| 'future' | 'private' | 'custom_registered_status' ] //Set the status of the new post.
  'post_title'     => [ <the title> ] //The title of your post.
  'post_type'      => [ 'post' | 'page' | 'link' | 'nav_menu_item' | 'custom_post_type' ] //You may want to insert a regular post, page, link, a menu item or some custom post type
  'tags_input'     => [ '<tag>, <tag>, <...>' ] //For tags.
  'to_ping'        => [ ? ] //?
  'tax_input'      => [ array( 'taxonomy_name' => array( 'term', 'term2', 'term3' ) ) ] // support for custom taxonomies. 
);  

NOTE: The page_template key was removed from the $post table and is now located in the wp_postmeta table. To set the page template of a page, use update_post_meta instead with a meta key of _wp_page_template.

NOTE 2: The post_status is documented at Post Status Transitions.

NOTE 3: If providing a post_status of 'future' you must specify the post_date in order for WordPress to know when to publish your post.

NOTE 4: If the current user doesn't have the capability to work with a custom taxonomy then using tax_input to add a term won't work. You will need to use wp_set_object_terms.

tt$wp_error/tt
(bool) (optional) Allow return of WP_Error object on failure
Default: falsenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

Return

The ID of the post if the post is successfully added to the database. On failure, it returns 0 if $wp_error is set to false, or a WP_Error object if $wp_error is set to true.

Usage

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

Example

Before calling wp_insert_post() it is necessary to create an array to pass the necessary elements that make up a post. The wp_insert_post() will fill out a default list of these but the user is required to provide the title and content otherwise the database write will fail.

The user can provide more elements than are listed here by simply defining new keys in the database. The keys should match the names of the columns in the wp_posts table in the database.

// Create post object
$my_post = array(
  'post_title'    => 'My post',
  'post_content'  => 'This is my post.',
  'post_status'   => 'publish',
  'post_author'   => 1,
  'post_category' => array(8,39)
);

// Insert the post into the database
wp_insert_post( $my_post );

Insert a new post and return the new post id.

$post_id = wp_insert_post( $post, $wp_error );
//now you can use $post_id withing add_post_meta or update_post_meta

The default list referred to above is defined in the function body. It is as follows:

$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
);

Categories

Categories need to be passed as an array of integers that match the category IDs in the database. This is the case even where only one category is assigned to the post.

See also: wp_set_post_terms()

Security

wp_insert_post() passes data through sanitize_post(), which itself handles all necessary sanitization and validation (kses, etc.).

As such, you don't need to worry about that.

You may wish, however, to remove HTML, JavaScript, and PHP tags from the post_title and any other fields. Surprisingly, WordPress does not do this automatically. This can be easily done by using the wp_strip_all_tags() function (as of 2.9) and is especially useful when building front-end post submission forms.

// Create post object
$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 )
);

// Insert the post into the database
wp_insert_post( $my_post );

Change Log

Source File

wp_insert_post() is located in onlyincludecodewp-includes/post.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn.

Related

wp_update_post(), wp_delete_post(), wp_publish_post(), wp_delete_attachment(), wp_get_attachment_url(), wp_insert_attachment(), wp_insert_post_data()

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude includeonlydiv style=clear:both; background-color:#EEEEFF; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;This article is marked as in need of editing. You can help Codex by editing it./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude