wp_insert_post( array $postarr, bool $wp_error = false, bool $fire_after_hooks = true ): int|WP_Error

Description

Compatibility

Present in every tracked release (6.7.10 to 7.1.3), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$postarrarray

An array of elements that make up a post to update or insert.

• $IDintdefault: 0

  The post ID. If equal to something other than 0, the post with that ID will be updated.

• $post_authorintdefault: is the current user ID

  The ID of the user who added the post.

• $post_datestringdefault: is the current time

  The date of the post.

• $post_date_gmtstringdefault: is the value of $post_date

  The date of the post in the GMT timezone.

• $post_contentstringdefault: empty

  The post content.

• $post_content_filteredstringdefault: empty

  The filtered post content.

• $post_titlestringdefault: empty

  The post title.

• $post_excerptstringdefault: empty

  The post excerpt.

• $post_statusstringdefault: 'draft'

  The post status.

• $post_typestringdefault: 'post'

  The post type.

• $comment_statusstringdefault: is the value of 'default_comment_status' option

  Whether the post can accept comments. Accepts 'open' or 'closed'.

• $ping_statusstringdefault: is the value of 'default_ping_status' option

  Whether the post can accept pings. Accepts 'open' or 'closed'.

• $post_passwordstringdefault: empty

  The password to access the post.

• $post_namestringdefault: is the sanitized post title when creating a new post

  The post name.

• $to_pingstringdefault: empty

  Space or carriage return-separated list of URLs to ping.

• $pingedstringdefault: empty

  Space or carriage return-separated list of URLs that have been pinged.

• $post_parentintdefault: 0

  Set this for the post it belongs to, if any.

• $menu_orderintdefault: 0

  The order the post should be displayed in.

• $post_mime_typestringdefault: empty

  The mime type of the post.

• $guidstringdefault: empty

  Global Unique ID for referencing the post.

• $import_idintdefault: 0

  The post ID to be used when inserting a new post. If specified, must not match any existing post ID.

• $post_categoryint[]

  Array of category IDs. Defaults to value of the 'default_category' option.

• $tags_inputarraydefault: empty

  Array of tag names, slugs, or IDs.

• $tax_inputarraydefault: empty

  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.

• $meta_inputarraydefault: empty

  Array of post meta values keyed by their post meta key.

• $page_templatestring

  Page template to use.

$wp_errorbooloptional

Whether to return a WP_Error on failure. Default false.Default: false

$fire_after_hooksbooloptional

Whether to fire the after insert hooks. Default true.Default: true

Return value

int|WP_Error

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

Code examples

Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.

$post_id = wp_insert_post( array(
	'post_title'   => 'Imported release notes',
	'post_content' => 'What changed in this release.',
	'post_status'  => 'draft',
	'post_author'  => 1,
	'tags_input'   => array( 'featured' ),
	'meta_input'   => array( 'price' => '0.00' ),
), true );

if ( is_wp_error( $post_id ) ) {
	echo 'Failed: ', $post_id->get_error_message();
} else {
	echo "created post {$post_id}\n";
	echo 'status:     ', get_post_status( $post_id ), "\n";
	echo 'price meta: ', get_post_meta( $post_id, 'price', true ), "\n";
	echo 'tags:       ', implode( ', ', wp_get_post_tags( $post_id, array( 'fields' => 'names' ) ) );
}

$slug     = 'pricing';
$existing = get_page_by_path( $slug );

if ( $existing ) {
	echo "already exists as page {$existing->ID}, nothing to do";
} else {
	$id = wp_insert_post( array(
		'post_title'  => 'Pricing',
		'post_name'   => $slug,
		'post_type'   => 'page',
		'post_status' => 'publish',
		'post_parent' => 6,
		'post_author' => 1,
	), true );

	echo is_wp_error( $id ) ? $id->get_error_message() : "created page {$id} under page 6";
}

Performance profile

How much work a call to wp_insert_post() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Heavy

Reaches the database via ->insert().

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

314–430

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 1047.

Plugin surface

15 hooks

Third-party callbacks on 'wp_insert_post_empty_content', 'wp_insert_post_parent', 'add_trashed_suffix_to_trashed_posts' run inside this call, and their cost is not bounded by anything here.

Called by

21

21 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• querycontent queryget_post()called directly
• hookthird-party callbacksapply_filters()called directly
• optionoption read or writeget_option()called directly
• sqldatabase query->insert()called directly
• cacheobject cachewp_cache_get()one call below wp_insert_post()
• serializeserialisationmaybe_unserialize()one call below wp_insert_post()

Further down the call graph this can also reach transient. That is the worst case, several calls deep and usually down an error path, not what a normal call pays.

What one call costs · 195 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost wp_insert_post() can have, taken from its control-flow graph on PHP 8.5.

This body has more branch combinations than are worth enumerating, so the table covers the outcomes found first rather than every one that exists.

Hooks and filters fired · 15

15 hooks fire while wp_insert_post() runs, in this order:

1. 1
   apply_filters( wp_insert_post_empty_content )filterline 4529 (+97 into the body)

   Filters whether the post should be considered "empty".

2. 2
   apply_filters( wp_insert_post_parent )filterline 4702 (+270 into the body)

   Filters the post parent -- used to check for and prevent hierarchy loops.

3. 3
   apply_filters( add_trashed_suffix_to_trashed_posts )filterline 4728 (+296 into the body)

   Filters whether or not to add a `__trashed` suffix to trashed posts that match the name of the updated post.

4. 4
   apply_filters( wp_insert_attachment_data )filterline 4796 (+364 into the body)

   Filters attachment post data before it is updated in or added to the database.

5. 5
   apply_filters( wp_insert_post_data )filterline 4811 (+379 into the body)

   Filters slashed post data just before it is inserted into the database.

6. 6
   do_action( pre_post_update )actionline 4826 (+394 into the body)

   Fires immediately before an existing post is updated in the database.

7. 7
   do_action( edit_attachment )actionline 5010 (+578 into the body)

   Fires once an existing attachment has been updated.

8. 8
   do_action( attachment_updated )actionline 5023 (+591 into the body)

   Fires once an existing attachment has been updated.

9. 9
   do_action( add_attachment )actionline 5033 (+601 into the body)

   Fires once an attachment has been added.

10. 10
    do_action( edit_post_{$post->post_type} )actionline 5056 (+624 into the body)

    Fires once an existing post has been updated.

11. 11
    do_action( edit_post )actionline 5066 (+634 into the body)

    Fires once an existing post has been updated.

12. 12
    do_action( post_updated )actionline 5079 (+647 into the body)

    Fires once an existing post has been updated.

13. 13
    do_action( save_post_{$post->post_type} )actionline 5099 (+667 into the body)

    Fires once a post has been saved.

14. 14
    do_action( save_post )actionline 5110 (+678 into the body)

    Fires once a post has been saved.

15. 15
    do_action( wp_insert_post )actionline 5121 (+689 into the body)

    Fires once a post has been saved.

Uses · 48

• get_current_user_id()Gets the current user's ID.
• wp_parse_args()Merges user defined arguments into defaults array.
• sanitize_post()Sanitizes every post field.
• get_post()Retrieves post data given a post ID or post object.
• __()Retrieves the translation of $text.
• get_post_field()Retrieves data from a post field based on Post ID.
• post_type_supports()Checks a post type's support for a given feature.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• get_option()Retrieves an option value based on an option name.
• get_post_type_object()Retrieves a post type object by name.
• current_user_can()Returns whether the current user has the specified capability.
• sanitize_title()Sanitizes a string into a slug, which can be used in URLs or HTML attributes.

Used by · 21

• WP_Customize_Manager::save_changeset_post()Saves the post for the loaded changeset.
• WP_Customize_Nav_Menus::insert_auto_draft_post()Adds a new `auto-draft` post.
• WP_Embed::shortcode()The do_shortcode() callback function.
• WP_Navigation_Fallback::create_classic_menu_fallback()Creates a Navigation Menu post from a Classic Menu.
• WP_Navigation_Fallback::create_default_fallback()Creates a default Navigation Block Menu fallback.
• WP_REST_Posts_Controller::create_item()Creates a single post.
• WP_REST_Templates_Controller::create_item()Creates a single template.
• WP_REST_Templates_Controller::update_item()Updates a single template.
• WP_Theme_JSON_Resolver::get_user_data_from_wp_global_styles()Returns the custom post type that contains the user's origin config for the active theme or an empty array if none are found.
• _wp_put_post_revision()Inserts post data into the posts table as a post revision.
• block_core_navigation_maybe_use_classic_menu_fallback()If there's a classic menu then use it as a fallback.
• get_default_post_to_edit()Returns default post information to use when populating the "Write Post" form.

Source code

View on Trac ↗View on GitHub ↗

4432function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true ) {4433	global $wpdb;4434 4435	// Capture original pre-sanitized array for passing into filters.4436	$unsanitized_postarr = $postarr;4437 4438	$user_id = get_current_user_id();4439 4440	$defaults = array(4441		'post_author'           => $user_id,4442		'post_content'          => '',4443		'post_content_filtered' => '',4444		'post_title'            => '',4445		'post_excerpt'          => '',4446		'post_status'           => 'draft',4447		'post_type'             => 'post',4448		'comment_status'        => '',4449		'ping_status'           => '',4450		'post_password'         => '',4451		'to_ping'               => '',4452		'pinged'                => '',4453		'post_parent'           => 0,4454		'menu_order'            => 0,4455		'guid'                  => '',4456		'import_id'             => 0,4457		'context'               => '',4458		'post_date'             => '',4459		'post_date_gmt'         => '',4460	);4461 4462	$postarr = wp_parse_args( $postarr, $defaults );4463 4464	unset( $postarr['filter'] );4465 4466	$postarr = sanitize_post( $postarr, 'db' );4467 4468	// Are we updating or creating?4469	$post_id = 0;4470	$update  = false;4471	$guid    = $postarr['guid'];4472 4473	if ( ! empty( $postarr['ID'] ) ) {4474		$update = true;4475 4476		// Get the post ID and GUID.4477		$post_id     = $postarr['ID'];4478		$post_before = get_post( $post_id );4479 4480		if ( is_null( $post_before ) ) {4481			if ( $wp_error ) {4482				return new WP_Error( 'invalid_post', __( 'Invalid post ID.' ) );4483			}4484			return 0;4485		}4486 4487		$guid            = get_post_field( 'guid', $post_id );4488		$previous_status = get_post_field( 'post_status', $post_id );4489	} else {4490		$previous_status = 'new';4491		$post_before     = null;4492	}4493 4494	$post_type = empty( $postarr['post_type'] ) ? 'post' : $postarr['post_type'];4495 4496	$post_title   = $postarr['post_title'];4497	$post_content = $postarr['post_content'];4498	$post_excerpt = $postarr['post_excerpt'];4499 4500	if ( isset( $postarr['post_name'] ) ) {4501		$post_name = $postarr['post_name'];4502	} elseif ( $update ) {4503		// For an update, don't modify the post_name if it wasn't supplied as an argument.4504		$post_name = $post_before->post_name;4505	}4506 4507	$maybe_empty = 'attachment' !== $post_type4508		&& ! $post_content && ! $post_title && ! $post_excerpt4509		&& post_type_supports( $post_type, 'editor' )4510		&& post_type_supports( $post_type, 'title' )4511		&& post_type_supports( $post_type, 'excerpt' );

Changelog

Introduced in 1.0.0. Unchanged from 6.7.10 through 7.1.3.

1. 6.7.10
2. 6.8.11
3. 6.9.10
4. 7.0.7
5. 7.1.3

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.8.11 tag, from src/wp-includes/post.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.