WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Function Reference/wp insert post

Contents

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

$post
(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: None
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?
  'post_content'   => [ <string> ] // The full text of the post.
  'post_name'      => [ <string> ] // The name (slug) for your post
  'post_title'     => [ <string> ] // The title of your post.
  'post_status'    => [ 'draft' | 'publish' | 'pending'| 'future' | 'private' | custom registered status ] // Default 'draft'.
  'post_type'      => [ 'post' | 'page' | 'link' | 'nav_menu_item' | custom post type ] // Default 'post'.
  'post_author'    => [ <user ID> ] // The user ID number of the author. Default is the current user ID.
  'ping_status'    => [ 'closed' | 'open' ] // Pingbacks or trackbacks allowed. Default is the option 'default_ping_status'.
  'post_parent'    => [ <post ID> ] // Sets the parent of the new post, if any. Default 0.
  'menu_order'     => [ <order> ] // If new post is a page, sets the order in which it should appear in supported menus. Default 0.
  'to_ping'        => // Space or carriage return-separated list of URLs to ping. Default empty string.
  'pinged'         => // Space or carriage return-separated list of URLs that have been pinged. Default empty string.
  'post_password'  => [ <string> ] // Password for post, if any. Default empty string.
  'guid'           => // Skip this and let Wordpress handle it, usually.
  'post_content_filtered' => // Skip this and let Wordpress handle it, usually.
  'post_excerpt'   => [ <string> ] // For all your post excerpt needs.
  '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.
  'comment_status' => [ 'closed' | 'open' ] // Default is the option 'default_comment_status', or 'closed'.
  'post_category'  => [ array(<category id>, ...) ] // Default empty.
  'tags_input'     => [ '<tag>, <tag>, ...' | array ] // Default empty.
  'tax_input'      => [ array( <taxonomy> => <array | string> ) ] // For custom taxonomies. Default empty.
  'page_template'  => [ <string> ] // Requires name of template file, eg template.php. Default empty.
);  

Notes

  • 'post_status': If providing a post_status of 'future' you must specify the post_date in order for WordPress to know when to publish your post. See also Post Status Transitions.
  • 'post_category': Equivalent to calling wp_set_post_categories().
  • 'tags_input': Equivalent to calling wp_set_post_tags().
  • 'tax_input': Equivalent to calling wp_set_post_terms() for each custom taxonomy in the array. If the current user doesn't have the capability to work a taxonomy, the you must use wp_set_object_terms() instead.
  • 'page_template': If post_type is 'page', will attempt to set the page template. On failure, the function will return either a WP_Error or 0, and stop before the final actions are called. If the post_type is not 'page', the parameter is ignored. You can set the page template for a non-page by calling update_post_meta() with a key of '_wp_page_template'.
$wp_error
(bool) (optional) Allow return of WP_Error object on failure
Default: false

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 next example shows the post title, content, status, author, and post categories being set. You can add further key-value pairs, making sure the keys 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 wp-includes/post.php.

Related

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

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.