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.7 to 7.1.0), 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

313–429

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

Plugin surface

16 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 · 16

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

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

   Filters whether the post should be considered "empty".

2. 2
   apply_filters( wp_insert_post_parent )filterline 4868 (+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 4894 (+296 into the body)

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

4. 4
   apply_filters( wp_insert_attachment_data )filterline 4963 (+365 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 4978 (+380 into the body)

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

6. 6
   do_action( pre_post_update )actionline 4993 (+395 into the body)

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

7. 7
   do_action( pre_post_insert )actionline 5025 (+427 into the body)

   Fires immediately before a new post is inserted in the database.

8. 8
   do_action( edit_attachment )actionline 5186 (+588 into the body)

   Fires once an existing attachment has been updated.

9. 9
   do_action( attachment_updated )actionline 5199 (+601 into the body)

   Fires once an existing attachment has been updated.

10. 10
    do_action( add_attachment )actionline 5209 (+611 into the body)

    Fires once an attachment has been added.

11. 11
    do_action( edit_post_{$post->post_type} )actionline 5232 (+634 into the body)

    Fires once an existing post has been updated.

12. 12
    do_action( edit_post )actionline 5242 (+644 into the body)

    Fires once an existing post has been updated.

13. 13
    do_action( post_updated )actionline 5255 (+657 into the body)

    Fires once an existing post has been updated.

14. 14
    do_action( save_post_{$post->post_type} )actionline 5275 (+677 into the body)

    Fires once a post has been saved.

15. 15
    do_action( save_post )actionline 5286 (+688 into the body)

    Fires once a post has been saved.

16. 16
    do_action( wp_insert_post )actionline 5297 (+699 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 ↗

4598function wp_insert_post( $postarr, $wp_error = false, $fire_after_hooks = true ) {4599	global $wpdb;4600 4601	// Capture original pre-sanitized array for passing into filters.4602	$unsanitized_postarr = $postarr;4603 4604	$user_id = get_current_user_id();4605 4606	$defaults = array(4607		'post_author'           => $user_id,4608		'post_content'          => '',4609		'post_content_filtered' => '',4610		'post_title'            => '',4611		'post_excerpt'          => '',4612		'post_status'           => 'draft',4613		'post_type'             => 'post',4614		'comment_status'        => '',4615		'ping_status'           => '',4616		'post_password'         => '',4617		'to_ping'               => '',4618		'pinged'                => '',4619		'post_parent'           => 0,4620		'menu_order'            => 0,4621		'guid'                  => '',4622		'import_id'             => 0,4623		'context'               => '',4624		'post_date'             => '',4625		'post_date_gmt'         => '',4626	);4627 4628	$postarr = wp_parse_args( $postarr, $defaults );4629 4630	unset( $postarr['filter'] );4631 4632	$postarr = sanitize_post( $postarr, 'db' );4633 4634	// Are we updating or creating?4635	$post_id = 0;4636	$update  = false;4637	$guid    = $postarr['guid'];4638 4639	if ( ! empty( $postarr['ID'] ) ) {4640		$update = true;4641 4642		// Get the post ID and GUID.4643		$post_id     = $postarr['ID'];4644		$post_before = get_post( $post_id );4645 4646		if ( is_null( $post_before ) ) {4647			if ( $wp_error ) {4648				return new WP_Error( 'invalid_post', __( 'Invalid post ID.' ) );4649			}4650			return 0;4651		}4652 4653		$guid            = get_post_field( 'guid', $post_id );4654		$previous_status = get_post_field( 'post_status', $post_id );4655	} else {4656		$previous_status = 'new';4657		$post_before     = null;4658	}4659 4660	$post_type = empty( $postarr['post_type'] ) ? 'post' : $postarr['post_type'];4661 4662	$post_title   = $postarr['post_title'];4663	$post_content = $postarr['post_content'];4664	$post_excerpt = $postarr['post_excerpt'];4665 4666	if ( isset( $postarr['post_name'] ) ) {4667		$post_name = $postarr['post_name'];4668	} elseif ( $update ) {4669		// For an update, don't modify the post_name if it wasn't supplied as an argument.4670		$post_name = $post_before->post_name;4671	}4672 4673	$maybe_empty = 'attachment' !== $post_type4674		&& ! $post_content && ! $post_title && ! $post_excerpt4675		&& post_type_supports( $post_type, 'editor' )4676		&& post_type_supports( $post_type, 'title' )4677		&& post_type_supports( $post_type, 'excerpt' );

Changelog

Introduced in 1.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

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

About this page

Parsed data

Generated from the wordpress-develop 7.1.0 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.