wp_insert_post() – Insert or update a post.

Description

Insert or update a post.

If the $postarr parameter has 'ID' set to a value, then post will be updated. You can set the post date manually, by setting the values for 'post_date' and 'post_date_gmt' keys. You can close the comments or open the comments by setting the value for 'comment_status' key.

Usage

$int|WP_Error = wp_insert_post( $postarr, $wp_error, $fire_after_hooks );

Parameters

$postarr
( array ) required – { An array of elements that make up a post to update or insert.
$ID
( int ) required – The post ID. If equal to something other than 0, the post with that ID will be updated. Default 0.
$post_author
( int ) required – The ID of the user who added the post. Default is the current user ID.
$post_date
( string ) required – The date of the post. Default is the current time.
$post_date_gmt
( string ) required – The date of the post in the GMT timezone. Default is the value of `$post_date`.
$post_content
( string ) required – The post content. Default empty.
$post_content_filtered
( string ) required – The filtered post content. Default empty.
$post_title
( string ) required – The post title. Default empty.
$post_excerpt
( string ) required – The post excerpt. Default empty.
$post_status
( string ) required – The post status. Default 'draft'.
$post_type
( string ) required – The post type. Default 'post'.
$comment_status
( string ) required – Whether the post can accept comments. Accepts 'open' or 'closed'. Default is the value of 'default_comment_status' option.
$ping_status
( string ) required – Whether the post can accept pings. Accepts 'open' or 'closed'. Default is the value of 'default_ping_status' option.
$post_password
( string ) required – The password to access the post. Default empty.
$post_name
( string ) required – The post name. Default is the sanitized post title when creating a new post.
$to_ping
( string ) required – Space or carriage return-separated list of URLs to ping. Default empty.
$pinged
( string ) required – Space or carriage return-separated list of URLs that have been pinged. Default empty.
$post_modified
( string ) required – The date when the post was last modified. Default is the current time.
$post_modified_gmt
( string ) required – The date when the post was last modified in the GMT timezone. Default is the current time.
$post_parent
( int ) required – Set this for the post it belongs to, if any. Default 0.
$menu_order
( int ) required – The order the post should be displayed in. Default 0.
$post_mime_type
( string ) required – The mime type of the post. Default empty.
$guid
( string ) required – Global Unique ID for referencing the post. Default empty.
$import_id
( int ) required – The post ID to be used when inserting a new post. If specified, must not match any existing post ID. Default 0.
$post_category
( int[] ) required – Array of category IDs. Defaults to value of the 'default_category' option.
$tags_input
( array ) required – Array of tag names, slugs, or IDs. Default empty.
$tax_input
( array ) required – An array of taxonomy terms keyed by their taxonomy name. If the taxonomy is hierarchical, the term list needs to be either an array of term IDs or a comma-separated string of IDs. If the taxonomy is non-hierarchical, the term list can be an array that contains term names or slugs, or a comma-separated string of names or slugs. This is because, in hierarchical taxonomy, child terms can have the same names with different parent terms, so the only way to connect them is using ID. Default empty.
$meta_input
( array ) required – Array of post meta values keyed by their post meta key. Default empty. }
$wp_error
( bool ) optional – Optional. Whether to return a WP_Error on failure. Default false.
$fire_after_hooks
( bool ) optional default: 1 – Optional. Whether to fire the after insert hooks. Default true.

Returns

int|WP_Error The post ID on success. The value 0 or WP_Error on failure.

Source

File name: wordpress/wp-includes/post.php
Lines:

1 to 100 of 663
function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true ) {
  global $wpdb;

  // Capture original pre-sanitized array for passing into filters.
  $unsanitized_postarr = $postarr;

  $user_id = get_current_user_id();

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

  $postarr = wp_parse_args( $postarr, $defaults );

  unset( $postarr['filter'] );

  $postarr = sanitize_post( $postarr, 'db' );

  // Are we updating or creating?
  $post_ID = 0;
  $update  = false;
  $guid    = $postarr['guid'];

  if ( ! empty( $postarr['ID'] ) ) {
    $update = true;

    // Get the post ID and GUID.
    $post_ID     = $postarr['ID'];
    $post_before = get_post( $post_ID );

    if ( is_null( $post_before ) ) {
      if ( $wp_error ) {
        return new WP_Error( 'invalid_post', __( 'Invalid post ID.' ) );
      }
      return 0;
    }

    $guid            = get_post_field( 'guid', $post_ID );
    $previous_status = get_post_field( 'post_status', $post_ID );
  } else {
    $previous_status = 'new';
    $post_before     = null;
  }

  $post_type = empty( $postarr['post_type'] ) ? 'post' : $postarr['post_type'];

  $post_title   = $postarr['post_title'];
  $post_content = $postarr['post_content'];
  $post_excerpt = $postarr['post_excerpt'];

  if ( isset( $postarr['post_name'] ) ) {
    $post_name = $postarr['post_name'];
  } elseif ( $update ) {
    // For an update, don't modify the post_name if it wasn't supplied as an argument.
    $post_name = $post_before->post_name;
  }

  $maybe_empty = 'attachment' !== $post_type
    && ! $post_content && ! $post_title && ! $post_excerpt
    && post_type_supports( $post_type, 'editor' )
    && post_type_supports( $post_type, 'title' )
    && post_type_supports( $post_type, 'excerpt' );

  
/**
 * Filters whether the post should be considered "empty".
 *
 * The post is considered "empty" if both:
 * 1. The post type supports the title, editor, and excerpt fields
 * 2. The title, editor, and excerpt fields are all empty
 *
 * Returning a truthy value from the filter will effectively short-circuit
 * the new post being inserted and return 0. If $wp_error is true, a WP_Error
 * will be returned instead.
 *
 * @since 3.3.0
 *
 * @param bool  $maybe_empty Whether the post should be considered "empty".
 * @param array $postarr     Array of post data.
 */
  if ( apply_filters( 'wp_insert_post_empty_content', $maybe_empty, $postarr ) ) {
    if ( $wp_error ) {
      return new WP_Error( 'empty_content', __( 'Content, title, and excerpt are empty.' ) );
 

 View on GitHub View on Trac

Called by

    Invoked by

      API Letters: ,,