wp_delete_post( int $post_id = 0, bool $force_delete = false ): WP_Post|false|null

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

$post_idintoptional

Post ID. (The default of 0 is for historical reasons; providing it is incorrect.)Default: 0

$force_deletebooloptional

Whether to bypass Trash and force deletion.
Default false.Default: false

Return value

WP_Post|false|null

Post data on success, false or null on failure.

Performance profile

How much work a call to wp_delete_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 ->get_row().

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

16–224

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

Plugin surface

7 hooks

Third-party callbacks on 'pre_delete_post', 'before_delete_post', 'delete_post_{$post->post_type}' run inside this call, and their cost is not bounded by anything here.

Called by

29

29 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
• sqldatabase query->get_row()called directly
• cacheobject cachewp_cache_delete()one call below wp_delete_post()

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

What one call costs · 19 distinct outcomes

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

Hooks and filters fired · 7

7 hooks fire while wp_delete_post() runs, in this order:

1. 1
   apply_filters( pre_delete_post )filterline 3871 (+37 into the body)

   Filters whether a post deletion should take place.

2. 2
   do_action( before_delete_post )actionline 3887 (+53 into the body)

   Fires before a post is deleted, at the start of wp_delete_post().

3. 3
   do_action( delete_post_{$post->post_type} )actionline 3956 (+122 into the body)

   Fires immediately before a post is deleted from the database.

4. 4
   do_action( delete_post )actionline 3967 (+133 into the body)

   Fires immediately before a post is deleted from the database.

5. 5
   do_action( deleted_post_{$post->post_type} )actionline 3985 (+151 into the body)

   Fires immediately after a post is deleted from the database.

6. 6
   do_action( deleted_post )actionline 3996 (+162 into the body)

   Fires immediately after a post is deleted from the database.

7. 7
   do_action( after_delete_post )actionline 4019 (+185 into the body)

   Fires after a post is deleted, at the conclusion of wp_delete_post().

Uses · 18

• _doing_it_wrong()Marks something as being incorrectly called.
• __()Retrieves the translation of $text.
• get_post()Retrieves post data given a post ID or post object.
• get_post_status()Retrieves the post status based on the post ID.
• wp_trash_post()Moves a post or page to the Trash
• wp_delete_attachment()Trashes or deletes an attachment.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• do_action()Calls the callback functions that have been added to an action hook.
• delete_post_meta()Deletes a post meta field for the given post ID.
• wp_delete_object_term_relationships()Unlinks the object from the taxonomy or taxonomies.
• get_object_taxonomies()Returns the names or objects of the taxonomies which are registered for the requested object or object type, such as a post object or post type name.
• is_post_type_hierarchical()Determines whether the post type is hierarchical.

Used by · 29

• WP_Customize_Manager::handle_dismiss_autosave_or_lock_request()Deletes a given auto-draft changeset or the autosave revision for a given changeset or delete changeset lock.
• WP_Customize_Manager::save_changeset_post()Saves the post for the loaded changeset.
• WP_Customize_Manager::trash_changeset_post()Trashes or deletes a changeset post.
• WP_Customize_Nav_Menu_Item_Setting::update()Creates/updates the nav_menu_item post for this setting.
• WP_Privacy_Requests_Table::process_bulk_action()Process bulk actions.
• WP_REST_Menu_Items_Controller::delete_item()Deletes a single nav menu item.
• WP_REST_Posts_Controller::delete_item()Deletes a single post.
• WP_REST_Revisions_Controller::delete_item()Deletes a single revision.
• WP_REST_Templates_Controller::delete_item()Deletes a single template.
• WP_REST_Templates_Controller::update_item()Updates a single template.
• _wp_after_delete_font_family()Deletes child font faces when a font family is deleted.
• _wp_delete_customize_changeset_dependent_auto_drafts()Deletes auto-draft posts associated with the supplied changeset.

Source code

View on Trac ↗View on GitHub ↗

3834function wp_delete_post( $post_id = 0, $force_delete = false ) {3835	global $wpdb;3836 3837	$post_id = (int) $post_id;3838	if ( $post_id <= 0 ) {3839		_doing_it_wrong( __FUNCTION__, __( 'The post ID must be greater than 0.' ), '6.9.0' );3840		return false;3841	}3842 3843	$post = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE ID = %d", $post_id ) );3844 3845	if ( ! $post ) {3846		return $post;3847	}3848 3849	$post = get_post( $post );3850 3851	if ( ! $force_delete3852		&& ( 'post' === $post->post_type || 'page' === $post->post_type )3853		&& 'trash' !== get_post_status( $post_id ) && EMPTY_TRASH_DAYS3854	) {3855		return wp_trash_post( $post_id );3856	}3857 3858	if ( 'attachment' === $post->post_type ) {3859		return wp_delete_attachment( $post_id, $force_delete );3860	}3861 3862	/**3863	 * Filters whether a post deletion should take place.3864	 *3865	 * @since 4.4.03866	 *3867	 * @param WP_Post|false|null $check        Whether to go forward with deletion. Anything other than null will short-circuit deletion.3868	 * @param WP_Post            $post         Post object.3869	 * @param bool               $force_delete Whether to bypass the Trash.3870	 */3871	$check = apply_filters( 'pre_delete_post', null, $post, $force_delete );3872	if ( null !== $check ) {3873		return $check;3874	}3875 3876	/**3877	 * Fires before a post is deleted, at the start of wp_delete_post().3878	 *3879	 * @since 3.2.03880	 * @since 5.5.0 Added the `$post` parameter.3881	 *3882	 * @see wp_delete_post()3883	 *3884	 * @param int     $post_id Post ID.3885	 * @param WP_Post $post    Post object.3886	 */3887	do_action( 'before_delete_post', $post_id, $post );3888 3889	delete_post_meta( $post_id, '_wp_trash_meta_status' );3890	delete_post_meta( $post_id, '_wp_trash_meta_time' );3891 3892	wp_delete_object_term_relationships( $post_id, get_object_taxonomies( $post->post_type ) );3893 3894	$parent_data  = array( 'post_parent' => $post->post_parent );3895	$parent_where = array( 'post_parent' => $post_id );3896 3897	if ( is_post_type_hierarchical( $post->post_type ) ) {3898		// Point children of this page to its parent, also clean the cache of affected children.3899		$children_query = $wpdb->prepare(3900			"SELECT * FROM $wpdb->posts WHERE post_parent = %d AND post_type = %s",3901			$post_id,3902			$post->post_type3903		);3904 3905		$children = $wpdb->get_results( $children_query );3906 3907		if ( $children ) {3908			$wpdb->update( $wpdb->posts, $parent_data, $parent_where + array( 'post_type' => $post->post_type ) );3909		}3910	}3911 3912	// Do raw query. wp_get_post_revisions() is filtered.3913	$revision_ids = $wpdb->get_col(

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.